FHIR Chat · fhircast-docs / Issue #253 Proposal for Websocket specifi... · fhircast-github

Stream: fhircast-github

Topic: fhircast-docs / Issue #253 Proposal for Websocket specifi...

---

Github Notifications (FHIRcast) (May 29 2019 at 13:32):

gkustas opened Issue #253:

Please see and comment on this proposal. It is a Confluence documented exported to PDF. Please let me know if there is a better way to do this.

PO-FHIRCastWebsocketsSpecification-290519-0927-40.pdf

This proposal uses direct Websocket communication with a JSON payload (formatted with header and body elements).
I made some assumptions and recommendations that should probably be changed - this is my first attempt at this sort of a thing (international standard).

Github Notifications (FHIRcast) (Jun 09 2019 at 21:29):

gkustas commented on Issue #253:

I've added several updates, probably too many to enumerate. Mostly minor changes t the websocket message format, but more importantly use intent verification and use of the hub.channel.endpoint field for unsubscribing. This field will be the Websocket URL returned by the hub when the websocket client subscribes.

PO-FHIRCastWebsocketsSpecification-090619-1726-188.pdf

Github Notifications (FHIRcast) (Jun 18 2019 at 16:25):

isaacvetter commented on Issue #253:

Hey @gkustas ,

Apologies for the delayed response. Keeping Intent Verification seems important to enable the hub to confirm the subscription details to the client.

A few questions:

1) body element?
2) Intent verification response should include the hub.challenge.
3) How should a client "nack" a websocket intent verification? In your proposal, the client responds
4) Should there be a websocket response from the client in the event notification ?
5) Should the request context change and unsubscribe also happen over wss?

Isaac

Github Notifications (FHIRcast) (Jun 18 2019 at 16:29):

isaacvetter edited a comment on Issue #253:

Hey @gkustas ,

Apologies for the delayed response. Keeping Intent Verification seems important to enable the hub to confirm the subscription details to the client.

A few questions:

1) Does the body element accomplish anything beyond mirroring the HTTP model (and the headers element in the "response")?
2) Intent verification response should include the hub.challenge. Right?
3) How should a client "nack" a websocket intent verification? In your proposal, the client responds with an HTTP status, even though there's no HTTP. Is there a better way to do this?
4) Should there be a websocket response from the client in the event notification ?
5) Should the request context change and unsubscribe also happen over wss?

Isaac

Github Notifications (FHIRcast) (Jun 18 2019 at 17:45):

gkustas commented on Issue #253:

Hi Isaac, thanks for getting back to me. First... Are you using the second
version of my spec posted? Attaching it here to make sure.

1. The intent of having a "headers" element and a "body" element is to
create a model that somewhat resembles an HTTP response/request. I don't
know just how much we'll need it, but it seems to make sense in case of
message acknowledgements (Acks/Nacks).

2. Yes, I guess it should, although to be honest, I'm not even sure the
intent verification is necessary at all. I like the fact that we're
following the standard rest specification, but it is even possible for a
rogue application to sneak into a web socket connection? If so, then of
course we need the intent and the challenge. I'll just add it in for now.

3. Depending on the error, probably something like this:
{
"headers": {
"status": "INVALID",
"statusCode": "400"
}
}
4. Yes, I neglected to put that into the spec, after the notification event
code, but ALL messages over the socket require acknowledgement . See Json
Format section: "All websocket clients MUST respond with an acknowledgement
response. The Header will contain a status and status code. A body section
is provided here, but there is not response data currently needed."
5. No, personally I think the client should use the REST API for everything
not requiring a callback endpoint. This will be more consistent and require
less implementation on the hub side as well.

On Tue, Jun 18, 2019 at 12:25 PM Isaac Vetter <notifications@github.com>
wrote:

Hey @gkustas <https://github.com/gkustas> ,

Apologies for the delayed response. Keeping Intent Verification seems
important to enable the hub to confirm the subscription details to the
client.

A few questions:

1. body element?
2. Intent verification response should include the hub.challenge.
3. How should a client "nack" a websocket intent verification? In your
proposal, the client responds
4. Should there be a websocket response from the client in the event
notification ?
5. Should the request context change and unsubscribe also happen over
wss?

Isaac

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<https://github.com/HL7/fhircast-docs/issues/253?email_source=notifications&email_token=ABODZ3TC5VQQY4TNHCK6RLDP3ED67A5CNFSM4HQM2N52YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODX7GDIY#issuecomment-503210403>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ABODZ3U5FBE4ISF3GXNUBQLP3ED67ANCNFSM4HQM2N5Q>
.

--
George Kustas

Github Notifications (FHIRcast) (Jun 18 2019 at 18:07):

gkustas commented on Issue #253:

EDIT: I responded via email which truncated a lot of your post @isaacvetter . Please see additional comments:

#1. Yes - I basically answered you with your question :-). It was cut off after "the body element..."
#3. So, yes, maybe there is a better way. How is the intent verification rejected via Rest? Isn't that callback done using HTTP? Maybe I'm not understanding...

Github Notifications (FHIRcast) (Jun 18 2019 at 18:35):

isaacvetter commented on Issue #253:

Hey @gkustas - I moved your content from the pdf into this wiki page: https://github.com/HL7/fhircast-docs/wiki/Websocket-proposal to provide additional transparency and edit history.

(3) REST FHIRcast says that the client should respond with an HTTP 404 to reject a subscription. I'm just trying to get my head around the modeling of HTTP in websockets.

(4)

Should there be a websocket response from the client in the event notification ?
Errr, sorry about that, I'd scanned your design too quickly. I clarified that in the wiki.

(5)

Should the request context change and unsubscribe also happen over wss?
5. No, personally I think the client should use the REST API for everything
not requiring a callback endpoint. This will be more consistent and require
less implementation on the hub side as well.

Okay, we'll need to justify this.

Github Notifications (FHIRcast) (Jun 18 2019 at 21:22):

gkustas commented on Issue #253:

Great! Thanks Isaac. I'll use the wiki for future updates.

Regarding the HTTP modelling of the web socket messages... I'm not married to the idea. It was a suggestion from Martin quite some time ago and it sounded like a good idea. I still think so, but perhaps there is a different model more appropriate for our limited use of web sockets. I'm open to suggestions.

There are only three messages sent over a web socket in the proposed spec:
1. intent verification
2. event notification
3. client->hub ack/nack
I can't think of any headers that we'd ever need for intent verification, and likewise for event notification, since authentication isn't needed once the websocket has been connected.
The client ack/nack messages use ONLY the header, in order to mimic HTTP response headers.

We could simplify things by creating a model for client response to something like:

{
"status": "NOTFOUND",
"statusCode": "404"
}

Likewise, remove the "body" element from the event notification and intent verification messages.

Github Notifications (FHIRcast) (Jun 19 2019 at 08:54):

gedw99 commented on Issue #253:

What about Catchup scenarios ?

I should explain my scenario.

If the Client has a VIew Model (Resource Collection) and its changed on the Server, you want the Client to be able to request updates when it starts up, then you want to have an orderable sequence ID.
This is useful when many clients are hitting the same log endpoint that holds the immutable CUD ( create, update, deletes)events for that collection. The client knows what Sequence ID it is at, and so can just say give me a stream of all CUD event from this sequence forward in time.

As far as i can see the proposal is generalised enough to enable this, but i wanted to raie this for discussion and to check my assertions. Also others maybe using Events in this way too.

Github Notifications (FHIRcast) (Jun 19 2019 at 12:37):

gkustas commented on Issue #253:

Thanks @gedw99 . I'm not sure if we will have the scenario you mention, but I agree that sequencing is needed. This is why the timestamp (along with a unique id) are sent with the event. Should events be received out of sequence, the client will be able to decide what to do with the "old" event. In the scenario where the old event becomes obsolete (like a simple context change (open study, close study), the client may simply choose to ignore it. Later, as we introduce structured data (like measurements), sequencing may not be important and the event can be processed.

Please feel free to point out scenarios where this won't work. It's certainly not too late to change the spec.

Github Notifications (FHIRcast) (Jun 19 2019 at 12:38):

gkustas edited a comment on Issue #253:

Thanks @gedw99 . I'm not sure if we will have the scenario you mention, but I agree that sequencing is needed. This is why the timestamp (along with a unique id) are sent with the event. Should events be received out of sequence, the client will be able to decide what to do with the "old" event. In the scenario where the old event becomes obsolete, like a simple context change (open study, close study), the client may simply choose to ignore it. Later, as we introduce structured data (like measurements), sequencing may not be important and the event can be processed.

Please feel free to point out scenarios where this won't work. It's certainly not too late to change the spec.

Github Notifications (FHIRcast) (Jun 19 2019 at 18:00):

bvdh commented on Issue #253:

Great! Thanks Isaac. I'll use the wiki for future updates.

Regarding the HTTP modelling of the web socket messages... I'm not married to the idea. It was a suggestion from Martin quite some time ago and it sounded like a good idea. I still think so, but perhaps there is a different model more appropriate for our limited use of web sockets. I'm open to suggestions.

There are only three messages sent over a web socket in the proposed spec:

1. intent verification
2. event notification
3. client->hub ack/nack

I can't think of any headers that we'd ever need for intent verification, and likewise for event notification, since authentication isn't needed once the websocket has been connected.
The client ack/nack messages use ONLY the header, in order to mimic HTTP response headers.

We could simplify things by creating a model for client response to something like:

{
"status": "NOTFOUND",
"statusCode": "404"
}

Likewise, remove the "body" element from the event notification and intent verification messages.

Why would the client need to respond to an event or subscription confirmation over the websocket channel?

Github Notifications (FHIRcast) (Jun 19 2019 at 18:01):

bvdh deleted a comment on Issue #253:

Great! Thanks Isaac. I'll use the wiki for future updates.

Regarding the HTTP modelling of the web socket messages... I'm not married to the idea. It was a suggestion from Martin quite some time ago and it sounded like a good idea. I still think so, but perhaps there is a different model more appropriate for our limited use of web sockets. I'm open to suggestions.

There are only three messages sent over a web socket in the proposed spec:

1. intent verification
2. event notification
3. client->hub ack/nack

I can't think of any headers that we'd ever need for intent verification, and likewise for event notification, since authentication isn't needed once the websocket has been connected.
The client ack/nack messages use ONLY the header, in order to mimic HTTP response headers.

We could simplify things by creating a model for client response to something like:

{
"status": "NOTFOUND",
"statusCode": "404"
}

Likewise, remove the "body" element from the event notification and intent verification messages.

Why would the client need to respond to an event or subscription confirmation over the websocket channel?

Github Notifications (FHIRcast) (Jun 25 2019 at 16:38):

gkustas commented on Issue #253:

@isaacvetter -

I found a problem with the specification, and I will update the wiki if my proposal is sound. I thought I'd run it by you first:

1. When a REST client subscribes, it sends hub.callback to a valid endpoint. In the hub, the callback is the "unique identifier" for this subscription. It persists a list of all subscriptions.
2. When a websocket client subscribes, it send a hub.channel.type = "websocket" and null for hub.channel. The hub creates a unique websocket endpoint and returns it to the client. MY HUB uses that endpoint to persist this subscription.
3. In a RESTful unsubscribe for a RESTful (non-websocket) client, the hub can easily look up the subscriber by using the hub.callback value. But in a websocket client, it cannot. It's null.
My proposal is simple. I suggest that the websocket client MUST provide the websocket endpoint they are using on the hub in any REST method (such as unsubscribe) using hub.channel.endpoint.

Make sense?

---

Last updated: Apr 12 2022 at 19:14 UTC