atlas_rb 1.6.6 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73faf0ef6535c48fc4e56f6aead845d9110cd9cc41966a8fc336d397840040b0
-  data.tar.gz: 36ad840afae41129b06fafd5b4957502d9264800dc27b3998e36dfaa6d3c1a4a
+  metadata.gz: 1a9ee4ab4b57221618d8ad13ab874acbfce61a452efc8e9562559fcb0215bef8
+  data.tar.gz: 22c8c48404af609784177ba0f157380bc1cef435f9b6b37b76f6e65b95cef1a2
 SHA512:
-  metadata.gz: 830fc91838b5aaa0a6faa92f040657caa59aa5da3b304c251faf5966cea78807b045af0299220378a0a5c8214c88e8aad335c0aa98f9ff0ec8148204d36bb6a9
-  data.tar.gz: be1b28b4473fe3761c9d99f00e7138b9bb7ef7445bf62b58d990d94b9b34627434e5a72b4d9cfe9bb4666f0a5c1ec0a95a4a9f6d795aea97078b7b2bf8aa3ede
+  metadata.gz: 68ddbb93d8ad4049f16d01786d860f3ccc7bd610e5f57144f79ba0e30dd1bb8e66fd4c98adf17e9847b8551e9b42265b649650acd6c23f3a6dad3ffa3479879b
+  data.tar.gz: bdfa9d364af363d50466158d13a944c3062b6d8649e5de57fdbb350d87e30e2c0fbf4dcc72c6ff515b536b40358456dc7359d449e1b2926149ff5f489f3ba9d5

data/.version

@@ -1 +1 @@
-1.6.6
+1.7.0

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.7.0
+
+### Added — binary version read surface (`Blob.versions` / `version_content` / `rollback`)
+
+The binary counterpart to `Resource.mods_versions` / `mods_version`. Replacing a
+file (`Blob.update`) already retains prior bytes in OCFL; these bindings make the
+retained versions addressable:
+
+- `Blob.versions(id)` → `GET /files/:id/versions` — reverse-chronological
+  envelope (`{ "blob_id", "versions" }`), one descriptor per retained content
+  revision (`version_id`, `file_identifier`, `created`, `digest`, `size`,
+  `original_filename`, plus correlated `actor_nuid` / `on_behalf_of_nuid`).
+  Admin-gated by the server.
+- `Blob.version_content(id, version_id, &chunk_handler)` →
+  `GET /files/:id/versions/:version_id/content` — streams a prior version's
+  bytes through a block, exactly like `Blob.content`.
+- `Blob.rollback(id, version_id)` → `POST /files/:id/rollback` — reinstates a
+  prior version by appending its bytes as a new revision (non-destructive; NOID
+  preserved).
+
+### Added — `Blob.update` accepts `idempotency_key:`
+
+`Blob.update` (`PATCH /files/:id`) now takes an optional `idempotency_key:`,
+threaded as the `Idempotency-Key` header (same semantics as `Blob.create` /
+`FileSet.create`). A double-submitted replace sharing a key returns the existing
+Blob instead of minting a second OCFL version.
+
 ## 1.5.0
 
 ### Added — optional auth for `Reset.clean`

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.6.6)
+    atlas_rb (1.7.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -25,7 +25,7 @@ GEM
       net-http (~> 0.5)
     hashie (5.1.0)
       logger
-    json (2.19.9)
+    json (2.20.0)
     jwt (2.10.3)
       base64
     logger (1.7.0)

data/lib/atlas_rb/blob.rb

@@ -153,6 +153,10 @@ module AtlasRb
     # @param blob_path [String] path to the replacement binary on disk.
     # @param expected_digest [String, nil] optional verify-on-ingest checksum,
     #   `"<algorithm>:<hexvalue>"`. 422 ({AtlasRb::FixityMismatchError}) on mismatch.
+    # @param idempotency_key [String, nil] optional UUID. A double-submit of the
+    #   replace with the same key returns the existing Blob instead of minting a
+    #   second OCFL version — without it a retried replace appends a duplicate
+    #   revision. See {AtlasRb::Work.create} for full semantics.
     # @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).
@@ -168,15 +172,123 @@ module AtlasRb
     #
     # @example
     #   AtlasRb::Blob.update("b-321", "/tmp/revised.pdf")
-    def self.update(id, blob_path, expected_digest: nil, nuid: nil, on_behalf_of: nil)
+    #
+    # @example Retry-safe replace
+    #   AtlasRb::Blob.update("b-321", "/tmp/revised.pdf", idempotency_key: SecureRandom.uuid)
+    def self.update(id, blob_path, expected_digest: nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
       with_file_part(blob_path) do |part|
         payload = { binary: part }
         payload[:expected_digest] = expected_digest if expected_digest
 
         AtlasRb::Mash.new(JSON.parse(
-          multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
+          multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
+            .patch(ROUTE + id, payload)&.body
         ))
       end
     end
+
+    # List a Blob's retained binary version history.
+    #
+    # Wraps Atlas's `GET /files/<id>/versions` — the binary counterpart to
+    # {Resource.mods_versions}. Returns a reverse-chronological (newest first)
+    # envelope: one descriptor per retained content revision, each carrying its
+    # OCFL `version_id` label, the `file_identifier` appended for that revision,
+    # the `created` timestamp, the `digest`/`size` recorded at that version,
+    # the stable `original_filename`, and actor attribution (`actor_nuid` /
+    # `on_behalf_of_nuid`, null when no audit event correlates).
+    #
+    # Server admin-gates this endpoint (it exposes edit attribution), so
+    # `401` / `403` surface as raw Faraday responses, matching
+    # {Resource.mods_versions}. An unknown Blob id yields a `404`.
+    #
+    # @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] the parsed envelope, with `"blob_id"` and a
+    #   `"versions"` array (reverse chronological).
+    #
+    # @example
+    #   history = AtlasRb::Blob.versions("b-321")
+    #   history["versions"].first["version_id"] # => "v5"
+    #   history["versions"].first["digest"]      # => "sha512:9f86d0…"
+    def self.versions(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/versions")&.body
+      ))
+    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
+    # twin of {.content}, and the read half of "download the superseded file".
+    # Like {.content}, the body is **not** buffered: each chunk is yielded to
+    # `chunk_handler` immediately (safe for files larger than memory), and the
+    # response headers are captured and returned.
+    #
+    # Pass a `version_id` obtained from {.versions} (an opaque OCFL `vN` label);
+    # only labels the history surfaced are addressable. An unknown id or version
+    # yields a `404` (raw Faraday response).
+    #
+    # @param id [String] the Blob ID.
+    # @param version_id [String] an OCFL version label from {.versions}, e.g. `"v1"`.
+    # @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.
+    # @yieldparam chunk [String] the next chunk of binary data.
+    # @return [Hash] the response headers from the version-content request.
+    #
+    # @example Download a superseded version to disk
+    #   File.open("/tmp/old.pdf", "wb") do |f|
+    #     AtlasRb::Blob.version_content("b-321", "v1") { |chunk| f.write(chunk) }
+    #   end
+    def self.version_content(id, version_id, nuid: nil, on_behalf_of: nil, &chunk_handler)
+      headers = {}
+      connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/versions/#{version_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
+      end
+      headers
+    end
+
+    # Roll a Blob back to a prior version.
+    #
+    # Wraps `POST /files/<id>/rollback`. Atlas promotes the given version to
+    # current by appending its bytes again as a NEW revision — so rollback is
+    # itself non-destructive (it becomes vN+1 with the bytes of vN) and the Blob
+    # NOID is preserved. OCFL dedups the identical content, so no bytes are
+    # recopied. Avoids a full round-trip of the bytes back through the caller
+    # (vs. re-streaming {.version_content} into {.update}).
+    #
+    # Pass a `version_id` obtained from {.versions}. An unknown id or version
+    # yields a `404` (raw Faraday response).
+    #
+    # @param id [String] the Blob ID.
+    # @param version_id [String] the OCFL version label to reinstate, e.g. `"v1"`.
+    # @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] the updated `"blob"` payload (NOID unchanged,
+    #   `"digest"` refreshed to the reinstated bytes).
+    #
+    # @example
+    #   AtlasRb::Blob.rollback("b-321", "v1")
+    def self.rollback(id, version_id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .post("#{ROUTE}#{id}/rollback", JSON.dump(version_id: version_id))&.body
+      ))['blob']
+    end
   end
 end

metadata

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