atlas_rb 1.8.0 → 1.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3d2bc949790f66ee7081de2e94d427f69869fcb301c45d4b9399c072f466820
-  data.tar.gz: 466abe63f27507e1845bc1126b739d2bfa396f7c79c447b1bf57e5be42352f4c
+  metadata.gz: 0a0fac04427bc3f23f92da8a5241a263111f45b28fa01cc8829da0de3b6b48f9
+  data.tar.gz: 8e95150d0f2ecd0a33c52179e384f8462546b422dcd6997c69886163215811c8
 SHA512:
-  metadata.gz: 87494a7060c9b9f192edb404ecffd98ea5b8f4859f4b507e25e7a8d66717d34af7c240f3d99df13163f5e822163d5d3f146df4e9898937a5cb0687b80d12cae1
-  data.tar.gz: 04b3221d9ae88ff6bd1b4586321dbd4eda20a4f6753cedfbf465ad4ad2d27214f5252a6e7dd4259e10a24b813eda4a966a7a39fd243244ad295b9c9a749cd5a6
+  metadata.gz: 4ced2b3f0f3fee473712f38ae3161ea8f678d9468abaf1250c9577e13261b5688be16ea687a69f6b28931a6e8920ad737d7a2057059c14751cceb683e463c2ef
+  data.tar.gz: 017e1004f59a5529184e3f07f93c815a463da07937863ff72b2063b3e1986f624e5e8ea83c0b5750b57885e7942ef981b32e66f7d3e5931ea6545108c643162d

data/.version

@@ -1 +1 @@
-1.8.0
+1.8.2

data/Gemfile.lock

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

data/lib/atlas_rb/blob.rb

@@ -39,14 +39,65 @@ module AtlasRb
       ))['blob']
     end
 
+    # Resolve a content Blob to its parent FileSet and containing Work noids.
+    #
+    # Wraps `GET /files/<id>/ancestry`. The download path is keyed only by the
+    # blob id, so a consumer recording a download/stream impression against the
+    # containing Work resolves it here — instead of threading the work noid
+    # through the download URL. Reads on the Blob floor (no admin gate). An
+    # unknown id yields a `404` (raw Faraday response); either value is `nil`
+    # when unresolvable (e.g. an orphan blob with no FileSet parent).
+    #
+    # @param id [String] the Blob ID.
+    # @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] `{ "file_set" => "<noid>", "work" => "<noid>" }`
+    #   (either value `nil` when unresolvable).
+    #
+    # @example
+    #   AtlasRb::Blob.ancestry("b-321")
+    #   # => { "file_set" => "fs-654", "work" => "w-789" }
+    def self.ancestry(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/ancestry")&.body
+      ))
+    end
+
+    # Convenience over {.ancestry}: the containing Work's noid for a content
+    # Blob (or `nil` when unresolvable). The shape Cerberus's impression-capture
+    # job wants — roll a download up to its Work from the blob id alone.
+    #
+    # @param id [String] the Blob ID.
+    # @param nuid [String, nil] optional acting user's NUID (see {.ancestry}).
+    # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID (see {.ancestry}).
+    # @return [String, nil] the containing Work's noid, or `nil` when unresolvable.
+    #
+    # @example
+    #   AtlasRb::Blob.work("b-321") # => "w-789"
+    def self.work(id, nuid: nil, on_behalf_of: nil)
+      ancestry(id, nuid: nuid, on_behalf_of: on_behalf_of)['work']
+    end
+
     # Stream the Blob's binary content through a caller-supplied block.
     #
     # The body is **not** buffered — each chunk Faraday receives is yielded
     # to `chunk_handler` immediately, making this safe for files larger than
-    # available memory. The first chunk's response headers are captured and
-    # returned so callers can inspect `Content-Type`, `Content-Length`, etc.
+    # available memory.
+    #
+    # Pass `range:` (e.g. `"bytes=0-1048575"`) to forward an HTTP `Range`
+    # header; Atlas answers `206 Partial Content` and the chunks yielded are
+    # just the requested slice. The returned hash exposes both the response
+    # **status** (200 vs 206) and the response **headers** — so a caller
+    # proxying to a browser media element can relay `Content-Range`,
+    # `Content-Length` and `Accept-Ranges` verbatim and reproduce the 206.
     #
     # @param id [String] the Blob ID.
+    # @param range [String, nil] optional HTTP byte range (`"bytes=START-END"`,
+    #   `"bytes=START-"`, or `"bytes=-SUFFIX"`). Omitted ⇒ whole-body `200`.
     # @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).
@@ -54,22 +105,25 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @yieldparam chunk [String] the next chunk of binary data.
-    # @return [Hash] the response headers from `GET /files/<id>/content`.
+    # @return [Hash] `{ status: Integer, headers: Faraday::Utils::Headers }` for
+    #   `GET /files/<id>/content` (`headers` is case-insensitive, hash-like).
     #
-    # @example Stream to disk
+    # @example Stream the whole body to disk
     #   File.open("/tmp/out.pdf", "wb") do |f|
-    #     headers = AtlasRb::Blob.content("b-321") { |chunk| f.write(chunk) }
-    #     puts headers["content-type"]
+    #     res = AtlasRb::Blob.content("b-321") { |chunk| f.write(chunk) }
+    #     puts res[:headers]["content-type"]
     #   end
-    def self.content(id, nuid: nil, on_behalf_of: nil, &chunk_handler)
-      headers = {}
-      connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/content") do |req|
-        req.options.on_data = proc do |chunk, _bytes_received, env|
-          headers = env.response_headers if headers.empty? && env
-          chunk_handler.call(chunk)
-        end
+    #
+    # @example Relay a browser's Range request as a 206
+    #   res = AtlasRb::Blob.content("b-321", range: "bytes=0-1048575") { |c| out << c }
+    #   res[:status]                       # => 206
+    #   res[:headers]["content-range"]     # => "bytes 0-1048575/52428800"
+    def self.content(id, range: nil, nuid: nil, on_behalf_of: nil, &chunk_handler)
+      response = connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/content") do |req|
+        req.headers["Range"] = range if range
+        req.options.on_data = proc { |chunk, _bytes_received, _env| chunk_handler.call(chunk) }
       end
-      headers
+      { status: response.status, headers: response.headers }
     end
 
     # Upload a new Blob attached to a Work.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.8.2
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-24 00:00:00.000000000 Z
+date: 2026-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday