Websocket proposal (closed)

FHIRcast Websockets Specification

This page presents some initial discussions related to websocket support. Websockets are part of the current STU2 proposal. This page should be seen a history artifact to explain some of the discussion and not as an explanation of the current specification.

=====================================OLD=========================================================

Summary

This document proposes an addition to the current FHIRcast specification which will allow FHIRcast client applications (subscribers) to receive event notifications via a websocket connection, as opposed to a REST web service callback.

The proposed specification will adhere to the current FHIRcast specification in all cases, unless otherwise specified. All communication from client to server will conform to WebSub and FHIRcast REST API specifications. Only Hub notifications to the client will be over Websockets.

The client can be any application that will authenticate, subscribe to a topic, send context changes, and receive context changes via Websockets using the "FHIRcast Hub" as described in this proposal.

WebSocket JSON Format

The hub will send notifications to websocket clients in raw json format, conforming to FHIRcast specification. Because the communication is done over "WSS" as opposed to HTTPS, there are no HTTP headers present on the messages. The subscribing client only authenticates to the hub during RESTful creation of the subscription.

Subscribe as WebSocket

The FHIRcast WebSocket client will subscribe using the standard Subscribe REST method. It will:

1. Obtain a topic as part of the authentication process
2. Subscribe to the Hub using the standard REST method, including authenticating with the bearer token (if using OAuth 2.0). The client will specify "hub.channel.type" : "websocket". NOTE: hub.channel.endpoint is not specified since there is no callback with Websockets.
3. The Hub will return the websocket endpoint to be used by the client.
4. The client will connect to the endpoint provided in the previous step.

Unsubscribe as WebSocket

The FHIRCast WebSocket client will subscribe using the standard Subscribe REST method (See section above - Subscribe), but will specify "hub.mode":"unsubscribe". The client must also pass the websocket endpoint URL in hub.channel.endpoint. This endpoint was returned to the client by the hub in the Subscribe method.

---

Example Message Flows

Authentication

Client authenticates and receives the following data from the authentication server. **Authentication details are to be documented in subsequent HL7 /FHIRCast documentation. //TODO **

• topic : fba7b1e2-53e9-40aa-883a-2af57ab4e2c
• access token : i8hweunweunweofiwweoijewiwe
• base Hub URL (also called cast-hub) : https://hub.example.com

Subscription Sequence

1. Client subscribes via websocket

POST https://hub.example.com Host: hub.example.com
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Content-Type: application/x-www-form-urlencoded

hub.mode=subscribe&hub.topic=fba7b1e2-53e9-40aa-883a-2af57ab4e2c&hub.secret=shhh-this-is-a-secret
 &hub.events=patient-open,patient-close&hub.channel.type=websocket

2. Hub responds with websocket connection URL:

202 Accepted

wss://hub.example.com/ee30d3b9-1558-464f-a299-cbad6f8135de

3. Client connects using the URL received above

Websocket Notification Event

1. Hub sends notification event to client over established websocket

{
      "timestamp":"2019-02-08T10:40:05.14",
      "id":"ZzdStHqxFQyHFKuY",
      "event":{
         "hub.topic":" fba7b1e2-53e9-40aa-883a-2af57ab4e2c",
         "hub.event":"imagingstudy-open",
         "context":[
            {
               "key":"patient",
               "resource":{
                  "resourceType":"Patient",
                  "id":"ewUbXT9RWEbSj5wPEdgRaBw3",
                  "identifier":[
                     {
                        "system":"urn:MRN",
                        "value":"2667"
                     }
                  ]
               }
            },
            {
               "key":"study",
               "resource":{
                  "resourceType":"ImagingStudy",
                  "id":"8i7tbu6fby5ftfbku6fniuf",
                  "uid":"urn:oid:2.16.124.113543.6003.1154777499.30246.19789.3503430045",
                  "identifier":[
                     {
                        "system":"urn:accession",
                        "value":"185444"
                     }
                  ],
                  "patient":{
                     "reference":"Patient/ewUbXT9RWEbSj5wPEdgRaBw3"
                  }
               }
            }
         ]
      }
}

Client unsubscribes via rest

POST https://hub.example.com Host: hub.example.com
Authorization: Bearer i8hweunweunweofiwweoijewiwe
Content-Type: application/x-www-form-urlencoded

hub.mode=unsubscribe&hub.topic=fba7b1e2-53e9-40aa-883a-2af57ab4e2c&hub.secret=shhh-this-is-a-secret
 &hub.events=patient-open,patient-close&hub.channel.type=websocket
 &hub.channel.endpoint=wss%3A%2F%2Fhub.example.com%2F7jaa86kgdudewiaq0wtu_1A3DF21C14514DC58B593F824D3A7ED7

Alternatively, hub unsubscribes client over websockets

{
   "hub.mode": "unsubscribe",
   "hub.topic":" "fba7b1e2-53e9-40aa-883a-2af57ab4e2c",
   "hub.secret": "shhh-this-is-a-secret",
   "hub.events": "patient-open,patient-close"
   "hub.channel.type": "websocket",
   "hub.channel.endpoint": "wss://hub.example.com/ee30d3b9-1558-464f-a299-cbad6f8135de"
}

Outstanding questions

• Is intent verification needed?
• How should authentication work?
• Do we have enough implementation experience?