Skip to content

F17.1 — Problem rows from an exception hierarchy

State Closed
Parent E17
Iteration Release 8
Start Date 2026-10-31
Closed Date 2026-10-31
Predecessors —
Source Owner request, 2026-10-21

Stories: 3 Closed

Story State Depends on
S17.1.1 — Register a hierarchy Closed (2026-10-31) —
S17.1.2 — Document keeping programming errors at 500 Closed (2026-10-31) —
S17.1.3 — Log 5xx problems with their traceback Closed (2026-10-31) —

Outcome: on 2026-10-31 ProblemRegistry.register_hierarchy, a guide recipe that keeps programming errors at 500, and log_server_errors shipped, replacing the per-class ProblemType list and 5xx log function an application such as Apollo wrote by hand. The rn-forge-web API conventions guide and the rn-forge-fastapi wiring guide (Logging server errors) document them.

Context

Entry criteria for adopting it: Apollo does not wait. Its rebuild writes problem_registry() and the log function itself on today's pins (rn-forge-fastapi 0.2.0, rn-forge-web 0.2.0, rn-forge-commons 0.5.0) and deletes them after this ships and its pins move.

The code travels as the problem type. RFC 9457 makes type the problem's machine-readable identifier, so register_hierarchy makes each class's code its slug and an application that sets type_base publishes the code with no extension member. Apollo's rebuild replaces its client's error.code envelope with problem+json, so the client matches on type from the start.

Design

register_hierarchy walks the base first, because problem_for resolves by MRO so registration order does not decide it, but problem_for_status returns the first registered row with a status and the base's row should be the answer for a bare status. The lookup recipe is a guide recipe, not an API, and default_registry() keeps LookupError at 404 because rn-forge-fastapi's soft-delete routes raise a bare LookupError for their 404s. AppConfig.log stays None by default; an application passes log=log_server_errors().

S17.1.1 — Register a hierarchy

State: Closed (2026-10-31)

Acceptance:

  • ProblemRegistry.register_hierarchy behaves as under Design, with the tests listed there.
  • It is exported from rn_forge.web and documented in the registry guide, with a type_base and the import-order note.
  • uv run pyright and uv run lint-imports pass.

S17.1.2 — Document keeping programming errors at 500

State: Closed (2026-10-31)

Acceptance:

  • The registry guide carries the recipe under Design and names the ValueError → 422 default it leaves alone.
  • A test proves the recipe's behaviour; default_registry is unchanged.

S17.1.3 — Log 5xx problems with their traceback

State: Closed (2026-10-31)

Acceptance:

  • rn_forge.fastapi.log_server_errors exists and is passed to AppConfig.log in a test application; a raising route produces one log record carrying the original traceback.
  • AppConfig.log still defaults to None.
  • The package site builds with --strict.

Acceptance

set -euo pipefail
uv run pytest -q packages/rn-forge-web/tests packages/rn-forge-fastapi/tests  # S17.1.1 S17.1.2 S17.1.3
uv run pyright && uv run lint-imports                                         # S17.1.1
(cd packages/rn-forge-web && uv run --group docs mkdocs build --strict)       # S17.1.1 S17.1.2
(cd packages/rn-forge-fastapi && uv run --group docs mkdocs build --strict)   # S17.1.3

Considered and rejected

  • A CodedException base publishing a code extension member. With type_base set the type already carries the code, so the member repeats it, and the exception would hold a second code beside AppException.error_code.
  • AppException implements HasProblemExtensions by default. HasProblemExtensions states that error_data is never published automatically because it routinely carries credentials and internal identifiers. Every rn-forge-* package raises AppException, so a default would put that data on the wire for all of them.
  • A default_registry(programming_errors_are_500=...) keyword. It stands in for two register calls; the recipe is enough.
  • Normalising _ to - in codes. The code is the slug as written; Apollo renames its codes to hyphens.
  • Registering classes in reverse, subclasses first. The MRO walk makes order irrelevant to problem_for; base-first order only matters to problem_for_status.