# Public API

## Metadata

- `Headers::empty`, `Headers::from_array`, `Headers::add`, `without`, and
  `replace` create duplicate-preserving immutable-style field collections.
- `request`, `response`, and `stored_response` construct metadata values.
- `CacheMode` distinguishes `PrivateCache` from `SharedCache`.
- `CachePolicy` controls only behavior that RFC 9111 leaves discretionary.

## Parsing and time

- `parse_cache_control(headers)` returns normalized directives and diagnostics.
- `CacheControl::delta` distinguishes missing, valid, invalid, and repeated
  delta-seconds instead of choosing an ambiguous value.
- `parse_http_date` accepts IMF-fixdate plus both obsolete recipient forms.
- `calculate_current_age` exposes every intermediate RFC age value.
- `calculate_freshness` reports the selected lifetime source and result.

All time values are Unix seconds in `Int64`. Delta-seconds calculations saturate
at 2^31 seconds as required by RFC 9111; reversed clocks are clamped and diagnosed.

## Decisions

- `evaluate_storage(request, response, mode, now)` reports whether metadata may
  be stored and which qualified `private` fields must be removed.
- `evaluate_cache_key(stored, presented)` compares URI, method, and `Vary` fields.
- `evaluate_reuse(stored?, presented, mode, now, origin?, policy?)` returns the
  terminal reuse action and explanation trace.
- `prepare_validation(stored, presented)` creates `If-None-Match` or
  `If-Modified-Since` request metadata.
- `merge_not_modified(stored, response304, request_time, response_time)` returns
  updated stored metadata without changing body ownership.
- `evaluate_invalidation(request, response)` returns cache-key URIs that the
  caller should invalidate after a successful unsafe request.

## RFC 5861 extension

Import `oyjh0381/http-cache/extensions/rfc5861` separately. Call `evaluate` only
after normal RFC 9111 evaluation requires origin interaction. The result says
whether stale content may be served while revalidating or after a qualifying
network, DNS, 500, 502, 503, or 504 failure.

## Scenario package

`oyjh0381/http-cache/scenario` provides a bounded JSON schema used by the CLI and
external fixtures. `Scenario::evaluate`, `render_human`, and `render_json` expose
the same deterministic core without filesystem access.