#moon_ua_parser_crescent

#Install

moon add bobzhang/crescent
moon add vicoproplus/moon_ua_parser
moon add vicoproplus/moon_ua_parser_middleware_core
moon add vicoproplus/moon_ua_parser_crescent

Pre-release note: vicoproplus/moon_ua_parser_crescent is not yet published to the mooncakes registry — moon add applies after the first release; until then, users inside this repository's moon.work workspace already consume the package as a local path dependency.

#Register

// build + register on a crescent App (onion model, async callbacks)
let app = @crescent.App()
app.use_middleware(@middleware.request_id())            // optional: request correlation
app.use_middleware(@moon_ua_parser_crescent.middleware()) // UA parsing + mount + forensics
app.get("/probe", event => {
  // handler-side typed read-back of the mounted value
  match @moon_ua_parser_crescent.mounted_ua_info(event) {
    Some(info) => "browser=\{info.browser.family}"
    None => "nothing-mounted"
  }
})

#Configuration

• forensics_sink : (@middleware_core.ForensicsRecord) -> Unit — the forensics (FO) output channel invoked for every degraded request. Default: console_forensics_sink, which prints one line [moon_ua_parser] degraded user-agent parse: reason=<reason> ua_summary="<≤64 chars>" to the console. Inject a closure to forward records to any logging backend; bobzhang/crescent ships no logger middleware, so the sink IS the log-channel adaptation.

• mounted_ua_info(event : @crescent.Event) -> @ua_parser.UaInfo? — handler-side; parses the mount back from the event's response headers.
• parse_mounted_ua_info(header_value : String) -> @ua_parser.UaInfo? — client-side; parse a X-Ua-Info response header value.
• Family headers: X-Ua-Browser / X-Ua-Os / X-Ua-Device (constants HEADER_UA_BROWSER / HEADER_UA_OS / HEADER_UA_DEVICE), plus the full JSON round-trip header X-Ua-Info (HEADER_UA_INFO).

#Mounting mechanism (and why)

• headers are written before next(), so downstream handlers see the mount on the shared event.res and App::dispatch finalizes the HTTP response from the same record — one write, two observers;
• no global mutable state and no per-request entry lifecycle (a request_id-keyed map would need explicit eviction to avoid unbounded growth);
• the mounted value is therefore directly observable by tests/clients in the response (X-Ua-Info JSON round-trips the full UaInfo, including versions and rule_index).

#Degradation behavior

1. the response keeps its normal status (e.g. 200);
2. the mount is the empty UaInfo — empty-string families (deliberately distinct from the library's "Other" fallback), visible as empty X-Ua-Browser / X-Ua-Os / X-Ua-Device headers;
3. one {ua_summary, reason} forensics record is emitted to the sink, with ua_summary truncated to 64 characters (UA_SUMMARY_MAX_LENGTH) and reason ∈ {parse_error, empty_fallback}.

#Version range

• Tested against crescent 0.11.x — dependency pinned to bobzhang/crescent@0.11.1 in moon.mod (upstream commit d99287ae409d198e1f7c1fd606e4883188d97c02, moon.mod version 0.11.1).
• vicoproplus/moon_ua_parser@0.2.0, vicoproplus/moon_ua_parser_middleware_core@0.1.0 (workspace-resolved), moonbitlang/async@0.20.3 (crescent's own requirement).
• Toolchain: moon 0.1.20260904, --target native (supported_targets = "-all+native" — wasm deliberately NOT declared: the adapter has no wasm build/test evidence yet (local wasm-gc runtime broken; CI wasm gate covers the lib only). Re-declare +wasm together with a CI wasm build/test step for this package).

#Example (one command)

moon run moon_ua_parser_crescent/examples/ua_echo --target native

#Tests

moon test --target native -p moon_ua_parser_crescent