skyfall 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3917568c1283d599d3103b428599141e04d0df2cce33c4b17291bc935b8add4d
-  data.tar.gz: 329dd70a2f17bb689fa0a10c6646c7f522c1ac165b1e0ef49f96cd5b6d746d57
+  metadata.gz: 34e2166dc123a74140ce5cae67d3c000c1f88972d15cbe8a2550bde11ba4034d
+  data.tar.gz: 334f4b8b0ddce03b2258a0266e01e08cac9528924ac13380e91b66a0bb1217b8
 SHA512:
-  metadata.gz: '09e6812b1234a0f7e4aeab3dee4fe962b47a781d7ddcf1151b1f310558e72837808caee9c1ca0d4e98f7e137e7147b72c8bdcd9ae17501c48f1d1dcc1a32ca35'
-  data.tar.gz: 5c558d41a7fc49ecc34273a791dc26a706c00708ca0b00b09a59d5bdc4684ff4f14611c065e35343f65d7989a948e5294b7c9edc55b41426f5b2eae893bea392
+  metadata.gz: f56ab132941d80a577e5f3ba630b58d6f99548d0cde398fdb4f15e7c24d9557c3b0243d64a3940c18bf370afb219df3282c935300fc0359b6b0e00915b7002ca
+  data.tar.gz: 4bd7672a9450d8b1ec80ec679b69e6ba4242c4a6554865e296e7a347769795239b99a95539fe0b637407c2736b0716dfc8d1c3a9dea2d8d7a9654b47158262c9

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [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
+
+## [0.2.5] - 2024-03-14
+
+- added `:bsky_labeler` record type symbol & collection constant
+
+## [0.2.4] - 2024-02-27
+
+- added support for `#identity` message type
+- added `Operation#did` as an alias of `#repo`
+- added `Stream#reconnect` method which forces the websocket to reconnect
+- added some validation for the `cursor` parameter in `Stream` initializer
+- the `server` parameter in `Stream` initializer can be a full URL with scheme, which lets you connect to e.g. `ws://localhost` (since by default, `wss://` is used)
+- tweaked `#inspect` output of `Stream` and `Operation`
+
 ## [0.2.3] - 2023-09-28
 
 - fixed encoding of image CIDs again (they should be wrapped in a `$link` object)

data/README.md

@@ -22,7 +22,7 @@ Start a connection to the firehose by creating a `Skyfall::Stream` object, passi
 ```rb
 require 'skyfall'
 
-sky = Skyfall::Stream.new('bsky.social', :subscribe_repos)
+sky = Skyfall::Stream.new('bsky.network', :subscribe_repos)
 ```
 
 Add event listeners to handle incoming messages and get notified of errors:
@@ -44,27 +44,53 @@ sky.connect
 
 ### Processing messages
 
-Each message passed to `on_message` is an instance of the `WebsocketMessage` class and has such properties:
+Each message passed to `on_message` is an instance of a subclass of `WebsocketMessage`, depending on the message type. The supported message types are:
+
+- `CommitMessage` (`#commit`) - represents a change in a user's repo; most messages are of this type
+- `HandleMessage` (`#handle`) - when a different handle is assigned to a user's DID
+- `TombstoneMessage` (`#tombstone`) - when an account is deleted
+- `InfoMessage` (`#info`) - a protocol error message, e.g. about an invalid cursor parameter
+- `UnknownMessage` is used for other unrecognized message types
+
+All message objects have the following properties:
+
+- `type` (symbol) - the message type identifier, e.g. `:commit`
+- `seq` (integer) - a sequential index of the message
+- `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:
 
-- `type` (symbol) - usually `:commit`
-- `seq` (sequential number)
-- `time` (Time)
-- `repo` (string) - DID of the repository (user account)
 - `commit` - CID of the commit
 - `prev` - CID of the previous commit in that repo
 - `operations` - list of operations (usually one)
 
+Handle messages additionally have:
+
+- `handle` - the new handle assigned to the DID
+
+Info messages additionally have:
+
+- `name` - identifier of the message/error
+- `message` - a human-readable description
+
+
+### Commit operations
+
 Operations are objects of type `Operation` and have such properties:
 
-- `repo` (string) - DID of the repository (user account)
+- `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`
-- `uri` (string) - the at:// URI
-- `type` (symbol) - short name of the collection, e.g. `:bsky_post`
 - `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 a later version).
+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).
 
 So for example, in order to filter only "create post" operations and print their details, you can do something like this:
 
@@ -82,7 +108,16 @@ sky.on_message do |m|
 end
 ```
 
-See complete example in [example/firehose.rb](https://github.com/mackuba/skyfall/blob/master/example/firehose.rb).
+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.
+
+
+### Custom lexicons
+
+A note on custom lexicons: the `Skyfall::Operation` objects have two properties that tell you the kind of record they're about: `#collection`, which is a string containing the official name of the collection/lexicon, e.g. `"app.bsky.feed.post"`; and `#type`, which is a symbol meant to save you some typing, e.g. `:bsky_post`.
+
+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.
 
 
 ## Credits

data/example/block_tracker.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+
+# Example: monitor the network for people blocking your account or adding you to mute lists.
+
+# load skyfall from a local folder - you normally won't need this
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'json'
+require 'open-uri'
+require 'skyfall'
+
+$monitored_did = ARGV[0]
+
+if $monitored_did.to_s.empty?
+  puts "Usage: #{$PROGRAM_NAME} <monitored_did>"
+  exit 1
+elsif ARGV[0] !~ /^did:plc:[a-z0-9]{24}$/
+  puts "Not a valid DID: #{$monitored_did}"
+  exit 1
+end
+
+sky = Skyfall::Stream.new('bsky.network', :subscribe_repos)
+
+sky.on_connect { puts "Connected, monitoring #{$monitored_did}" }
+sky.on_disconnect { puts "Disconnected" }
+sky.on_reconnect { puts "Reconnecting..." }
+sky.on_error { |e| puts "ERROR: #{e}" }
+
+sky.on_message do |msg|
+  # we're only interested in repo commit messages
+  next if msg.type != :commit
+
+  msg.operations.each do |op|
+    next if op.action != :create
+
+    begin
+      case op.type
+      when :bsky_block
+        process_block(msg, op)
+      when :bsky_listitem
+        process_list_item(msg, op)
+      end
+    rescue StandardError => e
+      puts "Error: #{e}"
+    end
+  end
+end
+
+def process_block(msg, op)
+  if op.raw_record['subject'] == $monitored_did
+    owner_handle = get_user_handle(op.repo)
+    puts "@#{owner_handle} has blocked you! (#{msg.time.getlocal})"
+  end
+end
+
+def process_list_item(msg, op)
+  if op.raw_record['subject'] == $monitored_did
+    owner_handle = get_user_handle(op.repo)
+
+    list_uri = op.raw_record['list']
+    list_name = get_list_name(list_uri)
+
+    puts "@#{owner_handle} has added you to list \"#{list_name}\" (#{msg.time.getlocal})"
+  end
+end
+
+def get_user_handle(did)
+  url = "https://plc.directory/#{did}"
+  json = JSON.parse(URI.open(url).read)
+  json['alsoKnownAs'][0].gsub('at://', '')
+end
+
+def get_list_name(list_uri)
+  repo, type, rkey = list_uri.gsub('at://', '').split('/')
+  url = "https://bsky.social/xrpc/com.atproto.repo.getRecord?repo=#{repo}&collection=#{type}&rkey=#{rkey}"
+
+  json = JSON.parse(URI.open(url).read)
+  json['value']['name']
+end
+
+# close the connection cleanly on Ctrl+C
+trap("SIGINT") { sky.disconnect }
+
+sky.connect

data/example/monitor_phrases.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+# Example: monitor new posts for mentions of one or more words or phrases (e.g. anyone mentioning your name or the name
+# of your company, project etc.).
+
+# load skyfall from a local folder - you normally won't need this
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'json'
+require 'open-uri'
+require 'skyfall'
+
+terms = ARGV.map(&:downcase)
+
+if terms.empty?
+  puts "Usage: #{$PROGRAM_NAME} <word_or_phrase> [<word_or_phrase>...]"
+  exit 1
+end
+
+sky = Skyfall::Stream.new('bsky.network', :subscribe_repos)
+
+sky.on_message do |msg|
+  # we're only interested in repo commit messages
+  next if msg.type != :commit
+
+  msg.operations.each do |op|
+    # ignore any operations other than "create post"
+    next unless op.action == :create && op.type == :bsky_post
+
+    text = op.raw_record['text'].to_s.downcase
+
+    if terms.any? { |x| text.include?(x) }
+      owner_handle = get_user_handle(op.repo)
+      puts "\n#{msg.time.getlocal} @#{owner_handle}: #{op.raw_record['text']}"
+    end
+  end
+end
+
+def get_user_handle(did)
+  url = "https://plc.directory/#{did}"
+  json = JSON.parse(URI.open(url).read)
+  json['alsoKnownAs'][0].gsub('at://', '')
+end
+
+sky.on_connect { puts "Connected" }
+sky.on_disconnect { puts "Disconnected" }
+sky.on_reconnect { puts "Reconnecting..." }
+sky.on_error { |e| puts "ERROR: #{e}" }
+
+# close the connection cleanly on Ctrl+C
+trap("SIGINT") { sky.disconnect }
+
+sky.connect

data/example/print_all_posts.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+
+# Example: print the date and text of every new post made on the network as they appear.
+
+# load skyfall from a local folder - you normally won't need this
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'skyfall'
+
+sky = Skyfall::Stream.new('bsky.network', :subscribe_repos)
+
+sky.on_message do |msg|
+  # we're only interested in repo commit messages
+  next if msg.type != :commit
+
+  msg.operations.each do |op|
+    # ignore any operations other than "create post"
+    next unless op.action == :create && op.type == :bsky_post
+
+    puts "#{op.repo} • #{msg.time.getlocal}"
+    puts op.raw_record['text']
+    puts
+  end
+end
+
+sky.on_connect { puts "Connected" }
+sky.on_disconnect { puts "Disconnected" }
+sky.on_reconnect { puts "Reconnecting..." }
+sky.on_error { |e| puts "ERROR: #{e}" }
+
+# close the connection cleanly on Ctrl+C
+trap("SIGINT") { sky.disconnect }
+
+sky.connect

data/example/push_notifications.rb

@@ -0,0 +1,262 @@
+#!/usr/bin/env ruby
+
+# Example: send push notifications to a client app about interactions with a given account.
+
+# load skyfall from a local folder - you normally won't need this
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'json'
+require 'open-uri'
+require 'skyfall'
+
+monitored_did = ARGV[0]
+
+if monitored_did.to_s.empty?
+  puts "Usage: #{$PROGRAM_NAME} <monitored_did>"
+  exit 1
+elsif monitored_did !~ /^did:plc:[a-z0-9]{24}$/
+  puts "Not a valid DID: #{monitored_did}"
+  exit 1
+end
+
+class InvalidURIException < StandardError
+  def initialize(uri)
+    super("Invalid AT URI: #{uri}")
+  end
+end
+
+class AtURI
+  attr_reader :did, :collection, :rkey
+
+  def initialize(uri)
+    if uri =~ /\Aat:\/\/(did:[\w]+:[\w\.\-]+)\/([\w\.]+)\/([\w\-]+)\z/
+      @did = $1
+      @collection = $2
+      @rkey = $3
+    else
+      raise InvalidURIException, uri
+    end
+  end
+end
+
+class NotificationEngine
+  def initialize(user_did)
+    @user_did = user_did
+  end
+
+  def connect
+    @sky = Skyfall::Stream.new('bsky.network', :subscribe_repos)
+
+    @sky.on_connect { puts "Connected, monitoring #{@user_did}" }
+    @sky.on_disconnect { puts "Disconnected" }
+    @sky.on_reconnect { puts "Reconnecting..." }
+    @sky.on_error { |e| puts "ERROR: #{e}" }
+
+    @sky.on_message do |msg|
+      process_message(msg)
+    end
+
+    @sky.connect
+  end
+
+  def disconnect
+    @sky.disconnect
+  end
+
+  def process_message(msg)
+    # we're only interested in repo commit messages
+    return if msg.type != :commit
+
+    # ignore user's own actions
+    return if msg.repo == @user_did
+
+    msg.operations.each do |op|
+      next if op.action != :create
+
+      begin
+        case op.type
+        when :bsky_post
+          process_post(msg, op)
+        when :bsky_like
+          process_like(msg, op)
+        when :bsky_repost
+          process_repost(msg, op)
+        when :bsky_follow
+          process_follow(msg, op)
+        end
+      rescue StandardError => e
+        puts "Error: #{e}"
+      end
+    end
+  end
+
+
+  # posts
+
+  def process_post(msg, op)
+    data = op.raw_record
+
+    if reply = data['reply']
+      # check for replies (direct only)
+      if reply['parent'] && reply['parent']['uri']
+        parent_uri = AtURI.new(reply['parent']['uri'])
+
+        if parent_uri.did == @user_did
+          send_reply_notification(msg, op)
+        end
+      end
+    end
+
+    if embed = data['embed']
+      # check for quotes
+      if embed['record'] && embed['record']['uri']
+        quoted_uri = AtURI.new(embed['record']['uri'])
+
+        if quoted_uri.did == @user_did
+          send_quote_notification(msg, op)
+        end
+      end
+
+      # second type of quote (recordWithMedia)
+      if embed['record'] && embed['record']['record'] && embed['record']['record']['uri']
+        quoted_uri = AtURI.new(embed['record']['record']['uri'])
+
+        if quoted_uri.did == @user_did
+          send_quote_notification(msg, op)
+        end
+      end
+    end
+
+    if facets = data['facets']
+      # check for mentions
+      if facets.any? { |f| f['features'] && f['features'].any? { |x| x['did'] == @user_did }}
+        send_mention_notification(msg, op)
+      end
+    end
+  end
+
+  def send_reply_notification(msg, op)
+    handle = get_user_handle(msg.repo)
+
+    send_push("@#{handle} replied:", op.raw_record)
+  end
+
+  def send_quote_notification(msg, op)
+    handle = get_user_handle(msg.repo)
+
+    send_push("@#{handle} quoted you:", op.raw_record)
+  end
+
+  def send_mention_notification(msg, op)
+    handle = get_user_handle(msg.repo)
+
+    send_push("@#{handle} mentioned you:", op.raw_record)
+  end
+
+
+  # likes
+
+  def process_like(msg, op)
+    data = op.raw_record
+
+    if data['subject'] && data['subject']['uri']
+      liked_uri = AtURI.new(data['subject']['uri'])
+
+      if liked_uri.did == @user_did
+        case liked_uri.collection
+        when 'app.bsky.feed.post'
+          send_post_like_notification(msg, liked_uri)
+        when 'app.bsky.feed.generator'
+          send_feed_like_notification(msg, liked_uri)
+        end
+      end
+    end
+  end
+
+  def send_post_like_notification(msg, uri)
+    handle = get_user_handle(msg.repo)
+    post = get_record(uri)
+
+    send_push("@#{handle} liked your post", post)
+  end
+
+  def send_feed_like_notification(msg, uri)
+    handle = get_user_handle(msg.repo)
+    feed = get_record(uri)
+
+    send_push("@#{handle} liked your feed", feed)
+  end
+
+
+  # reposts
+
+  def process_repost(msg, op)
+    data = op.raw_record
+
+    if data['subject'] && data['subject']['uri']
+      reposted_uri = AtURI.new(data['subject']['uri'])
+
+      if reposted_uri.did == @user_did && reposted_uri.collection == 'app.bsky.feed.post'
+        send_repost_notification(msg, reposted_uri)
+      end
+    end
+  end
+
+  def send_repost_notification(msg, uri)
+    handle = get_user_handle(msg.repo)
+    post = get_record(uri)
+
+    send_push("@#{handle} reposted your post", post)
+  end
+
+
+  # follows
+
+  def process_follow(msg, op)
+    if op.raw_record['subject'] == @user_did
+      send_follow_notification(msg)
+    end
+  end
+
+  def send_follow_notification(msg)
+    handle = get_user_handle(msg.repo)
+
+    send_push("@#{handle} followed you", msg.repo)
+  end
+
+
+  #
+  # Note: in this example, we're calling the Bluesky AppView to get details about the person interacting with the user
+  # and the post/feed that was liked/reposted etc. In a real app, you might run into rate limits if you do that,
+  # because these requests will all be sent from the server's IP.
+  #
+  # So you might need to take a different route and send just the info that you have here in the push notification data
+  # (the AT URI / DID) and fetch the details on the client side, e.g. in a Notification Service Extension on iOS.
+  #
+
+  def get_user_handle(did)
+    url = "https://api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=#{did}"
+    json = JSON.parse(URI.open(url).read)
+    json['handle']
+  end
+
+  def get_record(uri)
+    url = "https://api.bsky.app/xrpc/com.atproto.repo.getRecord?" +
+          "repo=#{uri.did}&collection=#{uri.collection}&rkey=#{uri.rkey}"
+    json = JSON.parse(URI.open(url).read)
+    json['value']
+  end
+
+  def send_push(message, data = nil)
+    # send the message to APNS/FCM here
+    puts
+    puts "[#{Time.now}] #{message} #{data&.inspect}"
+  end
+end
+
+engine = NotificationEngine.new(monitored_did)
+
+# close the connection cleanly on Ctrl+C
+trap("SIGINT") { engine.disconnect }
+
+engine.connect

data/lib/skyfall/collection.rb

@@ -11,5 +11,6 @@ module Skyfall
     BSKY_LIST       = "app.bsky.graph.list"
     BSKY_LISTBLOCK  = "app.bsky.graph.listblock"
     BSKY_LISTITEM   = "app.bsky.graph.listitem"
+    BSKY_LABELER    = "app.bsky.labeler.service"
   end
 end

data/lib/skyfall/label.rb

@@ -0,0 +1,63 @@
+require_relative 'errors'
+require 'time'
+
+module Skyfall
+  class Label
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+
+      raise DecodeError.new("Missing version: #{data}") unless data.has_key?('ver')
+      raise DecodeError.new("Invalid version: #{ver}") unless ver.is_a?(Integer) && ver >= 1
+      raise UnsupportedError.new("Unsupported version: #{ver}") unless ver == 1
+
+      raise DecodeError.new("Missing source: #{data}") unless data.has_key?('src')
+      raise DecodeError.new("Invalid source: #{src}") unless src.is_a?(String) && src.start_with?('did:')
+
+      raise DecodeError.new("Missing uri: #{data}") unless data.has_key?('uri')
+      raise DecodeError.new("Invalid uri: #{uri}") unless uri.is_a?(String)
+      raise DecodeError.new("Invalid uri: #{uri}") unless uri.start_with?('at://') || uri.start_with?('did:')
+    end
+
+    def version
+      @data['ver']
+    end
+
+    def authority
+      @data['src']
+    end
+
+    def subject
+      @data['uri']
+    end
+
+    def cid
+      @cid ||= @data['cid'] && CID.from_json(@data['cid'])
+    end
+
+    def value
+      @data['val']
+    end
+
+    def negation?
+      !!@data['neg']
+    end
+
+    def created_at
+      @created_at ||= Time.parse(@data['cts'])
+    end
+
+    def expires_at
+      @expires_at ||= @data['exp'] && Time.parse(@data['exp'])
+    end
+
+    alias ver version
+    alias src authority
+    alias uri subject
+    alias val value
+    alias neg negation?
+    alias cts created_at
+    alias exp expires_at
+  end
+end

data/lib/skyfall/messages/identity_message.rb

@@ -0,0 +1,4 @@
+module Skyfall
+  class IdentityMessage < WebsocketMessage
+  end
+end

data/lib/skyfall/messages/labels_message.rb

@@ -0,0 +1,23 @@
+require_relative 'websocket_message'
+require_relative '../label'
+
+module Skyfall
+  class LabelsMessage
+    using Skyfall::Extensions
+
+    attr_reader :type_object, :data_object
+    attr_reader :type, :seq
+
+    def initialize(type_object, data_object)
+      @type_object = type_object
+      @data_object = data_object
+
+      @type = @type_object['t'][1..-1].to_sym
+      @seq = @data_object['seq']
+    end
+
+    def labels
+      @labels ||= @data_object['labels'].map { |x| Label.new(x) }
+    end
+  end
+end

data/lib/skyfall/messages/websocket_message.rb

@@ -10,7 +10,9 @@ module Skyfall
 
     require_relative 'commit_message'
     require_relative 'handle_message'
+    require_relative 'identity_message'
     require_relative 'info_message'
+    require_relative 'labels_message'
     require_relative 'tombstone_message'
     require_relative 'unknown_message'
 
@@ -25,7 +27,9 @@ module Skyfall
       message_class = case type_object['t']
         when '#commit' then CommitMessage
         when '#handle' then HandleMessage
+        when '#identity' then IdentityMessage
         when '#info' then InfoMessage
+        when '#labels' then LabelsMessage
         when '#tombstone' then TombstoneMessage
         else UnknownMessage
       end

data/lib/skyfall/operation.rb

@@ -11,6 +11,8 @@ module Skyfall
       @message.repo
     end
 
+    alias did repo
+
     def path
       @json['path']
     end
@@ -44,6 +46,7 @@ module Skyfall
       when Collection::BSKY_BLOCK      then :bsky_block
       when Collection::BSKY_FEED       then :bsky_feed
       when Collection::BSKY_FOLLOW     then :bsky_follow
+      when Collection::BSKY_LABELER    then :bsky_labeler
       when Collection::BSKY_LIKE       then :bsky_like
       when Collection::BSKY_LIST       then :bsky_list
       when Collection::BSKY_LISTBLOCK  then :bsky_listblock
@@ -55,5 +58,14 @@ module Skyfall
       else :unknown
       end
     end
+
+    def inspectable_variables
+      instance_variables - [:@message]
+    end
+
+    def inspect
+      vars = inspectable_variables.map { |v| "#{v}=#{instance_variable_get(v).inspect}" }.join(", ")
+      "#<#{self.class}:0x#{object_id} #{vars}>"
+    end
   end
 end

data/lib/skyfall/stream.rb

@@ -7,26 +7,28 @@ require 'uri'
 module Skyfall
   class Stream
     SUBSCRIBE_REPOS = "com.atproto.sync.subscribeRepos"
+    SUBSCRIBE_LABELS = "com.atproto.label.subscribeLabels"
 
     NAMED_ENDPOINTS = {
-      :subscribe_repos => SUBSCRIBE_REPOS
+      :subscribe_repos => SUBSCRIBE_REPOS,
+      :subscribe_labels => SUBSCRIBE_LABELS
     }
 
+    EVENTS = %w(message raw_message connecting connect disconnect reconnect error)
+
     MAX_RECONNECT_INTERVAL = 300
 
     attr_accessor :heartbeat_timeout, :heartbeat_interval, :cursor, :auto_reconnect
 
     def initialize(server, endpoint, cursor = nil)
       @endpoint = check_endpoint(endpoint)
-      @server = check_hostname(server)
-      @cursor = cursor
+      @root_url = build_root_url(server)
+      @cursor = check_cursor(cursor)
       @handlers = {}
-      @heartbeat_mutex = Mutex.new
-      @heartbeat_interval = 5
-      @heartbeat_timeout = 30
-      @last_update = nil
       @auto_reconnect = true
       @connection_attempts = 0
+
+      @handlers[:error] = proc { |e| puts "ERROR: #{e}" }
     end
 
     def connect
@@ -37,6 +39,9 @@ module Skyfall
       @handlers[:connecting]&.call(url)
       @engines_on = true
 
+      @reconnect_timer&.cancel
+      @reconnect_timer = nil
+
       EM.run do
         EventMachine.error_handler do |e|
           @handlers[:error]&.call(e)
@@ -49,6 +54,7 @@ module Skyfall
         end
 
         @ws.on(:message) do |msg|
+          @reconnecting = false
           @connection_attempts = 0
 
           data = msg.data.pack('C*')
@@ -70,10 +76,12 @@ module Skyfall
         @ws.on(:close) do |e|
           @ws = nil
 
-          if @auto_reconnect && @engines_on
-            EM.add_timer(reconnect_delay) do
+          if @reconnecting || @auto_reconnect && @engines_on
+            @handlers[:reconnect]&.call
+
+            @reconnect_timer&.cancel
+            @reconnect_timer = EM::Timer.new(reconnect_delay) do
               @connection_attempts += 1
-              @handlers[:reconnect]&.call
               connect
             end
           else
@@ -85,41 +93,40 @@ module Skyfall
       end
     end
 
+    def reconnect
+      @reconnecting = true
+      @connection_attempts = 0
+
+      @ws ? @ws.close : connect
+    end
+
     def disconnect
       return unless EM.reactor_running?
 
+      @reconnecting = false
       @engines_on = false
       EM.stop_event_loop
     end
 
     alias close disconnect
 
-    def on_message(&block)
-      @handlers[:message] = block
-    end
-
-    def on_raw_message(&block)
-      @handlers[:raw_message] = block
-    end
-
-    def on_connecting(&block)
-      @handlers[:connecting] = block
-    end
-
-    def on_connect(&block)
-      @handlers[:connect] = block
-    end
+    EVENTS.each do |event|
+      define_method "on_#{event}" do |&block|
+        @handlers[event.to_sym] = block
+      end
 
-    def on_disconnect(&block)
-      @handlers[:disconnect] = block
+      define_method "on_#{event}=" do |block|
+        @handlers[event.to_sym] = block
+      end
     end
 
-    def on_error(&block)
-      @handlers[:error] = block
+    def inspectable_variables
+      instance_variables - [:@handlers, :@ws]
     end
 
-    def on_reconnect(&block)
-      @handlers[:reconnect] = block
+    def inspect
+      vars = inspectable_variables.map { |v| "#{v}=#{instance_variable_get(v).inspect}" }.join(", ")
+      "#<#{self.class}:0x#{object_id} #{vars}>"
     end
 
 
@@ -134,32 +141,44 @@ module Skyfall
     end
 
     def build_websocket_url
-      url = "wss://#{@server}/xrpc/#{@endpoint}"
-      url += "?cursor=#{@cursor}" if @cursor
-      url
+      @root_url + "/xrpc/" + @endpoint + (@cursor ? "?cursor=#{@cursor}" : "")
+    end
+
+    def check_cursor(cursor)
+      if cursor.nil?
+        nil
+      elsif cursor.is_a?(Integer) || cursor.is_a?(String) && cursor =~ /^[0-9]+$/
+        cursor.to_i
+      else
+        raise ArgumentError, "Invalid cursor: #{cursor.inspect} - cursor must be an integer number"
+      end
     end
 
     def check_endpoint(endpoint)
       if endpoint.is_a?(String)
-        raise ArgumentError("Invalid endpoint name: #{endpoint}") if endpoint.strip.empty? || !endpoint.include?('.')
+        raise ArgumentError.new("Invalid endpoint name: #{endpoint}") if endpoint.strip == '' || !endpoint.include?('.')
       elsif endpoint.is_a?(Symbol)
-        raise ArgumentError("Unknown endpoint: #{endpoint}") if NAMED_ENDPOINTS[endpoint].nil?
+        raise ArgumentError.new("Unknown endpoint: #{endpoint}") if NAMED_ENDPOINTS[endpoint].nil?
         endpoint = NAMED_ENDPOINTS[endpoint]
       else
-        raise ArgumentError("Endpoint should be a string or a symbol")
+        raise ArgumentError, "Endpoint should be a string or a symbol"
       end
 
       endpoint
     end
 
-    def check_hostname(server)
+    def build_root_url(server)
       if server.is_a?(String)
-        raise ArgumentError("Invalid server name: #{server}") if server.strip.empty? || server.include?('/')
+        if server.start_with?('ws://') || server.start_with?('wss://')
+          server
+        elsif server.strip.empty? || server.include?('/')
+          raise ArgumentError, "Server parameter should be a hostname or a ws:// or wss:// URL"
+        else
+          "wss://#{server}"
+        end
       else
-        raise ArgumentError("Server name should be a string")
+        raise ArgumentError, "Server parameter should be a string"
       end
-
-      server
     end
   end
 end

data/lib/skyfall/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Skyfall
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skyfall
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Kuba Suder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-28 00:00:00.000000000 Z
+date: 2024-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32
@@ -50,20 +50,96 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.5.9.6
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.7
 - !ruby/object:Gem::Dependency
   name: faye-websocket
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.2
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: stringio
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: uri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.2
+        version: '0.13'
 description: "\n    Skyfall is a Ruby library for connecting to the \"firehose\" of
   the Bluesky social network, i.e. a websocket which\n    streams all new posts and
   everything else happening on the Bluesky network in real time. The code connects
@@ -79,16 +155,22 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- example/firehose.rb
+- example/block_tracker.rb
+- example/monitor_phrases.rb
+- example/print_all_posts.rb
+- example/push_notifications.rb
 - lib/skyfall.rb
 - lib/skyfall/car_archive.rb
 - lib/skyfall/cid.rb
 - lib/skyfall/collection.rb
 - lib/skyfall/errors.rb
 - lib/skyfall/extensions.rb
+- lib/skyfall/label.rb
 - lib/skyfall/messages/commit_message.rb
 - lib/skyfall/messages/handle_message.rb
+- lib/skyfall/messages/identity_message.rb
 - lib/skyfall/messages/info_message.rb
+- lib/skyfall/messages/labels_message.rb
 - lib/skyfall/messages/tombstone_message.rb
 - lib/skyfall/messages/unknown_message.rb
 - lib/skyfall/messages/websocket_message.rb

data/example/firehose.rb

@@ -1,27 +0,0 @@
-#!/usr/bin/env ruby
-
-lib = File.expand_path('../../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-
-require 'skyfall'
-
-sky = Skyfall::Stream.new('bsky.social', :subscribe_repos)
-
-sky.on_message do |m|
-  next if m.type != :commit
-
-  m.operations.each do |op|
-    next unless op.action == :create && op.type == :bsky_post
-
-    puts "#{op.repo}:"
-    puts op.raw_record['text']
-    puts
-  end
-end
-
-sky.on_connect { puts "Connected" }
-sky.on_disconnect { puts "Disconnected" }
-sky.on_reconnect { puts "Reconnecting..." }
-sky.on_error { |e| puts "ERROR: #{e}" }
-
-sky.connect