ratproto 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ae75289d3bfe8a1adb0a27e3f33111b194756524fc6b040bb7131cd16fe0b6a
-  data.tar.gz: 0a424e54c22bb32ffcfa5ee69f078b12705d0c19c3413a16867b9f4fc331d1a5
+  metadata.gz: dd51fed594f086af2d560047baf82a7adfe1f29483421d8dd1c4e0ffef8e00f4
+  data.tar.gz: b91f3eaac638d75e04d3030fb9cf59f70e6d8589f223fe0c1a846837ffa1336e
 SHA512:
-  metadata.gz: 9f1e9a749a2d46ba339a194f5331569b89d05480f419b84a208062b39306893bd2bc88139f144426330c234ff5cdc63303a728ce3d47228bd664e8e59d7ec600
-  data.tar.gz: '08d7134fd2647848dfd1df605c05b8b2b03893d0be2b2ffd0d55da50d36fd6168679b292765283231693fbeba80883f26a5464d6098a9f49cdd9853a5ef1c770'
+  metadata.gz: 5cb31e38a0d44e863da64ccbd826258d48c8ae6451e63279e577213fe482ed4122c084a338264c8dcb118369a3fd8e571678a02bf070537368b89b5d4011b91e
+  data.tar.gz: 85cd4e59791b9f09a987dbe1ac2e8ebfe2d4d991b7033d851d7d26e8b56f21b19816fb6fb763c9272491378d98c2e3fe7e4acdb0a7925e17a15ac31eba8efa59

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.3.0] - 2026-07-30
+
+* `stream`:
+  - added option `--print-cursor` (`-s`)
+  - print account status change messages
+  - added option `--[no-]account` (`-a`) to enable/disable account messages
+  - print the timestamp of the last message on stop
+  - allow passing handles with `@` to `-d` option
+  - status messages are printed to stderr
+  - suggest that `-j` might be missing on connection error
+* added `stream-labels` command which works similarly to `stream`, but streams labels from a labeller
+  - pass labeller service as a hostname or a DID/handle of an account
+  - filter labels by type (value) or by pattern in the labelled URI
+
 ## [0.2.0] - 2026-07-28
 
 - converted the codebase from a single script in `exe/rat` to per-command classes using Clamp framework

data/lib/ratproto/cli.rb

@@ -7,6 +7,7 @@ require_relative 'commands/base'
 require_relative 'commands/fetch'
 require_relative 'commands/resolve'
 require_relative 'commands/stream'
+require_relative 'commands/stream_labels'
 
 Clamp.allow_options_after_parameters = true
 
@@ -50,6 +51,7 @@ module RatProto
 
     subcommand 'fetch', 'fetch a single record given its at:// URI', Commands::Fetch
     subcommand 'stream', 'stream events from a relay or PDS firehose', Commands::Stream
+    subcommand 'stream-labels', 'stream labels a labeller firehose', Commands::StreamLabels
     subcommand 'resolve', 'resolve a DID or @handle', Commands::Resolve
     subcommand 'help', 'show help', Commands::Help
     subcommand 'version', 'show version', Commands::Version

data/lib/ratproto/commands/base.rb

@@ -11,6 +11,10 @@ module RatProto
 
       private
 
+      def log(text = nil)
+        $stderr.puts text
+      end
+
       def parse_at_uri(value)
         signal_usage_error "not an at:// URI: #{value.inspect}" unless value.start_with?('at://')
 
@@ -33,7 +37,7 @@ module RatProto
       def map_argument_to_did(did)
         if did =~ DID_REGEXP
           did
-        elsif did =~ HANDLE_REGEXP
+        elsif did.gsub(/\A@/, '') =~ HANDLE_REGEXP
           if resolved_did = DID.resolve_handle(did)
             resolved_did.to_s
           else

data/lib/ratproto/commands/stream.rb

@@ -15,9 +15,11 @@ module RatProto
 
       option ['-j', '--jetstream'], :flag, 'use a Jetstream source'
 
-      option ['-r', '--cursor'], 'CURSOR', 'start from a given cursor' do |value|
+      option(
+        ['-r', '--cursor'], 'CURSOR',
+        'start from a given cursor (pass 0 to read from the beginning of the playback window)'
+      ) do |value|
         raise ArgumentError, 'must be a decimal integer' unless value =~ /\A\d+\z/
-
         value.to_i
       end
 
@@ -27,35 +29,48 @@ module RatProto
       option ['-c', '--collection'], 'NSID[,NSID...]', 'filter events by collection (comma-separated or repeated)',
              multivalued: true, attribute_name: :collection_values
 
+      option ['-a', '--[no-]account'], :flag, 'print account status events (default: enabled unless filtering by collection)'
+      option ['-s', '--print-cursor'], :flag, 'only print current cursor (seq)'
+
+
       def execute
         require 'skyfall'
 
-        dids = comma_separated(did_values, '-d/--did')
-        collections = comma_separated(collection_values, '-c/--collection')
+        @dids = comma_separated(did_values, '-d/--did')
+        @collections = comma_separated(collection_values, '-c/--collection')
+
+        @dids = (@dids.length > 0) ? @dids.map { |did| map_argument_to_did(did) } : nil
+        @collections = (@collections.length > 0) ? @collections.map { |collection| validate_nsid(collection) } : nil
 
-        dids = (dids.length > 0) ? dids.map { |did| map_argument_to_did(did) } : nil
-        collections = (collections.length > 0) ? collections.map { |collection| validate_nsid(collection) } : nil
+        @sky = build_stream
+        configure_interrupt_handler
 
-        sky = build_stream(dids, collections)
-        configure_callbacks(sky, dids, collections)
-        configure_interrupt_handler(sky)
+        if print_cursor?
+          @sky.on_message do |msg|
+            print_cursor_and_stop(msg)
+            next
+          end
 
-        sky.connect
+          @sky.connect
+        else
+          configure_callbacks
+          @sky.connect
 
-        puts "Stopped stream at cursor #{sky.cursor}"
+          log "Stopped stream at cursor #{@sky.cursor}" + (@last_timestamp ? " (#{@last_timestamp})" : "")
+        end
       end
 
 
       private
 
-      def build_stream(dids, collections)
+      def build_stream
         if jetstream?
           options = {}
           options[:cursor] = cursor if cursor
 
           # pass DID/collection filters to Jetstream to filter events server-side
-          options[:wanted_dids] = dids if dids
-          options[:wanted_collections] = collections if collections
+          options[:wanted_dids] = @dids if @dids
+          options[:wanted_collections] = @collections if @collections
 
           Skyfall::Jetstream.new(service, options)
         else
@@ -63,36 +78,84 @@ module RatProto
         end
       end
 
-      def configure_callbacks(sky, dids, collections)
-        sky.on_connecting { |url| puts "Connecting to #{url}..." }
-        sky.on_connect    { puts "Connected" }
-        sky.on_disconnect { puts "Disconnected" }
-        sky.on_reconnect  { puts "Connection lost, trying to reconnect..." }
-        sky.on_timeout    { puts "Connection stalled, triggering a reconnect..." }
-        sky.on_error      { |e| puts "ERROR: #{e}" }
+      def configure_callbacks
+        @sky.on_connecting { |url| log "Connecting to #{url}..." }
+        @sky.on_connect    { log "Connected" }
+        @sky.on_disconnect { log "Disconnected" }
+        @sky.on_reconnect  { log "Connection lost, trying to reconnect..." }
+        @sky.on_timeout    { log "Connection stalled, triggering a reconnect..." }
+        @sky.on_error      { |e| report_error(e) }
 
-        sky.on_message do |msg|
-          next unless msg.type == :commit
-          next if dids && !dids.include?(msg.repo)
+        @sky.on_message { |msg| process_message(msg) }
+      end
 
-          time = msg.time.getlocal.iso8601
+      def report_error(error)
+        log "ERROR: #{error.message}"
 
-          msg.operations.each do |op|
-            next if collections && !collections.include?(op.collection)
+        if !jetstream? && error.message.include?('Unexpected response code')
+          log "If this is a Jetstream server, retry with -j / --jetstream."
+        end
+      end
 
-            json = op.raw_record && JSON.generate(op.raw_record)
-            puts "[#{time}] (#{msg.seq}) #{msg.repo} #{op.action.inspect} #{op.collection} #{op.rkey} #{json}"
-          end
+      def process_message(msg)
+        case msg.type
+        when :commit
+          print_commit_message(msg)
+        when :account
+          print_account_message(msg) if show_account_messages?
         end
       end
 
-      def configure_interrupt_handler(sky)
+      def print_commit_message(msg)
+        return if @dids && !@dids.include?(msg.repo)
+
+        time = msg.time.getlocal.iso8601
+        @last_timestamp = time
+
+        msg.operations.each do |op|
+          next if @collections && !@collections.include?(op.collection)
+
+          json = op.raw_record && JSON.generate(op.raw_record.except('$type'))
+          puts "[#{time}] (#{msg.seq}) #{msg.repo} #{op.action.inspect} #{op.collection} #{op.rkey} #{json}"
+        end
+      end
+
+      def print_account_message(msg)
+        return if @dids && !@dids.include?(msg.repo)
+
+        time = msg.time.getlocal.iso8601
+        @last_timestamp = time
+
+        status = (msg.active?) ? :active : msg.status
+
+        puts "[#{time}] (#{msg.seq}) #{msg.repo} #account (status = #{status.inspect})"
+      end
+
+      def show_account_messages?
+        if account? == nil
+          # enabled by default if -c is not used
+          @collections.nil?
+        else
+          # if enabled/disabled explicitly, follow user's choice
+          account?
+        end
+      end
+
+      def configure_interrupt_handler
         trap('SIGINT') do
-          puts
-          puts 'Disconnecting...'
-          sky.disconnect
+          log
+          log 'Disconnecting...'
+          @sky.disconnect
         end
       end
+
+      def print_cursor_and_stop(msg)
+        return if @disconnecting
+
+        puts msg.seq
+        @sky.disconnect
+        @disconnecting = true
+      end
     end
   end
 end

data/lib/ratproto/commands/stream_labels.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'didkit'
+require 'json'
+require 'time'
+
+require_relative 'base'
+
+module RatProto
+  module Commands
+    class StreamLabels < Base
+      banner 'Stream labels from a labeller firehose'
+
+      parameter 'SERVICE', 'labeller hostname, or a @handle/DID of the labeller account (handle must start with @)'
+
+      option ['-r', '--cursor'], 'CURSOR', 'start from a given cursor' do |value|
+        raise ArgumentError, 'must be a decimal integer' unless value =~ /\A\d+\z/
+        value.to_i
+      end
+
+      option ['-l', '--labels'], 'LABEL[,LABEL...]', 'filter events by label type (comma-separated or repeated)',
+             multivalued: true, attribute_name: :label_types
+
+      option ['-t', '--target'], 'PATTERN', "filter by labelled DID/URI (can be a pattern with '*' as a wildcard; repeatable)",
+             multivalued: true, attribute_name: :target_patterns
+
+      option ['-s', '--print-cursor'], :flag, 'only print current cursor (seq)'
+
+
+      def execute
+        require 'skyfall'
+
+        @labels = (label_types.length > 0) ? comma_separated(label_types, '-l/--labels') : nil
+        @targets = (target_patterns.length > 0) ? target_patterns.map { |pattern| target_regexp(pattern) } : nil
+        @service = determine_hostname(service)
+
+        @sky = Skyfall::Firehose.new(@service, :subscribe_labels, cursor)
+        configure_interrupt_handler
+
+        if print_cursor?
+          @sky.on_message do |msg|
+            print_cursor_and_stop(msg)
+            next
+          end
+
+          @sky.connect
+        else
+          configure_callbacks
+          @sky.connect
+
+          log "Stopped stream at cursor #{@sky.cursor}" + (@last_timestamp ? " (#{@last_timestamp})" : "")
+        end
+      end
+
+
+      private
+
+      def target_regexp(pattern)
+        source = Regexp.escape(pattern).gsub('\*', '.*')
+        Regexp.new("\\A#{source}\\z")
+      end
+
+      def determine_hostname(service)
+        if service =~ /\A(https?:\/\/)?[a-zA-Z0-9\-]+(\.[a-zA-Z0-9\-]+)+(:[0-9]+)?\z/
+          return service
+        end
+
+        if service =~ DID_REGEXP
+          did = DID.new(service)
+        else
+          handle = service.gsub(/\A@/, '')
+
+          if handle =~ HANDLE_REGEXP
+            if resolved_did = DID.resolve_handle(handle)
+              did = resolved_did
+            else
+              signal_error "couldn't resolve handle @#{handle}"
+            end
+          else
+            signal_usage_error "#{service.inspect} is not a valid hostname, DID or handle"
+          end
+        end
+
+        did.document.labeller_host
+      end
+
+      def configure_callbacks
+        @sky.on_connecting { |url| log "Connecting to #{url}..." }
+        @sky.on_connect    { log "Connected" }
+        @sky.on_disconnect { log "Disconnected" }
+        @sky.on_reconnect  { log "Connection lost, trying to reconnect..." }
+        @sky.on_timeout    { log "Connection stalled, triggering a reconnect..." }
+        @sky.on_error      { |e| log "ERROR: #{e}" }
+
+        @sky.on_message do |msg|
+          next unless msg.type == :labels
+
+          msg.labels.each do |label|
+            next if @labels && !@labels.include?(label.value)
+            next if @targets && @targets.none? { |pattern| pattern.match?(label.subject) }
+
+            @last_timestamp = label.created_at
+
+            json = JSON.generate(label.data.except('cid', 'cts', 'sig', 'src', 'ver'))
+            puts "[#{label.created_at}] (#{msg.seq}) #{json}"
+          end
+        end
+      end
+
+      def configure_interrupt_handler
+        trap('SIGINT') do
+          log
+          log 'Disconnecting...'
+          @sky.disconnect
+        end
+      end
+
+      def print_cursor_and_stop(msg)
+        return if @disconnecting
+
+        puts msg.seq
+        @sky.disconnect
+        @disconnecting = true
+      end
+    end
+  end
+end

data/lib/ratproto/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratproto
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kuba Suder
@@ -106,6 +106,7 @@ files:
 - lib/ratproto/commands/fetch.rb
 - lib/ratproto/commands/resolve.rb
 - lib/ratproto/commands/stream.rb
+- lib/ratproto/commands/stream_labels.rb
 - lib/ratproto/version.rb
 - sig/ratproto.rbs
 homepage: https://ruby.sdk.blue