best-practices: Server-side robustness (deps, event loop, load_sibling)

[topkoa]

Summary

Second of four gap-closing PRs. Adds a "Server-side robustness" section for routes-shipping plugins — the server-side concerns that let one plugin stall the whole server or delay others. Ground-truthed against the loader.

Rules (34–37)

• 34 — Declare Python deps in requirements.txt, keep them light. There's no manifest field; the Host pip installs them to a persistent, hash-keyed location. Installs are sequential and slow — they delay later plugins (yours shows "installing…"), so keep them minimal and pinned. A failed install is non-fatal (the Host still tries your routes), so guard heavy/optional imports and degrade if missing.
• 35 — Don't block the event loop; keep setup() fast. setup() runs on the event-loop thread and is killed at a ~60s timeout — wire only, defer heavy work. A blocking async def handler freezes the whole server for every request; use non-blocking I/O or a plain def (the Host runs sync handlers in a threadpool).
• 36 — Split routes.py with context["load_sibling"], not bare imports. The Host puts each plugin dir on sys.path, so two plugins shipping a top-level util.py collide in sys.modules (first wins). load_sibling namespaces per plugin and enables relative imports; don't mix bare import and load_sibling for the same file.
• 37 — Log through context["log"], never print() (correlation + rotation); plus a route-namespacing reminder (silent + permanent collisions, rules 6/7).

Added a "Server-side robustness" checklist block; Shipping renumbered to 38–42 (contiguous 1–42).

Scope & stacking

Docs only. Stacked on #9. Full stack: … → #8 → #9 → #10 (two more coming: styling, diagnostics). mkdocs build --strict + check_versions.py pass.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6cc7e1d1-7bfe-4714-9ed9-05fc91e7b6f9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/best-practices-server-robustness

---

_{Comment @coderabbitai help to get the list of available commands.}