atproto utils for zig zat.dev

Decide shared ownership and API for strict form percent decoding #36

Open zzstoatzz.io
Open opened by zzstoatzz.io

Zat v0.7.0-alpha.10 ships strict URI decoding through zat.percent.decodeAlloc and zat.percent.decodedEql. Its literal-+ behavior is correct. The downstream audit found form/query decoders that cannot adopt it directly because they map raw + to space.

Decide whether the shared form-decoding primitive belongs in Zat, in zttp, or in a small caller adapter before extending the API. Concrete consumers:

  • Stream filter and status-page decoders use form semantics and parse percent pairs with std.fmt.parseInt(u8, pair, 16).
  • ZDS HTTP decoder has the same semantics and needs caller-provided output storage.
  • Prefect server also has a form decoder, but deliberately tolerates malformed escapes; it is not automatically a consumer of a strict API.

parseInt accepts signed pairs: %+A becomes byte 0x0a and %-0 becomes NUL. These are not valid percent escapes. Preserve raw + → space, %2B → literal plus, and exactly one decoding pass. Replacing plus after URI decoding would incorrectly turn %2B into space.

Acceptance:

  • Record the ownership/API decision using the actual caller requirements; avoid adding unused modes or wrappers.
  • If shared code is added, reuse strict per-digit validation and keep URI behavior unchanged.
  • Cover signs, truncated/nonhex escapes, %2B, %252B, NUL, allocation failures and buffer boundaries where applicable.
  • Run zig zen, adversarial review, replayable fuzzing with mutation calibration, and paired performance measurements before shipping; verify real consumers.

This follows Brooke's ZDS fix and the shared-decoder review and measurements. The released URI fix is complete; this issue tracks the remaining form semantics and ownership decision.

Downstream tracking: Stream #6, ZDS #34, Prefect server #35. The URI-only adopter is tracked separately in Typeahead #51.

Sign up or Sign in to add to the discussion.