atlas_rb 1.27.0 → 1.27.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ea8cbef3fa493fefcf29c0dd15a4d7edf72efb58134f8d21050421517ef05f
-  data.tar.gz: 36a4eb18338f27da7ee744233e7b54fd6eb20faa76201e907f94703b8c6583e2
+  metadata.gz: 3bf07fbfa75e57be6651cc352fc2216f8c5e4029a68393018fa14b8e6a34e6aa
+  data.tar.gz: 63d66617e658bc0693c7a07afdf0b38cac2067f464b3ba1e0466b3a8d7d1860e
 SHA512:
-  metadata.gz: d33812411e71cfa8bf0031fae4f81b735d598b75cb31f099e0c67a31d8dc0e4cc9c193524443f8dce983f87f96add5c9cc82c6de8c3d1d4211e69611254d4cc6
-  data.tar.gz: f287d655a86594da49f54caa8cb505277577b3b81284e313cf956ee6424fd09f3bdf0085ae51fae14420468c386626eba3c300be3f41e5762d57c65de5938213
+  metadata.gz: 2071b3face694f62a03db93362462bf77381cfdcee77c138ff5a2baabe47f000d94ede673ca1d28f160d0348506a844346f920b71457669bae326769aa9286e3
+  data.tar.gz: 823ca671c648afad8c4a82111d658a691c6bf757e02cb942594c0a1c6afec2a1b6fda628c954ca909497c7168a6384f845fcf4ed229a1f470d5fabb1bac212c8

data/.version

@@ -1 +1 @@
-1.27.0
+1.27.2

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.27.2
+
+Requires an Atlas that serves `GET /metrics/latency`.
+
+### Added — `AtlasRb::Metrics.latency`
+
+Reads Atlas's own request latency for a window of up to 120 minutes: calls,
+5xx count, mean and approximate p50/p95/p99, and the slowest actions. Sent
+with the acting NUID's signed assertion, which must name an admin. A
+5-second deadline, no retry and a fresh socket per call. Raises
+`BackendUnavailableError` when Atlas's Redis is down and `ResourceError` on
+any other non-200.
+
+## 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.2)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)

data/README.md

@@ -819,6 +819,68 @@ 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`.
+
+### Atlas's own latency
+
+`AtlasRb::Metrics.latency` reports how long Atlas took to serve its own
+requests over a recent window. Atlas gates it to admins and `:system`, so
+`nuid` must name an admin:
+
+```ruby
+latency = AtlasRb::Metrics.latency(minutes: 60, nuid: current_user.nuid)
+latency["calls"]          # => 18402
+latency["server_errors"]  # => 3
+latency["p95_ms"]         # => 98
+latency["slowest_actions"].first  # => { "action" => "works#mods", "calls" => 912, "p95_ms" => 188 }
+```
+
+Atlas times each request from when Rails dispatches it until it returns, so
+the figures leave out the network and your own waiting. If you also time your
+Atlas calls, the difference is time spent on your side. The percentiles are
+interpolated from histogram buckets, so they are approximate.
+
+Like `Health.read`, it has a 5-second deadline and no retry. It raises
+`BackendUnavailableError` (with `dependency == "cache"`) when Atlas's Redis is
+down, `ResourceError` on any other non-200 such as a `403`, and `Faraday`
+errors when nothing answers.
+
 ## 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/metrics.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Atlas's own operational figures. Admin- or `:system`-gated in Atlas.
+  class Metrics
+    extend AtlasRb::FaradayHelper
+
+    # Seconds to wait for a socket to open.
+    OPEN_TIMEOUT = 2
+
+    # Seconds to wait for the report. It reads at most 120 small Redis hashes,
+    # so a slower answer means Atlas is struggling, and an admin page should
+    # not wait on it.
+    READ_TIMEOUT = 5
+
+    # How long Atlas took to serve its own requests (`GET /metrics/latency`).
+    #
+    # Measured inside Atlas, from when Rails dispatches the action until it
+    # returns, so it leaves out the network and the caller's own waiting. A
+    # caller that also times its Atlas calls can subtract to see how much of
+    # its wait was its own. The percentiles are interpolated from histogram
+    # buckets, so they are approximate.
+    #
+    # No retry, and a fresh socket per call: like {AtlasRb::Health.read}, it is
+    # polled rarely and should fail fast rather than hide a struggling Atlas.
+    #
+    # @param minutes [Integer] the window, 1 to 120. Atlas clamps it.
+    # @param nuid [String, nil] the acting NUID, signed into the assertion
+    #   `sub`. It must name an admin; falls through to
+    #   {AtlasRb.config#default_nuid}.
+    # @param on_behalf_of [String, nil] optional NUID carried as a signed `obo`
+    #   claim.
+    # @return [AtlasRb::Mash] `window_minutes`, `calls`, `server_errors`,
+    #   `mean_ms`, `p50_ms`, `p95_ms`, `p99_ms` (Integer, or nil with no calls),
+    #   and `slowest_actions`, an Array of `action` / `calls` / `p95_ms`.
+    # @raise [AtlasRb::BackendUnavailableError] when Atlas answers that Redis,
+    #   which holds the figures, is down (`dependency == "cache"`).
+    # @raise [AtlasRb::ResourceError] on any other non-200, notably a `403`
+    #   for a caller who is not an admin.
+    # @raise [Faraday::ConnectionFailed, Faraday::TimeoutError] when Atlas does
+    #   not answer at all.
+    #
+    # @example
+    #   latency = AtlasRb::Metrics.latency(minutes: 15, nuid: current_user.nuid)
+    #   latency.p95_ms  # => 98
+    def self.latency(minutes: 60, nuid: nil, on_behalf_of: nil)
+      resp = metrics_connection(nuid, on_behalf_of).get("/metrics/latency", minutes: minutes)
+      return AtlasRb::Mash.new(JSON.parse(resp.body)) if resp.status == 200
+
+      raise AtlasRb::ResourceError.new("#{request_target(resp)} → #{resp.status}: #{resp.body}", response: resp)
+    end
+
+    class << self
+      private
+
+      def metrics_connection(nuid, on_behalf_of)
+        headers = auth_headers(nuid, on_behalf_of).merge("Content-Type" => "application/json")
+        Faraday.new(url: ENV.fetch("ATLAS_URL", nil), headers: headers) do |f|
+          f.options.open_timeout = OPEN_TIMEOUT
+          f.options.timeout      = READ_TIMEOUT
+          instrument(f)
+          f.use AtlasRb::Middleware::RaiseOnBackendUnavailable
+          f.adapter :net_http
+        end
+      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,8 @@ 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"
+require_relative "atlas_rb/metrics"
 
 # 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.2
 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,11 @@ 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/metrics.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