some updates for dev documentation

Merged
AJ
3mo ago
+92-0

trying to distill the changes from #10052 into something more repeatable

truly not sure if some of this might be better as dev/guides/backend/creating-new-components.md


Summary by cubic

Improves backend dev docs on constructor-first wiring, interfaces/protocols, configuration invariants, and testing doubles. Extends the API backpressure example to show named-event observers, a single _notify, and how protocols keep third‑party deps out of core logic.

  • Documentation
    • Wiring: no late registration; pass deps to __init__ (0+ as required list[...]); build near entry points; factories resolve settings and accept adapters; configure at construction; process‑global registries build lazily in their own module.
    • Interfaces/Protocols: choose implicit Protocol or explicit interface module (prefer explicit); never put an ABC in the consumer; name methods in the consumer’s vocabulary; adapters live in their own module; only the wiring imports both; verify no third‑party imports under logic.
    • Configuration: tightly bound numeric fields with allow_inf_nan=False; enforce cross‑field rules with @model_validator and clear, greppable messages; test the validator and shipped defaults; use enums for values that leave the process and pass enum members.
    • Testing: two doubles for collaborators — a recording double for exact call sequences/values, and a failing double to prove failure containment; keep helpers shared and prefer adapters over patching.
    • API backpressure example: events are named methods; one _notify fans out with per‑observer failure containment; collaborators arrive via the constructor; wiring in server.py chooses sinks so api/admission stays decoupled behind Protocols.