atlas_rb 1.6.5 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19c01cf68a6a94d94dceff16d5e8ea00e147b8db2c6fd51f8d6c1e9b8ec36fac
-  data.tar.gz: 457092385fc63ed58a2c2e871983bfb2a62d2d69448a74c78796d6a6f14506be
+  metadata.gz: 1a9ee4ab4b57221618d8ad13ab874acbfce61a452efc8e9562559fcb0215bef8
+  data.tar.gz: 22c8c48404af609784177ba0f157380bc1cef435f9b6b37b76f6e65b95cef1a2
 SHA512:
-  metadata.gz: 2008dd0082b8de90ca4016a8a66c378bc88a6a6cc61b44070d9fcf9c9fd13ed5d21f81787dbd1b0131194b8edbd10eaf4904366c5e496452fd689fe2eedab429
-  data.tar.gz: 801b406750972c2dc014c4e202fcb53a2d204e554197c5594015f4dd0c0b60d58839ad6aab8b7c8659399082618483be9bc918543355f06d6a7ad3d125ed7107
+  metadata.gz: 68ddbb93d8ad4049f16d01786d860f3ccc7bd610e5f57144f79ba0e30dd1bb8e66fd4c98adf17e9847b8551e9b42265b649650acd6c23f3a6dad3ffa3479879b
+  data.tar.gz: bdfa9d364af363d50466158d13a944c3062b6d8649e5de57fdbb350d87e30e2c0fbf4dcc72c6ff515b536b40358456dc7359d449e1b2926149ff5f489f3ba9d5

data/.version

@@ -1 +1 @@
-1.6.5
+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.5)
+    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

data/lib/atlas_rb/person.rb

@@ -5,7 +5,14 @@ module AtlasRb
   # directory. A Person correlates the several `users` rows that share a NUID
   # and carries the authoritative, librarian-editable `display_name` (the SSO
   # `users.name` is frequently wrong and is clobbered on every login), plus
-  # community affiliations.
+  # community affiliations and a stable **personal-root Collection**.
+  #
+  # The returned Mash carries `personal_root_id` — the **NOID** of that personal
+  # root, the structural parent the weighted-deposit publish conduit writes the
+  # person's own Works under (then linked into a community showcase via
+  # {Work.add_linked_member}). Atlas mints it eagerly at create, so it is always
+  # present on a Person; read it straight off the resolve/find Mash, e.g.
+  # `AtlasRb::Work.create(person["personal_root_id"], depositor: person["nuid"])`.
   #
   # Addressed by **NOID** (like Work/Collection) — the staff-facing NUID is kept
   # server-side and never put in a public URL. So the positional `id` argument
@@ -27,7 +34,8 @@ module AtlasRb
     # @param nuid [String, nil] acting principal (signed into the assertion sub).
     # @param on_behalf_of [String, nil] acting-as target.
     # @return [AtlasRb::Mash] the unwrapped `"person"` object (carries the
-    #   server-side `nuid` for callers that need it, e.g. depositor gating).
+    #   server-side `nuid` for callers that need it, e.g. depositor gating, and
+    #   `personal_root_id` for the publish-conduit parent).
     def self.find(id, nuid: nil, on_behalf_of: nil)
       AtlasRb::Mash.new(JSON.parse(
         connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id)&.body
@@ -35,8 +43,9 @@ module AtlasRb
     end
 
     # List people — the NOID-keyed People-index source. Returns the page's
-    # Persons (each with `noid`, `display_name`, and the server-side `nuid`), so
-    # a consumer builds the index and profiles entirely through atlas_rb without
+    # Persons (each with `noid`, `display_name`, the server-side `nuid`, and
+    # `personal_root_id`), so a consumer builds the index and profiles entirely
+    # through atlas_rb without
     # routing People through the catalog/Solr or exposing a NUID publicly.
     #
     # @param page [Integer, nil] 1-based page (server default when nil).
@@ -54,11 +63,14 @@ module AtlasRb
 
     # Batch-resolve people to their authoritative display_name in one call
     # (supersedes the SSO users directory's resolve). Unresolved NUIDs drop.
+    # The deposit fork reads `affiliated_community_ids` and `personal_root_id`
+    # off the same resolve Mash it already makes for the depositor's Person.
     #
     # @param nuids [Array<String>] the NUIDs to resolve.
     # @param nuid [String, nil] acting principal.
     # @param on_behalf_of [String, nil] acting-as target.
-    # @return [Array<AtlasRb::Mash>] one unwrapped `"person"` per resolved NUID.
+    # @return [Array<AtlasRb::Mash>] one unwrapped `"person"` per resolved NUID
+    #   (each carries `nuid`, `affiliated_community_ids`, and `personal_root_id`).
     def self.resolve(nuids, nuid: nil, on_behalf_of: nil)
       JSON.parse(
         connection({ nuids: Array(nuids).join(",") }, nuid, on_behalf_of: on_behalf_of).get(ROUTE)&.body

metadata

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