From 9e460f891cfa05a90033f9ea801bfb5d328968bc Mon Sep 17 00:00:00 2001 From: Kuba Suder Date: Tue, 19 May 2026 18:31:44 +0200 Subject: [PATCH] en-dashes --- README.md | 60 +++++++++++++++++++++++++++---------------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index ea5acb1..be06758 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ require 'skyfall' sky = Skyfall::Firehose.new('bsky.network', :subscribe_repos) ``` -The server name can be just a hostname, or a full URL with a `ws:` or `wss:` scheme, which is useful if you want to use a non-encrypted websocket connection, e.g. `"ws://localhost:8000"`. The endpoint can be either a full NSID string like `"com.atproto.sync.subscribeRepos"`, or one of the defined symbol shortcuts - you will almost always want to pass `:subscribe_repos` here. +The server name can be just a hostname, or a full URL with a `ws:` or `wss:` scheme, which is useful if you want to use a non-encrypted websocket connection, e.g. `"ws://localhost:8000"`. The endpoint can be either a full NSID string like `"com.atproto.sync.subscribeRepos"`, or one of the defined symbol shortcuts – you will almost always want to pass `:subscribe_repos` here. Next, set up event listeners to handle incoming messages and get notified of errors. Here are all the available listeners (you will need at least either `on_message` or `on_raw_message`): @@ -60,7 +60,7 @@ sky.on_timeout { puts "Connection stalled, triggering a reconnect..." } sky.on_error { |e| puts "ERROR: #{e}" } ``` -You can also call these as setters accepting a `Proc` - e.g. to disable default error handling, you can do: +You can also call these as setters accepting a `Proc` – e.g. to disable default error handling, you can do: ```rb sky.on_error = nil @@ -94,7 +94,7 @@ sky.connect ### Cursors -ATProto websocket endpoints implement a "*cursor*" feature to help you make sure that you don't miss anything if your connection is down for a bit (because of a network issue, server restart, deploy etc.). Each message includes a `seq` field, which is the sequence number of the event. You can keep track of the last seq you've seen, and when you reconnect, you pass that number as a cursor parameter - the server will then "replay" all events you might have missed since that last one. (The `bsky.network` Relay firehose currently has a buffer of about 72 hours, though that's not something required by specification.) +ATProto websocket endpoints implement a "*cursor*" feature to help you make sure that you don't miss anything if your connection is down for a bit (because of a network issue, server restart, deploy etc.). Each message includes a `seq` field, which is the sequence number of the event. You can keep track of the last seq you've seen, and when you reconnect, you pass that number as a cursor parameter – the server will then "replay" all events you might have missed since that last one. (The `bsky.network` Relay firehose currently has a buffer of about 72 hours, though that's not something required by specification.) To use a cursor when connecting to the firehose, pass it as the third parameter to `Skyfall::Firehose`. You should then regularly save the `seq` of the last event to some permanent storage, and then load it from there when reconnecting. @@ -127,57 +127,57 @@ end Each message passed to `on_message` is an instance of a subclass of either `Skyfall::Firehose::Message` or `Skyfall::Jetstream::Message`, depending on the selected source. The supported message types are: -- `CommitMessage` (`#commit`) - represents a change in a user's repo; most messages are of this type -- `IdentityMessage` (`#identity`) - notifies about a change in user's DID document, e.g. a handle change or a migration to a new PDS -- `AccountMessage` (`#account`) - notifies about a change of an account's status (de/activation, suspension, deletion) -- `SyncMessage` (`#sync`) - updates repository state, can be used to trigger account resynchronization -- `LabelsMessage` (`#labels`) - only used in `subscribe_labels` endpoint -- `InfoMessage` (`#info`) - a protocol error message, e.g. about an invalid cursor parameter +- `CommitMessage` (`#commit`) – represents a change in a user's repo; most messages are of this type +- `IdentityMessage` (`#identity`) – notifies about a change in user's DID document, e.g. a handle change or a migration to a new PDS +- `AccountMessage` (`#account`) – notifies about a change of an account's status (de/activation, suspension, deletion) +- `SyncMessage` (`#sync`) – updates repository state, can be used to trigger account resynchronization +- `LabelsMessage` (`#labels`) – only used in `subscribe_labels` endpoint +- `InfoMessage` (`#info`) – a protocol error message, e.g. about an invalid cursor parameter - `UnknownMessage` is used for other unrecognized message types `Skyfall::Firehose::Message` and `Skyfall::Jetstream::Message` variants of message classes should have more or less the same interface, except when a given field is not included in one of the formats. All message objects have the following shared properties: -- `type` (symbol) - the message type identifier, e.g. `:commit` -- `seq` (integer) - a sequential index of the message; Jetstream messages instead have a `time_us` value, which is a Unix timestamp in microseconds (also aliased as `seq` for compatibility) -- `repo` or `did` (string) - DID of the repository (user account) -- `time` (Time) - timestamp of the described action +- `type` (symbol) – the message type identifier, e.g. `:commit` +- `seq` (integer) – a sequential index of the message; Jetstream messages instead have a `time_us` value, which is a Unix timestamp in microseconds (also aliased as `seq` for compatibility) +- `repo` or `did` (string) – DID of the repository (user account) +- `time` (Time) – timestamp of the described action All properties except `type` may be nil for some message types that aren't related to a specific user, like `#info`. Commit messages additionally have: -- `commit` - CID of the commit -- `operations` - list of operations (usually one) +- `commit` – CID of the commit +- `operations` – list of operations (usually one) Handle and Identity messages additionally have: -- `handle` - the new handle assigned to the DID +- `handle` – the new handle assigned to the DID Account messages additionally have: -- `active?` - whether the account is active, or inactive for any reason -- `status` - if not active, shows the status of the account (`:deactivated`, `:deleted`, `:takendown`) +- `active?` – whether the account is active, or inactive for any reason +- `status` – if not active, shows the status of the account (`:deactivated`, `:deleted`, `:takendown`) Info messages additionally have: -- `name` - identifier of the message/error -- `message` - a human-readable description +- `name` – identifier of the message/error +- `message` – a human-readable description ### Commit operations Operations are objects of type `Skyfall::Firehose::Operation` or `Skyfall::Jetstream::Operation` and have such properties: -- `repo` or `did` (string) - DID of the repository (user account) -- `collection` (string) - name of the relevant collection in the repository, e.g. `app.bsky.feed.post` for posts -- `type` (symbol) - short name of the collection, e.g. `:bsky_post` -- `rkey` (string) - identifier of a record in a collection -- `path` (string) - the path part of the at:// URI - collection name + ID (rkey) of the item -- `uri` (string) - the complete at:// URI -- `action` (symbol) - `:create`, `:update` or `:delete` -- `cid` (CID) - CID of the operation/record (`nil` for delete operations) +- `repo` or `did` (string) – DID of the repository (user account) +- `collection` (string) – name of the relevant collection in the repository, e.g. `app.bsky.feed.post` for posts +- `type` (symbol) – short name of the collection, e.g. `:bsky_post` +- `rkey` (string) – identifier of a record in a collection +- `path` (string) – the path part of the at:// URI – collection name + ID (rkey) of the item +- `uri` (string) – the complete at:// URI +- `action` (symbol) – `:create`, `:update` or `:delete` +- `cid` (CID) – CID of the operation/record (`nil` for delete operations) Create and update operations will also have an attached record (JSON object) with details of the post, like etc. The record data is currently available as a Ruby hash via `raw_record` property (custom types will be added in future). @@ -206,7 +206,7 @@ Note that the `Operation` objects have two properties that tell you the kind of When Skyfall receives a message about a record type that's not on the list, whether in the `app.bsky` namespace or not, the operation `type` will be `:unknown`, while the `collection` will be the original string. So if an app like e.g. "Skygram" appears with a `zz.skygram.*` namespace that lets you share photos on ATProto, the operations will have a type `:unknown` and collection names like `zz.skygram.feed.photo`, and you can check the `collection` field for record types known to you and process them in some appropriate way, even if Skyfall doesn't recognize the record type. -Do not however check if such operations have a `type` equal to `:unknown` first - just ignore the type and only check the `collection` string. The reason is that some next version of Skyfall might start recognizing those records and add a new `type` value for them like e.g. `:skygram_photo`, and then they won't match your condition anymore. +Do not however check if such operations have a `type` equal to `:unknown` first – just ignore the type and only check the `collection` string. The reason is that some next version of Skyfall might start recognizing those records and add a new `type` value for them like e.g. `:skygram_photo`, and then they won't match your condition anymore. ## Reconnection logic @@ -260,7 +260,7 @@ sky.on_message do |msg| end ``` -See [ATProto label docs](https://atproto.com/specs/label) for info on what fields are included with each label - `Skyfall::Label` includes properties with these original names, and also more friendly aliases for each (e.g. `value` instead of `val`). +See [ATProto label docs](https://atproto.com/specs/label) for info on what fields are included with each label – `Skyfall::Label` includes properties with these original names, and also more friendly aliases for each (e.g. `value` instead of `val`). ## Other configuration -- 2.51.2