atlas_rb 1.8.2 → 1.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a0fac04427bc3f23f92da8a5241a263111f45b28fa01cc8829da0de3b6b48f9
-  data.tar.gz: 8e95150d0f2ecd0a33c52179e384f8462546b422dcd6997c69886163215811c8
+  metadata.gz: d25a6bf4fdadf6bacf1de67390aeb15343547dba8384c511d8c34b62c1fb058e
+  data.tar.gz: f002dfcb1638bd8c5c5cb668121b9a8515f85765aaab4b229770d8d7b6b3587c
 SHA512:
-  metadata.gz: 4ced2b3f0f3fee473712f38ae3161ea8f678d9468abaf1250c9577e13261b5688be16ea687a69f6b28931a6e8920ad737d7a2057059c14751cceb683e463c2ef
-  data.tar.gz: 017e1004f59a5529184e3f07f93c815a463da07937863ff72b2063b3e1986f624e5e8ea83c0b5750b57885e7942ef981b32e66f7d3e5931ea6545108c643162d
+  metadata.gz: 9b7f605825d8d4ebb6c44c93c16bc8a7f16a6ee5cb3d7a83c2cba05c7de59e9c25fc92811f35a332ff326dc929b63c057c2743ed8d5fdeb807288f49f2cb2c79
+  data.tar.gz: 20066bd2c7f096a70d3ace6d3c36ed888d135f91e2e31dec7f7828f6eb1f0298e46e4fb0b06fe112be840846675240f6a026787f2479e8e7c73599414f3830d9

data/.version

@@ -1 +1 @@
-1.8.2
+1.8.3

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.8.3
+
+### Changed — `find` is status-aware (stops swallowing Atlas error envelopes)
+
+Every typed single-resource reader — `Resource.find` (the polymorphic resolver)
+and the `Work` / `Collection` / `Community` / `FileSet` / `Person` /
+`Compilation` / `Blob` / `Delegate` overrides — now routes through a shared
+status-aware read path instead of blindly `JSON.parse`-ing the body and
+unwrapping a fixed key.
+
+Previously, any non-2xx that wasn't a re-parent/linked-member/Compilation/upload
+signal (which `RaiseOnResourceError` already translates) passed straight through:
+Atlas renders its auth/validation failures as a JSON envelope (`{ "error" => …}`,
+status 400/401/403/422), so `JSON.parse(body)["work"]` found no `"work"` key and
+returned **`nil`**. Callers then dereferenced that `nil` far from the cause — the
+canonical symptom being `undefined method 'tombstoned' for nil`, a 500 surfaced
+nowhere near the request that actually failed.
+
+Now:
+
+- **`404` → `nil`** — a clean "not found" (and no more `JSON::ParserError` on the
+  empty `head :not_found` body, which is what a missing id used to raise).
+- **any other non-2xx → `AtlasRb::ResourceError`** — a new typed error carrying
+  Atlas's `status`, `body`, and `response`, raised **at the boundary** so the
+  real cause (e.g. `GET /works/abc → 401: {"error":"invalid bearer token"}`) is
+  attributable everywhere `find` is used.
+- **`2xx`** → unchanged (the unwrapped resource).
+
+Authorization failures on the narrow re-parent / linked-member / Compilation
+write paths still surface as `AtlasRb::ForbiddenError` via
+`RaiseOnResourceError`; `ResourceError` is the catch-all for the read path that
+middleware intentionally does not cover.
+
+**Behavior change to note:** `find` of a missing id now returns `nil` rather than
+raising `JSON::ParserError`. Callers that relied on the parse error (none known)
+should nil-check instead.
+
 ## 1.8.0
 
 ### Added — `Work.set_full_text` (full-text search seam)

data/Gemfile.lock

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

data/lib/atlas_rb/blob.rb

@@ -23,20 +23,22 @@ module AtlasRb
     # @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 `"blob"` object, already unwrapped — typically
+    # @return [Hash, nil] the `"blob"` object, already unwrapped — typically
     #   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.
+    #   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
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Blob.find("b-321")
     #   # => { "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
-      ))['blob']
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)['blob']
     end
 
     # Resolve a content Blob to its parent FileSet and containing Work noids.

data/lib/atlas_rb/collection.rb

@@ -22,16 +22,17 @@ module AtlasRb
     # @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 `"collection"` object, already unwrapped from the
-    #   JSON response.
+    # @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
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Collection.find("col-456")
     #   # => { "id" => "col-456", "title" => "Faculty Publications", ... }
     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
-      ))["collection"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["collection"]
     end
 
     # Create a new Collection under an existing Community.

data/lib/atlas_rb/community.rb

@@ -23,16 +23,17 @@ module AtlasRb
     # @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 `"community"` object from the JSON response,
-    #   already unwrapped.
+    # @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
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Community.find("c-123")
     #   # => { "id" => "c-123", "title" => "College of Engineering", ... }
     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
-      ))["community"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["community"]
     end
 
     # Create a new Community, optionally seeded with MODS metadata.

data/lib/atlas_rb/compilation.rb

@@ -38,19 +38,20 @@ module AtlasRb
     # @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 `"compilation"` object, already unwrapped — `id`,
+    # @return [Hash, nil] the `"compilation"` object, already unwrapped — `id`,
     #   `title`, `description`, `depositor`, the three recipe arrays
     #   (`included_collections`, `included_works`, `excluded_works`), the
-    #   ACL arrays, and timestamps.
+    #   ACL arrays, and timestamps — or `nil` when the Set does not exist (`404`).
     # @raise [AtlasRb::ForbiddenError] if the caller may not read this Set.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx (e.g. `401`),
+    #   carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Compilation.find("c-123", nuid: "000000002")
     #   # => { "id" => "c-123", "title" => "Course readings", ... }
     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
-      ))["compilation"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["compilation"]
     end
 
     # List Compilations, paginated (newest first), in one of three modes.

data/lib/atlas_rb/delegate.rb

@@ -29,16 +29,18 @@ module AtlasRb
     # @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 `"delegate"` object, already unwrapped —
+    # @return [AtlasRb::Mash, nil] the `"delegate"` object, already unwrapped —
     #   includes `id`, `valkyrie_id`, `use`, `uri`, `mime_type`,
-    #   `original_filename`, `label`, and tombstone fields.
+    #   `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
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Delegate.find("d-555")
     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
-      ))["delegate"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["delegate"]
     end
   end
 end

data/lib/atlas_rb/errors.rb

@@ -200,6 +200,50 @@ module AtlasRb
     end
   end
 
+  # 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
+  # (`{ "error" => ... }`, status 400/401/403/422) on what the caller treated
+  # as a plain read.
+  #
+  # Before this existed, `find` unwrapped the success body by a fixed key
+  # (`["work"]`, `["collection"]`, …); on an error envelope that key is
+  # absent, so `find` returned `nil` and silently discarded Atlas's status and
+  # message. The caller then dereferenced the `nil` far from the cause (the
+  # canonical symptom: `undefined method 'tombstoned' for nil`). This error
+  # keeps the failure **at the boundary**, carrying the status and body so the
+  # real cause (e.g. `… → 401: {"error":"invalid bearer token"}`) is
+  # 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.
+  #
+  # @note Authorization failures on the narrow re-parent / linked-member /
+  #   Compilation write paths surface as {ForbiddenError} via
+  #   {Middleware::RaiseOnResourceError}; this is the catch-all for the read
+  #   path, which that middleware intentionally does not cover.
+  class ResourceError < Error
+    # @return [Faraday::Response, nil] the originating response, when available.
+    attr_reader :response
+
+    # @return [Integer, nil] Atlas's HTTP status.
+    attr_reader :status
+
+    # @return [String, nil] Atlas's raw response body (the error envelope).
+    attr_reader :body
+
+    # @param message [String] human-readable failure description.
+    # @param response [Faraday::Response, nil] the originating response; its
+    #   status and body are captured for callers that rescue this.
+    def initialize(message, response: nil)
+      super(message)
+      @response = response
+      @status = response&.status
+      @body = response&.body
+    end
+  end
+
   # Raised when the transport has no way to authenticate a relay request:
   # neither `ATLAS_JWT` (BYO-JWT mode) nor a signing key
   # ({AtlasRb.config#assertion_signing_key}, relay-signing mode) is configured.

data/lib/atlas_rb/file_set.rb

@@ -23,14 +23,16 @@ module AtlasRb
     # @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 `"file_set"` object, already unwrapped.
+    # @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
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::FileSet.find("fs-001")
     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
-      ))["file_set"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["file_set"]
     end
 
     # Create a new FileSet under a Work.

data/lib/atlas_rb/person.rb

@@ -33,13 +33,15 @@ module AtlasRb
     # @param id [String] the person's NOID.
     # @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
+    # @return [AtlasRb::Mash, nil] the unwrapped `"person"` object (carries the
     #   server-side `nuid` for callers that need it, e.g. depositor gating, and
-    #   `personal_root_id` for the publish-conduit parent).
+    #   `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
+    #   auth/validation error envelope), carrying Atlas's status + body.
     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
-      ))["person"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["person"]
     end
 
     # List people — the NOID-keyed People-index source. Returns the page's

data/lib/atlas_rb/resource.rb

@@ -32,17 +32,20 @@ module AtlasRb
     # @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{String => String, Hash}] hash with two keys:
+    # @return [Hash{String => String, Hash}, nil] hash with two keys, or `nil`
+    #   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
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example Polymorphic lookup
     #   AtlasRb::Resource.find("abc123")
     #   # => { "klass" => "Work", "resource" => { "id" => "abc123", "title" => "..." } }
     def self.find(id, nuid: nil, on_behalf_of: nil)
-      result = JSON.parse(
-        connection({}, nuid, on_behalf_of: on_behalf_of).get('/resources/' + id)&.body
-      )
+      result = fetch_resource('/resources/' + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      return nil if result.nil?
+
       AtlasRb::Mash.new("klass" => result.first[0].capitalize,
                         "resource" => result.first[1])
     end
@@ -242,5 +245,40 @@ module AtlasRb
           (kind.present? ? ".#{kind}" : '')
       )&.body
     end
+
+    # Shared read path behind every typed `find`: perform a single-resource
+    # `GET` and return the parsed JSON envelope, or `nil` when Atlas reports
+    # the resource is absent (`404`).
+    #
+    # Its job is to stop `find` from silently coercing an error *envelope*
+    # into `nil`. Atlas renders auth/validation failures as a JSON body
+    # (`{ "error" => ... }`, status 400/401/403/422); a naive
+    # `JSON.parse(body)["work"]` returns `nil` for the missing `"work"` key —
+    # losing the status and message, and surfacing as a baffling
+    # `NoMethodError` far from the cause. Mapping:
+    #
+    # - `404`             → `nil` (clean "not found"; also avoids the
+    #   `JSON::ParserError` the old code raised on the empty `head :not_found`
+    #   body).
+    # - 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.
+    #
+    # @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`.
+    # @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?
+        raise AtlasRb::ResourceError.new("GET #{path} → #{resp.status}: #{resp.body}", response: resp)
+      end
+
+      JSON.parse(resp.body)
+    end
+    private_class_method :fetch_resource
   end
 end

data/lib/atlas_rb/work.rb

@@ -22,16 +22,17 @@ module AtlasRb
     # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
     #   header (acting-as / view-as). Falls through to
     #   {AtlasRb.config}.default_on_behalf_of when omitted.
-    # @return [Hash] the `"work"` object, already unwrapped from the JSON
-    #   response.
+    # @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
+    #   auth/validation error envelope), carrying Atlas's status + body.
     #
     # @example
     #   AtlasRb::Work.find("w-789")
     #   # => { "id" => "w-789", "title" => "An Article", ... }
     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
-      ))["work"]
+      body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
+      body && AtlasRb::Mash.new(body)["work"]
     end
 
     # List Works, paginated.

metadata

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