atlas_rb 1.13.2 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee82f1db7ce18ffe409251ea5a22e0d8692d06d27feb2563ffaeeb8ebb3ac808
-  data.tar.gz: 448a08729406f6565e33fb42d317f3a52f4ccbe252381cea05717b473022aa69
+  metadata.gz: 683f9aa507f7cfa025781f231f839bdb39bb44f566e074e8ca304200da86e426
+  data.tar.gz: e12684f3de4d03e69e1024ab43765a4912f2f550c2ff01e72bc5953da5d55089
 SHA512:
-  metadata.gz: 709a6b7987e43637465f30345224a52792e936383f146c0a70311dce3484d3b4bd129c54bc84051c3047778871d8692bdd26e132557cffef1e87af609de14b65
-  data.tar.gz: 409ee2cfd24bae4d5b2bb89b9cdfd1eafc50c011f6f9c0842151d7c36ff09f53f19a61f9ffcab19c53e1beffe62bf179be21e106b3f813efee2af7dbca521a8d
+  metadata.gz: 9b34332d51540262c758c6e40e1c8eab538b3601e22fdde3639e60897e75b6c0cc9483b8a79eed1165f179f07bc2012ee9fd96d218e5dcf589f1d8c0734bd8ab
+  data.tar.gz: b56c2e3c5cadff71fb0ec53765c3160c27d6d695a0458d0e0e8cb09b65aaf7da483d3d436735cda2d41f82b8dc6227a0a3c262c4a2fc9696d39c9247f5c1e139

data/.version

@@ -1 +1 @@
-1.13.2
+1.14.0

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.14.0
+
+### Added — `Blob.find_many_versions`, the batch version-history read
+
+`AtlasRb::Blob.versions` takes one id, so a caller holding a set of Blob noids
+had to fan out a request per noid. The admin file-manage listing does exactly
+that: it reads every replaceable Blob on a Work, which on a multipage Work is
+one request per page binary, all before the page returns a byte.
+
+`Blob.find_many_versions` wraps Atlas's `POST /files/find_many_versions` and
+answers one `versions`-shaped envelope per Blob in a single call.
+
+```ruby
+assets  = AtlasRb::Work.assets(work_noid).reject { |a| a[:uri].present? }
+history = AtlasRb::Blob.find_many_versions(assets.map(&:noid))
+                       .index_by { |h| h["blob_id"] }
+history[assets.first.noid]["versions"].first["revision"] # => 3
+```
+
+The result is **unordered** and **may be shorter than the input** — an id that
+resolves to nothing, or to a resource that is not a Blob, is dropped silently.
+Index by `"blob_id"`.
+
+Requires Atlas >= 0.6.161. Admin-gated exactly like `.versions`. `.versions`
+itself is unchanged.
+
 ## 1.13.2
 
 ### Documentation — point `children` callers at the batch resolver

data/Gemfile.lock

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

data/lib/atlas_rb/blob.rb

@@ -290,6 +290,48 @@ module AtlasRb
       ))
     end
 
+    # Read binary version history for many Blobs in one round-trip.
+    #
+    # Wraps Atlas's `POST /files/find_many_versions` — the batch counterpart to
+    # {.versions}, returning one envelope of exactly that shape per Blob. Use it
+    # anywhere a set of Blob noids would otherwise be resolved with a
+    # `versions`-per-noid fan-out (the admin file-manage listing, which reads
+    # every replaceable Blob on a Work): one HTTP call instead of N.
+    #
+    # The ids travel in the request **body**, so the list is not bounded by URL
+    # length. The result is **unordered** and **may be shorter than the input** —
+    # an id that resolves to nothing, or to a resource that is not a Blob, is
+    # dropped silently. Index by `"blob_id"`; do not assume positional
+    # correspondence with `ids`.
+    #
+    # Server admin-gates this exactly like {.versions} (the descriptors expose
+    # the same edit attribution), so `401` / `403` surface as raw Faraday
+    # responses. The grant is class-wide, so nothing is dropped for
+    # authorization — a dropped id is an unresolvable one.
+    #
+    # @param ids [Array<String>] Blob NOIDs.
+    # @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 [Array<AtlasRb::Mash>] one {.versions}-shaped envelope per resolved
+    #   Blob (`"blob_id"` plus a reverse-chronological `"versions"` array); empty
+    #   when none resolved.
+    #
+    # @example Render a Work's files with their histories in two calls
+    #   assets  = AtlasRb::Work.assets(work_noid).reject { |a| a[:uri].present? }
+    #   history = AtlasRb::Blob.find_many_versions(assets.map(&:noid))
+    #                          .index_by { |h| h["blob_id"] }
+    #   history[assets.first.noid]["versions"].first["revision"] # => 3
+    def self.find_many_versions(ids, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .post("#{ROUTE}find_many_versions", JSON.dump(ids: Array(ids)))&.body
+      ).map { |envelope| AtlasRb::Mash.new(envelope) }
+    end
+
     # Stream the bytes of a *prior* version of a Blob through a block.
     #
     # Wraps `GET /files/<id>/versions/<version_id>/content` — the version-pinned

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.13.2
+  version: 1.14.0
 platform: ruby
 authors:
 - David Cliff