atlas_rb 1.15.0 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a32e3df39d1a5f9648e47a42b88be5deff1b28dc696f9575a073baac4b9fa58
-  data.tar.gz: cb224b216444752165a39f242120e478cbe03c4a2613e36b19665d1897ec59b8
+  metadata.gz: ed32d60a2b3c2a562ee64d095a266c6b45848122ce4d75a0201c6736aeb52c2f
+  data.tar.gz: 229e5722c7b2036e490df5c06a5ad7afe496164fe7105a2ee232b7cb64f5d970
 SHA512:
-  metadata.gz: 43cf01a77168ae4ae78de02bf26403e9c116b63f18d685adc7bf82275124aaa498129ea1a8dad9c4867330b455c236f68f20b05763743be8b4db97ceef0b8324
-  data.tar.gz: 6fb09278babb33a465f090e32b0616649bddd4fb043337cbeace8c6c0b7f83ff0cde6710f01eecec69e91d8c65db2d58c67683a7c55496078f090312d7f77317
+  metadata.gz: e63d081a6b2f67297e95e2feb361ed232e585b3c22a84b68c0d35dd0a816aae1cfca0106613ddc9f097644bd8b02a098285ce48f7ee930126102037c2dff808c
+  data.tar.gz: 70931eed6c2ceaf7fd901a07005df4dec7570a5f90649b0bfb277826f927922bfb3ad30f73a226254d8059fb1c82f4e114e11a4a7977ddd1ff7d7e291e846d8f

data/.version

@@ -1 +1 @@
-1.15.0
+1.16.0

data/CHANGELOG.md

@@ -1,5 +1,183 @@
 # Changelog
 
+## 1.16.0
+
+### Fixed — every read binding consults the HTTP status before it reads the body
+
+Twenty-nine read bindings parsed or returned a response body without checking
+the status. `Resource.fetch_resource` had enforced that contract for the typed
+single-resource `find`s since 1.8.3, but a binding had to opt in by routing
+through it, and the rest of the read surface never did. Four failure shapes
+came of it:
+
+| Binding shape | What the caller got on an error response |
+|---|---|
+| `JSON.parse(body).map { Mash.new(...) }` | `NoMethodError: undefined method 'each_pair' for [...]:Array` — the error envelope iterated as pairs |
+| `JSON.parse(body)["key"].map` | `NoMethodError ... for nil:NilClass`, raised far from the cause |
+| `Mash.new(JSON.parse(body))` | **no error at all** — the envelope came back as if it were data |
+| raw `resp.body` (the `mods` bindings) | **no error at all** — the error text came back as a `String`, ready to be rendered |
+| any of the above, non-JSON body | `JSON::ParserError`, naming neither the status nor the endpoint |
+
+Three of those were worse than a wrong error class:
+
+- **`Work.mods`** (and `Collection.mods`, `Community.mods`, `Resource.mods`,
+  `Resource.mods_version`) returned Atlas's error body as a `String`. Atlas
+  renders MODS to HTML server-side, so a consumer marks that body HTML-safe
+  and writes it into its own page. Pointing `ATLAS_URL` at another service in
+  the stack produced that service's stack trace by this route.
+- **`Maintenance.read`** failed open. A `401` parsed into a `Mash` with no
+  `read_only` key, so a host read "no maintenance window" precisely when it
+  could not read the flag — the opposite of the endpoint's contract, which is
+  that a client unable to read the window cannot honour it.
+- **`Blob.version_content`** discarded the status entirely, so an error body
+  became the bytes of the file an admin had just downloaded.
+
+The fix is one Faraday middleware plus one shared binding-level guard, rather
+than twenty-nine near-identical call-site edits:
+
+- **`Middleware::RaiseOnReadError`** raises `AtlasRb::ResourceError` on a
+  non-2xx read, at the transport, where a binding cannot forget it. Registered
+  on the `:json` and `:system` connections, ahead of the typed translators so
+  their `on_complete` still runs first — a maintenance `503` stays a
+  `ReadOnlyModeError`, a refused re-parent stays a `ForbiddenError`.
+- **`FaradayHelper#read_body` / `#read_raw`** apply the same mapping where a
+  binding can see it, which keeps the guarantee true for a caller who has
+  stubbed the transport. Every read binding now funnels through one of them,
+  and `Resource.fetch_resource` delegates to `read_body`.
+
+The mapping, uniform across the read surface:
+
+| Atlas answers | Read binding |
+|---|---|
+| `2xx` | the parsed body (or the raw body, for `mods`) |
+| `404` | `nil` |
+| `410` | the tombstone body |
+| anything else | raises `AtlasRb::ResourceError`, carrying the status, verb, path and body |
+
+**Two behaviour changes to note when upgrading.**
+
+`404` now returns `nil` where a binding used to raise `JSON::ParserError` on
+the empty body, and list reads return `nil` rather than `[]` — so a caller can
+tell "no such container" from "an empty container", which mean different
+things to a UI. Callers that iterate a list read need `&.each` or a nil check.
+
+`Blob.version_content` now returns `{ status:, headers: }`, matching
+`Blob.content`. Its status cannot be raised on: chunks reach the caller as
+they arrive, so by the time the status is known an error body would already
+have been streamed. A caller passing those chunks to an HTTP response must
+consult the status, or an Atlas error page becomes the downloaded file.
+
+`Reset.clean` raises where the env gate that guards `GET /reset` is closed,
+instead of returning the refusal body. A test suite that opens with a reset and
+then carries on against un-wiped state fails somewhere else entirely, so this
+one has to be loud.
+
+`Authentication.login` and `.groups` no longer document
+`@raise [JSON::ParserError]`. An auth failure is a `401` and now raises
+`ResourceError`; a host rescuing `JSON::ParserError` as a stand-in for "the
+read failed" can drop it.
+
+The streaming reads (`Blob.content`, `Blob.version_content`) are exempt from
+the middleware, which is keyed off `on_data` — see the middleware's note on
+why raising after the chunks have gone out is too late to help.
+
+### Added — a request deadline and a bounded retry on every connection
+
+`lib/` set no timeout anywhere, so `Net::HTTP`'s defaults applied: 60s open,
+60s read. Worse, the pooled adapter's `max_retries = 1` made `Net::HTTP`
+replay an idempotent GET after a read timeout, so a hung Atlas held a single
+`GET` for **120 seconds**. A consumer that fans out four reads per request
+thread parks that thread — and four sockets from a sixteen-socket pool — for
+that whole time, which turns one degraded backend into a front-end outage. No
+host can fix this from outside: it can rescue what the gem raises, but it
+cannot impose a deadline on a socket the gem owns.
+
+Four new configuration slots, following the `connection_pool_size` pattern
+(optional, read at connection-build time):
+
+| Slot | Default | Applies to |
+|---|---|---|
+| `open_timeout` | `2` seconds | all three connection shapes |
+| `read_timeout` | `10` seconds | `:json`, `:system` |
+| `upload_read_timeout` | `nil` (uncapped) | `:multipart` |
+| `read_retries` | `2` (three attempts) | `:json`, `:system` |
+
+`read_timeout` is sized off the measured read path — the slowest single call
+on a consumer's Work page was ~200ms and the whole eight-call page ~450ms — so
+ten seconds is roughly fifty times the observed per-call cost. It is
+`Net::HTTP`'s per-read deadline rather than a whole-response budget, so a
+streaming download is unaffected as long as bytes keep arriving. Set a slot to
+`false` to remove a deadline, or override one call:
+
+```ruby
+connection({}, nuid).get(path) { |req| req.options.timeout = 120 }
+```
+
+The multipart shape takes no read deadline and no retry: a multi-gigabyte
+upload legitimately outlives any page-sized budget, and a partially-streamed
+`POST` must not be replayed blindly — even under an `Idempotency-Key`, which
+the transport cannot see.
+
+**Retries now live in exactly one layer.** `faraday-retry ~> 2.4` is a new
+runtime dependency, registered as the outermost handler on the `:json` and
+`:system` connections, and `Net::HTTP`'s own `max_retries` drops from `1` to
+`0`. The 1.15.0 reasoning for that `1` was sound — a server that closed an
+idle pooled socket errors on the next write, and a replay is what turns that
+into a reconnect — and the middleware covers the same case better:
+`EOFError`, `Errno::ECONNRESET` and `Faraday::ConnectionFailed` are all in its
+exception list, now with jittered backoff, a bounded attempt count, and a
+`request.atlas_rb` notification per attempt instead of a silent replay.
+Stacking both layers would have given six timeout waits per call.
+
+The policy is deliberately narrow:
+
+- **Exceptions only** (`retry_statuses: []`). A response Atlas actually sent
+  is never retried. The maintenance `503` is why: its `Retry-After` is
+  measured in minutes, so an in-band retry would ignore it and hammer the
+  window, and `ReadOnlyModeError` must reach the caller on the first response.
+- **`GET` / `HEAD` / `OPTIONS` only**, narrower than HTTP idempotency. `PUT`
+  and `DELETE` are idempotent in the spec, but Atlas's `DELETE` purges an OCFL
+  object and its `PATCH`/`PUT` writes carry optimistic-lock semantics. A
+  replay there should be a call site's decision.
+- **`Faraday::ConnectionFailed` added explicitly.** It is not in the
+  middleware's own default list, and it is the failure that matters most here:
+  an Atlas restart mid-page-load is a refused connect, which one retry hides
+  completely.
+
+Worst case per `GET` is now three attempts of ten seconds plus backoff, about
+**30 seconds**, down from 120.
+
+## 1.15.1
+
+### Fixed — `Resource.permissions` no longer coerces a refused read to `nil`
+
+Atlas gates `GET /resources/:id/permissions` on the caller's read right over
+the resource itself, because the envelope names the Grouper groups and the
+depositor's NUID. A caller who may not read the resource gets a real `403`
+carrying `{ "error", "action", "subject" }`.
+
+The binding parsed that body without consulting the status. The error envelope
+has no `"resource"` key, so `JSON.parse(body)["resource"]` returned the same
+`nil` an unknown id returns — the status, the message and the distinction were
+all gone before the caller saw anything. A host reading this to drive its own
+gate rendered "not found" for a resource the reader was merely not allowed to
+see.
+
+`permissions` now routes through `fetch_resource`, the guarded read path every
+typed `find` already uses:
+
+| Atlas answers | `permissions` |
+|---|---|
+| `200` | the ACL `Mash` |
+| `404` | `nil` — unchanged |
+| `403` | raises `AtlasRb::ResourceError`, `status == 403` |
+
+A host that wants the old "nil for anything unreadable" behaviour rescues
+`AtlasRb::ResourceError` and returns `nil` itself.
+
+The YARD example was also wrong: the envelope carries `type`, `depositor`,
+`proxy_uploader`, `edit_users`, `read`, `edit` and `embargo`, never `id`.
+
 ## 1.15.0
 
 ### Changed — the transport reuses connections instead of opening one per request

data/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.15.0)
+    atlas_rb (1.16.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
       faraday-net_http_persistent (~> 2.3)
+      faraday-retry (~> 2.4)
       hashie (~> 5.0)
       jwt (~> 2.7)
 
@@ -28,9 +29,11 @@ GEM
     faraday-net_http_persistent (2.3.1)
       faraday (~> 2.5)
       net-http-persistent (>= 4.0.4, < 5)
+    faraday-retry (2.4.0)
+      faraday (~> 2.0)
     hashie (5.1.0)
       logger
-    json (2.21.2)
+    json (3.0.2)
     jwt (2.10.3)
       base64
     logger (1.7.0)

data/README.md

@@ -192,6 +192,62 @@ pool between examples, or a socket from one example stays open into the next:
 config.after(:each, :atlas_rb_server) { AtlasRb::Transport.reset_connections! }
 ```
 
+### Deadlines and retries
+
+Every connection the gem builds carries a deadline, because a host cannot
+retrofit one: it can rescue what the gem raises, but it cannot impose a
+timeout on a socket the gem owns. Left to `Net::HTTP`'s defaults a hung Atlas
+held a single `GET` for two minutes, which parks a request thread and its
+share of the socket pool for that whole time.
+
+Four knobs, all optional:
+
+```ruby
+AtlasRb.configure do |config|
+  # Seconds to wait for a socket to open. Defaults to 2 — Atlas is on the same
+  # host or the same overlay network, so a healthy connect is sub-millisecond.
+  config.open_timeout = 2
+
+  # Seconds to wait for a response on the JSON and system connections.
+  # Defaults to 10. This is a per-socket-read deadline, not a whole-response
+  # budget, so a streaming download is fine as long as bytes keep arriving.
+  config.read_timeout = 10
+
+  # The same, for binary uploads. Defaults to nil — uncapped, because a
+  # multi-gigabyte upload has no defensible cap and those calls run in jobs.
+  config.upload_read_timeout = nil
+
+  # Extra attempts an idempotent read gets after a transport failure, so 2
+  # means three attempts in all. Defaults to 2; set 0 to disable.
+  config.read_retries = 2
+end
+```
+
+Set a timeout slot to `false` to remove the deadline rather than change it.
+All four are read when a connection is first built, so set them before the
+first Atlas call.
+
+A single call that legitimately outlives the budget overrides it on the
+request — the block the transport forwards runs last, so it wins:
+
+```ruby
+# A bulk export paging a large Collection, or a metadata dump:
+AtlasRb::Work.connection({}, nuid).get("/resources/#{id}/descendant_works") do |req|
+  req.options.timeout = 120
+end
+```
+
+Only reads are retried, and only when the request failed in transport — a
+refused or reset connection, or a timeout. A response Atlas actually sent is
+never retried, which is what keeps the maintenance `503` honest: its
+`Retry-After` is measured in minutes, so `ReadOnlyModeError` reaches you on
+the first response instead of the gem waiting in band. Writes are never
+retried; a `POST` that may have landed is the call site's decision, not the
+transport's.
+
+Each attempt emits its own `request.atlas_rb` notification, so a host counting
+round-trips sees a retry as the second round-trip it really is.
+
 ## Resource hierarchy
 
 ```
@@ -507,6 +563,38 @@ question, and callers already nil-check a `find`:
 AtlasRb::Work.find("doesnotexist")   # => nil
 ```
 
+That holds across the whole read surface, not just `find`. A **list** read
+returns `nil` too, rather than an empty array, so you can tell "no such
+container" from "an empty container" — two answers that mean different things
+to a UI:
+
+```ruby
+AtlasRb::Work.assets("doesnotexist")   # => nil
+AtlasRb::Work.assets(real_work_noid)   # => [] for a Work with no assets
+```
+
+Anything else a read gets back raises `AtlasRb::ResourceError`, which carries
+the status, the endpoint and Atlas's body. That is the point: the failure is
+attributable where it happened, instead of surfacing as a `NoMethodError` on
+`nil` several frames later, or — for the `mods` bindings, which pass Atlas's
+rendered body through by design — as an error page returned to you as a
+`String` and rendered:
+
+```ruby
+begin
+  AtlasRb::Work.mods(noid, "html")
+rescue AtlasRb::ResourceError => e
+  e.status    # => 403
+  e.message   # => "GET /works/9zw3s1h/mods.html → 403: {\"error\":\"forbidden\",…}"
+end
+```
+
+A `410 Gone` is returned rather than raised, the same way `find` returns a
+tombstone. And the two streaming reads (`Blob.content`,
+`Blob.version_content`) hand you `{ status:, headers: }` instead of raising,
+because their chunks reach you as they arrive — check the status before you
+treat those bytes as a file.
+
 A **write** raises `AtlasRb::NotFoundError`. The caller asked for a change and
 did not get one, so `nil` would invite the silent failure the read guard was
 written to prevent:

data/lib/atlas_rb/authentication.rb

@@ -25,16 +25,19 @@ module AtlasRb
     # @param nuid [String] the user's Northeastern University ID.
     # @param email [String, nil] optional account email to act as (the `acct`
     #   selector); nil resolves the preferred account.
-    # @return [Hash] the user record returned by `GET /user`, including at
-    #   minimum `"id"`, `"name"`, and `"groups"`.
-    # @raise [JSON::ParserError] if the response body is not valid JSON
-    #   (typically caused by an auth failure returning HTML).
+    # @return [AtlasRb::Mash, nil] the user record returned by `GET /user`,
+    #   including at minimum `"id"`, `"name"`, and `"groups"`.
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     #
     # @example
     #   AtlasRb::Authentication.login("001234567")
     #   # => { "id" => 42, "name" => "Jane Doe", "groups" => [...] }
     def self.login(nuid, email: nil)
-      AtlasRb::Mash.new(JSON.parse(connection({}, nuid, account: email).get('/user')&.body))
+      read_body(connection({}, nuid, account: email).get('/user')) { |body| AtlasRb::Mash.new(body) }
     end
 
     # Fetch only the group memberships for an NUID.
@@ -43,8 +46,12 @@ module AtlasRb
     # when authorization checks only need group names.
     #
     # @param nuid [String] the user's Northeastern University ID.
-    # @return [Array<Hash>] the `"groups"` array from the user record.
-    # @raise [JSON::ParserError] if the response body is not valid JSON.
+    # @return [Array<Hash>, nil] the `"groups"` array from the user record.
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     #
     # @example
     #   AtlasRb::Authentication.groups("001234567")
@@ -54,7 +61,7 @@ module AtlasRb
       # token = user_details[:token] ...
       # TODO - need to update atlas login to give back name, id, and token upon logging in
       # result = JSON.parse(connection({ token: token }).post('/users/2/groups')&.body)["user"]["groups"]
-      AtlasRb::Mash.new(JSON.parse(connection({}, nuid).get('/user')&.body))["groups"]
+      read_body(connection({}, nuid).get('/user')) { |body| AtlasRb::Mash.new(body)["groups"] }
     end
   end
 end

data/lib/atlas_rb/blob.rb

@@ -57,16 +57,21 @@ 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] `{ "file_set" => "<noid>", "work" => "<noid>" }`
+    # @return [AtlasRb::Mash, nil] `{ "file_set" => "<noid>", "work" => "<noid>" }`
     #   (either value `nil` when unresolvable).
     #
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @example
     #   AtlasRb::Blob.ancestry("b-321")
     #   # => { "file_set" => "fs-654", "work" => "w-789" }
     def self.ancestry(id, nuid: nil, on_behalf_of: nil)
-      AtlasRb::Mash.new(JSON.parse(
-        connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/ancestry")&.body
-      ))
+      read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/ancestry")) do |body|
+        AtlasRb::Mash.new(body)
+      end
     end
 
     # Convenience over {.ancestry}: the containing Work's noid for a content
@@ -277,17 +282,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 [AtlasRb::Mash] the parsed envelope, with `"blob_id"` and a
+    # @return [AtlasRb::Mash, nil] the parsed envelope, with `"blob_id"` and a
     #   `"versions"` array (reverse chronological).
     #
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @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
-      ))
+      read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/versions")) do |body|
+        AtlasRb::Mash.new(body)
+      end
     end
 
     # Read binary version history for many Blobs in one round-trip.
@@ -316,20 +326,25 @@ 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 [Array<AtlasRb::Mash>] one {.versions}-shaped envelope per resolved
+    # @return [Array<AtlasRb::Mash>, nil] one {.versions}-shaped envelope per resolved
     #   Blob (`"blob_id"` plus a reverse-chronological `"versions"` array); empty
     #   when none resolved.
     #
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @example Render a Work's files with their histories in two calls
     #   assets  = AtlasRb::Work.assets(work_noid).reject { |a| a[:uri].present? }
     #   history = AtlasRb::Blob.find_many_versions(assets.map(&:noid))
     #                          .index_by { |h| h["blob_id"] }
     #   history[assets.first.noid]["versions"].first["revision"] # => 3
     def self.find_many_versions(ids, nuid: nil, on_behalf_of: nil)
-      JSON.parse(
+      read_body(
         connection({}, nuid, on_behalf_of: on_behalf_of)
-          .post("#{ROUTE}find_many_versions", JSON.dump(ids: Array(ids)))&.body
-      ).map { |envelope| AtlasRb::Mash.new(envelope) }
+          .post("#{ROUTE}find_many_versions", JSON.dump(ids: Array(ids)))
+      ) { |body| body.map { |envelope| AtlasRb::Mash.new(envelope) } }
     end
 
     # Stream the bytes of a *prior* version of a Blob through a block.
@@ -353,7 +368,13 @@ module AtlasRb
     #   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.
+    # @return [Hash] `{ status:, headers: }` — the HTTP status and response
+    #   headers. The status is handed back rather than raised on, because
+    #   chunks reach the caller as they arrive: by the time the status could
+    #   be checked, an error body would already have been streamed. A caller
+    #   writing the chunks to an HTTP response (or a file) must consult it, or
+    #   an Atlas error page becomes the bytes of the downloaded file. Matches
+    #   {.content}'s contract.
     #
     # @example Download a superseded version to disk
     #   File.open("/tmp/old.pdf", "wb") do |f|
@@ -361,13 +382,14 @@ module AtlasRb
     #   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|
+      response = 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
+      { status: response.status, headers: headers }
     end
 
     # Roll a Blob back to a prior version.

data/lib/atlas_rb/collection.rb

@@ -196,15 +196,18 @@ module AtlasRb
     # round-trip per child. For a whole subtree flattened to Works, use
     # {AtlasRb::Resource.descendant_works}.
     #
-    # @return [Array<String>] child noids from `GET /collections/<id>/children`.
+    # @return [Array<String>, nil] child noids from `GET /collections/<id>/children`.
     #
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @example
     #   AtlasRb::Collection.children("col-456")
     #   # => ["w-789", "w-790"]
     def self.children(id, nuid: nil, on_behalf_of: nil)
-      JSON.parse(
-        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/children')&.body
-      )
+      read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/children'))
     end
 
     # Replace a Collection's metadata by uploading a MODS XML document.
@@ -312,15 +315,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 [String] the raw response body in the requested format.
+    # @return [String, nil] the raw response body in the requested format.
     #
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @example
     #   AtlasRb::Collection.mods("col-456", "xml")
     def self.mods(id, kind = nil, nuid: nil, on_behalf_of: nil)
       # json default, html, xml
-      connection({}, nuid, on_behalf_of: on_behalf_of).get(
-        ROUTE + id + '/mods' + (kind.to_s.empty? ? '' : ".#{kind}")
-        )&.body
+      read_raw(connection({}, nuid, on_behalf_of: on_behalf_of).get(
+                 ROUTE + id + '/mods' + (kind.to_s.empty? ? '' : ".#{kind}")
+               ))
     end
   end
 end

data/lib/atlas_rb/community.rb

@@ -175,15 +175,18 @@ module AtlasRb
     # round-trip per child. For a whole subtree flattened to Works, use
     # {AtlasRb::Resource.descendant_works}.
     #
-    # @return [Array<String>] child noids from `GET /communities/<id>/children`.
+    # @return [Array<String>, nil] child noids from `GET /communities/<id>/children`.
     #
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @example
     #   AtlasRb::Community.children("c-123")
     #   # => ["fn106x926", "kw52j804p"]
     def self.children(id, nuid: nil, on_behalf_of: nil)
-      JSON.parse(
-        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/children')&.body
-      )
+      read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/children'))
     end
 
     # Replace a Community's metadata by uploading a MODS XML document.
@@ -293,16 +296,21 @@ 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 [String] the raw response body (JSON, HTML, or XML serialized
+    # @return [String, nil] the raw response body (JSON, HTML, or XML serialized
     #   as a string).
     #
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @example HTML rendering for display
     #   AtlasRb::Community.mods("c-123", "html")
     def self.mods(id, kind = nil, nuid: nil, on_behalf_of: nil)
       # json default, html, xml
-      connection({}, nuid, on_behalf_of: on_behalf_of).get(
-        ROUTE + id + '/mods' + (kind.to_s.empty? ? '' : ".#{kind}")
-        )&.body
+      read_raw(connection({}, nuid, on_behalf_of: on_behalf_of).get(
+                 ROUTE + id + '/mods' + (kind.to_s.empty? ? '' : ".#{kind}")
+               ))
     end
   end
 end

data/lib/atlas_rb/compilation.rb

@@ -88,9 +88,14 @@ 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] `{ "compilations" => [...], "pagination" => {...} }`.
+    # @return [AtlasRb::Mash, nil] `{ "compilations" => [...], "pagination" => {...} }`.
     #   Each entry in `"compilations"` is a flat Compilation, carrying the
     #   same keys {.find} returns.
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @raise [AtlasRb::ForbiddenError] on a cross-owner listing without admin.
     #
     # @example My Sets
@@ -114,9 +119,9 @@ module AtlasRb
       params[:q]        = q        if q
       params[:page]     = page     if page
       params[:per_page] = per_page if per_page
-      AtlasRb::Mash.new(JSON.parse(
-        connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE)&.body
-      ))
+      read_body(connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE)) do |body|
+        AtlasRb::Mash.new(body)
+      end
     end
 
     # Create a Compilation owned by the acting user.
@@ -414,10 +419,15 @@ 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] `{ "contents" => [...], "pagination" =>
+    # @return [AtlasRb::Mash, nil] `{ "contents" => [...], "pagination" =>
     #   { "total", "page", "per_page", "pages" } }`. Each entry is a
     #   lightweight digest in the {Resource.find_many} vocabulary —
     #   `id` / `noid` / `klass` / `title` / `thumbnail`.
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
+    #   Atlas's status and body so the failure is attributable at the boundary.
     # @raise [AtlasRb::ForbiddenError] if the caller may not read this Set.
     #
     # @example
@@ -428,9 +438,9 @@ module AtlasRb
       params = {}
       params[:page]     = page     if page
       params[:per_page] = per_page if per_page
-      AtlasRb::Mash.new(JSON.parse(
-        connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/contents')&.body
-      ))
+      read_body(connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/contents')) do |body|
+        AtlasRb::Mash.new(body)
+      end
     end
   end
 end