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_hierarchybehaves as under Design, with the tests listed there.- It is exported from
rn_forge.weband documented in the registry guide, with atype_baseand the import-order note. uv run pyrightanduv run lint-importspass.
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_registryis unchanged.
S17.1.3 — Log 5xx problems with their traceback
State: Closed (2026-10-31)
Acceptance:
rn_forge.fastapi.log_server_errorsexists and is passed toAppConfig.login a test application; a raising route produces one log record carrying the original traceback.AppConfig.logstill defaults toNone.- 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
CodedExceptionbase publishing acodeextension member. Withtype_baseset thetypealready carries the code, so the member repeats it, and the exception would hold a second code besideAppException.error_code. AppExceptionimplementsHasProblemExtensionsby default.HasProblemExtensionsstates thaterror_datais never published automatically because it routinely carries credentials and internal identifiers. Everyrn-forge-*package raisesAppException, 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 tworegistercalls; 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 toproblem_for_status.