atlas_rb 1.8.8 → 1.8.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 790f093dac74f6f06ec40f1be385888d0acb3123901f2056b39996ab8050e1ef
-  data.tar.gz: 5137778cc466b711c9862ab661d849b795142429b3507cc3e4a2549c8ccf7813
+  metadata.gz: 2a1ca62f7d0e0d49e63754618a22967d8a89a4496c05c894bbbff7f13903e94d
+  data.tar.gz: 5645596297711e7cc464645d249b91b4b62108eaf71978f9d07ffed9590043cd
 SHA512:
-  metadata.gz: f3244e997c783521e0a86b49cdfe2cd471ad744cca7399d4497d2a250102bb3c51f3f92c6d54b17d6137171baa355fe9f4ff42464565641efbb7fc7e83e489c3
-  data.tar.gz: 676ec01145ceb6773fa6ed13eda23a40949ef1ccaf7e984576fd00988169bdd19ae1710dc7f06f72b48f48165224aa57b585e1d9bdcd74c64038f58cb96f4b05
+  metadata.gz: acd99d449e3dd94bb23cfdeabfc1190d2a074e5bfe07a2a4a8e54723fad47680f525d52e761f5ccee50ac1b464a39b889331e6468fe63bb9a0b06f8d17526262
+  data.tar.gz: c2d0db210a2a66cb41bc68baec3b6158916a86866c9a20182efc1bc2240f26e0c00357e340d08b4313312e239fabc9338bbca3f6face3c9d0576ef13d9f1f74d

data/.version

@@ -1 +1 @@
-1.8.8
+1.8.10

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.8.8)
+    atlas_rb (1.8.10)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/lib/atlas_rb/faraday_helper.rb

@@ -36,9 +36,28 @@ module AtlasRb
   # If neither a signing key nor `ATLAS_JWT` is configured there is no relay
   # credential, so the transport raises {AtlasRb::ConfigurationError}.
   #
+  # ## Instrumentation
+  #
+  # Every builder brackets its request in an `ActiveSupport::Notifications`
+  # event named **`request.atlas_rb`** (Faraday's `:instrumentation`
+  # middleware, wired as the *outermost* handler so a redirect hop — e.g. the
+  # `/resources/:noid` NOID resolver — folds into one event per logical call
+  # rather than being double-counted). The payload is the Faraday `env`, so a
+  # subscriber reads `payload.method` / `payload.url` and the event's duration.
+  # This lets a host count/time Atlas round-trips (an N+1-over-HTTP detector)
+  # without reaching into gem internals. It is guarded on
+  # `defined?(ActiveSupport::Notifications)`: Rails hosts get the events; the
+  # headless BYO-JWT path (no AS loaded) is unaffected. With no subscriber
+  # attached the emit degrades to a listener lookup + `yield`, so it is safe to
+  # leave in the stack permanently — opt-in lives entirely on the consumer side.
+  #
   # The module is mixed in via `extend`, so its methods become class methods on
   # the host (e.g. `AtlasRb::Work.connection({})`).
   module FaradayHelper
+    # ActiveSupport::Notifications event name emitted per outbound Atlas request.
+    # A dedicated name (not Faraday's default `request.faraday`) so a host that
+    # also uses Faraday for other clients can subscribe to Atlas traffic alone.
+    INSTRUMENTATION_EVENT = "request.atlas_rb"
     # Wire contract Atlas enforces for relay-signing assertions (see Atlas
     # ApplicationController#verify_cerberus_assertion). iss/aud are fixed; the
     # short TTL bounds replay (Atlas allows 30s leeway on exp).
@@ -83,6 +102,7 @@ module AtlasRb
         params: params,
         headers: headers
       ) do |f|
+        instrument(f)
         f.use AtlasRb::Middleware::RaiseOnStaleResource
         f.use AtlasRb::Middleware::RaiseOnResourceError
         f.response :follow_redirects
@@ -123,6 +143,7 @@ module AtlasRb
         url: ENV.fetch("ATLAS_URL", nil),
         headers: headers
       ) do |f|
+        instrument(f)
         f.use AtlasRb::Middleware::RaiseOnStaleResource
         # Translate Atlas's verify-on-ingest 422 (fixity_mismatch /
         # unsupported_digest_algorithm) into a typed FixityMismatchError —
@@ -190,6 +211,7 @@ module AtlasRb
         params: params,
         headers: headers
       ) do |f|
+        instrument(f)
         f.response :follow_redirects
         f.adapter Faraday.default_adapter
       end
@@ -197,6 +219,20 @@ module AtlasRb
 
     private
 
+    # Register Faraday's instrumentation middleware as the OUTERMOST handler so
+    # each logical call emits exactly one {INSTRUMENTATION_EVENT} — a redirect
+    # hop (e.g. the `/resources/:noid` resolver) is bracketed with the request
+    # it redirects to, not counted twice. Guarded on
+    # `defined?(ActiveSupport::Notifications)` because Faraday defaults its
+    # instrumenter to that constant and would `NameError` at build time on the
+    # headless path where ActiveSupport isn't loaded; there, the emit is simply
+    # never wired and the transport is unaffected.
+    def instrument(builder)
+      return unless defined?(ActiveSupport::Notifications)
+
+      builder.request :instrumentation, name: INSTRUMENTATION_EVENT
+    end
+
     # Build the auth + identity headers shared by {#connection} and {#multipart}.
     # Precedence: ATLAS_JWT (BYO-JWT) > relay-signing. The acting nuid /
     # on_behalf_of fall through to the configured `default_nuid` /

data/lib/atlas_rb/resource.rb

@@ -88,6 +88,52 @@ module AtlasRb
       ).map { |node| AtlasRb::Mash.new(node) }
     end
 
+    # Every Work beneath a resource, at any depth — the structural counterpart
+    # to {Compilation.contents}. Wraps `GET /resources/<id>/descendant_works`,
+    # which flattens the resource's full descendant subtree to the Works it
+    # contains, gated to what the caller may read and paginated Solr-side. Gives
+    # a Collection the flatten-to-Works capability a Set already has, so a bulk
+    # export (e.g. hyperion) pages one gated, fast call family instead of the
+    # client-side `children → find_many → recurse` walk.
+    #
+    # Returns the same digest shape as {find_many} / {Compilation.contents}
+    # (`{ "id", "noid", "klass", "title", "thumbnail" }`) under a `"works"` key,
+    # plus a `"pagination"` envelope (`total` / `page` / `per_page` / `pages`).
+    # Membership is **structural** (`a_member_of`) only; pass
+    # `include_linked: true` to also surface linked members
+    # (`a_linked_member_of`). Restricted Works never appear for a caller who may
+    # not read them; tombstoned Works are dropped.
+    #
+    # @param id [String] an Atlas resource ID (subtree root; any type).
+    # @param page [Integer, nil] 1-based page (default 1 server-side).
+    # @param per_page [Integer, nil] page size (server default 25, capped 100).
+    # @param include_linked [Boolean, nil] also include linked members when
+    #   truthy; structural-only by default.
+    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
+    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
+    #   path it is ignored (identity lives in the token).
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when omitted.
+    # @return [AtlasRb::Mash, nil] the parsed envelope, with a `"works"` digest
+    #   array and a `"pagination"` block; `nil` when the id resolves to nothing
+    #   (`404`).
+    #
+    # @example Page a Collection's whole subtree of Works
+    #   result = AtlasRb::Resource.descendant_works("col-456", per_page: 100)
+    #   result["works"].map { |w| w["noid"] }
+    #   result.dig("pagination", "pages")
+    def self.descendant_works(id, page: nil, per_page: nil, include_linked: nil, nuid: nil, on_behalf_of: nil)
+      params = {}
+      params[:page]           = page           if page
+      params[:per_page]       = per_page       if per_page
+      params[:include_linked] = include_linked unless include_linked.nil?
+      resp = connection(params, nuid, on_behalf_of: on_behalf_of)
+             .get('/resources/' + id + '/descendant_works')
+      return nil if resp.status == 404
+
+      AtlasRb::Mash.new(JSON.parse(resp.body))
+    end
+
     # Validate a MODS XML document against Atlas's schema *without* persisting it.
     #
     # Useful for surfacing validation errors in UIs before the user commits.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.8.8
+  version: 1.8.10
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-05 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday