Skip to content

REST and legacy WebServer error-path coverage gate

Summary

Add an Beta 0.7.3 release gate that proves every release-relevant REST and legacy WebServer error branch through live or seam-backed fault injection.

The current suite validates many status mappings and malformed requests, but Beta 0.7.3 needs explicit coverage that distinguishes clean 4xx/5xx behavior from silent hangs, swallowed exceptions, truncated responses, or worker-thread leaks.

Risk Being Covered

  • 404, 405, 409, 500, and 503 branches drifting without live evidence
  • static-file and template failures being covered only by happy-path resources
  • runtime REST dispatch failures returning unstable envelopes
  • connection resets during error responses leaking queued send state
  • broad stress loops treating unexpected failures as expected negatives

Execution Plan

  1. Build a route/error matrix covering native /api/v1, qBit-compatible /api/v2, Torznab, and legacy HTML/static-file paths.
  2. Mark each row with its expected status, envelope expectation, payload expectation, and whether the test is native-seam, live HTTP, live HTTPS, or fault-injection only.
  3. Add missing live probes for unknown route, missing resource, unsupported method, invalid-state operation, missing auth, wrong auth, bad content type, malformed JSON, malformed query, oversized body, missing static file, and unavailable template/resource paths.
  4. Add targeted fault-injection seams for release-relevant 500 paths that cannot be triggered safely from black-box live traffic, including REST command dispatch failure, serialization/runtime failure, static-file read/allocation failure, and template/resource load failure.
  5. Add connection-reset probes during representative 4xx and 5xx responses to verify queued-send cleanup.
  6. Fail the report when an undeclared 4xx/5xx appears in contract coverage or when an expected error lacks the stable JSON envelope where the native REST contract requires it.

Acceptance Criteria

  • [x] live REST reports emit an explicit release error-path matrix artifact
  • [x] every release-relevant 400, 401/403, 404, 405, 409, 500, and 503 status has an explicit live or seam-backed matrix row
  • [x] native REST errors use the stable typed JSON envelope where required
  • [x] legacy HTML/static-file errors are deterministic and do not escape the web root or allocate unbounded content
  • [x] fault-injected 500 paths clean up request state and return deterministic failures
  • [x] reset-during-error-response cases do not leak queued send state
  • [x] the route/error matrix is emitted as a release artifact

Progress Evidence

  • Test harness commit: 36a612a.
  • Test harness commit: f12b49d.
  • Test harness commit: 69b8afa.
  • Added rest_error_path_matrix to live REST reports.
  • The matrix summarizes observed 4xx/5xx status counts, covered release statuses, missing release statuses, and sampled error responses.
  • Added explicit seam-backed 500 and 503 release rows tied to existing web_api.tests.cpp coverage for EMULE_ERROR and EMULE_UNAVAILABLE envelopes.
  • Added explicit seam-backed 405 and 409 release rows tied to existing web_api.tests.cpp coverage for METHOD_NOT_ALLOWED route rejection and INVALID_STATE runtime envelopes.
  • The matrix now distinguishes missing_release_statuses, live_missing_release_statuses, and seam_backed_release_statuses so live gaps stay visible even when seam-backed coverage exists.
  • HTTP contract artifact: repos\emulebb-build-tests\reports\rest-api-smoke\20260508-120738-eMule-main-release\result.json. The run passed with all release statuses covered by live or seam-backed rows, missing_release_statuses=[], and live gaps preserved for 405, 409, 500, and 503.
  • Test harness commit 704a97b promoted the route/error matrix from report-only evidence to a hard release gate and added the reset_during_error_response_send raw socket probe.
  • The Beta 0.7.3 release decision for 405, 409, 500, and 503 is seam-backed coverage: those rows remain visible in live_missing_release_statuses but are covered through deterministic native test seams, because live black-box generation of those internal failures would require unsafe product-only fault injection.
  • HTTPS 64-client contract-stress artifact: repos\emulebb-build-tests\reports\rest-api-smoke\20260508-202554-eMule-main-release\result.json. The run passed the hard matrix with ok=true, covered_release_statuses=[400,401,404,405,409,500,503], missing_release_statuses=[], live_missing_release_statuses=[405,409,500,503], and seam_backed_release_statuses=[405,409,500,503].
  • HTTP 64-client raw socket adversity artifact: repos\emulebb-build-tests\reports\rest-api-smoke\20260508-203041-eMule-main-release\result.json. The run passed the hard matrix with ok=true, covered_release_statuses=[400,401,404,405,409,500,503], missing_release_statuses=[], and reset-during-error-response socket cleanup coverage.
  • App hardening commit 2263e64 replaced REST UI dispatch stack ownership with a heap-owned completion context, bounded wait, timeout error, and abandoned late-message guard.
  • App hardening commit 4082be7 rejects malformed legacy Web remote-add hash strings before they can feed uninitialized bytes into search-result download lookup.
  • App hardening commit d1c8af6 bounds legacy Web column-menu indexes for server, transfer, queue, shared, and search pages before writing the fixed WS*ColumnHidden arrays.
  • App hardening commit 1ca8c63 validates legacy Web search-result hashes before using them for download/shared/known-file lookups.
  • App hardening commit 979ae8f rejects negative legacy Web preference values before unsigned setter conversion can turn them into oversized limits.
  • App hardening commit ddff25f caps legacy Web shared-file download reads to the remaining advertised content length, preventing over-send and byte-counter underflow if the disk file is larger than the known-file metadata.
  • App hardening commit c6927cb releases REST API search parameters on the dialog-exception failed-start path.
  • App hardening commit c062058 scopes REST ED2K link ownership so MFC or unexpected exceptions during transfer-add do not leak parsed link objects.
  • App hardening commit 440e5e5 resolves legacy Web clear-completed hashes through the download queue instead of casting arbitrary known files to CPartFile.
  • App hardening commit 5f0689f scopes the legacy Web shared-file send buffer so file read/send exceptions do not leak the temporary transfer buffer.
  • Validation:
  • python -m pytest tests\python\test_rest_api_smoke.py -q
  • python scripts\rest-api-smoke.py --help
  • python -m emule_workspace build app --config Release --platform x64
  • git -C repos\emulebb-build-tests diff --check
  • python -m emule_workspace validate

Pending Release Evidence

  • None.

Relationship To Other Items