Server Sent Events


  • There is a separate module for Server Sent Events called SSE and running as a standalone Grizzly Web Server. This server provides for two different sets of clients:
    • Clients subscribing to events
    • Clients that produce events to be broadcast.
  • The REST API provides for subscriptions for the first set of clients and POSTs to broadcast events for the second set of clients.
  • The YouTrack ticket SSE-6 is a good overview of the work to perform event consolidation:
  • To run the SSE server (on sagitta), see Running SSE Server. The ticket (SSE-4) worked out getting this running as a service (`systemd` sub-system on UNIX).

About SSE

  • Established once per session to open a single server-sent event channel that carries multiple message types. Subscribing clients should be prepared for any of the events once subscription begins, but there may be expected ordering to the events. It is up to the client to initialize its state properly by requesting state information which may impact the logic of responding to other events — particularly if a client is joining an Outing in progress, for example.
  • The channel itself has a heartbeat which is able to error out if the connection is broken. Heartbeat is a type of "event", but its function is to maintain the channel rather than provide application functionality such as Game State changes, Answer Summary changes, or Award Badge notifications.
  • Reporting on sessions for an outing begins with the establishment of these sessions.

Useful link:

Message Types

  • Single channel with different types of messages:
    • Tether — based on a given Outing, the Tether provides a series of LatLon events that tell clients the Guide's position.
    • Game Status — Tracks progress along a given Outing.
    • Puzzle Status — As Answer Summaries for a given Outing's current puzzle are broadcast, clients are given those events.
    • Award Badges — When a badge is awarded, the client is given an opportunity to handle the event and let the user know of the award.
  • SSE Supports Subscribers only for Mobile devices (Is this really just for mobile devices? I seem to be having success picking up the events using the browser.)
  • SSE supports broadcast requests only from Core server

Design Decisions

  • Create separate types of messages and listen for the separate events. (event: customType\n as an example)
  • The state can be represented as CONNECTING: Orange, OPEN: Green, CLOSED: Red.
  • Use a comment (:Keep Alive as an example) to hold the connection open. This is the true heartbeat — keep alive.

Remaining to be explored:

  • Check out the Server Load when multiple clients are subscribing
  • Sort out the Life-cycle of when the channels are brought up and shut down.
  • Reporting on the Server-side which connections are live (may be part of the API for reporting to the Team page).
  • Connectionless Push Notifications — how much of this is built-in already?

Tether (was Heartbeat)

This could be pushed with each position change and then if no new event after a configurable period (20 seconds?), the heartbeat will be sent to confirm connection.

Required Data

  • Event Type Heartbeat
  • GPS coordinates of Guide (tether)
  • Responding to the heartbeat goes back to Connection State on Core Server; absence means loss of connection

Considering the response from clients to confirm the connection is live for each member of the Team (and can be reflected there).

Game State

For a given Outing:

  • Confirming Team (Arrival at Start)
  • Ready to Roll
  • Arrival at next Attraction

Required Data

  • Event Type Game State
  • Outing ID
  • Event Data for Location Change
    • Departing or Arriving
    • When Departing, upcoming Location ID (this is when the next location is revealed)
    • When Arriving, the ID of the location we're arriving at.

Optional Data

  • Timestamp

Puzzle State

For the current puzzle on an outing (up to Core Server to know what this is for the outing)

Required Data

  • Event Type Puzzle State
  • Answer Summaries across team
    • Response total per Answer
    • Total responses


This is for the Game State, but the other two are similar.
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License