Skip to content

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb/issues/136. This local document is retained as an engineering spec/evidence record.

CI-050 - REST surface semantic proof and adapter hardening follow-up

Summary

Track the non-blocking REST surface follow-ups found during the RC1 REST review. The current /api/v1 route table, OpenAPI contract, adapter route contracts, auth checks, parser hardening, native tests, and REST smoke evidence are aligned. The remaining work is to deepen semantic proof for object-backed operations and tighten qBittorrent-compatible session cookie handling without expanding the advertised controller surface.

Current Evidence

  • Native REST contract sync shows 90 OpenAPI routes and 90 registered native routes with no missing or duplicate operations.
  • Adapter contract sync shows 20 adapter routes: 19 qBit-compatible routes and one Torznab route.
  • REST smoke and native web API tests pass for route dispatch, authentication, schema validation, typed errors, malformed request handling, adapter drift, and REST stress.
  • The installed local suite accepted authenticated /api/v1/app and /api/v1/status probes, rejected missing and wrong API keys, and accepted qBit-compatible login with the configured API key.

Gaps To Close

Object-Backed REST Semantics

The route contract smoke currently proves every safe route is reachable and envelope-correct, but many transfer, upload, source, shared-file, and peer operations are exercised through expected safe error paths with placeholder objects. Add deterministic fixture coverage that proves successful behavior for representative object-backed routes.

The qBit-compatible login path issues an SID cookie used by Arr-style controllers. The cookie is currently enough for local trusted compatibility, but the adapter should be hardened before treating LAN browser exposure as a first class operating mode:

  • add SameSite=Strict where compatible with Arr clients
  • add Secure when the WebServer is serving HTTPS
  • document or implement session lifetime and rotation expectations
  • keep qBit-compatible controller behavior stable

Unsafe Diagnostic Endpoint Proof

Normal REST smoke intentionally skips shutdown, diagnostic dump, and diagnostic crash-test execution. Preserve the default skip behavior, but add or document a separate opt-in diagnostic proof profile when release evidence requires live success proof for those endpoints.

Scope Constraints

  • Do not add new REST resource families.
  • Do not broaden the qBittorrent-compatible or Torznab-compatible surface.
  • Do not weaken API-key auth, lifecycle gating, diagnostic opt-in, or typed error envelopes.
  • Do not make destructive or unsafe endpoint execution part of default smoke.

Acceptance Criteria

  • [ ] REST smoke or a companion fixture lane covers successful object-backed semantics for representative transfer, upload/source, shared-file, and peer operations.
  • [ ] Coverage reports distinguish contract/error-path proof from successful live-object semantic proof.
  • [ ] qBit-compatible SID cookies are scoped with SameSite=Strict where compatible and Secure when HTTPS is active.
  • [ ] qBit-compatible session lifetime and rotation behavior is either implemented or documented as an explicit local-controller contract.
  • [ ] Unsafe diagnostic endpoint live proof is available through an explicit opt-in profile, or the release docs state that parser/lifecycle gating is the supported proof level.
  • [ ] Native and Python tests keep OpenAPI/native route sync and adapter route sync green after the changes.

Validation

  • python -m pytest tests\python\test_rest_api_smoke.py -q
  • python -m emule_workspace test native --suite-name web_api --config Release --platform x64 --build-output-mode ErrorsOnly
  • Smallest relevant live REST smoke or fixture profile that exercises the new semantic-success coverage.