skyfall 0.6.1 → 0.7.1

data/lib/skyfall/jetstream/identity_message.rb

@@ -1,13 +1,34 @@
+# frozen_string_literal: true
+
 require_relative '../errors'
 require_relative '../jetstream'
+require_relative 'message'
 
 module Skyfall
+
+  #
+  # Jetstream 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
+  # should include currently assigned handle (though the field is not required).
+  #
+  # 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 Jetstream::IdentityMessage < Jetstream::Message
+
+    #
+    # @param json [Hash] message JSON decoded from the websocket message
+    # @raise [DecodeError] if the message doesn't include required data
+    #
     def initialize(json)
-      raise DecodeError.new("Missing event details") if json['identity'].nil?
+      raise DecodeError.new("Missing event details (identity)") if json['identity'].nil?
       super
     end
 
+    # @return [String, nil] current handle assigned to the DID
     def handle
       @json['identity']['handle']
     end

data/lib/skyfall/jetstream/message.rb

@@ -1,22 +1,58 @@
+# frozen_string_literal: true
+
 require_relative '../errors'
 require_relative '../jetstream'
 
 require 'time'
 
 module Skyfall
+
+  # @abstract
+  # Abstract base class representing a Jetstream message.
+  #
+  # Actual messages are returned as instances of one of the subclasses of this class,
+  # depending on the type of message, most commonly as {Skyfall::Jetstream::CommitMessage}.
+  #
+  # The {new} method is overridden here so that it can be called with a JSON message from
+  # the websocket, and it parses the type from the JSON and builds an instance of a matching
+  # subclass.
+  # 
+  # You normally don't need to call this class directly, unless you're building a custom
+  # subclass of {Skyfall::Stream} or reading raw data packets from the websocket through
+  # the {Skyfall::Stream#on_raw_message} event handler.
+
   class Jetstream::Message
-    require_relative 'account_message'
-    require_relative 'commit_message'
-    require_relative 'identity_message'
-    require_relative 'unknown_message'
 
-    attr_reader :did, :type, :time_us
+    # Type of the message (e.g. `:commit`, `:identity` etc.)
+    # @return [Symbol]
+    attr_reader :type
+
+    # DID of the account (repo) that the event is sent by
+    # @return [String]
+    attr_reader :did
+
+    # Server timestamp of the message (in Unix time microseconds), which serves as a cursor
+    # when reconnecting; an equivalent of {Skyfall::Firehose::Message#seq} in CBOR firehose
+    # messages.
+    # @return [Integer]
+    attr_reader :time_us
+
     alias repo did
     alias seq time_us
+    alias kind type
 
-    # :nodoc: - consider this as semi-private API
+    # The raw JSON of the message as parsed from the websocket packet.
     attr_reader :json
 
+    #
+    # Parses the JSON data from a websocket message and returns an instance of an appropriate subclass.
+    # 
+    # {Skyfall::Jetstream::UnknownMessage} is returned if the message type is not recognized.
+    #
+    # @param data [String] plain text payload of a Jetstream websocket message
+    # @return [Skyfall::Jetstream::Message]
+    # @raise [DecodeError] if the message doesn't include required data
+    #
     def self.new(data)
       json = JSON.parse(data)
 
@@ -27,28 +63,79 @@ module Skyfall
         else Jetstream::UnknownMessage
       end
 
+      if self != Jetstream::Message && self != message_class
+        expected_type = self.name.split('::').last.gsub(/Message$/, '').downcase
+        raise DecodeError, "Expected '#{expected_type}' message, got '#{json['kind']}'"
+      end
+
       message = message_class.allocate
       message.send(:initialize, json)
       message
     end
 
+    #
+    # @param json [Hash] message JSON decoded from the websocket message
+    # @raise [DecodeError] if the message doesn't include required data
+    #
     def initialize(json)
+      %w(kind did time_us).each { |f| raise DecodeError.new("Missing event details (#{f})") if json[f].nil? }
+
       @json = json
       @type = @json['kind'].to_sym
       @did = @json['did']
       @time_us = @json['time_us']
     end
 
+    #
+    # @return [Boolean] true if the message is {Jetstream::UnknownMessage} (of unrecognized type)
+    #
     def unknown?
       self.is_a?(Jetstream::UnknownMessage)
     end
 
+    # Returns a record operation included in the message. Only `:commit` messages include
+    # operations, but for convenience the method is declared here and returns nil in other messages.
+    #
+    # @return [nil]
+    #
+    def operation
+      nil
+    end
+
+    alias op operation
+
+    # List of operations on records included in the message. Only `:commit` messages include
+    # operations, but for convenience the method is declared here and returns an empty array
+    # in other messages.
+    #
+    # @return [Array<Jetstream::Operation>]
+    #
     def operations
       []
     end
 
+    #
+    # Timestamp decoded from the message.
+    #
+    # Note: the time is read from the {#time_us} field, which stores the event time as an integer in
+    # Unix time microseconds, and which is used as an equivalent of {Skyfall::Firehose::Message#seq}
+    # in CBOR firehose messages. This timestamp represents the time when the message was received
+    # and stored by Jetstream, which might differ a lot from the `created_at` time saved in the
+    # record data, e.g. if user's local time is set incorrectly or if an archive of existing posts
+    # was imported from another platform. It will also differ (usually only slightly) from the
+    # timestamp of the original CBOR message emitted from the PDS and passed through the relay.
+    #
+    # @return [Time]
+    #
     def time
-      @time ||= @json['time_us'] && Time.at(@json['time_us'] / 1_000_000.0)
+      @time ||= Time.at(@time_us / 1_000_000.0)
     end
   end
 end
+
+# need to be at the end because of a circular dependency
+
+require_relative 'account_message'
+require_relative 'commit_message'
+require_relative 'identity_message'
+require_relative 'unknown_message'

data/lib/skyfall/jetstream/operation.rb

@@ -1,58 +1,111 @@
+# frozen_string_literal: true
+
 require_relative '../collection'
 require_relative '../jetstream'
+require 'oxygene'
 
 module Skyfall
+
+  #
+  # A single record operation from a Jetstream commit event. An operation is a new record being
+  # created, or an existing record modified or deleted. It includes the URI and other details of
+  # the record in question, type of the action taken, and record data for "created" and "update"
+  # actions.
+  #
+  # Note: when a record is deleted, the previous record data is *not* included in the commit, only
+  # its URI. This means that if you're tracking records which are referencing other records, e.g.
+  # follow, block, or like records, you need to store information about this referencing record
+  # including an URI or rkey, because in case of a delete, you will not get information about which
+  # post was unliked or which account was unfollowed, only which like/follow record was deleted.
+  #
+  # At the moment, Skyfall doesn't parse the record data into any rich models specific for a given
+  # record type with a convenient API, but simply returns them as `Hash` objects (see {#raw_record}).
+  # In the future, a second `#record` method might be added which returns a parsed record model.
+  #
+
   class Jetstream::Operation
+
+    #
+    # @param message [Skyfall::Jetstream::Message] commit message the operation is parsed from
+    # @param json [Hash] operation data
+    #
     def initialize(message, json)
       @message = message
       @json = json
     end
 
+    # @return [String] DID of the account/repository in which the operation happened
     def repo
       @message.repo
     end
 
     alias did repo
 
+    # @return [String] path part of the record URI (collection + rkey)
+    # @deprecated Use {#collection} + {#rkey}
     def path
+      @@path_warning_printed ||= false
+
+      unless @@path_warning_printed
+        $stderr.puts "Warning: Skyfall::Jetstream::Operation#path is deprecated - use #collection + #rkey"
+        @@path_warning_printed = true
+      end
+
       @json['collection'] + '/' + @json['rkey']
     end
 
+    # @return [Symbol] type of the operation (`:create`, `:update` or `:delete`)
     def action
       @json['operation'].to_sym
     end
 
+    # @return [String] record collection NSID
     def collection
       @json['collection']
     end
 
+    # @return [String] record rkey
     def rkey
       @json['rkey']
     end
 
+    # @return [String] full AT URI of the record
     def uri
       "at://#{repo}/#{collection}/#{rkey}"
     end
 
+    # @return [Oxygene::CID, nil] CID (Content Identifier) of the record (nil for delete operations)
     def cid
-      @cid ||= @json['cid'] && CID.from_json(@json['cid'])
+      @cid ||= @json['cid'] && Oxygene::CID.from_json(@json['cid'])
     end
 
+    # @return [Hash, nil] record data as a plain Ruby Hash (nil for delete operations)
     def raw_record
       @json['record']
     end
 
+    # Symbol short code of the collection, like `:bsky_post`. If the collection NSID is not
+    # recognized, the type is `:unknown`. The full NSID is always available through the
+    # `#collection` property.
+    #
+    # @return [Symbol]
+    # @see Skyfall::Collection
+    #
     def type
       Collection.short_code(collection)
     end
 
-    def inspectable_variables
-      instance_variables - [:@message]
-    end
-
+    # Returns a string with a representation of the object for debugging purposes.
+    # @return [String]
     def inspect
       vars = inspectable_variables.map { |v| "#{v}=#{instance_variable_get(v).inspect}" }.join(", ")
       "#<#{self.class}:0x#{object_id} #{vars}>"
     end
+
+    private
+
+    def inspectable_variables
+      instance_variables - [:@message]
+    end
   end
 end

data/lib/skyfall/jetstream/unknown_message.rb

@@ -1,6 +1,14 @@
+# frozen_string_literal: true
+
 require_relative '../jetstream'
+require_relative 'message'
 
 module Skyfall
+
+  #
+  # Jetstream message of an unrecognized type.
+  #
+
   class Jetstream::UnknownMessage < Jetstream::Message
   end
 end

data/lib/skyfall/jetstream.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'stream'
 
 require 'json'
@@ -5,9 +7,78 @@ require 'time'
 require 'uri'
 
 module Skyfall
+
+  #
+  # Client of a Jetstream service (JSON-based firehose).
+  #
+  # This is an equivalent of {Skyfall::Firehose} for Jetstream sources, mirroring its API.
+  # It returns messages as instances of subclasses of {Skyfall::Jetstream::Message}, which
+  # are generally equivalent to the respective {Skyfall::Firehose::Message} variants as much
+  # as possible.
+  #
+  # To connect to a Jetstream websocket, you need to:
+  #
+  # * create an instance of Jetstream, passing it the hostname/URL of the server, and optionally
+  #   parameters such as cursor or collection/DID filters
+  # * set up callbacks to be run when connecting, disconnecting, when a message is received etc.
+  #   (you need to set at least a message handler)
+  # * call {#connect} to start the connection
+  # * handle the received messages
+  #
+  # @example
+  #   client = Skyfall::Jetstream.new('jetstream2.us-east.bsky.network', {
+  #     wanted_collections: 'app.bsky.feed.post',
+  #     wanted_dids: @dids
+  #   })
+  #
+  #   client.on_message do |msg|
+  #     next unless msg.type == :commit
+  #
+  #     op = msg.operation
+  #
+  #     if op.type == :bsky_post && op.action == :create
+  #       puts "[#{msg.time}] #{msg.repo}: #{op.raw_record['text']}"
+  #     end
+  #   end
+  #
+  #   client.connect
+  #
+  #   # You might also want to set some or all of these lifecycle callback handlers:
+  #
+  #   client.on_connecting { |url| puts "Connecting to #{url}..." }
+  #   client.on_connect { puts "Connected" }
+  #   client.on_disconnect { puts "Disconnected" }
+  #   client.on_reconnect { puts "Connection lost, trying to reconnect..." }
+  #   client.on_timeout { puts "Connection stalled, triggering a reconnect..." }
+  #   client.on_error { |e| puts "ERROR: #{e}" }
+  #
+  # @note Most of the methods of this class that you might want to use are defined in {Skyfall::Stream}.
+  #
+
   class Jetstream < Stream
+
+    # Current cursor (time of the last seen message)
+    # @return [Integer, nil]
     attr_accessor :cursor
 
+    #
+    # @param server [String] Address of the server to connect to.
+    #   Expects a string with either just a hostname, or a ws:// or wss:// URL with no path.
+    # @param params [Hash] options, see below:
+    #
+    # @option params [Integer] :cursor
+    #   cursor from which to resume
+    #
+    # @option params [Array<String>] :wanted_dids
+    #   DID filter to pass to the server (`:wantedDids` is also accepted);
+    #   value should be a DID string or an array of those
+    #
+    # @option params [Array<String, Symbol>] :wanted_collections
+    #   collection filter to pass to the server (`:wantedCollections` is also accepted);
+    #   value should be an NSID string or a symbol shorthand, or an array of those
+    #
+    # @raise [ArgumentError] if the server parameter or the options are invalid
+    #
     def initialize(server, params = {})
       require_relative 'jetstream/message'
       super(server)
@@ -17,6 +88,28 @@ module Skyfall
       @root_url = ensure_empty_path(@root_url)
     end
 
+
+    protected
+
+    # Returns the full URL of the websocket endpoint to connect to.
+    # @return [String]
+
+    def build_websocket_url
+      params = @cursor ? @params.merge(cursor: @cursor) : @params
+      query = URI.encode_www_form(params)
+
+      @root_url + "/subscribe" + (query.length > 0 ? "?#{query}" : '')
+    end
+
+    # Processes a single message received from the websocket. Passes the received data to the
+    # {#on_raw_message} handler, builds a {Skyfall::Jetstream::Message} object, and passes it to
+    # the {#on_message} handler (if defined). Also updates the {#cursor} to this message's
+    # microsecond timestamp (note: this is skipped if {#on_message} is not set).
+    #
+    # @param msg
+    #   {https://rubydoc.info/gems/faye-websocket/Faye/WebSocket/API/MessageEvent Faye::WebSocket::API::MessageEvent}
+    # @return [nil]
+
     def handle_message(msg)
       data = msg.data
       @handlers[:raw_message]&.call(data)
@@ -30,14 +123,8 @@ module Skyfall
       end
     end
 
-    private
 
-    def build_websocket_url
-      params = @cursor ? @params.merge(cursor: @cursor) : @params
-      query = URI.encode_www_form(params)
-
-      @root_url + "/subscribe" + (query.length > 0 ? "?#{query}" : '')
-    end
+    private
 
     def check_params(params)
       params ||= {}

data/lib/skyfall/label.rb

@@ -1,10 +1,34 @@
+# frozen_string_literal: true
+
 require_relative 'errors'
+require 'oxygene'
 require 'time'
 
 module Skyfall
+
+  #
+  # A single label emitted from the "subscribeLabels" firehose of a labeller service.
+  #
+  # The label assigns some specific value - from a list of available values defined by this
+  # labeller - to a specific target (at:// URI or a DID). In general, this will usually be either
+  # a "badge" that a user requested to be assigned to themselves from a fun/informative labeller,
+  # or some kind of (likely negative) label assigned to a user or post by a moderation labeller.
+  #
+  # You generally don't need to create instances of this class manually, but will receive them
+  # from {Skyfall::Firehose} that's connected to `:subscribe_labels` in the {Stream#on_message}
+  # callback handler (wrapped in a {Skyfall::Firehose::LabelsMessage}).
+  #
+
   class Label
+
+    # @return [Hash] the label's JSON data
     attr_reader :data
 
+    #
+    # @param data [Hash] raw label JSON
+    # @raise [Skyfall::DecodeError] if the data has an invalid format
+    # @raise [Skyfall::UnsupportedError] if the label is in an unsupported future version
+    #
     def initialize(data)
       @data = data
 
@@ -20,34 +44,44 @@ module Skyfall
       raise DecodeError.new("Invalid uri: #{uri}") unless uri.start_with?('at://') || uri.start_with?('did:')
     end
 
+    # @return [Integer] label format version number
     def version
       @data['ver']
     end
 
+    # DID of the labelling authority (the labeller service).
+    # @return [String]
     def authority
       @data['src']
     end
 
+    # AT URI or DID of the labelled subject (e.g. a user or post).
+    # @return [String]
     def subject
       @data['uri']
     end
 
+    # @return [Oxygene::CID, nil] CID of the specific version of the subject that this label applies to
     def cid
-      @cid ||= @data['cid'] && CID.from_json(@data['cid'])
+      @cid ||= @data['cid'] && Oxygene::CID.from_json(@data['cid'])
     end
 
+    # @return [String] label value
     def value
       @data['val']
     end
 
+    # @return [Boolean] if true, then this is a negation (delete) of an existing label
     def negation?
       !!@data['neg']
     end
 
+    # @return [Time] timestamp when the label was created
     def created_at
       @created_at ||= Time.parse(@data['cts'])
     end
 
+    # @return [Time, nil] optional timestamp when the label expires
     def expires_at
       @expires_at ||= @data['exp'] && Time.parse(@data['exp'])
     end