| name | torrent-client-handler-patterns |
| description | Implement and review torrent client API handlers consistently across this repository. Use when adding or fixing files in api_handlers, authentication flow, request formatting, or post-add operations like labels, categories, and directories. |
Torrent Client Handler Patterns
Handler Design Rules
Use these conventions for api_handlers/* changes:
- Keep auth/session flow explicit and isolated per server profile.
- Normalize error handling into readable, user-facing messages.
- Preserve compatibility with older client variants when supported.
- Avoid assuming content-type correctness for torrent files; handle fallbacks.
- Keep test-connection logic separate from add-torrent logic.
Implementation Checklist
- Confirm URL construction for base URL + relative path edge cases.
- Add required headers (for example origin/referer/basic auth) when applicable.
- Treat optional capabilities defensively (missing RPC methods, partial stats).
- Keep parsing strict and predictable for JSON/XML responses.
- Maintain backward compatibility for stored server config fields.
Regression Hotspots
- Multi-server session leakage.
- Client version specific endpoints.
- Label/category/tag not applied after add.
- Race conditions around "latest torrent hash" detection.
- Silent failures in connection tests.
Validation
- Build with
bun run build.
- Manually validate one happy path and one failure path for the edited client.
