skyfall 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17dd2389545a6bd5c9c3483a89f95e40a62cf2014e263f69d3590cf651920865
-  data.tar.gz: 9fe379e3d713c50e4a4700941660b529827e2329e200859ddea58b7113da1c3b
+  metadata.gz: a3e987d12df25109508c0f673894e9a334a81d60d02f57c118e699de5e68dc4d
+  data.tar.gz: 152dfdced7c5fc6414f8cbf04d7cff6d184c592a0ed42463f0b156b373c8c8ac
 SHA512:
-  metadata.gz: e9f7c603360a483241cbd6b2af8b49b315149b308c2064332b42d9fa7b27fd302c1b181c6fc7a60871f1dfead09cc3621ed2b9106db2680e0919f12119af881d
-  data.tar.gz: e8c7da9dc57730ded46de52cc7e500d84129782bd534c2163205330143bb1a5ec0f24feb39a86e440c073972b1c4af3840ce688e9caf55177003d140267c6473
+  metadata.gz: 59c9da3c3d60b953f3963c16a86c56bb9e75561696ea47d0b8ce5a3274c00a8d831529f22aacace27df0d1dba55b5dc7db58301f1baa7aa19528756d77eb7ccd
+  data.tar.gz: 0575c825184297417f40a5f7248e2560fc24f19913631c23371b1f535feea3d3b38b62b76c0a4c610dafc2e52783ba58521eaf1f3407aa59699d26640fb0f94c

data/CHANGELOG.md

@@ -1,6 +1,56 @@
+## [0.7.0] - 2026-02-13
+
+The main change in this version is that inline YARD documentation 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
+- throw error when trying to run two streams in one process (see b4a1514f5da28983205765e55724b5c4abe6c5e4 for details)
+- added protected `#send_data` and `#socket` methods in `Stream` for use in `Stream` subclasses (currently for the Tapfall gem)
+- added a way to customize headers sent when connecting in `Stream` subclasses through the `#request_headers` method
+
 ## [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
@@ -23,11 +73,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
 
@@ -41,15 +91,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
 
@@ -76,7 +126,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
@@ -84,13 +134,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/LICENSE.txt

@@ -1,6 +1,6 @@
 The zlib License
 
-Copyright (c) 2023-2024 Jakub Suder
+Copyright (c) 2026 Jakub Suder
 
 This software is provided 'as-is', without any express or implied
 warranty.  In no event will the authors be held liable for any damages

data/README.md

@@ -3,7 +3,7 @@
 A Ruby gem for streaming data from the Bluesky/ATProto firehose 🦋
 
 > [!NOTE]
-> ATProto Ruby gems collection: [skyfall](https://github.com/mackuba/skyfall) | [blue_factory](https://github.com/mackuba/blue_factory) | [minisky](https://github.com/mackuba/minisky) | [didkit](https://github.com/mackuba/didkit)
+> Part of ATProto Ruby SDK: [ruby.sdk.blue](https://ruby.sdk.blue)
 
 
 ## What does it do
@@ -15,13 +15,15 @@ Since version 0.5, Skyfall also supports connecting to [Jetstream](https://githu
 
 ## Installation
 
-From the command line:
+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/)).
 
-    gem install skyfall
+To install the gem, run the command:
 
-Or, add this to your `Gemfile`:
+    [sudo] gem install skyfall
 
-    gem 'skyfall', '~> 0.5'
+Or add this to your app's `Gemfile`:
+
+    gem 'skyfall', '~> 0.6'
 
 
 ## Usage
@@ -128,14 +130,11 @@ Each message passed to `on_message` is an instance of a subclass of either `Skyf
 - `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
+- `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:
@@ -198,7 +197,7 @@ sky.on_message do |m|
 end
 ```
 
-For more examples, see the [example](https://github.com/mackuba/skyfall/blob/master/example) folder or the [bluesky-feeds-rb](https://github.com/mackuba/bluesky-feeds-rb/blob/master/app/firehose_stream.rb) project, which implements a feed generator service.
+For more examples, see the [examples page](https://ruby.sdk.blue/examples/) on [ruby.sdk.blue](https://ruby.sdk.blue), or the [bluesky-feeds-rb](https://tangled.org/mackuba.eu/bluesky-feeds-rb/blob/master/app/firehose_stream.rb) project, which implements a feed generator service.
 
 
 ### Note on custom lexicons
@@ -305,7 +304,7 @@ See [Jetstream docs](https://github.com/bluesky-social/jetstream?tab=readme-ov-f
 
 ## Credits
 
-Copyright © 2024 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
+Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
 
 The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).
 

data/lib/skyfall/car_archive.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'cid'
 require_relative 'errors'
 require_relative 'extensions'
@@ -30,15 +32,34 @@ module Skyfall
 
     def initialize(data)
       @sections = []
+      @buffer = StringIO.new(data)
 
-      buffer = StringIO.new(data)
-      read_header(buffer)
-      read_section(buffer) until buffer.eof?
+      read_header(@buffer)
     end
 
     def section_with_cid(cid)
-      section = @sections.detect { |s| s.cid == cid }
-      section && section.body
+      if section = @sections.detect { |s| s.cid == cid }
+        return section.body
+      end
+
+      if @buffer
+        while !@buffer.eof?
+          section = read_section(@buffer)
+          return section.body if section.cid == cid
+        end
+      end
+
+      @buffer = nil
+      nil
+    end
+
+    def sections
+      if @buffer
+        read_section(@buffer) while !@buffer.eof?
+        @buffer = nil
+      end
+
+      @sections
     end
 
     def self.convert_data(object)
@@ -75,6 +96,18 @@ module Skyfall
       { '$bytes' => Base64.encode64(data).chomp.gsub(/=+$/, '') }
     end
 
+    def inspect
+      vars = instance_variables.map { |v|
+        if v == :@sections && @buffer
+          "#{v}=[...]"
+        else
+          "#{v}=#{instance_variable_get(v).inspect}"
+        end
+      }
+
+      "#<#{self.class}:0x#{object_id} #{vars.join(", ")}>"
+    end
+
     private
 
     def read_header(buffer)
@@ -116,7 +149,10 @@ module Skyfall
       cid = CID.new(prefix + cid_data)
 
       body_data = sbuffer.read
-      @sections << CarSection.new(cid, body_data)
+      new_section = CarSection.new(cid, body_data)
+
+      @sections << new_section
+      new_section
     end
   end
 end

data/lib/skyfall/cid.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'errors'
 
 require 'base32'

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"
@@ -17,7 +26,10 @@ module Skyfall
     BSKY_VERIFICATION = "app.bsky.graph.verification"
     BSKY_LABELER      = "app.bsky.labeler.service"
 
-    BSKY_CHAT_DECLARATION = "chat.bsky.actor.declaration"
+    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,
@@ -37,12 +49,22 @@ module Skyfall
       BSKY_THREADGATE   => :bsky_threadgate,
       BSKY_VERIFICATION => :bsky_verification,
       BSKY_CHAT_DECLARATION => :bsky_chat_declaration,
+      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,13 +1,60 @@
+# 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
+
+  #
+  # Raised when some part of the message being decoded has invalid format.
+  #
+  class DecodeError < Error
   end
 
-  class UnsupportedError < 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. " +
+        "Skyfall doesn't currently support running two different Stream instances in a single process."
+      )
+    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
@@ -15,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/extensions.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 require 'cbor'
 require 'stringio'
 
 module Skyfall
+
+  # @private
   module Extensions
 
     refine StringIO do

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,67 @@
+# frozen_string_literal: true
+
 require_relative '../car_archive'
 require_relative '../cid'
 require_relative '../firehose'
+require_relative 'message'
 require_relative 'operation'
 
 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
+
+    # @return [String, nil] revision of the previous commit in the repo
+    def since
+      @data_object['since']
     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 [CID, nil] CID (Content Identifier) of data of the previous commit in the repo
+    def prev_data
+      @prev_data ||= CID.from_cbor_tag(@data_object['prevData'])
+    end
+
+    # @return [CID] CID (Content Identifier) of the commit
+    def commit
+      @commit ||= CID.from_cbor_tag(@data_object['commit'])
     end
 
+    # @return [Skyfall::CarArchive] commit data in the form of a parsed CAR archive
     def blocks
       @blocks ||= 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