# Architecture

MoonHttpCache follows a functional-core / imperative-shell design.

## Packages

- Root package: public metadata, directives, storage, age, freshness, cache key,
  reuse, validation, and invalidation decisions.
- `src/lex`: portable HTTP token, quoted-string, list, and saturated-number tools.
- `src/httpdate`: portable Gregorian and HTTP-date implementation.
- `extensions/rfc5861`: optional stale extension policy layered over the core.
- `scenario`: schema-versioned JSON adapter and stable report rendering.
- `cmd/moon-http-cache`: native filesystem shell only.
- `examples/library-demo`: cross-target library integration.

## Data flow

```text
request + stored metadata + injected time
        │
        ├─ cache-key / Vary matching
        ├─ Cache-Control parsing
        ├─ Age and freshness calculation
        └─ mandatory and discretionary policy checks
                       │
                       ▼
      terminal decision + trace + diagnostics
```

No core function reads a clock, environment variable, file, socket, or global
cache state. Arrays are copied when a public operation returns modified metadata.

## Complexity

Let H be the number of field lines, D the number of Cache-Control directives, and
V the number of `Vary` members. Ordinary evaluation is O(H + D + V) time and
O(H + D + V) result/diagnostic space. The simple ordered header representation
uses linear lookup intentionally: HTTP messages usually contain few fields and
duplicate order matters. A framework adapter can pre-normalize larger maps later
without changing decision semantics.

HTTP-date conversion uses bounded civil-calendar iteration over years 1601–9999;
its upper bound is fixed, independent of attacker-controlled message length.