[eyevinn-developer]

Summary

Epic-workflow Phase 1 spec for #628: only offer, and only accept, the SRT directions the Strom instance supports. Docs only. The PR touches nothing outside docs/specs/ and docs/decisions/, and contains no implementation code.

Refs #628

• docs/specs/srt-direction-capabilities.md: API contract (server-info.srt, 422 refusal on create/PATCH, connect.warning), data model (no changes), Mermaid sequence diagram, config, dependencies (none new), open questions, risks, test cases.
• docs/decisions/ADR-014-strom-reported-srt-capabilities.md (Status: Proposed): Strom is the source of truth, there is one shared cached poller, and writes are refused only when Strom gives a definite answer.

Dependencies and sequencing

• Know whether locally bound ports are reachable (STROM_INBOUND_REACHABLE) and report capabilities strom#1257 (open, no PR): the Strom capabilities contract. The spec proposes a payload for GET /api/capabilities (inbound_reachable, ports, srt {listener, caller, relay}). The parser also accepts the same fields on GET /api/srt-relay if Strom picks that option. Until it ships, every Strom reads as unsupported and behaviour does not change.
• feat(srt): SRT relay addresses with a sticky id (srt+relay://) #629 (draft) and feat(studio): SRT "Via relay" and dial-in addresses from the backend open-live-studio#259 (draft): this design generalises feat(srt): SRT relay addresses with a sticky id (srt+relay://) #629's srt-relay-status.ts cache and extends its resolveSrtAddress() gate. It does not re-specify the relay.

Open questions (each with a proposed answer)

1. Capabilities source and shared poller. Proposed: ask Strom for GET /api/capabilities, and parse either option. One refresh of one generalised feat(srt): SRT relay addresses with a sticky id (srt+relay://) #629 cache fetches both endpoints.
2. server-info shape. Proposed: add srt: {listener, caller, relay, ports, state}. Keep srtPorts, srtPortState and srtRelay as they are.
3. Refusal code and body. Proposed: 422 {error, statusCode, code: "srt-direction-unsupported", direction}. feat(srt): SRT relay addresses with a sticky id (srt+relay://) #629's relay 422 adopts the same code and direction.
4. Positively unsupported versus unknown. Proposed: refuse only when the capabilities state is ok and the direction is reported false. When the state is unreachable or unknown, accept and set connect.warning: "srt-capabilities-unknown".
5. "connect reason" when uri resolves. Proposed: a new optional connect.warning. reason stays null-uri-only.
6. PATCH semantics. Proposed: refuse only a PATCH that changes the direction into an unsupported one.
7. Existing records. Proposed: they are still listed and still activate, the flow generator is untouched, and connect.warning explains the problem.
8. Older Strom. Proposed: a 404 on capabilities, with no capability fields on srt-relay, gives state: "unsupported", and everything is offered.
9. Listener port outside STROM_PORTS. Proposed: warn, not refuse. Where the legacy reservation is active, its existing 422 stands.
10. Relay source of truth when both endpoints report it. Proposed: /api/srt-relay is authoritative, and a disagreement is logged.
11. Sequencing with feat(srt): SRT relay addresses with a sticky id (srt+relay://) #629. Proposed: implementation starts after feat(srt): SRT relay addresses with a sticky id (srt+relay://) #629 merges, or rebases onto it.
12. Rendezvous mode. Proposed: not gated and not offered, the same as today.

Test Plan

• Docs only. No code, tests or CI behaviour change
• Every referenced file and endpoint was checked on main or on the named PR branch

Checklist

• Spec has an API contract, data model, Mermaid sequence diagram, config, and open questions
• ADR follows the epic-workflow template, Status: Proposed
• No new external dependency
• No hardcoded SRT ports in the design (ports come from Strom or the existing allocator)

What a human does next

Nothing. team-lead reviews the spec and ADR against the Phase 1 gate. The Strom contract is proposed upstream on Eyevinn/strom#1257.

🤖 Generated with Claude Code

[eyevinn-pr-reviewer]

Phase 1.5 spec gate (team-lead): approve

I checked the spec (docs/specs/srt-direction-capabilities.md) and ADR-014 against #628, open-live main (src/routes/status.ts, src/lib/srt-connect.ts, src/services/listener-ports.ts, docs/openapi.yaml), draft #629, strom#1257 and strom#1258. The design is sound and covers every point in #628.

Checklist

• API contract: server-info.srt, the 422 on POST/PATCH sources and outputs, and connect.warning
• Data model: no changes, nothing persisted, no migration (explained)
• Mermaid sequence diagram
• Config: no new Open Live env vars. Strom env vars are mapped to their effect. No Strom pipeline JSON change
• Open questions: 12 listed, each with a proposed answer. All resolved below
• ADR follows the template, and 014 is the next free number
• Only docs/specs/** and docs/decisions/** are touched

Resolutions (team decisions)

1. Capabilities source and poller. Accepted. One generalised #629 cache fetches /api/srt-relay and /api/capabilities in the same refresh. If either half fails, the shared entry uses the 5 s error TTL, and each half keeps its own last-known value. The §3.1 payload still needs to be posted on strom#1257.
2. server-info shape. Accepted. srt {listener, caller, relay, ports, state} is added. srtPorts, srtPortState and srtRelay stay exactly as they are.
3. Refusal. Accepted. 422 with {error, statusCode, code: "srt-direction-unsupported", direction}, following the existing 422s. This is the first route to add code, which is fine because it only adds fields. #629's relay 422 adopts the same code. Document it in openapi on all four routes.
4. Unsupported versus unknown. Accepted. Refuse only when the state is ok and listener is false. unreachable and unknown accept and set srt-capabilities-unknown. Older Strom accepts with no warning.
5. connect.warning. Accepted. reason stays null-uri-only. warning does not depend on uri and can appear next to a reason.
6. PATCH. Accepted. Refuse only a PATCH that changes the direction to an unsupported one. The gate runs before the port checks, so a refused srt://:0 never takes a port.
7. Existing records. Accepted. Still listed, still activate, flow generator untouched, explained by connect.warning.
8. Older Strom. Accepted, and it is safe. A 404 gives unsupported (today's behaviour). Other failures give unreachable, which never refuses. Parsing fails open.
9. Port outside STROM_PORTS. Accepted. Warn, do not refuse. The legacy reservation's 422 still applies while it is active.
10. Relay source of truth. Accepted. /api/srt-relay is authoritative, and a disagreement is logged at warn.
11. Sequencing. Implementation starts only after #629 is merged to main. Do not stack it on the draft branch. Studio work follows open-live-studio#259 and starts after the backend is on staging.
12. Rendezvous. Accepted. Not gated and not offered.
13. srtDirection. Accepted as written. mode=listener with a host counts as a listener. Hostless mode=caller maps to null. Each case gets a unit test.
14. ADR status. Flip ADR-014 from Proposed to Accepted in the first implementation PR.

No human decision needed.