Skip to content

REST and WebServer typed error consistency

Summary

Make REST failure responses consistent across the WebServer JSON surface.

Beta 0.7.3 Classification

Release Gate. This must land before broad REST completeness and live E2E gates are meaningful, because callers need one stable failure contract for route, auth, parse, validation, missing-object, invalid-state, and internal operation failures.

The current contract uses:

{
  "error": "ERROR_CODE",
  "message": "human-readable description"
}

The release target allows an optional details object, but every failure must remain JSON and machine-readable.

Execution Plan

Historical release context: Beta 0.7.3 REST and Arr execution plan.

Acceptance Criteria

  • [x] route, auth, parse, validation, missing-object, invalid-state, and internal-operation failures use one envelope
  • [x] HTTP status mapping is stable and covered by tests
  • [x] optional details data is structured, bounded, and never required by clients for the primary error decision
  • [x] legacy HTML WebServer failures remain HTML/text where appropriate and do not adopt REST auth behavior

Completion Evidence

  • App commits: fcedfe3, c8e6609, 1e2ff57, 69d9262, 3c63552.
  • Test commits: 28f17db, 83093a6, c10f2a8, 8e67131, b7406d9, 957c31a, 51f8b6b, a3f3d56, 4c2240e, bc0ca24.
  • Tooling commits: 95fc6e9, a5d3d38.
  • Commands: python -m emule_workspace validate; python -m emule_workspace build tests --config Debug --platform x64; python -m emule_workspace test all --config Debug --platform x64; python -m pytest tests\python\test_rest_api_smoke.py -q.
  • Artifacts: workspaces\v0.72a\state\build-logs\20260506-175920; repos\emulebb-build-tests\reports\native-coverage\20260506-175927-eMulebb-workspace-v0.72a-eMule-main-x64-Debug.
  • Native tests passed 481/481 cases and 2679/2679 assertions; REST smoke unit output passed 25/25 tests.
  • Follow-up Beta 0.7.3 hardening: native PATCH /api/v1/shared-directories now requires confirmReplaceRoots: true before replacing the shared-root list, aligning directory replacement with the explicit confirmation rule used for transfer deletes, clear-completed, app shutdown, and delete-all searches.
  • Debug validation after the shared-directory confirmation hardening: python -m emule_workspace build tests --config Debug --platform x64; python -m emule_workspace build app --config Debug --platform x64 --variant main; python -m emule_workspace validate --config Debug --platform x64 --variant main; Python unit suite 160/160.
  • Live artifacts after the hardening: repos\emulebb-build-tests\reports\rest-api-smoke\20260507-212715-eMule-main-debug and repos\emulebb-build-tests\reports\shared-directories-rest\20260507-213150-eMule-main-debug. The REST run covered all 82 OpenAPI routes, exercised 81 safe routes with 0 failed routes, and completed 348 mixed stress requests with 0 failures, 0 timeouts, and 0 non-JSON native REST responses. The shared-directories run reached completed, covered 28 checks, and retained the long Unicode path proof at 325 characters.

Relationship To Other Items

  • gates CI-014 and CI-015
  • should be completed before broadening the REST surface further