ratproto 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a51437de2f57f2f70c839165f4721e3b9fc05ffced806ce652971d7bfe4d5e01
-  data.tar.gz: 6fd9738bde5c0c366a28f36e79c496e18f0686331af7b2f2b8385f60e8827024
+  metadata.gz: 9ae75289d3bfe8a1adb0a27e3f33111b194756524fc6b040bb7131cd16fe0b6a
+  data.tar.gz: 0a424e54c22bb32ffcfa5ee69f078b12705d0c19c3413a16867b9f4fc331d1a5
 SHA512:
-  metadata.gz: 38410b341c5c79fad987cea4e4d6430cda0c63735f58f204497ac8e240525729ab00e01e894512c2d57b55a1da1e913a233da977d084f1f23d909be2f55f1ffb
-  data.tar.gz: 0264f915d70d891447af5e87bc7b88635a1b530fd91e50eebcf9c9902c8037a21c2ab8d2e135ecf9519280dfe2d4ae765819f45c04341c81422709588efe42c7
+  metadata.gz: 9f1e9a749a2d46ba339a194f5331569b89d05480f419b84a208062b39306893bd2bc88139f144426330c234ff5cdc63303a728ce3d47228bd664e8e59d7ec600
+  data.tar.gz: '08d7134fd2647848dfd1df605c05b8b2b03893d0be2b2ffd0d55da50d36fd6168679b292765283231693fbeba80883f26a5464d6098a9f49cdd9853a5ef1c770'

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [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
+- `stream`: print the last received cursor when stopped
+- `stream`: accept also handles instead of DIDs for the `-d` argument
+- lazy-load `skyfall` only in `stream`
+
 ## [0.1.1] - 2026-01-03
 
 - fixed rat emoji in the help output :D

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,264 +2,6 @@
 
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 
-require 'didkit'
-require 'json'
-require 'minisky'
-require 'optparse'
-require 'skyfall'
-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/
-
-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 validate_did(did)
-  unless did =~ DID_REGEXP
-    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 run_resolve(args)
-  target = args.shift
-
-  if target.nil?
-    abort_with_error "Usage: #{$PROGRAM_NAME} resolve <did>|<handle>"
-  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
-
-  puts JSON.pretty_generate(did.document.json)
-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].each { |did| validate_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
-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'
-  run_stream(ARGV)
-else
-  abort_with_error "Error: unknown command: #{cmd}"
-end
+RatProto::CLI.run

data/lib/ratproto/cli.rb

@@ -0,0 +1,57 @@
+# 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'
+
+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 '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,54 @@
+# 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 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 =~ 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,98 @@
+# 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' 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
+
+      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(dids, collections)
+        configure_callbacks(sky, dids, collections)
+        configure_interrupt_handler(sky)
+
+        sky.connect
+
+        puts "Stopped stream at cursor #{sky.cursor}"
+      end
+
+
+      private
+
+      def build_stream(dids, collections)
+        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, 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}" }
+
+        sky.on_message do |msg|
+          next unless msg.type == :commit
+          next if dids && !dids.include?(msg.repo)
+
+          time = msg.time.getlocal.iso8601
+
+          msg.operations.each do |op|
+            next if collections && !collections.include?(op.collection)
+
+            json = op.raw_record && JSON.generate(op.raw_record)
+            puts "[#{time}] (#{msg.seq}) #{msg.repo} #{op.action.inspect} #{op.collection} #{op.rkey} #{json}"
+          end
+        end
+      end
+
+      def configure_interrupt_handler(sky)
+        trap('SIGINT') do
+          puts
+          puts 'Disconnecting...'
+          sky.disconnect
+        end
+      end
+    end
+  end
+end

data/lib/ratproto/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratproto
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.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,11 @@ 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/version.rb
 - sig/ratproto.rbs
 homepage: https://ruby.sdk.blue
@@ -104,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby CLI tool for accessing Bluesky API / ATProto
 test_files: []