[ityonemo]

Prepares the 1.0.0 release: resolves every outstanding TODO in lib/, adds egress (response) schema validation, and brings dependencies up to date.

Egress (response) schema validation

The headline feature. Response bodies can now be validated against the schemas declared for them under responses, the same way parameters and request bodies already are.

It is gated on the application environment, read with Application.compile_env/3:

# config/test.exs
config :apical, egress_testing: true

When the flag is false — the default — nothing of the feature is compiled. No plug, no validators, and neither Apical.Plugs.Egress nor Apical.Exceptions.EgressError is even defined. Verified by building :dev and :prod and checking both modules are absent:

Egress:      false
EgressError: false

A nonconforming response raises Apical.Exceptions.EgressError, carrying a 500. The status is 5xx rather than 4xx deliberately: responses are checked at the end of request handling, after the operation has run and its side effects (database writes, for example) have already happened. A 4xx would tell the client their request was rejected and nothing occurred, which is not true — the fault is the server's, for emitting a response its own schema forbids.

Validation runs in a Plug.Conn.register_before_send/2 callback, which fires with conn.state == :set — after the controller builds the response but before any of it reaches the socket — so a failure cannot leave a half-sent response. Validators key on status code and content type, falling back to the default response object. Responses with no schema, and bodies that are not JSON, pass through. Works on both the Phoenix and Plug adapters.

Real output from the Plug-adapter test:

** (Apical.Exceptions.EgressError) Egress Error in operation plugEgressNonconforming
   (200 application/json): value `{"wrong":"field"}` at `/` fails schema criterion at
   `#/paths/~1nonconforming/get/responses/200/content/application~1json/schema/required/0`.
   required: "/count"

Documented in a new guides/Response Validation.md and in the Apical moduledoc.

Bugfix: malformed matrix parameters returned a 500

A matrix segment carrying more than one = (e.g. ;a=b=c) fell through a case with no catch-all and raised CaseClauseError. That carries no plug_status, so a malformed request surfaced as a 500 instead of a 400.

The split runs before the cond dispatches on type, so this affected all four matrix shapes — array, object, exploded object and primitive — not just objects. Now reported with the same wording the simple and label styles already use.

Dependencies

mix hex.audit reported 47 advisories; this clears 46 of them across 22 packages:

		advisories
plug	1.19.1 → 1.20.3	4 (2 HIGH)
phoenix	1.8.5 → 1.8.16	3 (2 HIGH)
bandit	1.10.4 → 1.13.1	11 (6 HIGH)
mint	1.7.1 → 1.11.0	14 (7 HIGH)
cowlib	2.16.0 → 2.21.0	7 (3 HIGH)
cowboy	2.14.2 → 2.20.0	3 (1 HIGH)
req	0.5.17 → 0.7.5	2 (1 HIGH)
exonerate	1.2.1 → 1.3.0	—

plus hpax, plug_crypto, plug_cowboy, jason, mox, yaml_elixir, ex_doc and transitives. No requirement in mix.exs needed to change — every update was already permitted.

plug is the only affected package Apical depends on at runtime, so it was the only one whose advisories reached consumers through this library.

mox and bypass are now only: :test

Both were optional: true but not only: :test. Those control different things — optional: true governs whether a consumer is forced to install a package; only: scopes which of our environments fetch it. With just the former, dev and prod builds compiled bypass and the entire cowboy stack it hard-depends on, including cowlib:

before (MIX_ENV=prod):
  apical bypass cowboy cowboy_telemetry cowlib exonerate jason json_ptr
  match_spec mime mox nimble_ownership nimble_parsec pegasus plug
  plug_cowboy plug_crypto ranch telemetry yamerl yaml_elixir

after:
  apical exonerate jason json_ptr match_spec mime nimble_parsec pegasus
  plug plug_crypto telemetry yamerl yaml_elixir

Safe because Mox and Bypass are referenced only inside quote blocks in Apical.Testing, so neither is resolved when this library compiles; the generated code needs them in the user's test env, which optional: true still expresses.

One advisory remains, unfixable

cowlib EEF-CVE-2026-43966 (MEDIUM, HTTP response splitting) — 2.21.0 is the latest published version, so there is nothing to upgrade to. It arrives via bypass → plug_cowboy → cowboy. Bypass is hard-wired to Cowboy (its mix.exs requires plug_cowboy unconditionally, it depends on ranch directly, and it has had no release since 2020-11-13 — upstream master still requires plug_cowboy), so the Cowboy stack is unavoidable while Bypass is a dependency. With Bypass now only: :test it reaches no dev or prod build.

TODO cleanup

All seven TODOs in lib/ are resolved; grep TODO lib/ is now empty.

• Three ("make this recursive" ×2, "refactor into a recursive call") described work already done or that would have made the code less idiomatic — the surrounding code already iterates correctly via Enum/Map.new. Removed. One was orphaned between two functions, attached to neither.
• request_body.ex: content_sources is read only by init/1, which resolves the single source matching that plug's own media type; call/2 never touches it. It was being embedded in full in every generated plug/2 call, once per media type per operation. Now narrowed to the entry each plug can use.
• query.ex: the "assess if this can be done without a catch" note is replaced with the reason the catch stays. parse_kv/3 throws when a custom style parser rejects a value, and its result is spliced straight into the parser accumulator ({key, parse_kv(...)}) — it has no error channel, so returning an error tuple would store that tuple as the parsed value. Threading a failure out would have to pass through every handle_query_part/5 clause, the exploded-array accumulator and the context map, to replace a non-local exit that is caught at the module boundary and never escapes.
• parameter_error.ex: the note was truncated mid-phrase ("improve this error by turning") and never recorded enough intent to act on. The current describe_exonerate/1 output is asserted verbatim by ~30 tests, so the format is unchanged.

Testing

484 tests, 0 failures (up from 468 — 13 new egress tests, 3 new matrix regression tests).

Both bugfix/feature commits were red-green verified:

• matrix fix — with the fix stashed, all three new tests fail with CaseClauseError (no case clause matching: ["object", "foo", "bar"])
• egress — with the test handlers changed to return conforming bodies, all four raise-expecting tests fail with Expected exception Apical.Exceptions.EgressError but nothing was raised

Clean under --warnings-as-errors and --check-formatted in :test, :dev and :prod; docs build; mix hex.build produces apical-1.0.0.tar.

Exonerate 1.3.0 emits warnings about an optional Decimal dependency we do not pull in. Those are confined to that package's own compilation and do not affect the project build CI runs (verified: touching lib/apical.ex and recompiling with --warnings-as-errors exits 0).

Also

• CHANGELOG sorted into consistent descending version order — the older entries ran 0.1.0, 0.2.0, 0.2.1, 0.3.0 ascending while newer ones descended, so the file read in two directions. Content unchanged (verified by sorted-line diff).
• mix.exs → 1.0.0; README install snippet → {:apical, "~> 1.0"}.
• data egress checking (conditional, compile-time) removed from the roadmap, as it now ships.

Not included

• Milestones 0.2 / 0.3 / 0.4 are still open on GitHub with zero open issues — bookkeeping to close out separately.
• mix hex.publish has not been run. The version is bumped but nothing is published.

🤖 Generated with Claude Code