atlas_rb 1.5.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e6020b2b0ed84ff61541cdcc4ac4ef2634a4ee4573540c5e10888cab26ec2df
-  data.tar.gz: e18077da93ef29644e95cd94bc231bd42497d7bc21e05b5f97cd27df92346a6f
+  metadata.gz: f0b6def06432136a4f0fda238a5c8ff3599de63234325e8609d0fcc49012d42d
+  data.tar.gz: a50c8fbbcaa1776a171f199e86e5ab90a8034f8c9415547c97893f52dc26a449
 SHA512:
-  metadata.gz: '068bedce232453c430a4e55c3f252f24a11b3710bc6870cc3061f9d3ec183c39600a5c814147d26ec054684afa5e3a7bc07ffc7d98a676b63904e5a11fc36343'
-  data.tar.gz: 546dd7050f56a82cd66f54bc38d0d003cc1099f1b998b64255a06ba31ee54d9fbb84a799d56bc46a635b68dd97bb9b87abbb5a94f09bcf2c539220bbb40278c8
+  metadata.gz: 19578a460cb38f49fd97a7513cc2ba6d782fa260a82f3c1071cc88e01a6a21ad6026969422033af5ad013f3e81d2d4d400fab42c72b300bd410582dc806d7f29
+  data.tar.gz: 941ce0caf062890a63891e5a458d83e1300e9240240f8adaf39a9e7ed7879ddaf4ef8168c566b052c5c7f7fde50c66e00e93baa66f71462a5464f2ea1b4a03ad

data/.version

@@ -1 +1 @@
-1.5.0
+1.6.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.5.0)
+    atlas_rb (1.6.1)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -13,7 +13,7 @@ GEM
   specs:
     base64 (0.3.0)
     diff-lcs (1.6.1)
-    faraday (2.14.2)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger

data/lib/atlas_rb/blob.rb

@@ -24,11 +24,15 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @return [Hash] the `"blob"` object, already unwrapped — typically
-    #   includes `"id"`, `"original_filename"`, `"size"`, and a download URL.
+    #   includes `"id"`, `"original_filename"`, `"size"`, `"digest"` (the
+    #   recorded fixity digest `"sha512:<hex>"`, or `nil` for a Blob with no
+    #   held bytes — reconciliation compares this against the v1 manifest
+    #   without re-downloading), and a download URL.
     #
     # @example
     #   AtlasRb::Blob.find("b-321")
-    #   # => { "id" => "b-321", "original_filename" => "scan.pdf", ... }
+    #   # => { "id" => "b-321", "original_filename" => "scan.pdf",
+    #   #      "digest" => "sha512:9f86d0…", ... }
     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
@@ -82,33 +86,44 @@ module AtlasRb
     # @param idempotency_key [String, nil] optional UUID. A repeat call with
     #   the same key returns the originally-created Blob instead of creating
     #   a new one. See {AtlasRb::Work.create} for full semantics.
+    # @param expected_digest [String, nil] optional verify-on-ingest checksum,
+    #   `"<algorithm>:<hexvalue>"` (sha512/sha256/sha1/md5, e.g.
+    #   `"sha256:abc…"`). Atlas hashes the uploaded bytes **before** persisting
+    #   and raises {AtlasRb::FixityMismatchError} (HTTP 422) on a mismatch or an
+    #   unsupported algorithm — nothing is left behind on rejection.
     # @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 [Hash] the created `"blob"` payload, including its `"id"`.
+    # @return [Hash] the created `"blob"` payload, including its `"id"` and
+    #   `"digest"` (the recorded fixity digest, `"sha512:<hex>"`).
+    # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
+    #   the uploaded bytes did not match (or the algorithm is unsupported).
+    #
+    # @note Streams the file (FD closed deterministically); a multi-GB upload is
+    #   not buffered in memory. See {AtlasRb::FaradayHelper#with_file_part}.
     #
     # @example
     #   AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "final_thesis.pdf")
     #   # => { "id" => "b-321", "original_filename" => "final_thesis.pdf", ... }
     #
-    # @example Retry-safe bulk-deposit create
+    # @example Retry-safe bulk-deposit create with fixity verification
     #   key = SecureRandom.uuid
     #   AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "thesis.pdf",
-    #                        idempotency_key: key)
-    def self.create(id, blob_path, original_filename, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
-      payload = { work_id: id,
-                  original_filename: original_filename,
-                  binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
-                                                          "application/octet-stream",
-                                                          File.basename(blob_path)) }
+    #                        idempotency_key: key, expected_digest: "sha256:#{sha}")
+    def self.create(id, blob_path, original_filename, expected_digest: nil,
+                    idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+      with_file_part(blob_path) do |part|
+        payload = { work_id: id, original_filename: original_filename, binary: part }
+        payload[:expected_digest] = expected_digest if expected_digest
 
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
-          .post(ROUTE, payload)&.body
-      ))['blob']
+        AtlasRb::Mash.new(JSON.parse(
+          multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
+            .post(ROUTE, payload)&.body
+        ))['blob']
+      end
     end
 
     # Delete a Blob (the bytes *and* the metadata record).
@@ -136,23 +151,32 @@ module AtlasRb
     #
     # @param id [String] the Blob ID.
     # @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 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 [Hash] the parsed JSON response from the patch.
+    # @return [Hash] the parsed JSON response from the patch (the updated
+    #   `"blob"`, with a refreshed `"digest"` for the new revision).
+    # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
+    #   the uploaded bytes did not match (or the algorithm is unsupported).
+    #
+    # @note Streams the file with the FD closed deterministically — see {.create}.
     #
     # @example
     #   AtlasRb::Blob.update("b-321", "/tmp/revised.pdf")
-    def self.update(id, blob_path, nuid: nil, on_behalf_of: nil)
-      payload = { binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
-                                                          "application/octet-stream",
-                                                          File.basename(blob_path)) }
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
-      ))
+    def self.update(id, blob_path, expected_digest: 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
+        ))
+      end
     end
   end
 end

data/lib/atlas_rb/compilation.rb

@@ -53,16 +53,31 @@ module AtlasRb
       ))["compilation"]
     end
 
-    # List Compilations, owner-scoped and paginated (newest first).
-    #
-    # Defaults to the acting user's own Sets. Pass `owner:` to list another
-    # user's — that is admin-only and raises {AtlasRb::ForbiddenError} for
-    # anyone else. There is no public browse surface. Pass `q:` to narrow
-    # by case-insensitive title substring; the filter applies before
-    # pagination, so the `"pagination"` block describes the filtered result.
+    # List Compilations, paginated (newest first), in one of three modes.
+    #
+    # Default (no `scope:`) is owner-scoped: the acting user's own Sets. Pass
+    # `owner:` to list another user's — admin-only, raising
+    # {AtlasRb::ForbiddenError} for anyone else; there is no public browse
+    # surface.
+    #
+    # Pass `scope:` for grant-scoped discovery — Sets where the acting user is
+    # a *grantee* but **not** the owner (owned Sets are always excluded; list
+    # those with the default mode):
+    #   - `scope: :editable` — Sets the caller may edit (`edit_users` /
+    #     `edit_groups` grants).
+    #   - `scope: :shared` — Sets shared with the caller (`read_groups` grants,
+    #     plus the edit grants that imply read).
+    # Grant-scoped modes are keyed on the acting user; `owner:` is ignored and
+    # group membership is resolved server-side. An unknown `scope:` is a 400.
+    #
+    # Pass `q:` to narrow by case-insensitive title substring in any mode; the
+    # filter applies before pagination, so the `"pagination"` block describes
+    # the filtered result.
     #
     # @param owner [String, nil] NUID whose Sets to list (admin-only when it
-    #   isn't the acting user). Omit for "my Sets".
+    #   isn't the acting user). Omit for "my Sets". Ignored when `scope:` is set.
+    # @param scope [Symbol, String, nil] grant-scoped mode — `:editable` or
+    #   `:shared`. Omit for the owner-scoped default.
     # @param q [String, nil] case-insensitive title substring filter.
     # @param page [Integer, nil] 1-indexed page number.
     # @param per_page [Integer, nil] page size override.
@@ -82,11 +97,18 @@ module AtlasRb
     # @example Another user's Sets (admin)
     #   AtlasRb::Compilation.list(owner: "000000002", nuid: "000000004")
     #
+    # @example Sets shared with me that I can edit (not owned)
+    #   AtlasRb::Compilation.list(scope: :editable, nuid: "000000002")
+    #
+    # @example Sets shared with me to view (read + edit grants, not owned)
+    #   AtlasRb::Compilation.list(scope: :shared, nuid: "000000002")
+    #
     # @example Title typeahead
     #   AtlasRb::Compilation.list(q: "course", nuid: "000000002")
-    def self.list(owner: nil, q: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
+    def self.list(owner: nil, scope: nil, q: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
       params = {}
       params[:owner]    = owner    if owner
+      params[:scope]    = scope    if scope
       params[:q]        = q        if q
       params[:page]     = page     if page
       params[:per_page] = per_page if per_page

data/lib/atlas_rb/errors.rb

@@ -134,6 +134,41 @@ module AtlasRb
     end
   end
 
+  # Raised when Atlas rejects a binary upload's verify-on-ingest check with a
+  # `422` carrying a fixity discriminator — `fixity_mismatch` (the uploaded
+  # bytes don't match the supplied `expected_digest`) or
+  # `unsupported_digest_algorithm` (a malformed/unknown `expected_digest`).
+  # Fires on `POST /files`, `PATCH /files/:id`, and `PATCH /file_sets/:id`.
+  #
+  # The upload sibling of {ReparentError} / {LinkedMemberError}; same shape,
+  # same rationale — without it the `["blob"]` / `["file_set"]` unwrap would
+  # return `nil` on the 422 and discard the signal a migration needs to tell a
+  # corrupted transfer from a clean one. Atlas rejects *before* persisting, so
+  # nothing is left behind to clean up.
+  #
+  #   rescue AtlasRb::FixityMismatchError => e
+  #     # e.code == "fixity_mismatch": re-fetch the source, retry, or quarantine
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403).
+  class FixityMismatchError < Error
+    # @return [String, nil] the machine-readable error code from the envelope
+    #   (`"fixity_mismatch"` or `"unsupported_digest_algorithm"`).
+    attr_reader :code
+
+    # @return [String, nil] the rejected resource's ID, from the envelope (the
+    #   FileSet on the attach path; may be nil on `POST /files`).
+    attr_reader :resource_id
+
+    # @param message [String] human-readable rejection description.
+    # @param code [String, nil] the envelope's `error` discriminator.
+    # @param resource_id [String, nil] the rejected resource's ID.
+    def initialize(message, code: nil, resource_id: nil)
+      super(message)
+      @code = code
+      @resource_id = resource_id
+    end
+  end
+
   # Raised when Atlas refuses a re-parent, linked-member, or Compilation
   # request with an HTTP `403`, whose envelope is
   # `{ "error", "action", "subject" }`. Lets callers distinguish "you may

data/lib/atlas_rb/faraday_helper.rb

@@ -124,11 +124,38 @@ module AtlasRb
         headers: headers
       ) do |f|
         f.use AtlasRb::Middleware::RaiseOnStaleResource
+        # Translate Atlas's verify-on-ingest 422 (fixity_mismatch /
+        # unsupported_digest_algorithm) into a typed FixityMismatchError —
+        # the JSON-connection path already carries this; uploads need it too.
+        f.use AtlasRb::Middleware::RaiseOnResourceError
         f.request :multipart
         f.request :url_encoded
       end
     end
 
+    # Build a streaming multipart FilePart for `blob_path`, run the request
+    # inside the block, and close the underlying File handle deterministically
+    # afterward (on success or exception). The handle must stay open *during*
+    # the request — Faraday reads it while posting — so it can't be closed
+    # before the call; an unclosed handle leaks a descriptor per upload, which
+    # exhausts FDs across a TB migration of millions of files.
+    #
+    # Streaming/memory: faraday-multipart wraps the part in a streaming
+    # CompositeReadIO and the default net_http adapter sends it via
+    # `request.body_stream` (Content-Length known), so a multi-GB file uploads
+    # without being buffered into a String in memory. (Swapping the host app's
+    # default Faraday adapter to a buffering one would regress this.)
+    #
+    # @param blob_path [String] path to the binary on disk.
+    # @yieldparam part [Faraday::Multipart::FilePart] the streaming part.
+    # @return the block's return value.
+    def with_file_part(blob_path)
+      File.open(blob_path, "rb") do |io|
+        yield Faraday::Multipart::FilePart.new(io, "application/octet-stream",
+                                               File.basename(blob_path))
+      end
+    end
+
     # Build a Faraday connection authenticated as the Atlas `:system`
     # fixture for system-context calls (SSO user provisioning, etc.).
     #

data/lib/atlas_rb/file_set.rb

@@ -98,30 +98,52 @@ module AtlasRb
     # Attach (or replace) the binary content backing this FileSet.
     #
     # The body is uploaded as `application/octet-stream` regardless of the
-    # file's true type — Atlas inspects the content server-side. To upload
-    # a binary blob *plus* an original filename, use {Blob.create} directly
-    # against the underlying `/files/` endpoint.
+    # file's true type — Atlas inspects the content server-side. This is the
+    # ordered/classified-slot attach used after {.create} cuts the slot.
     #
     # @param id [String] the FileSet ID.
     # @param blob_path [String] path to the binary file on disk.
+    # @param original_filename [String, nil] the user-facing filename Atlas
+    #   should record on the resulting Blob (e.g. the v1 `"page-0001.tif"`);
+    #   preserved separately from the temp `File.basename(blob_path)`.
+    # @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 repeat call with the
+    #   same key returns the FileSet with its already-attached Blob **without
+    #   recopying the bytes** (and 410 if it was tombstoned in the interim). 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).
     # @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 [Hash] the parsed JSON response from the patch.
+    # @return [Hash] the parsed JSON response from the patch (the `"file_set"`).
+    # @raise [AtlasRb::FixityMismatchError] if `expected_digest` was supplied and
+    #   the uploaded bytes did not match (or the algorithm is unsupported).
+    #
+    # @note Streams the file with the FD closed deterministically — see
+    #   {Blob.create} / {AtlasRb::FaradayHelper#with_file_part}.
     #
     # @example
     #   AtlasRb::FileSet.update("fs-001", "/tmp/article.pdf")
-    def self.update(id, blob_path, nuid: nil, on_behalf_of: nil)
-      # Need to figure out blob vs XML
-      payload = { binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
-                                                          "application/octet-stream",
-                                                          File.basename(blob_path)) }
-      AtlasRb::Mash.new(JSON.parse(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
-      ))
+    #
+    # @example Resumable, filename-preserving migration attach
+    #   AtlasRb::FileSet.update(page["id"], "/tmp/p1.tif",
+    #                           original_filename: "page-0001.tif",
+    #                           idempotency_key: key)
+    def self.update(id, blob_path, original_filename: nil, expected_digest: nil,
+                    idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+      with_file_part(blob_path) do |part|
+        payload = { binary: part }
+        payload[:original_filename] = original_filename if original_filename
+        payload[:expected_digest]   = expected_digest   if expected_digest
+
+        AtlasRb::Mash.new(JSON.parse(
+          multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
+            .patch(ROUTE + id, payload)&.body
+        ))
+      end
     end
 
     # Persist the per-page IIIF image-service pointer on a FileSet.

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -15,39 +15,53 @@ module AtlasRb
     # {RaiseOnStaleResource}.
     #
     # It is intentionally narrow — it only fires on the re-parent
-    # (`.../parent`) and linked-member (`.../linked_members...`) write paths
-    # and the Compilation surface (`/compilations...`), and only on
-    # `403` / `422` bodies carrying an `error` discriminator.
+    # (`.../parent`) and linked-member (`.../linked_members...`) write paths,
+    # the Compilation surface (`/compilations...`), and binary uploads
+    # (`/files...`, `/file_sets...`), and only on `403` / `422` bodies carrying
+    # an `error` discriminator. The upload branch is further gated on a fixity
+    # discriminator ({FIXITY_CODES}), so a `422` on those paths with any other
+    # `error` (or `403`s on uploads, which stay raw) passes through untouched.
     # Everything else (other paths, other statuses, a `422` whose body uses a
     # different discriminator such as `tombstone`'s `code: "has_live_children"`)
     # passes through untouched, so atlas_rb stays a thin Faraday binding that
     # translates only the wire signals callers genuinely need to discriminate.
     #
     # Mapping:
-    # - `403` (any covered path) → {AtlasRb::ForbiddenError} (`error`/`action`/`subject`)
+    # - `403` on a re-parent/linked/Compilation path → {AtlasRb::ForbiddenError}
     # - `422` on `.../parent` → {AtlasRb::ReparentError} (`error`/`resource_id`)
     # - `422` on `.../linked_members...` → {AtlasRb::LinkedMemberError}
     # - `422` on `/compilations...` → {AtlasRb::CompilationError}
+    # - `422` + a fixity discriminator on `/files...` / `/file_sets...` →
+    #   {AtlasRb::FixityMismatchError}
     class RaiseOnResourceError < Faraday::Middleware
+      # Upload-path `422` discriminators this middleware translates; any other
+      # `error` on those paths passes through (Atlas owns these as a wire contract).
+      FIXITY_CODES = %w[fixity_mismatch unsupported_digest_algorithm].freeze
+
       # @param env [Faraday::Env] the completed response environment.
-      # @raise [AtlasRb::ForbiddenError] on a 403 to a covered path.
+      # @raise [AtlasRb::ForbiddenError] on a 403 to a re-parent/linked/Compilation path.
       # @raise [AtlasRb::ReparentError] on a 422 to a re-parent path.
       # @raise [AtlasRb::LinkedMemberError] on a 422 to a linked-member path.
       # @raise [AtlasRb::CompilationError] on a 422 to a Compilation path.
+      # @raise [AtlasRb::FixityMismatchError] on a 422 + fixity discriminator to an upload path.
       # @return [void]
       def on_complete(env)
-        return unless env.status == 403 || env.status == 422
+        return unless [403, 422].include?(env.status)
 
         path        = env.url&.path.to_s
         reparent    = path.end_with?("/parent")
         linked      = path.include?("/linked_members")
         compilation = path.start_with?("/compilations")
-        return unless reparent || linked || compilation
+        upload      = path.start_with?("/files") || path.start_with?("/file_sets")
+        return unless reparent || linked || compilation || upload
 
         body = parse_json(env.body)
         return unless body.is_a?(Hash) && body["error"]
 
         if env.status == 403
+          # 403s on upload paths stay raw — acting-as/authz isn't an upload concern here.
+          return unless reparent || linked || compilation
+
           raise AtlasRb::ForbiddenError.new(
             body["message"] || "Atlas refused the request",
             code: body["error"],
@@ -66,12 +80,18 @@ module AtlasRb
             code: body["error"],
             resource_id: body["resource_id"]
           )
-        else
+        elsif compilation
           raise AtlasRb::CompilationError.new(
             body["message"] || "Atlas rejected the compilation write",
             code: body["error"],
             resource_id: body["resource_id"]
           )
+        elsif FIXITY_CODES.include?(body["error"])
+          raise AtlasRb::FixityMismatchError.new(
+            body["message"] || "Atlas rejected the upload (fixity)",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
         end
       end
 

metadata

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