Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow options updates after stream initializes #3

Merged
merged 3 commits into from
Sep 25, 2024
Merged

Conversation

ericvolp12
Copy link
Collaborator

@ericvolp12 ericvolp12 commented Sep 25, 2024

This adds support for features requested in #2

A client can update their wantedCollections and wantedDids after connecting to the socket by sending a JSON payload in a Websocket Text message to Jetstream.

Some limitations apply around the size of the message: right now the message can be at most 10MB in size, contain 100 collection filters, and contain 10,000 DID filters.

Additionally, a client can connect with ?requireHello=true in the query params to pause replay/live-tail until the first Options Update message is sent by the client over the socket.

Invalid Options Updates in requireHello mode or normal operating mode will result in the client being disconnected.

Clients can now also request compression via the compress=true query parameter to help support websocket libraries that don't provide an interface for adding headers to the initial GET request.

Subscribers can send messages using the SubscriberSourcedMessage framing below:

type SubscriberSourcedMessage struct {
	Type    string          `json:"type"`
	Payload json.RawMessage `json:"payload"`
}

This framing will allow us to potentially add other control messages we may want to send from the Client to the Jetstream server in the future.

To send an Options Update, provide the string options_update in the type field and a SubscriberOptionsUpdatePayload in the payload field.

The shape for a SubscriberOptionsUpdatePayload is as follows:

type SubscriberOptionsUpdateMsg struct {
	WantedCollections []string `json:"wantedCollections"`
	WantedDIDs        []string `json:"wantedDids"`
}

If either array is empty, the relevant filter will be disabled (i.e. sending empty wantedDids will mean a client gets messages for all DIDs again).

An example Subscriber Sourced Message with an Options Update payload is as follows:

{
    "type": "options_update",
    "payload": {
        "wantedCollections": [
            "app.bsky.feed.post"
        ],
        "wantedDids": [
            "did:plc:q6gjnaw2blty4crticxkmujt"
        ]
    }
}

The above payload will filter such that a client receives only posts, and only from a the specified DID.

@ericvolp12 ericvolp12 merged commit df51fd6 into main Sep 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant