atlas_rb 1.6.6 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73faf0ef6535c48fc4e56f6aead845d9110cd9cc41966a8fc336d397840040b0
-  data.tar.gz: 36ad840afae41129b06fafd5b4957502d9264800dc27b3998e36dfaa6d3c1a4a
+  metadata.gz: a3d2bc949790f66ee7081de2e94d427f69869fcb301c45d4b9399c072f466820
+  data.tar.gz: 466abe63f27507e1845bc1126b739d2bfa396f7c79c447b1bf57e5be42352f4c
 SHA512:
-  metadata.gz: 830fc91838b5aaa0a6faa92f040657caa59aa5da3b304c251faf5966cea78807b045af0299220378a0a5c8214c88e8aad335c0aa98f9ff0ec8148204d36bb6a9
-  data.tar.gz: be1b28b4473fe3761c9d99f00e7138b9bb7ef7445bf62b58d990d94b9b34627434e5a72b4d9cfe9bb4666f0a5c1ec0a95a4a9f6d795aea97078b7b2bf8aa3ede
+  metadata.gz: 87494a7060c9b9f192edb404ecffd98ea5b8f4859f4b507e25e7a8d66717d34af7c240f3d99df13163f5e822163d5d3f146df4e9898937a5cb0687b80d12cae1
+  data.tar.gz: 04b3221d9ae88ff6bd1b4586321dbd4eda20a4f6753cedfbf465ad4ad2d27214f5252a6e7dd4259e10a24b813eda4a966a7a39fd243244ad295b9c9a749cd5a6

data/.version

@@ -1 +1 @@
-1.6.6
+1.8.0

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.8.0
+
+### Added — `Work.set_full_text` (full-text search seam)
+
+`Work.set_full_text(id, text:)` → `PATCH /works/:id/full_text`. Hands Atlas the
+Work-level aggregate of Cerberus-extracted document text; Atlas stores it as the
+Work's derived `full_text` and projects it onto the Work's Solr doc
+(`all_text_timv`) for body-text search and the "Full Text Match" snippet. Same
+"machine-set derived metadata" family as `set_thumbnails` / `set_image_derivatives`
+— a regenerable search aid re-sent on any re-ingest, not user-authored content.
+
+## 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.8.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/work.rb

@@ -344,6 +344,42 @@ module AtlasRb
       ))
     end
 
+    # Store a Work's derived full-document text for search indexing.
+    #
+    # Purpose-specific PATCH in the same "machine-set derived metadata" family
+    # as {.set_thumbnails} / {.set_image_derivatives}. Hand Atlas the Work-level
+    # aggregate of the extracted body text (the concatenation of the Work's
+    # content FileSets' text); Atlas stores it as the Work's derived `full_text`
+    # and its `FullTextIndexer` projects it onto the Work's Solr doc
+    # (`all_text_timv`) for body-text search + the "Full Text Match" snippet.
+    #
+    # Distinct from {.metadata} — this is a machine-extracted search aid
+    # (pdftotext / Tika in a Cerberus job), not user-authored descriptive
+    # content, and is re-sent on any re-ingest. Empty/blank text clears it.
+    #
+    # @param id [String] the Work ID.
+    # @param text [String] the extracted plain text (Work-level aggregate).
+    # @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 JSON response (the Work; the stored text
+    #   is not echoed back — it's read only through Solr).
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
+    #
+    # @example
+    #   AtlasRb::Work.set_full_text("w-789", text: extracted_pdf_text)
+    def self.set_full_text(id, text:, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id + '/full_text', JSON.dump(text: text))&.body
+      ))
+    end
+
     # List the assets attached to a Work — {Blob}s and {Delegate}s alike.
     #
     # Useful for building download UIs — the response includes enough to

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.6.6
+  version: 1.8.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