atlas_rb 1.8.4 → 1.8.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a319cfd0891ed913d8c08f8138d7e11cc12a3f13d79d1b41d9eab95a45e67824
-  data.tar.gz: a840bfac145c02f79f59b53e226d293d90a89a18466511d4b9dbb9bd90460f59
+  metadata.gz: c3cb4c5a2d7eb16f4647817a9afc282ce6ebb34d9a8b46c7bfaefa304373317f
+  data.tar.gz: 2524726c4bcc1d24bc0a51f812dde391da066ec5b65540ec3c91d8f37d7d4724
 SHA512:
-  metadata.gz: ba9b973ba96cbf0f132617bafe8d0475c0bba7b3f76328fbd54adfa20175c96f97fab5e6c4a66a025ea92890d3d2d90f00616674d143a7442dc10da763052013
-  data.tar.gz: 0cc2ce817a804eb2925963f8aae21108bd4151e85cf437c0220574c067025a37544212dc298b2a97b197a063ac258ff8d759ee140f957e3e9ba10f7e3f6a15ce
+  metadata.gz: 77c312024d884794f49976c38d1cc53ea949db0e1e24f24f016f104158509d219ec0517deb29567176ce5e53a9e971d9ec11996cba4f77fc4fe2050be3965e9a
+  data.tar.gz: e8d194e9632802f871cbd89efb7625a6ca633643f119d4aefaab306aecde4719b098e2e78578f862b190c9d2172a0ada3208976ddb600d6c2a4c8de6bfb413d4

data/.version

@@ -1 +1 @@
-1.8.4
+1.8.6

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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`)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.8.4)
+    atlas_rb (1.8.6)
       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

@@ -235,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.
   #
@@ -249,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/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,28 +345,37 @@ module AtlasRb
       ))
     end
 
-    # Replace a Work's per-tier derivative-visibility policy.
+    # Replace a Work's per-asset 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.
+    # Sets which read groups may fetch each of the Work's downloadable
+    # renditions, reusing the resource read-group vocabulary (`"public"`,
+    # Grouper group names, `[]` = private). Two media families:
+    #
+    # * the image ladder `small` / `medium` / `large` / `service` (deep-zoom) /
+    #   `master` (the original image), and
+    # * independent media `audio` / `video` / `pdf`.
     #
-    # 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.
+    # Unlike {.set_image_derivatives} (which upserts URIs) this is a whole-object
+    # REPLACE: the map you pass is the complete policy. Within the image ladder
+    # omitted tiers inherit by cascade (an absent tier inherits the next
+    # lower-resolution tier; `small` inherits the Work's own visibility).
+    # Independent media do NOT cascade — an absent `audio`/`video`/`pdf` key
+    # rides the Work. Pass a tier as `[]` to make it private.
+    #
+    # Atlas enforces: a tier may not be more visible than the Work, and — within
+    # the image ladder — visibility must narrow as resolution grows
+    # (`master` ⊆ `service` ⊆ `large` ⊆ `medium` ⊆ `small`; independent media
+    # impose no ordering). The gate is advisory — it surfaces on {.assets} as
+    # `gated` / `permission` for BOTH Delegate (image tier) and Blob (master /
+    # pdf / audio / video, classified by media type) entries, for the display
+    # layer (Cerberus / the IIIF auth service; Cerberus's download :read check)
+    # 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.
+    #   `{ large: ["northeastern:drs:repository:archives"], master: [...] }`.
+    #   Keys may be strings or symbols; recognized keys are `small` / `medium` /
+    #   `large` / `service` / `master` / `audio` / `video` / `pdf`.
     # @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).
@@ -437,6 +446,11 @@ module AtlasRb
     # duck-type on the field they need rather than expecting a single
     # schema.
     #
+    # Every entry (Blob and Delegate) also carries the advisory read gate set
+    # via {.set_derivative_permissions}: `gated` (true if the asset must be
+    # authorized rather than fetched directly) and `permission` (the effective
+    # read-group set, or `nil` for guests, to whom group names are withheld).
+    #
     # @param id [String] the Work 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`)

metadata

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