didkit 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae1ff103a9695991ae3e0e97072c2b10731e7c18e44cfa5f715995ef0631df4f
-  data.tar.gz: b2bc822873a7804515d3ad06caa6c15e4177943668f6bcbb79f8c48fa87e4733
+  metadata.gz: 7f394023d5e7e3f864041dc39e81d1e2730972b6bfe8f3c0a0d0178e27e6557e
+  data.tar.gz: e622af3eea9c05a7831c7b4630e16e0a879faede2a38b6605bb622d0ebb2eaf6
 SHA512:
-  metadata.gz: 5e4bbd991480a0a98c13c514e52a65bdceafd1c1a4feb75d60db07b22af10f376edaaea89bd98122c94c902c718c241a01965abaa801433b2a48162bb86d6ec1
-  data.tar.gz: 791481ed39520a72eb750e2d511f6017ca476a1386c15d6d6a667e2a170a7e63d0723e868b2d843c87d66d3d33306fcc6bd5cd3d359cbea8e213e6ba8a401f99
+  metadata.gz: 1dd40553f1f96d93bb746d1cfc628d3f4a2a34df99634a88775c3673f4ef721c2e13f85110e7a3a0b2880f29ffcbe7da21838378cdd04a3ea346a7ab2ccb2bfc
+  data.tar.gz: f32fc83842dcd9a1bf88817aa8a286f5a1bdf42004416f74ec2450104388426456c2d16b598ba4439d9cb6c13f5035d800df2abada369656ac0c883797f05d1d

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## [0.3.0] - 2025-12-15
+
+Breaking changes:
+
+* removed `DID#is_known_by_relay?` – it doesn't work anymore, since relays are now non-archival and they expose almost no XRPC routes
+* renamed a few handle-related methods:
+  - `get_validated_handle` -> `get_verified_handle`
+  - `pick_valid_handle` -> `first_verified_handle`
+
+Also:
+
+- added `DID#account_status` method, which checks `getRepoStatus` endpoint to tell if an account is active, deactivated, taken down etc.
+- added `DID#account_active?` helper (`account_status == :active`)
+- `DID#account_exists?` now calls `getRepoStatus` (via `account_status`, checking if it's not nil) instead of `getLatestCommit`
+- added `DID#document` which keeps a memoized copy of the document
+- added `pds_host` & `labeler_host` methods to `PLCOperation` and `Document`, which return the PDS/labeller address without the `https://`
+- added `labeller_endpoint` & `labeller_host` aliases for the double-L enjoyers :]
+- added `PLCOperation#cid`
+- `PLCImporter` now removes duplicate operations at the edge of pages returned from the `/export` API
+- rewritten some networking code – all classes now use `Net::HTTP` with consistent options instead of `open-uri`
+
+Note: `PLCImporter` will be rewritten soon to add support for updated [plc.directory](https://plc.directory) APIs, so be prepared for some breaking changes there in v. 0.4.
+
 ## [0.2.3] - 2024-07-02
 
 - added a `DID#get_audit_log` method that fetches the PLC audit log for a DID

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The zlib License
 
-Copyright (c) 2023 Jakub Suder
+Copyright (c) 2025 Jakub Suder
 
 This software is provided 'as-is', without any express or implied
 warranty.  In no event will the authors be held liable for any damages

data/README.md

@@ -3,7 +3,7 @@
 A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Protocol.
 
 > [!NOTE]
-> ATProto Ruby gems collection: [skyfall](https://github.com/mackuba/skyfall) | [blue_factory](https://github.com/mackuba/blue_factory) | [minisky](https://github.com/mackuba/minisky) | [didkit](https://github.com/mackuba/didkit)
+> Part of ATProto Ruby SDK: [ruby.sdk.blue](https://ruby.sdk.blue)
 
 
 ## What does it do
@@ -13,75 +13,99 @@ Accounts on Bluesky use identifiers like [did:plc:oio4hkxaop4ao4wz2pp3f4cr](http
 
 ## Installation
 
+From the command line:
+
     gem install didkit
 
+Or, add this to your `Gemfile`:
 
-## Usage
+    gem 'didkit', '~> 0.3'
 
-Use the `DIDKit::Resolver` class to look up DIDs and handles.
 
-To look up a handle:
+## Usage
+
+The simplest way to use the gem is through the `DIDKit::DID` class, aliased as just `DID`:
 
 ```rb
-resolver = DIDKit::Resolver.new
-resolver.resolve_handle('nytimes.com')
- # => #<DIDKit::DID:0x00000001035956b0 @did="did:plc:eclio37ymobqex2ncko63h4r", @type=:plc, @resolved_by=:dns>
+did = DID.resolve_handle('jay.bsky.team')
+  # => #<DIDKit::DID:0x0... @did="did:plc:oky5czdrnfjpqslsw2a5iclo",
+  #       @resolved_by=:dns, @type=:plc>
 ```
 
-This returns an object of `DIDKit::DID` class (aliased as just `DID`), which tells you:
+This returns a `DID` object, which tells you:
 
 - the DID as a string (`#to_s` or `#did`)
 - the DID type (`#type`, `:plc` or `:web`)
 - if the handle was resolved via a DNS entry or a `.well-known` file (`#resolved_by`, `:dns` or `:http`)
 
-To go in the other direction – to find an assigned and verified handle given a DID – use `get_validated_handle` (pass DID as a string or an object):
+To go in the other direction – to find an assigned and verified handle given a DID – create a `DID` from a DID string and call `get_verified_handle`:
 
 ```rb
-resolver.get_validated_handle('did:plc:ewvi7nxzyoun6zhxrhs64oiz')
- # => "atproto.com" 
+DID.new('did:plc:ewvi7nxzyoun6zhxrhs64oiz').get_verified_handle
+  # => "atproto.com"
 ```
 
-You can also load the DID document using `resolve_did`:
+You can also load the DID JSON document using `#document`, which returns a `DIDKit::Document` (`DID` caches the document, so don't worry about calling this method multiple times):
 
 ```rb
-doc = resolver.resolve_did('did:plc:ragtjsm2j2vknwkz3zp4oxrd')
- # => #<DIDKit::Document:0x0000000105d751f8 @did=#<DIDKit::DID:...>, @json={...}>
+did = DID.new('did:plc:ragtjsm2j2vknwkz3zp4oxrd')
 
-doc.handles
- # => ["pfrazee.com"] 
+did.document.handles
+  # => ["pfrazee.com"]
 
-doc.pds_endpoint
- # => "https://morel.us-east.host.bsky.network" 
+did.document.pds_host
+  # => "morel.us-east.host.bsky.network"
 ```
 
-There are also some helper methods in the `DID` class that create a `Resolver` for you to save you some typing:
+
+### Checking account status
+
+`DIDKit::DID` also includes a few methods for checking the status of a given account (repo), which call the `com.atproto.sync.getRepoStatus` endpoint on the account's assigned PDS:
 
 ```rb
-did = DID.resolve_handle('jay.bsky.team')
- #  => #<DIDKit::DID:0x000000010615ed28 @did="did:plc:oky5czdrnfjpqslsw2a5iclo", @type=:plc, @resolved_by=:dns>
+did = DID.new('did:plc:ch7azdejgddtlijyzurfdihn')
+did.account_status
+  # => :takendown
+did.account_active?
+  # => false
+did.account_exists?
+  # => true
+
+did = DID.new('did:plc:44ybard66vv44zksje25o7dz')
+did.account_status
+  # => :active
+did.account_active?
+  # => true
+```
 
-did.to_s
- # => "did:plc:oky5czdrnfjpqslsw2a5iclo" 
+### Configuration
 
-did.get_document
- # => #<DIDKit::Document:0x00000001066d4898 @did=#<DIDKit::DID:...>, @json={...}>
+You can customize some things about the DID/handle lookups by using the `DIDKit::Resolver` class, which the methods in `DID` use behind the scenes.
 
-did.get_validated_handle
- # => "jay.bsky.team" 
-```
+Currently available options include:
 
+- `:nameserver` - override the nameserver used for DNS lookups, e.g. to use Google's or CloudFlare's DNS
+- `:timeout` - change the connection/response timeout for HTTP requests (default: 15 s)
+- `:max_redirects` - change allowed maximum number of redirects (default: 5)
 
-### Configuration
+Example:
+
+```rb
+resolver = DIDKit::Resolver.new(nameserver: '8.8.8.8', timeout: 30)
 
-You can override the nameserver used for DNS lookups by setting the `nameserver` property in `Resolver`, e.g. to use Google's or CloudFlare's global DNS:
+did = resolver.resolve_handle('nytimes.com')
+  # => #<DIDKit::DID:0x0... @did="did:plc:eclio37ymobqex2ncko63h4r",
+  #       @resolved_by=:dns, @type=:plc>
 
-```
-resolver.nameserver = '8.8.8.8'
-```
+resolver.resolve_did(did)
+  # => #<DIDKit::Document:0x0... @did=#<DIDKit::DID:...>, @json={...}>
 
+resolver.get_verified_handle(did)
+  # => 'nytimes.com'
+```
 
 ## Credits
 
-Copyright © 2024 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
+Copyright © 2025 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
 
 The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).

data/lib/didkit/did.rb

@@ -1,3 +1,6 @@
+require 'json'
+require 'uri'
+
 require_relative 'errors'
 require_relative 'requests'
 require_relative 'resolver'
@@ -29,12 +32,16 @@ module DIDKit
 
     alias to_s did
 
+    def document
+      @document ||= get_document
+    end
+
     def get_document
       Resolver.new.resolve_did(self)
     end
 
-    def get_validated_handle
-      Resolver.new.get_validated_handle(self)
+    def get_verified_handle
+      Resolver.new.get_verified_handle(document)
     end
 
     def get_audit_log
@@ -49,32 +56,41 @@ module DIDKit
       did.gsub(/^did\:web\:/, '') if type == :web
     end
 
-    def is_known_by_relay?(relay, options = {})
-      relay_host = relay.include?('://') ? URI(relay).origin : "https://#{relay}"
-      url = URI("#{relay_host}/xrpc/com.atproto.sync.getLatestCommit")
-      url.query = URI.encode_www_form(:did => did)
+    def account_status(request_options = {})
+      doc = self.document
+      return nil if doc.pds_endpoint.nil?
 
-      response = get_response(url, { timeout: 30, max_redirects: 5 }.merge(options))
+      pds_host = URI(doc.pds_endpoint).origin
+      url = URI("#{pds_host}/xrpc/com.atproto.sync.getRepoStatus")
+      url.query = URI.encode_www_form(:did => @did)
+
+      response = get_response(url, request_options)
       status = response.code.to_i
       is_json = (response['Content-Type'] =~ /^application\/json(;.*)?$/)
 
-      if status == 200
-        true
+      if status == 200 && is_json
+        json = JSON.parse(response.body)
+
+        if json['active'] == true
+          :active
+        elsif json['active'] == false && json['status'].is_a?(String) && json['status'].length <= 100
+          json['status'].to_sym
+        else
+          raise APIError.new(response)
+        end
       elsif status == 400 && is_json && JSON.parse(response.body)['error'] == 'RepoNotFound'
-        false
-      elsif status == 404 && is_json && JSON.parse(response.body)['error']
-        false
+        nil
       else
         raise APIError.new(response)
       end
     end
 
-    def account_exists?
-      doc = get_document
-      return false if doc.pds_endpoint.nil?
+    def account_active?
+      account_status == :active
+    end
 
-      pds_host = URI(doc.pds_endpoint).origin
-      is_known_by_relay?(pds_host, timeout: 10)
+    def account_exists?
+      account_status != nil
     end
 
     def ==(other)

data/lib/didkit/document.rb

@@ -37,8 +37,8 @@ module DIDKit
       @handles = parse_also_known_as(json['alsoKnownAs'] || [])
     end
 
-    def get_validated_handle
-      Resolver.new.pick_valid_handle(did, handles)
+    def get_verified_handle
+      Resolver.new.get_verified_handle(self)
     end
   end
 end

data/lib/didkit/plc_importer.rb

@@ -1,14 +1,22 @@
 require 'json'
-require 'open-uri'
 require 'time'
+require 'uri'
 
 require_relative 'plc_operation'
+require_relative 'requests'
+
+#
+# NOTE: this class is pending a rewrite once new APIs are deployed to plc.directory.
+# Things will change here in v. 0.4.
+#
 
 module DIDKit
   class PLCImporter
     PLC_SERVICE = 'plc.directory'
     MAX_PAGE = 1000
 
+    include Requests
+
     attr_accessor :ignore_errors, :last_date, :error_handler
 
     def initialize(since: nil)
@@ -22,6 +30,8 @@ module DIDKit
         @last_date = Time.now
         @eof = true
       end
+
+      @last_page_cids = []
     end
 
     def plc_service
@@ -42,13 +52,13 @@ module DIDKit
       url = URI("https://#{plc_service}/export")
       url.query = URI.encode_www_form(args)
 
-      data = URI.open(url).read
+      data = get_data(url, content_type: 'application/jsonlines')
       data.lines.map(&:strip).reject(&:empty?).map { |x| JSON.parse(x) }
     end
 
     def fetch_audit_log(did)
-      response = URI.open("https://#{plc_service}/#{did}/log/audit").read
-      JSON.parse(response).map { |j| PLCOperation.new(j) }
+      json = get_json("https://#{plc_service}/#{did}/log/audit", :content_type => :json)
+      json.map { |j| PLCOperation.new(j) }
     end      
 
     def fetch_page
@@ -57,16 +67,22 @@ module DIDKit
       query = @last_date ? { :after => @last_date.utc.iso8601(6) } : {}
       rows = get_export(query)
 
-      operations = rows.filter_map do |json|
+      operations = rows.filter_map { |json|
         begin
           PLCOperation.new(json)
         rescue PLCOperation::FormatError, AtHandles::FormatError, ServiceRecord::FormatError => e
           @error_handler ? @error_handler.call(e, json) : raise
           nil
         end
-      end
+      }.reject { |op|
+        # when you pass the most recent op's timestamp to ?after, it will be returned as the first op again,
+        # so we need to use this CID list to filter it out (so pages will usually be 999 items long)
+
+        @last_page_cids.include?(op.cid)
+      }
 
       @last_date = operations.last&.created_at || request_time
+      @last_page_cids = Set.new(operations.map(&:cid))
       @eof = (rows.length < MAX_PAGE)
 
       operations

data/lib/didkit/plc_operation.rb

@@ -12,7 +12,7 @@ module DIDKit
     include AtHandles
     include Services
 
-    attr_reader :json, :did, :created_at, :type, :handles, :services
+    attr_reader :json, :did, :cid, :created_at, :type, :handles, :services
 
     def initialize(json)
       @json = json
@@ -20,6 +20,10 @@ module DIDKit
       raise FormatError, "Missing DID: #{json}" if @did.nil?
       raise FormatError, "Invalid DID: #{@did}" unless @did.is_a?(String) && @did.start_with?('did:')
 
+      @cid = json['cid']
+      raise FormatError, "Missing CID: #{json}" if @cid.nil?
+      raise FormatError, "Invalid CID: #{@cid}" unless @cid.is_a?(String)
+
       timestamp = json['createdAt']
       raise FormatError, "Missing createdAt: #{json}" if timestamp.nil?
       raise FormatError, "Invalid createdAt: #{timestamp.inspect}" unless timestamp.is_a?(String)

data/lib/didkit/requests.rb

@@ -1,27 +1,77 @@
-module DIDKit::Requests
-  def get_response(url, options = {})
-    url = URI(url) unless url.is_a?(URI)
-    request_options = { use_ssl: true }
-
-    if timeout = options[:timeout]
-      request_options[:open_timeout] = timeout
-      request_options[:read_timeout] = timeout
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'errors'
+
+module DIDKit
+  module Requests
+    def get_response(url, options = {})
+      url = URI(url) unless url.is_a?(URI)
+
+      timeout = options[:timeout] || 15
+
+      request_options = {
+        use_ssl: true,
+        open_timeout: timeout,
+        read_timeout: timeout
+      }
+
+      redirects = 0
+      visited_urls = []
+      max_redirects = options[:max_redirects] || 5
+
+      loop do
+        visited_urls << url
+
+        response = Net::HTTP.start(url.host, url.port, request_options) do |http|
+          request = Net::HTTP::Get.new(url)
+          http.request(request)
+        end
+
+        if response.is_a?(Net::HTTPRedirection) && redirects < max_redirects && (location = response['Location'])
+          url = URI(location.include?('://') ? location : (url.origin + location))
+
+          if visited_urls.include?(url)
+            return response
+          else
+            redirects += 1
+          end
+        else
+          return response
+        end
+      end
     end
 
-    redirects = 0
-    max_redirects = options[:max_redirects] || 0
+    def get_data(url, options = {})
+      content_type = options.delete(:content_type)
+      response = get_response(url, options)
 
-    loop do
-      response = Net::HTTP.start(url.host, url.port, request_options) do |http|
-        request = Net::HTTP::Get.new(url)
-        http.request(request)
+      if response.is_a?(Net::HTTPSuccess) && content_type_matches(response, content_type) && (data = response.body)
+        data
+      else
+        raise APIError.new(response)
       end
+    end
+
+    def get_json(url, options = {})
+      JSON.parse(get_data(url, options))
+    end
+
+    def content_type_matches(response, expected_type)
+      content_type = response['Content-Type']
 
-      if response.is_a?(Net::HTTPRedirection) && redirects < max_redirects && (location = response['Location'])
-        url = URI(location.include?('://') ? location : (url.origin + location))
-        redirects += 1
+      case expected_type
+      when String
+        content_type == expected_type
+      when Regexp
+        content_type =~ expected_type
+      when :json
+        content_type =~ /^application\/json(;.*)?$/
+      when nil
+        true
       else
-        return response
+        raise ArgumentError, "Invalid expected_type: #{expected_type.inspect}"
       end
     end
   end

data/lib/didkit/resolver.rb

@@ -1,5 +1,3 @@
-require 'json'
-require 'open-uri'
 require 'net/http'
 require 'resolv'
 
@@ -10,7 +8,6 @@ require_relative 'requests'
 module DIDKit
   class Resolver
     RESERVED_DOMAINS = %w(alt arpa example internal invalid local localhost onion test)
-    MAX_REDIRECTS = 5
 
     include Requests
 
@@ -18,6 +15,7 @@ module DIDKit
 
     def initialize(options = {})
       @nameserver = options[:nameserver]
+      @request_options = options.slice(:timeout, :max_redirects)
     end
 
     def resolve_handle(handle)
@@ -50,7 +48,7 @@ module DIDKit
 
     def resolve_handle_by_well_known(domain)
       url = "https://#{domain}/.well-known/atproto-did"
-      response = get_response(url, timeout: 10, max_redirects: MAX_REDIRECTS)
+      response = get_response(url, @request_options)
 
       if response.is_a?(Net::HTTPSuccess) && (text = response.body)
         return parse_did_from_well_known(text)
@@ -83,25 +81,23 @@ module DIDKit
     end
 
     def resolve_did_plc(did)
-      url = "https://plc.directory/#{did}"
-      json = JSON.parse(URI.open(url).read)
+      json = get_json("https://plc.directory/#{did}", content_type: /^application\/did\+ld\+json(;.+)?$/)
       Document.new(did, json)
     end
 
     def resolve_did_web(did)
-      url = "https://#{did.web_domain}/.well-known/did.json"
-      json = JSON.parse(URI.open(url).read)
+      json = get_json("https://#{did.web_domain}/.well-known/did.json")
       Document.new(did, json)
     end
 
-    def get_validated_handle(did_or_doc)
-      document = did_or_doc.is_a?(Document) ? did_or_doc : resolve_did(did_or_doc)
+    def get_verified_handle(subject)
+      document = subject.is_a?(Document) ? subject : resolve_did(subject)
 
-      pick_valid_handle(document.did, document.handles)
+      first_verified_handle(document.did, document.handles)
     end
 
-    def pick_valid_handle(did, handles)
-      handles.detect { |h| resolve_handle(h) == did }
+    def first_verified_handle(did, handles)
+      handles.detect { |h| resolve_handle(h) == did.to_s }
     end
   end
 end

data/lib/didkit/services.rb

@@ -1,3 +1,5 @@
+require 'uri'
+
 module DIDKit
   module Services
     def get_service(key, type)
@@ -11,5 +13,16 @@ module DIDKit
     def labeler_endpoint
       @labeler_endpoint ||= get_service('atproto_labeler', 'AtprotoLabeler')&.endpoint
     end
+
+    def pds_host
+      pds_endpoint&.then { |x| URI(x).host }
+    end
+
+    def labeler_host
+      labeler_endpoint&.then { |x| URI(x).host }
+    end
+
+    alias labeller_endpoint labeler_endpoint
+    alias labeller_host labeler_host
   end
 end

data/lib/didkit/version.rb

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

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: didkit
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Kuba Suder
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description:
 email:
 - jakub.suder@gmail.com
 executables: []
@@ -40,7 +38,6 @@ metadata:
   bug_tracker_uri: https://github.com/mackuba/didkit/issues
   changelog_uri: https://github.com/mackuba/didkit/blob/master/CHANGELOG.md
   source_code_uri: https://github.com/mackuba/didkit
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -55,8 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A library for handling Distributed ID (DID) identifiers used in Bluesky AT
   Protocol