Streaming Service

Repository: RoamView-Technologies/roamview-streaming-service

The Streaming Service is the low-latency video relay of a Live Walkthrough. It receives the robot's encoded video from the IoT Gateway and forwards it, without decoding or transcoding, towards the viewer through the API Gateway (WebRTC-style delivery; HLS/DASH excluded). It is also the hop that passes live control commands on to the IoT Gateway on the path App → API Gateway → Streaming Service → IoT Gateway (SP-4.1.1). It runs on the always-on App server next to the API Gateway, IoT Gateway and Ingestion Service (see the Deployment Diagram).

Related use cases: UC-GU01 Live Walkthrough, UC-GU07 Send Video Stream. Related specs: SP-4.1.1 (command latency), SP-4.1.6 (IoT Gateway video relay), SP-4.1.7 (Streaming Service relay capacity, ≤ 50 ms), SP-4.1.8 (API Gateway relay) in the Software Requirement Specification.

flowchart TB
    subgraph STR["«module» roamview-streaming-service"]
        direction TB
        MAIN["«package» cmd/streaming-service<br/>main: load config, create session registry,<br/>start server, graceful shutdown on SIGTERM"]

        subgraph INT["«package» internal"]
            direction TB
            SRV["«package» server<br/>NewRouter() · New()<br/>route table, http.Server timeouts"]
            HND["«package» handlers<br/>Health · Ready · Version · Sessions<br/>NotImplemented · WriteJSON"]
            SES["«package» session<br/>Registry: Start · Get ·<br/>List · End"]
            MW["«package» middleware<br/>RequestID · Logging · Recover · Chain"]
            CFG["«package» config<br/>Load() from env vars"]
            VER["«package» version<br/>Version · Commit (ldflags)"]
        end
    end

    STD["«library» Go standard library<br/>net/http · log/slog · sync · crypto/rand"]

    MAIN -->|«import»| CFG
    MAIN -->|«import»| SRV
    MAIN -->|«import»| SES
    MAIN -->|«import»| VER
    SRV -->|«import»| CFG
    SRV -->|«import»| HND
    SRV -->|«import»| MW
    SRV -->|«import»| SES
    HND -->|«import»| SES
    HND -->|«import»| VER
    INT -.->|«use»| STD
    MAIN -.->|«use»| STD

Loading

Packages

Package	Responsibility	Depends on
cmd/streaming-service	Entry point. Loads config, creates the session registry, builds the server, handles SIGINT/SIGTERM and shuts down gracefully	config, server, session, version
internal/server	Owns the route table and wraps it in middleware. Sets HTTP server timeouts (no write timeout, because video ingest and viewer signaling are long-lived)	config, handlers, middleware, session
internal/handlers	Endpoints the service answers itself: /healthz, /readyz, /version, the live-session endpoints, and 501 placeholders for routes still to be built	session, version
internal/session	Thread-safe, in-memory registry of live sessions (session ID, robot ID, start time). One live session per robot (single robot, single viewer, SP-4.1.7). Does not depend on the video transport	—
internal/middleware	Cross-cutting concerns applied to every request: request ID (X-Request-ID), structured logging, panic recovery	—
internal/config	Reads PORT (default 8082), APP_ENV, SHUTDOWN_TIMEOUT and IOT_GATEWAY_URL from the environment	—
internal/version	Build version and commit, injected at link time	—

Dependencies only point downward: cmd → server → handlers → leaf packages. Leaf packages (session, middleware, config, version) import nothing from this module, so each can be tested on its own. Everything under internal/ cannot be imported by other modules.

Interfaces

Exposes

The API Gateway forwards /api/v1/streaming/* here and strips that prefix, so a client calling /api/v1/streaming/sessions reaches /sessions.

Route	Caller	Status
GET /healthz, GET /readyz, GET /version	Orchestrator / ops	Implemented
POST /sessions	API Gateway (/api/v1/streaming/*)	Implemented: starts a live session for {"robotId": "..."}; 409 if the robot is already streaming
GET /sessions	API Gateway	Implemented: lists live sessions
GET /sessions/{sessionID}	API Gateway	Implemented: 404 if the session does not exist
DELETE /sessions/{sessionID}	API Gateway	Implemented: ends the session
GET /sessions/{sessionID}/signal	App (through the API Gateway)	501: viewer signaling for low-latency video (UC-GU01, SP-4.1.7)
POST /sessions/{sessionID}/commands	App (through the API Gateway)	501: live control (UC-GU01, SP-4.1.1)
GET /ingest/{robotID}	IoT Gateway	501: robot video in (UC-GU07, SP-4.1.6); transport depends on the robot protocol decision

Calls

Target	Why	Status
IoT Gateway POST /robots/{robotID}/commands	Forwards live control commands on a priority channel, separate from video (SP-4.1.1), set by IOT_GATEWAY_URL	Planned
Viewer (App, through the API Gateway)	Low-latency video out (SP-4.1.7, SP-4.1.8)	Planned

An incoming X-Request-ID header is kept, so a request can be traced across services.

Planned packages (later tasks)

Package	Purpose	Related use cases / specs
internal/ingest	Accepts the robot's encoded H.264 video from the IoT Gateway and hands it to the relay, ≤ 2 frames buffered	UC-GU07, SP-4.1.6, SP-4.1.7
internal/relay	Repackages the video for the viewer with WebRTC-style low latency; no decode or transcode	UC-GU01, SP-4.1.7
internal/signaling	Viewer connection setup (offer/answer and network candidates) for /sessions/{id}/signal	UC-GU01, SP-4.1.7
internal/commands	Client for the IoT Gateway: forwards control commands on a priority channel, separate from video	UC-GU01, SP-4.1.1

These will likely need outside Go libraries (for example a WebRTC library and a WebSocket library). None are added yet; the team decides before they are.

Running it

See the repo README for run steps, configuration and CI.