atlas_rb 1.27.0 → 1.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ea8cbef3fa493fefcf29c0dd15a4d7edf72efb58134f8d21050421517ef05f
-  data.tar.gz: 36a4eb18338f27da7ee744233e7b54fd6eb20faa76201e907f94703b8c6583e2
+  metadata.gz: 2c1b0723d54145c8be9868a1849502cf80adbc1a30b2f7b1ee39aadbfa1a2f3b
+  data.tar.gz: 7ab2bb5a662b02dd48275e645f9c6b3c1226d6bc995231766bd5a4252f17b25a
 SHA512:
-  metadata.gz: d33812411e71cfa8bf0031fae4f81b735d598b75cb31f099e0c67a31d8dc0e4cc9c193524443f8dce983f87f96add5c9cc82c6de8c3d1d4211e69611254d4cc6
-  data.tar.gz: f287d655a86594da49f54caa8cb505277577b3b81284e313cf956ee6424fd09f3bdf0085ae51fae14420468c386626eba3c300be3f41e5762d57c65de5938213
+  metadata.gz: 64f43d675ad66dac85657c0460702f53f95c99760e7a44ce6f0dec019e375f41b197c214ca3dc4d89a94a1e0b829fa9d377fd4dd9432fe68cdc53d9aa490e38e
+  data.tar.gz: dfc0ade69d92b8b100698091f6ec22d90eb428769bb61aebdc79a9e842840036bc45875bc330531be335d5a11459c823ff13a1ccd78e1b143b11009f083ca54b

data/.version

@@ -1 +1 @@
-1.27.0
+1.27.1

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.27.1
+
+Requires an Atlas that serves `GET /health` and the `backend_unavailable`
+envelope.
+
+### Added — `AtlasRb::Health.read`
+
+Reads Atlas's readiness report (`GET /health`). Returns the parsed body on a
+`200` or a `503`, because a `503` there is an answer. Raises only on
+transport failure, or `ResourceError` when the answer is not the report. No
+credential, a 5-second deadline, no retry, and a fresh socket per call.
+
+### Added — `AtlasRb::BackendUnavailableError`
+
+Raised on every binding when Atlas answers `503` with
+`error: "backend_unavailable"`. Carries `dependency` (`"database"`,
+`"index"` or `"storage"`) and `retry_after`. A sibling of
+`ReadOnlyModeError`, not a `ResourceError`. A bodyless `503` from a proxy
+still passes through.
+
 ## 1.27.0
 
 ### Removed — `Resource.class_for` and `Resource::TYPE_MAP`

data/Gemfile.lock

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

data/README.md

@@ -819,6 +819,44 @@ A `503` from a reverse proxy while Atlas restarts carries no JSON body and is
 a different condition with a different remedy, so it passes through as a plain
 response rather than raising.
 
+### Health and outages
+
+`AtlasRb::Health.read` returns Atlas's readiness report. It sends no
+credential, because Atlas serves `GET /health` unauthenticated:
+
+```ruby
+report = AtlasRb::Health.read
+report["status"]    # => "ok" / "degraded" / "unavailable"
+report["database"]  # => "ok" / "unavailable"
+report["index"]     # => "ok" / "unavailable"
+report["storage"]   # => "ok" / "unavailable"
+report["cache"]     # => "ok" / "unavailable" / "disabled"
+```
+
+Atlas answers `503` when the database, the index or the storage is down. That
+is an answer, so `read` returns it like a `200`. It raises
+`Faraday::ConnectionFailed` or `Faraday::TimeoutError` only when nothing
+answers, and `AtlasRb::ResourceError` when something answers that is not the
+report. It has a 5-second deadline (`read(timeout: 3)` to change it) and no
+retry, so a probe answers inside its poller's own deadline.
+
+When an ordinary call meets a dependency outage, Atlas answers `503` with
+`error: "backend_unavailable"`, and every binding raises:
+
+```ruby
+begin
+  AtlasRb::Work.find("w-789")
+rescue AtlasRb::BackendUnavailableError => e
+  e.dependency   # => "database" / "index" / "storage"
+  e.retry_after  # => 30
+end
+```
+
+It is not a `ResourceError`, which hosts treat as a refusal of the request.
+
+A streaming download (`Blob.content`, `Blob.version_content`) cannot raise
+this: its body has already gone to your block. Check the returned `status`.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/errors.rb

@@ -420,6 +420,47 @@ module AtlasRb
     end
   end
 
+  # Raised when Atlas cannot reach one of its own dependencies: an HTTP `503`
+  # whose body carries `error: "backend_unavailable"` and a `dependency` key
+  # naming `"database"`, `"index"` or `"storage"`.
+  #
+  # A sibling of {ReadOnlyModeError}, and deliberately NOT a {ResourceError}.
+  # Hosts commonly treat a `ResourceError` as a refusal of the request (Cerberus's
+  # `Authorizable` renders it as one), and an outage is no statement about the
+  # caller or the resource. Without this the outage reaches the host as the
+  # generic `ResourceError` a `5xx` read raises, indistinguishable from a bug.
+  #
+  #   rescue AtlasRb::BackendUnavailableError => e
+  #     render "outage", status: :service_unavailable
+  #     response.headers["Retry-After"] = e.retry_after.to_s if e.retry_after
+  #
+  # A bodyless `503` from a proxy is not this; it keeps reaching the caller as
+  # it did before. Poll {AtlasRb::Health.read} to see every dependency at once.
+  class BackendUnavailableError < Error
+    # @return [String, nil] the envelope's `error` discriminator
+    #   (`"backend_unavailable"`).
+    attr_reader :code
+
+    # @return [String, nil] which dependency failed: `"database"`, `"index"` or
+    #   `"storage"`.
+    attr_reader :dependency
+
+    # @return [Integer, nil] seconds to wait before retrying, from Atlas's
+    #   `Retry-After` response header.
+    attr_reader :retry_after
+
+    # @param message [String, nil] human-readable description.
+    # @param code [String, nil] the envelope's `error` discriminator.
+    # @param dependency [String, nil] the dependency that failed.
+    # @param retry_after [Integer, nil] seconds from the `Retry-After` header.
+    def initialize(message=nil, code: nil, dependency: nil, retry_after: nil)
+      @code = code
+      @dependency = dependency
+      @retry_after = retry_after
+      super(message || "Atlas cannot reach its #{dependency || "backend"}")
+    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/faraday_helper.rb

@@ -408,11 +408,16 @@ module AtlasRb
     #   above: a maintenance window refuses writes on every path and a `503`
     #   reaches neither of them. On all three shapes, because a write that
     #   slips past it silently unwraps nil and reports success.
+    # - {Middleware::RaiseOnBackendUnavailable} — path-independent for the same
+    #   reason: a dependency outage can answer any request on any shape. It
+    #   must run before the read guard, or an outage on a read becomes the
+    #   generic {AtlasRb::ResourceError} a host treats as a refusal.
     def error_middleware(builder, reads:)
       builder.use AtlasRb::Middleware::RaiseOnReadError if reads
       builder.use AtlasRb::Middleware::RaiseOnStaleResource
       builder.use AtlasRb::Middleware::RaiseOnResourceError
       builder.use AtlasRb::Middleware::RaiseOnReadOnlyMode
+      builder.use AtlasRb::Middleware::RaiseOnBackendUnavailable
     end
 
     # Retry an idempotent read that failed in transport, in exactly one layer.

data/lib/atlas_rb/health.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Atlas's readiness report (`GET /health`): whether it can reach its database,
+  # its Solr index, its storage and its cache.
+  #
+  # Atlas answers `200` when every required dependency answers and `503` when
+  # one does not, with the same body either way:
+  #
+  #   { "status" => "degraded", "database" => "ok", "index" => "unavailable",
+  #     "storage" => "ok", "cache" => "ok" }
+  #
+  # The endpoint is unauthenticated, so this sends no credential, and works
+  # without a signing key or `ATLAS_JWT` configured.
+  #
+  # Not to be confused with `GET /up`, the liveness route the orchestrator
+  # polls; it has no binding.
+  class Health
+    extend AtlasRb::FaradayHelper
+
+    # Seconds to wait for a socket to open.
+    OPEN_TIMEOUT = 2
+
+    # Seconds to wait for the report. Atlas bounds each of its own probes, so a
+    # slower answer means Atlas itself is struggling. Short enough to answer
+    # inside a monitor's own deadline (Nagios's `check_http` defaults to 10s).
+    READ_TIMEOUT = 5
+
+    # Read the report.
+    #
+    # A `503` here is an answer, not an error, so it is returned like a `200`;
+    # read `status` off the result. There is no retry: a probe must answer
+    # faster than its poller times out, and a retry would hide the very
+    # flakiness it exists to show.
+    #
+    # @param timeout [Numeric] seconds to wait for the report.
+    # @return [AtlasRb::Mash] `status` (`"ok"` / `"degraded"` /
+    #   `"unavailable"`), and `database`, `index`, `storage` (`"ok"` /
+    #   `"unavailable"`) and `cache` (`"ok"` / `"unavailable"` / `"disabled"`).
+    # @raise [Faraday::ConnectionFailed, Faraday::TimeoutError] when Atlas
+    #   does not answer at all.
+    # @raise [AtlasRb::ResourceError] when something answers that is not
+    #   Atlas's report: a `404` from an Atlas that predates the endpoint, or a
+    #   proxy's `502` with an HTML body.
+    def self.read(timeout: READ_TIMEOUT)
+      resp = health_connection(timeout).get("/health")
+      report = parse_report(resp)
+      return AtlasRb::Mash.new(report) if report
+
+      raise AtlasRb::ResourceError.new("#{request_target(resp)} → #{resp.status}: #{resp.body}", response: resp)
+    end
+
+    class << self
+      private
+
+      # A fresh socket per call rather than the shared pool. With no retry, a
+      # pooled socket the server had closed would report a healthy Atlas as
+      # down; a probe runs far too rarely for the handshake to matter.
+      def health_connection(timeout)
+        Faraday.new(url: ENV.fetch("ATLAS_URL", nil)) do |f|
+          f.options.open_timeout = OPEN_TIMEOUT
+          f.options.timeout      = timeout
+          instrument(f)
+          f.adapter :net_http
+        end
+      end
+
+      def parse_report(resp)
+        return nil unless [200, 503].include?(resp.status)
+
+        body = JSON.parse(resp.body.to_s)
+        body.is_a?(Hash) && body.key?("status") ? body : nil
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/atlas_rb/middleware/raise_on_backend_unavailable.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Middleware
+    # Translates Atlas's dependency-outage answer into a typed Ruby exception.
+    #
+    # When Atlas cannot reach its database, its Solr index or its storage, it
+    # answers `503 Service Unavailable` with the discriminator
+    # `error: "backend_unavailable"`, a `dependency` key and a `Retry-After`
+    # header. This middleware keys on the **status + discriminator pair** and
+    # raises {AtlasRb::BackendUnavailableError}.
+    #
+    # Path-independent, like {RaiseOnReadOnlyMode}: an outage can answer any
+    # request. A 503 without Atlas's envelope — a proxy while Atlas restarts —
+    # passes through untouched, because that is a different condition.
+    class RaiseOnBackendUnavailable < Faraday::Middleware
+      # The discriminator Atlas renders. An exact-match wire contract.
+      CODE = "backend_unavailable"
+
+      # @param env [Faraday::Env] the completed response environment.
+      # @raise [AtlasRb::BackendUnavailableError] on a 503 whose body carries
+      #   `error: "backend_unavailable"`.
+      # @return [void]
+      def on_complete(env)
+        return unless env.status == 503
+
+        body = parse_json(env.body)
+        return unless body.is_a?(Hash) && body["error"] == CODE
+
+        raise AtlasRb::BackendUnavailableError.new(
+          body["message"],
+          code: body["error"],
+          dependency: body["dependency"],
+          retry_after: env.response_headers&.[]("retry-after")&.to_i
+        )
+      end
+
+      private
+
+      def parse_json(body)
+        return body if body.is_a?(Hash)
+
+        JSON.parse(body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/atlas_rb.rb

@@ -21,6 +21,7 @@ require_relative "atlas_rb/middleware/raise_on_read_error"
 require_relative "atlas_rb/middleware/raise_on_stale_resource"
 require_relative "atlas_rb/middleware/raise_on_resource_error"
 require_relative "atlas_rb/middleware/raise_on_read_only_mode"
+require_relative "atlas_rb/middleware/raise_on_backend_unavailable"
 require_relative "atlas_rb/faraday_helper"
 require_relative "atlas_rb/mash"
 require_relative "atlas_rb/authentication"
@@ -46,6 +47,7 @@ require_relative "atlas_rb/system/token"
 require_relative "atlas_rb/system/work"
 require_relative "atlas_rb/audit_event"
 require_relative "atlas_rb/maintenance"
+require_relative "atlas_rb/health"
 
 # Ruby client for the Atlas API — Northeastern University's institutional
 # digital repository.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.27.0
+  version: 1.27.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -170,8 +170,10 @@ files:
 - lib/atlas_rb/errors.rb
 - lib/atlas_rb/faraday_helper.rb
 - lib/atlas_rb/file_set.rb
+- lib/atlas_rb/health.rb
 - lib/atlas_rb/maintenance.rb
 - lib/atlas_rb/mash.rb
+- lib/atlas_rb/middleware/raise_on_backend_unavailable.rb
 - lib/atlas_rb/middleware/raise_on_read_error.rb
 - lib/atlas_rb/middleware/raise_on_read_only_mode.rb
 - lib/atlas_rb/middleware/raise_on_resource_error.rb