skyfall 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d216f6eca172d8982c358d594511fa31212dd9dfdb949ed1149d16b23862bfa
-  data.tar.gz: c381c2abebdb22265568b0183b7d78525a6cbbbd01192b32faad4ed1dadbec02
+  metadata.gz: c52f2f3c63530b1e032666c7bfb71ba0b0279bfe0128c7432b8e267f1e2f9e95
+  data.tar.gz: 1c7e2e5cac7ec4f421be5c291a311dede53221150901a44418f01f7a6cdeae9e
 SHA512:
-  metadata.gz: 1d4c45ef3103036b5e13c5614615f20b61d9beaa7092af2058b8135cd4b460ede00c23b1d05cc5b57751a64a50e6286946d438ccd80c899023c9d92be6ac710e
-  data.tar.gz: d7bd5bb732b86db3c56b9389a25a5e6d80f57629ec27621c32330ad0155c379864388eb347381e8f5e38387c4b22ce019fd4879c0e33eb46852e1565c2aef844
+  metadata.gz: 1eb9556cbc363f6a9c2ae42d27dc9a4471a24f8e08f0b1b8046c131fe320b63de73498d839367f0fd89c3841b27877c53bc0a937b9eeed41ea486f05b55a38c3
+  data.tar.gz: 9b61caf5cc63834efd8185622c435a9102b4a310f890a988fd029e9e691e80acf7527e0afc5e5fecde967c4f2de538559168d07a72a2af4dd9d5ef06cc16ab50

data/CHANGELOG.md

@@ -1,3 +1,51 @@
+## [0.7.1] - 2026-08-05
+
+- extracted `CID` and `CarArchive` to a new gem "oxygene"
+- added `CommitMessage#cid` as alias of `#commit`
+
+## [0.7.0] - 2026-02-13
+
+The main change in this version is that inline [YARD documentation](https://rubydoc.info/gems/skyfall/) has been added. This was also a good opportunity to review some APIs and tweak some things in order to get Skyfall a bit closer to 1.0.
+
+New APIs:
+
+- the `Skyfall::Firehose` initializer now allows skipping `:subscribe_repos`, i.e. `.new(host)` or `.new(host, cursor)`
+- added `Skyfall::Jetstream::CommitMessage#operation` (aliased as `op`) which returns the (always single) operation in the `operations` array
+- added `#kind` as alias for `#type` in both `Message` classes
+- added a base class for error types, `Skyfall::Error`
+- added `#blocks` to `Skyfall::Firehose::SyncMessage`
+- added `#rev`, `#since` and `#prev_data` to `Skyfall::Firehose::CommitMessage`
+
+Deprecated & removed APIs:
+
+- removed deprecated `HandleMessage` and `TombstoneMessage` message classes
+- removed deprecated `CommitMessage#prev`
+- deprecated `#path` in both `Operation` classes
+
+Optimizations:
+
+- much faster `Skyfall::Firehose::Message#time` parsing on Ruby 3.2+
+- lazy decoding of sections in `CarArchive` – saves quite a lot of work if sections are only accessed through `Operation#raw_record`
+- added `frozen_string_literal: true` in all files to reduce garbage collection
+
+Access level changes:
+
+- restricted `Stream#start_heartbeat_timer` & `Stream#stop_heartbeat_timer` methods' access to private
+- restricted `Stream#handle_message` method access to protected
+- restricted `Stream#last_update` to read-only access
+- restricted `#inspectable_variables` access to either private or protected
+- relaxed `Stream#build_websocket_url` & `Stream#build_websocket_client` access from private to protected
+- fixed private class method `Skyfall::Firehose::Message.decode_cbor_objects` which wasn't actually private
+
+Additional validations and other changes:
+
+- `Stream#connect` throws an error if neither `on_message` nor `on_raw_message` handlers have been configured
+- `Message` subclasses do additional checks if the fields they require to not be nil aren't nil
+- `Message` subclasses raise an error if `.new` is called on a subclass (and not on the base `Message`) passing the data of a wrong kind of message (instead of returning e.g. a `CommitMessage` from `AccountMessage.new` as it worked previously)
+- made `LabelsMessage` a subclass of `Firehose::Message`
+- fixed the `require`s config in some files so they can be loaded in any order
+
+
 ## [0.6.1] - 2026-01-08
 
 - added `:bsky_notif_declaration` shortcode for `app.bsky.notification.declaration` collection
@@ -7,7 +55,7 @@
 
 ## [0.6.0] - 2025-06-25
 
-- significantly speeded up reading of events from the binary firehose (`Skyfall::Firehose`) - up to 4-5x faster than before
+- significantly speeded up reading of events from the binary firehose (`Skyfall::Firehose`) – up to 4-5x faster than before
 - removed the `Skyfall::Stream.new` constructor deprecated in 0.5.0
 
 ## [0.5.1] - 2025-05-18
@@ -30,11 +78,11 @@ This required some breaking changes in the existing API:
 
 In most cases, you should only need to update the `Skyfall::Stream` class name in the constructor. If you've referenced message classes like `Skyfall::CommitMessage` directly, it's probably better to just check the `#type` property instead.
 
-Also, small change to the user agent API: `Skyfall::Stream` now has an additional metod `version_string`, which will always return `Skyfall/0.x.y` - it's recommended to use that instead of `default_user_agent` to build your own user agent string that includes the library version. `default_user_agent` now passes through to `version_string`, but it could be changed in future to return something else.
+Also, small change to the user agent API: `Skyfall::Stream` now has an additional metod `version_string`, which will always return `Skyfall/0.x.y` – it's recommended to use that instead of `default_user_agent` to build your own user agent string that includes the library version. `default_user_agent` now passes through to `version_string`, but it could be changed in future to return something else.
 
 ## [0.4.1] - 2024-10-04
 
-- performance fix - don't decode CAR sections which aren't needed, which is most of them; this cuts the amount of memory that GC has to free up by about one third, and should speed up processing by around ~10%
+- performance fix – don't decode CAR sections which aren't needed, which is most of them; this cuts the amount of memory that GC has to free up by about one third, and should speed up processing by around ~10%
 
 ## [0.4.0] - 2024-09-23
 
@@ -48,15 +96,15 @@ Also, small change to the user agent API: `Skyfall::Stream` now has an additiona
 - added `#account` event type (`AccountMessage`)
 - added `handle` field to `IdentityMessage`
 - fixed param validation on `Stream` initialization
-- reverted the change that added Ruby stdlib dependencies explicitly to the gemspec, since this causes more problems than it's worth - only `base64` is left there, since it's the one now required to be listed
+- reverted the change that added Ruby stdlib dependencies explicitly to the gemspec, since this causes more problems than it's worth – only `base64` is left there, since it's the one now required to be listed
 
 ## [0.3.0] - 2024-03-21
 
 - added support for labeller firehose, served by labeller services at the `com.atproto.label.subscribeLabels` endpoint (aliased as `:subscribe_labels`)
 - the `#labels` messages from the labeller firehose are parsed into a `LabelsMessage`, which includes a `labels` array of `Label` objects
 - `Stream` callbacks can now also be assigned via setters, e.g. `stream.on_message = proc { ... }`
-- added default error handler to `Stream` which logs the error to `$stdout` - set `stream.on_error = nil` to disable
-- added Ruby stdlib dependencies explicitly to the gemspec - fixes a warning in Ruby 3.3 when requiring `base64`, which will be extracted as an optional gem in 3.4
+- added default error handler to `Stream` which logs the error to `$stdout` – set `stream.on_error = nil` to disable
+- added Ruby stdlib dependencies explicitly to the gemspec – fixes a warning in Ruby 3.3 when requiring `base64`, which will be extracted as an optional gem in 3.4
 
 ## [0.2.5] - 2024-03-14
 
@@ -83,7 +131,7 @@ Also, small change to the user agent API: `Skyfall::Stream` now has an additiona
 
 ## [0.2.1] - 2023-08-19
 
-- optimized `WebsocketMessage` parsing performance - lazy parsing of most properties (message decoding should be over 50% faster on average)
+- optimized `WebsocketMessage` parsing performance – lazy parsing of most properties (message decoding should be over 50% faster on average)
 - added separate subclasses of `WebsocketMessage` for different message types
 - added support for `#handle`, `#info` and `#tombstone` message types
 - `UnknownMessage` is returned for unrecognized message types
@@ -91,13 +139,13 @@ Also, small change to the user agent API: `Skyfall::Stream` now has an additiona
 ## [0.2.0] - 2023-07-24
 
 - switched the websocket library from `websocket-client-simple` to `faye-websocket`, which should make event parsing up to ~30× faster (!)
-- added `auto_reconnect` property to `Stream` (on by default) - if true, it will try to reconnect with an exponential backoff when the websocket disconnects, until you call `Stream#disconnect`
+- added `auto_reconnect` property to `Stream` (on by default) – if true, it will try to reconnect with an exponential backoff when the websocket disconnects, until you call `Stream#disconnect`
 
 Note:
 
-- calling `sleep` is no longer needed after connecting - call `connect` on a new thread instead to get previously default behavior of running the event loop asynchronously
+- calling `sleep` is no longer needed after connecting – call `connect` on a new thread instead to get previously default behavior of running the event loop asynchronously
 - the disconnect event no longer passes an error object in the argument
-- there is currently no "heartbeat" feature as in 0.1.x that checks for a stuck connection - but it doesn't seem to be needed
+- there is currently no "heartbeat" feature as in 0.1.x that checks for a stuck connection – but it doesn't seem to be needed
 
 ## [0.1.3] - 2023-07-04
 

data/README.md

@@ -1,5 +1,7 @@
 # Skyfall
 
+[![Gem Version](https://badge.fury.io/rb/skyfall.svg?icon=si%3Arubygems&icon_color=%23ff6251)](https://rubygems.org/gems/skyfall) [![YARD Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/skyfall)
+
 A Ruby gem for streaming data from the Bluesky/ATProto firehose 🦋
 
 > [!NOTE]
@@ -15,7 +17,7 @@ Since version 0.5, Skyfall also supports connecting to [Jetstream](https://githu
 
 ## Installation
 
-To use Skyfall, you need a reasonably new version of Ruby – it should run on Ruby 2.6 and above, although it's recommended to use a version that's still getting maintainance updates, i.e. currently 3.2+. A compatible version should be preinstalled on macOS Big Sur and above and on many Linux systems. Otherwise, you can install one using tools such as [RVM](https://rvm.io), [asdf](https://asdf-vm.com), [ruby-install](https://github.com/postmodern/ruby-install) or [ruby-build](https://github.com/rbenv/ruby-build), or `rpm` or `apt-get` on Linux (see more installation options on [ruby-lang.org](https://www.ruby-lang.org/en/downloads/)).
+To use Skyfall, you need a reasonably new version of Ruby – it should run on Ruby 2.6 and above, although it's recommended to use a version that's still getting maintainance updates, i.e. currently 3.3+. A compatible version should be preinstalled on macOS Big Sur and above and on many Linux systems. Otherwise, you can install one using tools such as [RVM](https://rvm.io), [asdf](https://asdf-vm.com), [ruby-install](https://github.com/postmodern/ruby-install) or [ruby-build](https://github.com/rbenv/ruby-build), or `rpm` or `apt-get` on Linux (see more installation options on [ruby-lang.org](https://www.ruby-lang.org/en/downloads/)).
 
 To install the gem, run the command:
 
@@ -38,7 +40,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 +62,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 +96,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,60 +129,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)
-- `HandleMessage` (`#handle` - deprecated) - when a different handle is assigned to a user's DID
-- `TombstoneMessage` (`#tombstone` - deprecated) - when an account is deleted
-- `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
 
-`#handle` and `#tombstone` events are considered deprecated, replaced by `#identity` and `#account` respectively. They are still being emitted at the moment (in parallel with the newer event types), but they might stop being sent at any moment, so it's recommended that you don't rely on those.
-
 `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).
 
@@ -209,7 +208,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
@@ -263,7 +262,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
@@ -305,6 +304,13 @@ See [Jetstream docs](https://github.com/bluesky-social/jetstream?tab=readme-ov-f
 > The `compress` and `requireHello` options (and zstd compression) are not available at the moment. Also the "subscriber sourced messages" aren't implemented yet.
 
 
+## Other resources
+
+- [YARD API documentation](https://rubydoc.info/gems/skyfall) at rubydoc.info
+- [ruby.sdk.blue](https://ruby.sdk.blue)
+- [Example scripts](https://ruby.sdk.blue/examples/)
+- [bluesky-feeds-rb](https://tangled.org/mackuba.eu/bluesky-feeds-rb) – feed generator template project
+
 ## Credits
 
 Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).

data/lib/skyfall/collection.rb

@@ -1,4 +1,13 @@
+# frozen_string_literal: true
+
 module Skyfall
+
+  #
+  # This module defines constants for known Bluesky record collection types, and a mapping of those
+  # names to symbol short codes which can be used as shorthand when processing events or in
+  # Jetstream filters.
+  #
+
   module Collection
     BSKY_PROFILE      = "app.bsky.actor.profile"
     BSKY_ACTOR_STATUS = "app.bsky.actor.status"
@@ -20,6 +29,8 @@ module Skyfall
     BSKY_NOTIF_DECLARATION = "app.bsky.notification.declaration"
     BSKY_CHAT_DECLARATION  = "chat.bsky.actor.declaration"
 
+    # Mapping of NSID collection names to symbol short codes
+
     SHORT_CODES = {
       BSKY_ACTOR_STATUS => :bsky_actor_status,
       BSKY_BLOCK        => :bsky_block,
@@ -41,10 +52,19 @@ module Skyfall
       BSKY_NOTIF_DECLARATION => :bsky_notif_declaration
     }
 
+    # Returns a symbol short code for a given collection NSID, or `:unknown`
+    # if NSID is not on the list.
+    # @param collection [String] collection NSID
+    # @return [Symbol] short code or :unknown
+
     def self.short_code(collection)
       SHORT_CODES[collection] || :unknown
     end
 
+    # Returns a collection NSID assigned to a given short code symbol, if one is defined.
+    # @param code [Symbol] one of the symbols listed in {SHORT_CODES}
+    # @return [String, nil] assigned NSID string, or nil when code is not known
+
     def self.from_short_code(code)
       SHORT_CODES.detect { |k, v| v == code }&.first
     end

data/lib/skyfall/errors.rb

@@ -1,11 +1,36 @@
+# frozen_string_literal: true
+
 module Skyfall
-  class DecodeError < StandardError
+  #
+  # Wrapper base class for Skyfall error classes.
+  #
+  class Error < StandardError
+  end
+
+  #
+  # Raised when some code is not configured or configured incorrectly.
+  #
+  class ConfigError < Error
   end
 
-  class UnsupportedError < StandardError
+  #
+  # Raised when some part of the message being decoded has invalid format.
+  #
+  class DecodeError < Error
   end
 
-  class ReactorActiveError < StandardError
+  #
+  # Raised when {Stream#connect} is called and there's already another instance of {Stream} or its
+  # subclass like {Firehose} that's connected to another websocket.
+  #
+  # This is currently not supported in Skyfall, because it uses EventMachine behind the scenes, which
+  # runs everything on a single "reactor" thread, and there can be only one such reactor thread in
+  # a given process. In theory, it should be possible for two connections to run inside a single
+  # shared EventMachine event loop, but it would require some more coordination and it might have
+  # unexpected side effects - e.g. synchronous work (including I/O and network requests) done during
+  # processing of an event from one connection would be blocking the other connection.
+  #
+  class ReactorActiveError < Error
     def initialize
       super(
         "An EventMachine reactor thread is already running, but it seems to have been launched by another Stream. " +
@@ -14,9 +39,22 @@ module Skyfall
     end
   end
 
-  class SubscriptionError < StandardError
-    attr_reader :error_type, :error_message
+  #
+  # Raised when the server sends a message which is formatted correctly, but describes some kind of
+  # error condition that the server has detected.
+  #
+  class SubscriptionError < Error
+
+    # @return [String] a short machine-readable error code
+    attr_reader :error_type
 
+    # @return [String] a human-readable error message
+    attr_reader :error_message
+
+    #
+    # @param error_type [String] a short machine-readable error code
+    # @param error_message [String, nil] a human-readable error message
+    #
     def initialize(error_type, error_message = nil)
       @error_type = error_type
       @error_message = error_message
@@ -24,4 +62,11 @@ module Skyfall
       super("Subscription error: #{error_type}" + (error_message ? " (#{error_message})" : ""))
     end
   end
+
+  #
+  # Raised when the server sends a message which is formatted correctly, but written in a version
+  # that's not supported by this library.
+  #
+  class UnsupportedError < Error
+  end
 end

data/lib/skyfall/events.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Skyfall
+
+  # @private
+  module Events
+    protected
+
+    def event_handler(name)
+      define_method("on_#{name}") do |&block|
+        @handlers[name.to_sym] = block
+      end
+
+      define_method("on_#{name}=") do |block|
+        @handlers[name.to_sym] = block
+      end
+    end
+  end
+end

data/lib/skyfall/firehose/account_message.rb

@@ -1,13 +1,41 @@
+# frozen_string_literal: true
+
 require_relative '../firehose'
+require_relative 'message'
 
 module Skyfall
+
+  #
+  # Firehose message sent when the status of an account changes. This can be:
+  # 
+  # - an account being created, sending its initial state (should be active)
+  # - an account being deactivated or suspended
+  # - an account being restored back to an active state from deactivation/suspension
+  # - an account being deleted (the status returning `:deleted`)
+  #
+
   class Firehose::AccountMessage < Firehose::Message
-    def active?
-      @data_object['active']
+
+    #
+    # @private
+    # @param type_object [Hash] first decoded CBOR frame with metadata
+    # @param data_object [Hash] second decoded CBOR frame with payload
+    # @raise [DecodeError] if the message doesn't include required data
+    #
+    def initialize(type_object, data_object)
+      super
+      check_if_not_nil 'seq', 'did', 'time', 'active'
+
+      @active = @data_object['active']
+      @status = @data_object['status']&.to_sym
     end
 
-    def status
-      @data_object['status']&.to_sym
+    # @return [Boolean] true if the account is active, false if it's deactivated/suspended etc.
+    def active?
+      @active
     end
+
+    # @return [Symbol, nil] for inactive accounts, specifies the exact state; nil for active accounts
+    attr_reader :status
   end
 end

data/lib/skyfall/firehose/commit_message.rb

@@ -1,27 +1,68 @@
-require_relative '../car_archive'
-require_relative '../cid'
+# frozen_string_literal: true
+
 require_relative '../firehose'
+require_relative 'message'
 require_relative 'operation'
+require 'oxygene'
 
 module Skyfall
+
+  #
+  # Firehose message which includes one or more operations on records in the repo (a record was
+  # created, updated or deleted). In most cases this is a single record operation.
+  #
+  # Most of the messages received from the firehose are of this type, and this is the type you
+  # will usually be most interested in.
+  #
+
   class Firehose::CommitMessage < Firehose::Message
-    def commit
-      @commit ||= @data_object['commit'] && CID.from_cbor_tag(@data_object['commit'])
+
+    #
+    # @private
+    # @param type_object [Hash] first decoded CBOR frame with metadata
+    # @param data_object [Hash] second decoded CBOR frame with payload
+    # @raise [DecodeError] if the message doesn't include required data
+    #
+    def initialize(type_object, data_object)
+      super
+      check_if_not_nil 'seq', 'repo', 'commit', 'blocks', 'ops', 'time', 'rev'
+    end
+
+    # @return [String] current revision of the repo
+    def rev
+      @data_object['rev']
     end
 
-    def prev
-      STDERR.puts "Warning: `prev` property has been deprecated and will be removed in a future version."
-      @prev ||= @data_object['prev'] && CID.from_cbor_tag(@data_object['prev'])
+    # @return [String, nil] revision of the previous commit in the repo
+    def since
+      @data_object['since']
     end
 
+    # @return [Oxygene::CID, nil] CID (Content Identifier) of data of the previous commit in the repo
+    def prev_data
+      @prev_data ||= Oxygene::CID.from_cbor_tag(@data_object['prevData'])
+    end
+
+    # @return [Oxygene::CID] CID (Content Identifier) of the commit
+    def commit
+      @commit ||= Oxygene::CID.from_cbor_tag(@data_object['commit'])
+    end
+
+    alias cid commit
+
+    # @return [Oxygene::CARArchive] commit data in the form of a parsed CAR archive
     def blocks
-      @blocks ||= CarArchive.new(@data_object['blocks'])
+      @blocks ||= Oxygene::CARArchive.new(@data_object['blocks'])
     end
 
+    # @return [Array<Firehose::Operation>] record operations (usually one) included in the commit
     def operations
       @operations ||= @data_object['ops'].map { |op| Firehose::Operation.new(self, op) }
     end
 
+    # Looks up record data assigned to a given operation in the commit's CAR archive.
+    # @param op [Firehose::Operation]
+    # @return [Hash, nil]
     def raw_record_for_operation(op)
       op.cid && blocks.section_with_cid(op.cid)
     end

data/lib/skyfall/firehose/identity_message.rb

@@ -1,9 +1,37 @@
+# frozen_string_literal: true
+
 require_relative '../firehose'
+require_relative 'message'
 
 module Skyfall
+
+  #
+  # Firehose message sent when a new DID is created or when the details of someone's DID document
+  # are changed (usually either a handle change or a migration to a different PDS). The message
+  # may include currently assigned handle, though it's not required that this field is set.
+  #
+  # Note: the message is originally emitted from the account's PDS and is passed as is by relays,
+  # which means you can't fully trust that the handle is actually correctly assigned to the DID
+  # and verified by DNS or well-known. To confirm that, use `DID.resolve_handle` from
+  # [DIDKit](https://ruby.sdk.blue/didkit/).
+  #
+
   class Firehose::IdentityMessage < Firehose::Message
-    def handle
-      @data_object['handle']
+
+    #
+    # @private
+    # @param type_object [Hash] first decoded CBOR frame with metadata
+    # @param data_object [Hash] second decoded CBOR frame with payload
+    # @raise [DecodeError] if the message doesn't include required data
+    #
+    def initialize(type_object, data_object)
+      super
+      check_if_not_nil 'seq', 'did', 'time'
+
+      @handle = @data_object['handle']
     end
+
+    # @return [String, nil] current handle assigned to the DID
+    attr_reader :handle
   end
 end

data/lib/skyfall/firehose/info_message.rb

@@ -1,22 +1,56 @@
+# frozen_string_literal: true
+
 require_relative '../firehose'
+require_relative 'message'
 
 module Skyfall
+
+  #
+  # An informational firehose message from the websocket service itself, unrelated to any repos.
+  #
+  # Currently there is only one type of message defined, `"OutdatedCursor"`, which is sent when
+  # the client connects with a cursor that is older than the oldest event currently kept in the
+  # backfill buffer. This message means that you're likely missing some events that were sent
+  # since the last time the client was connected but which were already deleted from the buffer.
+  #
+  # Note: the {#did}, {#seq} and {#time} properties are always `nil` for `#info` messages.
+  #
+
   class Firehose::InfoMessage < Firehose::Message
-    attr_reader :name, :message
 
+    # @return [String] short machine-readable code of the info message
+    attr_reader :name
+
+    # @return [String, nil] a human-readable description
+    attr_reader :message
+
+    # Message which means that the cursor passed when connecting is older than the oldest event
+    # currently kept in the backfill buffer, and that you've likely missed some events that have
+    # already been deleted
     OUTDATED_CURSOR = "OutdatedCursor"
 
+    #
+    # @private
+    # @param type_object [Hash] first decoded CBOR frame with metadata
+    # @param data_object [Hash] second decoded CBOR frame with payload
+    # @raise [DecodeError] if the message doesn't include required data
+    #
     def initialize(type_object, data_object)
       super
+      check_if_not_nil 'name'
 
       @name = @data_object['name']
       @message = @data_object['message']
     end
 
+    # @return [String] a formatted summary
     def to_s
       (@name || "InfoMessage") + (@message ? ": #{@message}" : "")
     end
 
+    protected
+
+    # @return [Array<Symbol>] list of instance variables to be printed in the {#inspect} output
     def inspectable_variables
       super - [:@did, :@seq]
     end