ms2k/remora
SHA256
Watch
0
Code Releases Activity

Define API and live update contract

Browse source
This commit is contained in:
ms2k 2026-07-13 14:59:50 +09:00
commit 8c0ec9627e
1 changed files with 954 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

9
docs/spec/architecture.md
View file

@ -150,6 +150,15 @@ flowchart TD
- Redirects are bounded to five by default. Every hop repeats URL, scheme/port, DNS, and address validation before dialing. HTTPS-to-HTTP downgrade is denied, and credentials and cookies are removed when the origin changes.
- Ambient proxy environment variables are ignored. An outbound proxy is disabled unless configured as a trusted enforcement boundary that provides the same hostname, resolution, address, redirect, and credential controls. Infrastructure egress policy remains defense in depth.
## API and Live Updates
- [`api/openapi.yaml`](api/openapi.yaml) is the normative HTTP contract and [`api/events.schema.json`](api/events.schema.json) is the normative WebSocket frame contract. Their compatibility and replay semantics are defined in [`api/README.md`](api/README.md).
- Every public mutation uses a caller- and operation-scoped idempotency key. The server atomically retains the canonical request fingerprint and original response for at least the advertised 24-hour default window; changed payload reuse is a conflict.
- Public job status projects the `JobProtocol` phase without redefining its transitions and separately exposes deletion lifecycle, current authoritative attempt, matching progress, validated checkpoint, committed result, and structured failure.
- Job listing applies current authorization before stable keyset pagination. Cursors are opaque, integrity-protected, and bound to the subject, filters, and membership snapshot.
- HTTP snapshots carry a live-event cursor. WebSocket replay is ordered and at least once; invalid, expired, authorization-incompatible, or unavailable history requires a new HTTP snapshot. Stale-attempt progress is suppressed before emission.
- Internal claim identifies the job, worker incarnation, and idempotent operation because no attempt exists yet. Renew, progress, and outcome additionally require the opaque attempt ID and fence defined by `JobProtocol`; stale authority has no effect.
## Requirements
### Functional Requirements