skyfall 0.4.1 → 0.5.0

data/lib/skyfall/firehose.rb

@@ -0,0 +1,79 @@
+require_relative 'stream'
+require 'uri'
+
+module Skyfall
+  class Firehose < Stream
+    SUBSCRIBE_REPOS = "com.atproto.sync.subscribeRepos"
+    SUBSCRIBE_LABELS = "com.atproto.label.subscribeLabels"
+
+    NAMED_ENDPOINTS = {
+      :subscribe_repos => SUBSCRIBE_REPOS,
+      :subscribe_labels => SUBSCRIBE_LABELS
+    }
+
+    attr_accessor :cursor
+
+    def self.new(server, endpoint, cursor = nil)
+      # to be removed in 0.6
+      instance = self.allocate
+      instance.send(:initialize, server, endpoint, cursor)
+      instance
+    end
+
+    def initialize(server, endpoint, cursor = nil)
+      require_relative 'firehose/message'
+      super(server)
+
+      @endpoint = check_endpoint(endpoint)
+      @cursor = check_cursor(cursor)
+      @root_url = @root_url.chomp('/')
+
+      if URI(@root_url).path != ''
+        raise ArgumentError, "Server parameter should not include any path"
+      end
+    end
+
+    def handle_message(msg)
+      data = msg.data.pack('C*')
+      @handlers[:raw_message]&.call(data)
+
+      if @handlers[:message]
+        atp_message = Message.new(data)
+        @cursor = atp_message.seq
+        @handlers[:message].call(atp_message)
+      else
+        @cursor = nil
+      end
+    end
+
+
+    private
+
+    def build_websocket_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.new("Invalid endpoint name: #{endpoint}") if endpoint.strip == '' || !endpoint.include?('.')
+      elsif endpoint.is_a?(Symbol)
+        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"
+      end
+
+      endpoint
+    end
+  end
+end

data/lib/skyfall/jetstream/account_message.rb

@@ -0,0 +1,19 @@
+require_relative '../errors'
+require_relative '../jetstream'
+
+module Skyfall
+  class Jetstream::AccountMessage < Jetstream::Message
+    def initialize(json)
+      raise DecodeError.new("Missing event details") if json['account'].nil?
+      super
+    end
+
+    def active?
+      @json['account']['active']
+    end
+
+    def status
+      @json['account']['status']&.to_sym
+    end
+  end
+end

data/lib/skyfall/jetstream/commit_message.rb

@@ -0,0 +1,16 @@
+require_relative '../errors'
+require_relative '../jetstream'
+require_relative 'operation'
+
+module Skyfall
+  class Jetstream::CommitMessage < Jetstream::Message
+    def initialize(json)
+      raise DecodeError.new("Missing event details") if json['commit'].nil?
+      super
+    end
+
+    def operations
+      @operations ||= [Jetstream::Operation.new(self, json['commit'])]
+    end
+  end
+end

data/lib/skyfall/jetstream/identity_message.rb

@@ -0,0 +1,15 @@
+require_relative '../errors'
+require_relative '../jetstream'
+
+module Skyfall
+  class Jetstream::IdentityMessage < Jetstream::Message
+    def initialize(json)
+      raise DecodeError.new("Missing event details") if json['identity'].nil?
+      super
+    end
+
+    def handle
+      @json['identity']['handle']
+    end
+  end
+end

data/lib/skyfall/jetstream/message.rb

@@ -0,0 +1,50 @@
+require_relative '../errors'
+require_relative '../jetstream'
+
+require 'time'
+
+module Skyfall
+  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
+    alias repo did
+    alias seq time_us
+
+    # :nodoc: - consider this as semi-private API
+    attr_reader :json
+
+    def self.new(data)
+      json = JSON.parse(data)
+
+      message_class = case json['kind']
+        when 'account'  then Jetstream::AccountMessage
+        when 'commit'   then Jetstream::CommitMessage
+        when 'identity' then Jetstream::IdentityMessage
+        else Jetstream::UnknownMessage
+      end
+
+      message = message_class.allocate
+      message.send(:initialize, json)
+      message
+    end
+
+    def initialize(json)
+      @json = json
+      @type = @json['kind'].to_sym
+      @did = @json['did']
+      @time_us = @json['time_us']
+    end
+
+    def operations
+      []
+    end
+
+    def time
+      @time ||= @json['time_us'] && Time.at(@json['time_us'] / 1_000_000.0)
+    end
+  end
+end

data/lib/skyfall/jetstream/operation.rb

@@ -0,0 +1,58 @@
+require_relative '../collection'
+require_relative '../jetstream'
+
+module Skyfall
+  class Jetstream::Operation
+    def initialize(message, json)
+      @message = message
+      @json = json
+    end
+
+    def repo
+      @message.repo
+    end
+
+    alias did repo
+
+    def path
+      @json['collection'] + '/' + @json['rkey']
+    end
+
+    def action
+      @json['operation'].to_sym
+    end
+
+    def collection
+      @json['collection']
+    end
+
+    def rkey
+      @json['rkey']
+    end
+
+    def uri
+      "at://#{repo}/#{collection}/#{rkey}"
+    end
+
+    def cid
+      @cid ||= @json['cid'] && CID.from_json(@json['cid'])
+    end
+
+    def raw_record
+      @json['record']
+    end
+
+    def type
+      Collection.short_code(collection)
+    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/jetstream/unknown_message.rb

@@ -0,0 +1,6 @@
+require_relative '../jetstream'
+
+module Skyfall
+  class Jetstream::UnknownMessage < Jetstream::Message
+  end
+end

data/lib/skyfall/jetstream.rb

@@ -0,0 +1,121 @@
+require_relative 'stream'
+
+require 'json'
+require 'time'
+require 'uri'
+
+module Skyfall
+  class Jetstream < Stream
+    def self.new(server, params = {})
+      # to be removed in 0.6
+      instance = self.allocate
+      instance.send(:initialize, server, params)
+      instance
+    end
+
+    attr_accessor :cursor
+
+    def initialize(server, params = {})
+      require_relative 'jetstream/message'
+      super(server)
+
+      @root_url = @root_url.chomp('/')
+
+      if URI(@root_url).path != ''
+        raise ArgumentError, "Server parameter should not include any path"
+      end
+
+      @params = check_params(params)
+      @cursor = @params.delete(:cursor)
+    end
+
+    def handle_message(msg)
+      data = msg.data
+      @handlers[:raw_message]&.call(data)
+
+      if @handlers[:message]
+        jet_message = Message.new(data)
+        @cursor = jet_message.time_us
+        @handlers[:message].call(jet_message)
+      else
+        @cursor = nil
+      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
+
+    def check_params(params)
+      params ||= {}
+      processed = {}
+
+      raise ArgumentError.new("Params should be a hash") unless params.is_a?(Hash)
+
+      params.each do |k, v|
+        next if v.nil?
+
+        if k.is_a?(Symbol)
+          k = k.to_s
+        elsif !k.is_a?(String)
+          raise ArgumentError.new("Invalid params key: #{k.inspect}")
+        end
+
+        k = k.gsub(/_([a-zA-Z])/) { $1.upcase }.to_sym
+        processed[k] = check_option(k, v)
+      end
+
+      processed
+    end
+
+    def check_option(k, v)
+      case k
+      when :wantedCollections
+        check_wanted_collections(v)
+      when :wantedDids
+        check_wanted_dids(v)
+      when :cursor
+        check_cursor(v)
+      when :compress, :requireHello
+        raise ArgumentError.new("Skyfall::Jetstream doesn't support the #{k.inspect} option yet")
+      else
+        raise ArgumentError.new("Unknown option: #{k.inspect}")
+      end
+    end
+
+    def check_wanted_collections(list)
+      list = [list] unless list.is_a?(Array)
+
+      list.map do |c|
+        if c.is_a?(String)
+          # TODO: more validation
+          c
+        elsif c.is_a?(Symbol)
+          Collection.from_short_code(c) or raise ArgumentError.new("Unknown collection symbol: #{c.inspect}")
+        else
+          raise ArgumentError.new("Invalid collection argument: #{c.inspect}")
+        end
+      end
+    end
+
+    def check_wanted_dids(list)
+      list = [list] unless list.is_a?(Array)
+
+      if x = list.detect { |c| !c.is_a?(String) || c !~ /\Adid:[a-z]+:/ }
+        raise ArgumentError.new("Invalid DID argument: #{x.inspect}")
+      end
+
+      # TODO: more validation
+      list
+    end
+
+    def check_cursor(cursor)
+      cursor.to_i
+    end
+  end
+end

data/lib/skyfall/stream.rb

@@ -1,30 +1,30 @@
-require_relative 'messages/websocket_message'
-
 require 'eventmachine'
 require 'faye/websocket'
 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_labels => SUBSCRIBE_LABELS
-    }
-
     EVENTS = %w(message raw_message connecting connect disconnect reconnect error timeout)
-
     MAX_RECONNECT_INTERVAL = 300
 
-    attr_accessor :cursor, :auto_reconnect, :last_update, :user_agent
+    attr_accessor :auto_reconnect, :last_update, :user_agent
     attr_accessor :heartbeat_timeout, :heartbeat_interval, :check_heartbeat
 
-    def initialize(server, endpoint, cursor = nil)
-      @endpoint = check_endpoint(endpoint)
-      @root_url = build_root_url(server)
-      @cursor = check_cursor(cursor)
+    def self.new(server, endpoint = nil, cursor = nil)
+      # to be removed in 0.6
+      if endpoint || cursor
+        STDERR.puts "Warning: Skyfall::Stream has been renamed to Skyfall::Firehose. This initializer will be removed in the next version."
+        Firehose.new(server, endpoint, cursor)
+      else
+        instance = self.allocate
+        instance.send(:initialize, server)
+        instance
+      end
+    end
+
+    def initialize(service)
+      @root_url = build_root_url(service)
+
       @handlers = {}
       @auto_reconnect = true
       @check_heartbeat = false
@@ -65,17 +65,7 @@ module Skyfall
           @reconnecting = false
           @connection_attempts = 0
           @last_update = Time.now
-
-          data = msg.data.pack('C*')
-          @handlers[:raw_message]&.call(data)
-
-          if @handlers[:message]
-            atp_message = Skyfall::WebsocketMessage.new(data)
-            @cursor = atp_message.seq
-            @handlers[:message].call(atp_message)
-          else
-            @cursor = nil
-          end
+          handle_message(msg)
         end
 
         @ws.on(:error) do |e|
@@ -103,6 +93,11 @@ module Skyfall
       end
     end
 
+    def handle_message(msg)
+      data = msg.data
+      @handlers[:raw_message]&.call(data)
+    end
+
     def reconnect
       @reconnecting = true
       @connection_attempts = 0
@@ -121,6 +116,10 @@ module Skyfall
     alias close disconnect
 
     def default_user_agent
+      version_string
+    end
+
+    def version_string
       "Skyfall/#{Skyfall::VERSION}"
     end
 
@@ -185,43 +184,24 @@ module Skyfall
     end
 
     def build_websocket_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
+      @root_url
     end
 
-    def check_endpoint(endpoint)
-      if endpoint.is_a?(String)
-        raise ArgumentError.new("Invalid endpoint name: #{endpoint}") if endpoint.strip == '' || !endpoint.include?('.')
-      elsif endpoint.is_a?(Symbol)
-        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"
-      end
-
-      endpoint
-    end
-
-    def build_root_url(server)
-      if server.is_a?(String)
-        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"
+    def build_root_url(service)
+      if service.is_a?(String)
+        if service.include?('/')
+          uri = URI(service)
+          if uri.scheme != 'ws' && uri.scheme != 'wss'
+            raise ArgumentError, "Service parameter should be a hostname or a ws:// or wss:// URL"
+          end
+          uri.to_s
         else
-          "wss://#{server}"
+          service = "wss://#{service}"
+          uri = URI(service) # raises if invalid
+          service
         end
       else
-        raise ArgumentError, "Server parameter should be a string"
+        raise ArgumentError, "Service parameter should be a string"
       end
     end
   end

data/lib/skyfall/version.rb

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

data/lib/skyfall.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
-require_relative 'skyfall/stream'
-require_relative 'skyfall/messages/websocket_message'
+require_relative 'skyfall/firehose'
+require_relative 'skyfall/firehose/message'
+require_relative 'skyfall/jetstream'
+require_relative 'skyfall/jetstream/message'
 require_relative 'skyfall/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skyfall
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Kuba Suder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-04 00:00:00.000000000 Z
+date: 2024-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32
@@ -114,8 +114,7 @@ files:
 - LICENSE.txt
 - README.md
 - example/block_tracker.rb
-- example/follower_tracker.rb
-- example/monitor_phrases.rb
+- example/jet_monitor_phrases.rb
 - example/print_all_posts.rb
 - example/push_notifications.rb
 - lib/skyfall.rb
@@ -124,17 +123,25 @@ files:
 - lib/skyfall/collection.rb
 - lib/skyfall/errors.rb
 - lib/skyfall/extensions.rb
+- lib/skyfall/firehose.rb
+- lib/skyfall/firehose/account_message.rb
+- lib/skyfall/firehose/commit_message.rb
+- lib/skyfall/firehose/handle_message.rb
+- lib/skyfall/firehose/identity_message.rb
+- lib/skyfall/firehose/info_message.rb
+- lib/skyfall/firehose/labels_message.rb
+- lib/skyfall/firehose/message.rb
+- lib/skyfall/firehose/operation.rb
+- lib/skyfall/firehose/tombstone_message.rb
+- lib/skyfall/firehose/unknown_message.rb
+- lib/skyfall/jetstream.rb
+- lib/skyfall/jetstream/account_message.rb
+- lib/skyfall/jetstream/commit_message.rb
+- lib/skyfall/jetstream/identity_message.rb
+- lib/skyfall/jetstream/message.rb
+- lib/skyfall/jetstream/operation.rb
+- lib/skyfall/jetstream/unknown_message.rb
 - lib/skyfall/label.rb
-- lib/skyfall/messages/account_message.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
-- lib/skyfall/operation.rb
 - lib/skyfall/stream.rb
 - lib/skyfall/version.rb
 - sig/skyfall.rbs

data/example/follower_tracker.rb

@@ -1,84 +0,0 @@
-#!/usr/bin/env ruby
-
-# Example: track when people follow and unfollow your 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 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/lib/skyfall/messages/handle_message.rb

@@ -1,12 +0,0 @@
-module Skyfall
-
-  #
-  # Note: this event type is deprecated and will stop being emitted at some point.
-  # You should instead listen for 'identity' events (Skyfall::IdentityMessage).
-  #
-  class HandleMessage < WebsocketMessage
-    def handle
-      @data_object['handle']
-    end
-  end
-end