Subscriptions with no immediate response

[josephg]

We had an issue come up today around subscriptions where the server:

• Doesn't respond with a snapshot and
• Doesn't name the current version

Eg, the subscription response looks like this:

HTTP/1.1 209 Subscription
content-type: application/json
transfer-encoding: chunked

(And no subsequent data is sent indefinitely.)

The problem is that the client has no idea what to display to the user - they have no idea what the document looks like until the server sends an update. This would result in bad UX (loading spinner forever), and I consider it an antipattern. I think the spec should recommend against this.

I think either:

• The client doesn't have a copy of the document. In the response the server should immediately either send a snapshot of the document, or send all patches immediately) or
• The client does have a copy of the document at some known version. The client names that version in its request (using the parents: header) and the server responds by bringing the client up to date, and uses the current-versions: header to name the most recent version.

I propose we add wording like this in the spec:

The server SHOULD either use the current-version header or when a client connects, or immediately send a full snapshot update.

@toomim said there are some other valid use cases for servers doing this. What are the other use cases I'm missing?

[toomim]

The use-case that comes to mind for me is the one in https://github.com/braid-org/braid-spec/issues/110 where you want to subscribe to a resource before it exists.

Here's an example:

Goal: A web app has a page with an optional "notes" field at /foo/notes, that contains a collaborative editor.

• The notes is optional. No need to create and store the resource unless a user types into it.

Operations:

1. Client subscribes to /foo/notes
2. If user types, client issues a PUT to /foo/notes to start editing

So we should probably add a mechanism for expressing "resource does not exist 404" as an update over a subscription, and then modify your proposed language to:

The server's response SHOULD either specify the Current-Version header, or immediately send (a) a full snapshot update or (b) 404 update.

I'm confused, though, why we would require a "full snapshot update". It seems that it would also be ok to provide a patch update, especially if the client specified Parents: in the subscription. So perhaps this language would suffice:

If a server does not immediately send an update after a client's request, then it SHOULD specify the Current-Version header, so the client knows what it will be waiting for.

[toomim]

However, I'm not sure that we should be prescribing at the protocol level how a server should behave to provide a particular UX at the application level.

If an app has a bad UX, it will become pretty obvious, and the programmers will know to fix things. I don't see why we need to prescribe that behavior in the protocol spec.

The protocol could also be used at a system-level, from server to server. Maybe a developer wants to build a system that can tolerate really slow responses from machine to machine. If we say that he SHOULD not do that, he might get worried, and feel the need to build more complexity into his system than is necessary.