Skip to main content

Subscriptions

SVRunner supports GraphQL subscriptions over WebSocket for some realtime updates. This can be useful for dashboards, monitors, and integrations that need live state instead of periodic polling.

Endpoint​

Subscriptions use the GraphQL WebSocket path:

ws://<host>:<port>/graphql

When the deployment is served over HTTPS, use the secure websocket form:

wss://<host>:<port>/graphql

What Subscriptions Are Good For​

Subscriptions are most useful when you need to react to state changes such as:

  • logs being created
  • systems updating
  • targets updating
  • Quick Play updates
  • resource-specific change notifications

The exact subscription surface depends on the schema for your deployed version.

Examples In The Current Product​

Current code paths show subscription usage for:

  • logCreated
  • quickPlayUpdated
  • targetUpdated
  • systemUpdated

These are good reference points for building your own realtime consumers.

Example Subscription​

subscription OnLogCreated($input: LogCreatedInput!) {
  logCreated(input: $input) {
    id
    assetId
    screenId
    playerId
    time
    duration
  }
}

Authentication Caveat​

HTTP auth behavior is clear in the codebase. Subscription auth is less clear.

Current observations:

  • the client WebSocket link does not obviously send connectionParams
  • the server onConnect path creates a context without a request object
  • the HTTP auth path depends on request.headers.authorization

That means you should not assume websocket subscriptions inherit authenticated behavior the same way HTTP requests do.

If your integration depends on authenticated subscriptions:

  1. validate it directly in your environment
  2. test with the exact deployment topology you will use in production
  3. fall back to polling if the auth story is not sufficient

When Polling Is Still Appropriate​

Polling may still be a better choice when:

  • the data changes slowly
  • you need deterministic auth behavior quickly
  • you only need periodic snapshots
  • your deployment environment makes websocket behavior hard to validate

API Subscription Client Stub screenshot: websocket client view showing a live subscription result. Save final image at packages/docs/screenshots/api-subscription-client.png.

The current UI itself still uses polling in some places, such as dashboard action updates.

Practical Guidance​

  • use subscriptions when the data stream is clearly event-driven
  • use polling when auth, network policy, or reliability matters more than immediacy
  • treat subscriptions as an enhancement, not a default requirement, unless you have validated them thoroughly