ratproto 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7897b08049db9ed366fe7bace08dc7fba37089accf140df8a266071c1d30c676
-  data.tar.gz: e8a7d6779e21941e3fb02a6c54683a22bb3d8bd65be4bef10d64507c86f193fe
+  metadata.gz: dd51fed594f086af2d560047baf82a7adfe1f29483421d8dd1c4e0ffef8e00f4
+  data.tar.gz: b91f3eaac638d75e04d3030fb9cf59f70e6d8589f223fe0c1a846837ffa1336e
 SHA512:
-  metadata.gz: 847b25a95b46ad7b07898790205e5e87761746b96c9488554548f27b74052f9086374e896a12ba8562d55f3560a0139d91ebf67eac495161bec27590ac5e4b67
-  data.tar.gz: cdb37c2c7d782977c75207ad17cfed669e183beb73b6fb71f8fe9cc135516879aac8966814afd559236be1d1ad58907e822b296069c9a1f059fd5916cc3d17a3
+  metadata.gz: 5cb31e38a0d44e863da64ccbd826258d48c8ae6451e63279e577213fe482ed4122c084a338264c8dcb118369a3fd8e571678a02bf070537368b89b5d4011b91e
+  data.tar.gz: 85cd4e59791b9f09a987dbe1ac2e8ebfe2d4d991b7033d851d7d26e8b56f21b19816fb6fb763c9272491378d98c2e3fe7e4acdb0a7925e17a15ac31eba8efa59

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [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
+
 ## [0.1.2] - 2026-05-24
 
 - `resolve`: added `-d` and `-p` options to print only the DID or the PDS endpoint respectively

data/README.md

@@ -14,7 +14,7 @@ It builds on top of the existing ATProto Ruby gems:
 
 ## Installation
 
-To run this tool, you need some reasonably recent version of Ruby installed – it should run on Ruby 2.6 and above, although it's recommended to use a version that still gets maintainance updates, i.e. currently 3.2+.
+To run this tool, you need some reasonably recent version of Ruby installed – it should run on Ruby 2.6 and above, although it's recommended to use a version that still gets maintainance updates, i.e. currently 3.3+.
 
 An older version of Ruby (2.6.x) that should work is shipped with macOS versions 11.0 or later, a recent version of Ruby is also likely to be already installed on most Linux systems, or at least available through the OS's package manager. More installation options can be found on [ruby-lang.org](https://www.ruby-lang.org/en/downloads/).
 

data/exe/rat

@@ -2,319 +2,6 @@
 
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 
-require 'didkit'
-require 'json'
-require 'minisky'
-require 'optparse'
-require 'time'
-require 'uri'
+require 'ratproto/cli'
 
-require 'ratproto/version'
-
-DID_REGEXP = /\Adid:[a-z]+:[a-zA-Z0-9.\-_]+\z/
-NSID_REGEXP = /\A[a-z0-9]+(\.[a-z0-9]+)+\z/
-HANDLE_REGEXP = /\A[a-zA-Z0-9\-]+(\.[a-zA-Z0-9\-]+)+\z/
-
-def print_help
-  puts <<~HELP
-    rat #{RatProto::VERSION} 🐀
-
-    Usage:
-      rat fetch at://uri
-      rat stream <firehose-host> [options]
-      rat resolve <did>|<handle>
-
-    Commands:
-      fetch     Fetch a single record given its at:// URI
-      stream    Stream events from a relay / PDS firehose
-      resolve   Resolve a DID or @handle
-      help      Show this help
-      version   Show version
-
-    Stream options:
-      -j, --jetstream                  Use a Jetstream source instead of a CBOR firehose
-      -r, --cursor CURSOR              Start from a given cursor
-      -d, --did DID[,DID...]           Filter only events from given DID(s)
-                                       (can be passed multiple times)
-      -c, --collection NSID[,NSID...]  Filter only events of given collection(s)
-                                       (can be passed multiple times)
-  HELP
-end
-
-def abort_with_error(message)
-  puts message
-  exit 1
-end
-
-def check_stream_did(did)
-  if did =~ DID_REGEXP
-    did
-  elsif did =~ HANDLE_REGEXP
-    if resolved_did = DID.resolve_handle(did)
-      resolved_did.to_s
-    else
-      abort_with_error "Error: couldn't resolve handle @#{did}"
-    end
-  else
-    abort_with_error "Error: #{did.inspect} is not a valid DID"
-  end
-end
-
-def validate_nsid(collection)
-  unless collection =~ NSID_REGEXP
-    abort_with_error "Error: #{collection.inspect} is not a valid collection NSID"
-  end
-end
-
-def parse_at_uri(uri)
-  unless uri.start_with?('at://')
-    abort_with_error "Error: not an at:// URI: #{uri.inspect}"
-  end
-
-  unless uri =~ /\Aat:\/\/([^\/]+)\/([^\/]+)\/([^\/]+)\z/
-    abort_with_error "Error: invalid at:// URI: #{uri.inspect}"
-  end
-
-  [$1, $2, $3]
-end
-
-def run_fetch(args)
-  uri = args.shift
-
-  if uri.nil?
-    abort_with_error "Usage: #{$PROGRAM_NAME} fetch <at://uri>"
-  end
-
-  if !args.empty?
-    abort_with_error "Error: Unexpected arguments for fetch: #{args.join(' ')}"
-  end
-
-  repo, collection, rkey = parse_at_uri(uri)
-
-  begin
-    pds = DID.new(repo).document.pds_host
-    sky = Minisky.new(pds, nil)
-
-    response = sky.get_request('com.atproto.repo.getRecord', {
-      repo: repo, collection: collection, rkey: rkey
-    })
-  rescue StandardError => e
-    abort_with_error "Error loading record: #{e.class}: #{e.message}"
-  end
-
-  puts JSON.pretty_generate(response['value'])
-end
-
-def parse_resolve_options(args)
-  options = {}
-
-  parser = OptionParser.new do |opts|
-    opts.banner = "Usage: #{$PROGRAM_NAME} resolve <did>|<handle> [options]"
-
-    opts.on('-d', '--did', 'Print only the DID resolved from the handle') do
-      options[:only_did] = true
-    end
-
-    opts.on('-p', '--pds', 'Print only the PDS endpoint') do
-      options[:only_pds] = true
-    end
-
-    opts.on('-h', '--help', 'Show resolve-specific help') do
-      puts opts
-      exit
-    end
-  end
-
-  remaining = []
-
-  begin
-    parser.order!(args) { |other| remaining << other }
-  rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
-    puts "Error: #{e.message}"
-    puts parser
-    exit 1
-  end
-
-  if options[:only_did] && options[:only_pds]
-    abort_with_error "--pds and --did options cannot be used together"
-  end
-
-  [options, remaining]
-end
-
-def run_resolve(args)
-  options, arguments = parse_resolve_options(args)
-  target = arguments.shift
-
-  if target.nil?
-    abort_with_error "Usage: #{$PROGRAM_NAME} resolve <did>|<handle> [options]"
-  end
-
-  if !args.empty?
-    abort_with_error "Error: Unexpected arguments for resolve: #{args.join(' ')}"
-  end
-
-  did = DID.resolve_handle(target)
-
-  if did.nil?
-    abort_with_error "Couldn't resolve #{target}"
-  end
-
-  if options[:only_did]
-    puts did
-  elsif options[:only_pds]
-    puts did.document.pds_endpoint
-  else
-    puts JSON.pretty_generate(did.document.json)
-  end
-rescue StandardError => e
-  abort_with_error "Error resolving #{target.inspect}: #{e.class}: #{e.message}"
-end
-
-def parse_stream_options(args)
-  options = {}
-
-  parser = OptionParser.new do |opts|
-    opts.banner = "Usage: #{$PROGRAM_NAME} stream <relay.host> [options]"
-
-    opts.on('-j', '--jetstream', 'Use a Jetstream source') do
-      options[:jetstream] = true
-    end
-
-    opts.on('-rCURSOR', '--cursor=CURSOR', 'Start from a given cursor') do |cursor|
-      options[:cursor] = cursor
-    end
-
-    opts.on('-dLIST', '--did=LIST', 'Filter only events from given DID(s) (comma-separated or repeated)') do |list|
-      items = list.split(',').map(&:strip).reject(&:empty?)
-
-      if items.empty?
-        abort_with_error "Error: empty argument to -d/--did"
-      end
-
-      options[:dids] ||= []
-      options[:dids] += items
-    end
-
-    opts.on('-cLIST', '--collection=LIST', 'Filter only events of given collections') do |list|
-      items = list.split(',').map(&:strip).reject(&:empty?)
-
-      if items.empty?
-        abort_with_error "Error: empty argument to -c/--collection"
-      end
-
-      options[:collections] ||= []
-      options[:collections] += items
-    end
-
-    opts.on('-h', '--help', 'Show stream-specific help') do
-      puts opts
-      exit
-    end
-  end
-
-  remaining = []
-
-  begin
-    parser.order!(args) { |other| remaining << other }
-  rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
-    puts "Error: #{e.message}"
-    puts parser
-    exit 1
-  end
-
-  [options, remaining]
-end
-
-def run_stream(args)
-  options, arguments = parse_stream_options(args)
-
-  service = arguments.shift
-
-  if service.nil?
-    abort_with_error "Usage: #{$PROGRAM_NAME} stream <firehose-host> [options]"
-  end
-
-  if !arguments.empty?
-    abort_with_error "Error: Unexpected arguments for stream: #{arguments.join(' ')}"
-  end
-
-  if options[:cursor] && options[:cursor] !~ /\A\d+\z/
-    abort_with_error "Error: cursor must be a decimal integer, got: #{options[:cursor].inspect}"
-  end
-
-  if options[:dids]
-    options[:dids] = options[:dids].map { |did| check_stream_did(did) }
-  end
-
-  if options[:collections]
-    options[:collections].each { |collection| validate_nsid(collection) }
-  end
-
-  if options[:jetstream]
-    jet_opts = {}
-    jet_opts[:cursor] = options[:cursor].to_i if options[:cursor]
-
-    # pass DID/collection filters to Jetstream to filter events server-side
-    jet_opts[:wanted_dids] = options[:dids] if options[:dids]
-    jet_opts[:wanted_collections] = options[:collections] if options[:collections]
-
-    sky = Skyfall::Jetstream.new(service, jet_opts)
-  else
-    cursor = options[:cursor]&.to_i
-    sky = Skyfall::Firehose.new(service, :subscribe_repos, cursor)
-  end
-
-  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}" }
-
-  sky.on_message do |msg|
-    next unless msg.type == :commit
-    next if options[:dids] && !options[:dids].include?(msg.repo)
-
-    time = msg.time.getlocal.iso8601
-
-    msg.operations.each do |op|
-      next if options[:collections] && !options[:collections].include?(op.collection)
-
-      json = op.raw_record && JSON.generate(op.raw_record)
-      puts "[#{time}] #{msg.repo} #{op.action.inspect} #{op.collection} #{op.rkey} #{json}"
-    end
-  end
-
-  trap('SIGINT') do
-    puts 'Disconnecting...'
-    sky.disconnect
-  end
-
-  sky.connect
-
-  puts "Stopped stream at cursor #{sky.cursor}"
-end
-
-if ARGV.empty?
-  print_help
-  exit
-end
-
-cmd = ARGV.shift
-
-case cmd
-when 'help', '--help', '-h'
-  print_help
-when 'version', '--version'
-  puts "RatProto #{RatProto::VERSION} 🐀"
-when 'fetch'
-  run_fetch(ARGV)
-when 'resolve'
-  run_resolve(ARGV)
-when 'stream'
-  require 'skyfall'
-  run_stream(ARGV)
-else
-  abort_with_error "Error: unknown command: #{cmd}"
-end
+RatProto::CLI.run

data/lib/ratproto/cli.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'clamp'
+
+require_relative 'version'
+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
+
+module RatProto
+  module Commands
+    class Version < Base
+      banner 'Show version'
+
+      def execute
+        puts "RatProto #{RatProto::VERSION} 🐀"
+      end
+    end
+
+    class Help < Base
+      banner 'Show help for rat or one of its commands'
+
+      parameter '[COMMAND]', 'command to describe'
+
+      def execute
+        program_name = File.basename($PROGRAM_NAME)
+
+        if command
+          command_class = RatProto::CLI.find_subcommand_class(command)
+          signal_usage_error "unknown command: #{command}" unless command_class
+
+          puts command_class.help("#{program_name} #{command}")
+        else
+          puts RatProto::CLI.help(program_name)
+        end
+      end
+    end
+  end
+
+  class CLI < Commands::Base
+    banner "RatProto #{RatProto::VERSION} 🐀 — Ruby ATProto CLI"
+
+    option '--version', :flag, 'show version' do
+      Commands::Version.run("", [])
+      exit
+    end
+
+    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
+  end
+end

data/lib/ratproto/commands/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'clamp'
+
+module RatProto
+  module Commands
+    class Base < Clamp::Command
+      DID_REGEXP = /\Adid:[a-z]+:[a-zA-Z0-9.\-_]+\z/
+      NSID_REGEXP = /\A[a-z0-9]+(\.[a-z0-9]+)+\z/
+      HANDLE_REGEXP = /\A[a-zA-Z0-9\-]+(\.[a-zA-Z0-9\-]+)+\z/
+
+      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://')
+
+        match = value.match(/\Aat:\/\/([^\/]+)\/([^\/]+)\/([^\/]+)\z/)
+        signal_usage_error "invalid at:// URI: #{value.inspect}" unless match
+
+        match.captures
+      end
+
+      def comma_separated(values, option_name)
+        values = (values || []).map { |value|
+          args = value.split(',').map(&:strip).reject(&:empty?)
+          signal_usage_error "empty argument to #{option_name}" if args.empty?
+          args
+        }
+
+        values.flatten
+      end
+
+      def map_argument_to_did(did)
+        if did =~ DID_REGEXP
+          did
+        elsif did.gsub(/\A@/, '') =~ HANDLE_REGEXP
+          if resolved_did = DID.resolve_handle(did)
+            resolved_did.to_s
+          else
+            signal_error "couldn't resolve handle @#{did}"
+          end
+        else
+          signal_usage_error "#{did.inspect} is not a valid DID"
+        end
+      end
+
+      def validate_nsid(collection)
+        return collection if collection =~ NSID_REGEXP
+
+        signal_usage_error "#{collection.inspect} is not a valid collection NSID"
+      end
+    end
+  end
+end

data/lib/ratproto/commands/fetch.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'didkit'
+require 'json'
+
+require_relative 'base'
+
+module RatProto
+  module Commands
+    class Fetch < Base
+      banner 'Fetch a single record given its at:// URI'
+
+      parameter 'URI', 'ATProto record URI'
+
+      def execute
+        require 'minisky'
+
+        repo, collection, rkey = parse_at_uri(uri)
+        response = load_record(repo, collection, rkey)
+        puts JSON.pretty_generate(response['value'])
+      end
+
+
+      private
+
+      def load_record(repo, collection, rkey)
+        pds = DID.new(repo).document.pds_host
+        sky = Minisky.new(pds, nil)
+
+        sky.get_request('com.atproto.repo.getRecord', {
+          repo: repo, collection: collection, rkey: rkey
+        })
+      rescue StandardError => e
+        signal_error "loading record: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ratproto/commands/resolve.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'didkit'
+require 'json'
+
+require_relative 'base'
+
+module RatProto
+  module Commands
+    class Resolve < Base
+      banner 'Resolve a DID or @handle'
+
+      parameter 'TARGET', 'DID or handle'
+
+      option ['-d', '--did'], :flag, 'print only the DID resolved from the handle'
+      option ['-p', '--pds'], :flag, 'print only the PDS endpoint'
+
+      def execute
+        signal_usage_error '--pds and --did options cannot be used together' if did? && pds?
+
+        begin
+          resolved_did = DID.resolve_handle(target)
+        rescue StandardError => e
+          signal_error "resolving #{target.inspect}: #{e.class}: #{e.message}"
+        end
+
+        if resolved_did.nil?
+          signal_error "couldn't resolve #{target}"
+        end
+
+        if did?
+          puts resolved_did
+        elsif pds?
+          puts resolved_did.document.pds_endpoint
+        else
+          puts JSON.pretty_generate(resolved_did.document.json)
+        end
+      end
+    end
+  end
+end

data/lib/ratproto/commands/stream.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'didkit'
+require 'json'
+require 'time'
+
+require_relative 'base'
+
+module RatProto
+  module Commands
+    class Stream < Base
+      banner 'Stream events from a relay or PDS firehose'
+
+      parameter 'SERVICE', 'relay, PDS or Jetstream hostname'
+
+      option ['-j', '--jetstream'], :flag, 'use a Jetstream source'
+
+      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
+
+      option ['-d', '--did'], 'DID[,DID...]', 'filter events by DID (comma-separated or repeated)',
+             multivalued: true, attribute_name: :did_values
+
+      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 = (@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
+
+        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 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
+
+          Skyfall::Jetstream.new(service, options)
+        else
+          Skyfall::Firehose.new(service, :subscribe_repos, cursor)
+        end
+      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| report_error(e) }
+
+        @sky.on_message { |msg| process_message(msg) }
+      end
+
+      def report_error(error)
+        log "ERROR: #{error.message}"
+
+        if !jetstream? && error.message.include?('Unexpected response code')
+          log "If this is a Jetstream server, retry with -j / --jetstream."
+        end
+      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 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
+          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.1.2"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratproto
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Kuba Suder
@@ -69,6 +69,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: clamp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 email:
 - jakub.suder@gmail.com
 executables:
@@ -81,6 +101,12 @@ files:
 - README.md
 - exe/rat
 - lib/ratproto.rb
+- lib/ratproto/cli.rb
+- lib/ratproto/commands/base.rb
+- 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
@@ -104,7 +130,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby CLI tool for accessing Bluesky API / ATProto
 test_files: []