atlas_rb 1.8.3 → 1.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d25a6bf4fdadf6bacf1de67390aeb15343547dba8384c511d8c34b62c1fb058e
-  data.tar.gz: f002dfcb1638bd8c5c5cb668121b9a8515f85765aaab4b229770d8d7b6b3587c
+  metadata.gz: 6b34244827cff750075d39c45f1fd628840b6b1637a06f6bfefc876f285eafbe
+  data.tar.gz: d3f429989a1b983ed13a39c8363b17f1eff439d829f3694244327a38cfc2ca7e
 SHA512:
-  metadata.gz: 9b7f605825d8d4ebb6c44c93c16bc8a7f16a6ee5cb3d7a83c2cba05c7de59e9c25fc92811f35a332ff326dc929b63c057c2743ed8d5fdeb807288f49f2cb2c79
-  data.tar.gz: 20066bd2c7f096a70d3ace6d3c36ed888d135f91e2e31dec7f7828f6eb1f0298e46e4fb0b06fe112be840846675240f6a026787f2479e8e7c73599414f3830d9
+  metadata.gz: 70c4cce5eacaabca34495bee0cd8ed0ada54998e7a90f3b39b26b601d4d20be9e16355d64ac68e75fe39fce8f28d3e25e275d5627afd3644e296c18fdca3453e
+  data.tar.gz: b46212f70bfbec6a343654f89e73e33a13a372abb2e42ff0bf88a0a667d2d5033cee6e221dbdc63022b9feca6f0fd7000c12eb90172a76feaa11540696c04daa

data/.version

@@ -1 +1 @@
-1.8.3
+1.8.5

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 1.8.5
+
+### Fixed — `find` returns a tombstone (`410`) instead of raising
+
+The status-aware `find` (1.8.3) raised `AtlasRb::ResourceError` on any non-2xx
+other than `404`. But Atlas returns a **tombstoned** resource as `410 Gone`
+**with its full body** (carrying `tombstoned` / `tombstoned_at` / `tombstoned_by`)
+— a "gone, but here it is" tombstone, not an error envelope. `fetch_resource`
+now parses a `410` like a `2xx`, so every typed `find` (`Work` / `Collection` /
+`Community` / `FileSet` / `Person` / `Compilation` / `Blob` / `Delegate` and the
+polymorphic `Resource.find`) yields the tombstone rather than raising. Genuine
+error statuses (400/401/403/422) still raise; a `404` still returns `nil`.
+
+## 1.8.4
+
+### Added — per-tier derivative-visibility policy (`Work.set_derivative_permissions`)
+
+New binding for the departmental "each download rendition has its own permissions"
+model: `AtlasRb::Work.set_derivative_permissions(id, policy:, …)` PATCHes a per-tier
+read policy to `PATCH /works/:id/derivative_permissions`. `policy` is a map of tier
+(`small` / `medium` / `large` / `service`) => array of read-group tokens (the resource
+vocabulary: `"public"`, Grouper group names, `[]` = private). Whole-object replace;
+omitted tiers inherit by cascade (an absent tier inherits the next lower-resolution
+tier; `small` inherits the Work). Atlas enforces two invariants — a tier may not be
+more visible than the Work, and visibility must narrow as resolution grows
+(`service` ⊆ `large` ⊆ `medium` ⊆ `small`).
+
+The effective per-Delegate gate surfaces on `Work.assets` entries as `gated` (must be
+authorized, not linked directly) and `permission` (the effective read-group set;
+`null` for guests). No `assets` change is needed — the new fields flow through the
+existing polymorphic Mash. The gate is advisory: Cerberus and the IIIF auth layer
+enforce it.
+
+A `422` rejection (`tier_exceeds_resource` / `tier_ordering_violation` /
+`unknown_tier`) now raises the typed `AtlasRb::DerivativePermissionsError` (with `code`
+/ `resource_id`) via `RaiseOnResourceError`, mirroring the re-parent / linked-member /
+Compilation mappings; a `403` raises `AtlasRb::ForbiddenError`; a `409` raises
+`AtlasRb::StaleResourceError`.
+
 ## 1.8.3
 
 ### Changed — `find` is status-aware (stops swallowing Atlas error envelopes)

data/Gemfile.lock

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

data/lib/atlas_rb/blob.rb

@@ -29,7 +29,7 @@ module AtlasRb
     #   held bytes — reconciliation compares this against the v1 manifest
     #   without re-downloading), and a download URL — or `nil` when the Blob
     #   does not exist (`404`).
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example

data/lib/atlas_rb/collection.rb

@@ -24,7 +24,7 @@ module AtlasRb
     #   omitted.
     # @return [Hash, nil] the `"collection"` object, already unwrapped from the
     #   JSON response, or `nil` when the Collection does not exist (`404`).
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example

data/lib/atlas_rb/community.rb

@@ -25,7 +25,7 @@ module AtlasRb
     #   omitted.
     # @return [Hash, nil] the `"community"` object from the JSON response,
     #   already unwrapped, or `nil` when the Community does not exist (`404`).
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example

data/lib/atlas_rb/delegate.rb

@@ -33,7 +33,7 @@ module AtlasRb
     #   includes `id`, `valkyrie_id`, `use`, `uri`, `mime_type`,
     #   `original_filename`, `label`, and tombstone fields — or `nil` when the
     #   Delegate does not exist (`404`).
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example

data/lib/atlas_rb/errors.rb

@@ -169,6 +169,38 @@ module AtlasRb
     end
   end
 
+  # Raised when Atlas rejects a per-tier derivative-visibility policy
+  # (`PATCH /works/:id/derivative_permissions`) with a `422` carrying a
+  # machine-readable `error` discriminator — `tier_exceeds_resource` (a tier
+  # more visible than its Work), `tier_ordering_violation` (visibility not
+  # narrowing as resolution grows), or `unknown_tier`.
+  #
+  # The derivative-permissions sibling of {ReparentError} / {LinkedMemberError};
+  # same shape, same rationale (the binding's `["work"]` unwrap would otherwise
+  # discard the envelope on the 422). Atlas rejects before persisting.
+  #
+  #   rescue AtlasRb::DerivativePermissionsError => e
+  #     flash.now[:alert] = t("derivative_permissions.errors.#{e.code}", default: e.message)
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403).
+  class DerivativePermissionsError < Error
+    # @return [String, nil] the machine-readable error code from the envelope,
+    #   suitable for keying an i18n map.
+    attr_reader :code
+
+    # @return [String, nil] the rejected Work's ID, from the envelope.
+    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 Work'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
@@ -203,7 +235,7 @@ module AtlasRb
   # Raised by the typed single-resource readers ({Resource.find} and the
   # `Work` / `Collection` / `Community` / `FileSet` / `Person` / `Compilation`
   # / `Blob` / `Delegate` overrides) when Atlas answers the `GET` with a
-  # non-2xx that is **not** a `404` — i.e. an error envelope
+  # non-2xx that is **not** a `404` or a `410` — i.e. an error envelope
   # (`{ "error" => ... }`, status 400/401/403/422) on what the caller treated
   # as a plain read.
   #
@@ -217,7 +249,10 @@ module AtlasRb
   # attributable everywhere `find` is used.
   #
   # A genuine `404` is **not** this — it stays a clean `nil` return, since
-  # "not found" is a normal `find` outcome callers already nil-check.
+  # "not found" is a normal `find` outcome callers already nil-check. A `410`
+  # is also **not** this — a tombstoned resource comes back as `410 Gone` with
+  # its full body, which `find` returns (the caller nil-checks / reads
+  # `tombstoned`), rather than an error to raise.
   #
   # @note Authorization failures on the narrow re-parent / linked-member /
   #   Compilation write paths surface as {ForbiddenError} via

data/lib/atlas_rb/file_set.rb

@@ -25,7 +25,7 @@ module AtlasRb
     #   omitted.
     # @return [Hash, nil] the `"file_set"` object, already unwrapped, or `nil`
     #   when the FileSet does not exist (`404`).
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -16,8 +16,9 @@ module AtlasRb
     #
     # It is intentionally narrow — it only fires on the re-parent
     # (`.../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
+    # the Compilation surface (`/compilations...`), the derivative-permissions
+    # write (`.../derivative_permissions`), 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.
@@ -27,10 +28,11 @@ module AtlasRb
     # translates only the wire signals callers genuinely need to discriminate.
     #
     # Mapping:
-    # - `403` on a re-parent/linked/Compilation path → {AtlasRb::ForbiddenError}
+    # - `403` on a re-parent/linked/Compilation/derivative-permissions path → {AtlasRb::ForbiddenError}
     # - `422` on `.../parent` → {AtlasRb::ReparentError} (`error`/`resource_id`)
     # - `422` on `.../linked_members...` → {AtlasRb::LinkedMemberError}
     # - `422` on `/compilations...` → {AtlasRb::CompilationError}
+    # - `422` on `.../derivative_permissions` → {AtlasRb::DerivativePermissionsError}
     # - `422` + a fixity discriminator on `/files...` / `/file_sets...` →
     #   {AtlasRb::FixityMismatchError}
     class RaiseOnResourceError < Faraday::Middleware
@@ -43,6 +45,7 @@ module AtlasRb
       # @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::DerivativePermissionsError] on a 422 to a derivative-permissions path.
       # @raise [AtlasRb::FixityMismatchError] on a 422 + fixity discriminator to an upload path.
       # @return [void]
       def on_complete(env)
@@ -52,15 +55,16 @@ module AtlasRb
         reparent    = path.end_with?("/parent")
         linked      = path.include?("/linked_members")
         compilation = path.start_with?("/compilations")
+        deriv_perms = path.end_with?("/derivative_permissions")
         upload      = path.start_with?("/files") || path.start_with?("/file_sets")
-        return unless reparent || linked || compilation || upload
+        return unless reparent || linked || compilation || deriv_perms || 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
+          return unless reparent || linked || compilation || deriv_perms
 
           raise AtlasRb::ForbiddenError.new(
             body["message"] || "Atlas refused the request",
@@ -86,6 +90,12 @@ module AtlasRb
             code: body["error"],
             resource_id: body["resource_id"]
           )
+        elsif deriv_perms
+          raise AtlasRb::DerivativePermissionsError.new(
+            body["message"] || "Atlas rejected the derivative-permissions policy",
+            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)",

data/lib/atlas_rb/person.rb

@@ -37,7 +37,7 @@ module AtlasRb
     #   server-side `nuid` for callers that need it, e.g. depositor gating, and
     #   `personal_root_id` for the publish-conduit parent), or `nil` when the
     #   Person does not exist (`404`).
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     def self.find(id, nuid: nil, on_behalf_of: nil)
       body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)

data/lib/atlas_rb/resource.rb

@@ -36,7 +36,7 @@ module AtlasRb
     #   when the id resolves to nothing (`404`):
     #   - `"klass"` — the resource type, capitalized (e.g. `"Work"`).
     #   - `"resource"` — the resource payload as a Hash.
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example Polymorphic lookup
@@ -260,6 +260,10 @@ module AtlasRb
     # - `404`             → `nil` (clean "not found"; also avoids the
     #   `JSON::ParserError` the old code raised on the empty `head :not_found`
     #   body).
+    # - `410`             → the parsed JSON Hash. A tombstoned resource is
+    #   returned as `410 Gone` WITH its full body (carrying tombstoned /
+    #   tombstoned_at / tombstoned_by), so it is a returnable tombstone, not an
+    #   error envelope — `find` yields the tombstone rather than raising.
     # - any other non-2xx → {AtlasRb::ResourceError} carrying Atlas's status +
     #   body, so the failure is attributable at the boundary.
     # - `2xx`             → the parsed JSON Hash, for the caller to unwrap.
@@ -267,13 +271,19 @@ module AtlasRb
     # @param path [String] the resource path to GET (e.g. `"/works/abc123"`).
     # @param nuid [String, nil] optional acting user's NUID (see {find}).
     # @param on_behalf_of [String, nil] optional `On-Behalf-Of` NUID (see {find}).
-    # @return [Hash, nil] the parsed JSON envelope, or `nil` on `404`.
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404`.
+    # @return [Hash, nil] the parsed JSON envelope (incl. a `410` tombstone), or
+    #   `nil` on `404`.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`.
     # @api private
     def self.fetch_resource(path, nuid: nil, on_behalf_of: nil)
       resp = connection({}, nuid, on_behalf_of: on_behalf_of).get(path)
       return nil if resp.status == 404
-      unless resp.success?
+
+      # A tombstoned resource comes back as 410 Gone WITH its full body — a
+      # "gone, but here it is" tombstone, not an error envelope — so parse it
+      # like a 2xx and let callers read the tombstone. Only genuine error
+      # statuses raise.
+      unless resp.success? || resp.status == 410
         raise AtlasRb::ResourceError.new("GET #{path} → #{resp.status}: #{resp.body}", response: resp)
       end
 

data/lib/atlas_rb/work.rb

@@ -24,7 +24,7 @@ module AtlasRb
     #   {AtlasRb.config}.default_on_behalf_of when omitted.
     # @return [Hash, nil] the `"work"` object, already unwrapped from the JSON
     #   response, or `nil` when the Work does not exist (`404`).
-    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` (e.g. an
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
@@ -345,6 +345,53 @@ module AtlasRb
       ))
     end
 
+    # Replace a Work's per-tier derivative-visibility policy.
+    #
+    # Sets which read groups may fetch the Work's sized image derivatives —
+    # the `small` / `medium` / `large` / `service` (deep-zoom) tiers — reusing
+    # the resource read-group vocabulary (`"public"`, Grouper group names,
+    # `[]` = private). Unlike {.set_image_derivatives} (which upserts URIs) this
+    # is a whole-object REPLACE: the map you pass is the complete policy;
+    # omitted tiers inherit by cascade (an absent tier inherits the next
+    # lower-resolution tier; `small` inherits the Work's own visibility). Pass a
+    # tier as `[]` to make it private.
+    #
+    # Atlas enforces two invariants: a tier may not be more visible than the
+    # Work, and visibility must narrow as resolution grows
+    # (`service` ⊆ `large` ⊆ `medium` ⊆ `small`). The gate is advisory — it
+    # surfaces per Delegate on {.assets} as `gated` / `permission` for the
+    # display layer (Cerberus / the IIIF auth service) to enforce.
+    #
+    # @param id [String] the Work ID.
+    # @param policy [Hash] tier => Array(read groups), e.g.
+    #   `{ large: ["northeastern:drs:repository:archives"], service: [...] }`.
+    #   Keys may be strings or symbols; only `small` / `medium` / `large` /
+    #   `service` are recognized.
+    # @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 On-Behalf-Of NUID.
+    # @return [AtlasRb::Mash] the updated Work; the stored map echoes back under
+    #   `derivative_permissions`.
+    # @raise [AtlasRb::DerivativePermissionsError] if Atlas rejects the policy
+    #   (422) — `tier_exceeds_resource` / `tier_ordering_violation` /
+    #   `unknown_tier` (see {#code}).
+    # @raise [AtlasRb::StaleResourceError] on an optimistic-lock conflict (409).
+    #
+    # @example
+    #   AtlasRb::Work.set_derivative_permissions(
+    #     "w-789",
+    #     policy: { small:   ["public"],
+    #               large:   ["northeastern:drs:repository:archives"],
+    #               service: ["northeastern:drs:repository:archives"] }
+    #   )
+    def self.set_derivative_permissions(id, policy:, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id + '/derivative_permissions', JSON.dump(policy))&.body
+      ))
+    end
+
     # Store a Work's derived full-document text for search indexing.
     #
     # Purpose-specific PATCH in the same "machine-set derived metadata" family

metadata

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