atlas_rb 1.12.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7340207635a0bb6db21f36e716000082d7d67fa3d62603388656bfe6d829c81
-  data.tar.gz: fbf68dbb0590ce6d05c3f75f6f879bb392dc45dcca488503b3c19ee57b823cb2
+  metadata.gz: c55fceb9d85a211c8e28903ae67f1b8b98a9114c8ab403c63af68721bef76df4
+  data.tar.gz: 2b0684c399abf35c57bb6aac6def417f6996126b5afec576295d5d57cd5f72d2
 SHA512:
-  metadata.gz: 1d07bb66ff2c4c7bf8c5f243fc01afe244e83d1bc53e9734ac22ea7b41990104c538ac53520cf47f4aa55195499ee6a9e0ed81c06fec2afad33b0f4076990bb5
-  data.tar.gz: 46bb9c90c94d5f5e2a3501693e2802ae6dfb84ccc4c5c68c5c99ee34e9c2b86203f20867a94251801f9d28e6d66387779e5f5a48ba3fb25439b257d208b3bbb0
+  metadata.gz: 46728839d509e41136a4a87f774c8f343055b0fd219d45e04732c6ef95ba635c5f13715e52b7f6dfd700ffe149e59debce03b77bf748e2c03b94f837540d24ff
+  data.tar.gz: 3bcd0432f0eab0d5bba7d0f7e8da7d1f29b50a083631cfe357c00eaf1d6403ac526dcb9c3ca6ecd68d26b4459d64d7407aa3a2b926bf9585f433e316369cdcbc

data/.version

@@ -1 +1 @@
-1.12.0
+1.13.0

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.13.0
+
+### Added — maintenance mode no longer passes through silently
+
+Atlas can now hold a repository-wide read-only window, refusing every write
+with `503` + `error: "read_only_mode"`. Before this release a `503` reached
+neither `RaiseOnStaleResource` (409-only) nor `RaiseOnResourceError`
+(403/422-only), and the body carries no `"work"` / `"collection"` key — so the
+binding unwrapped `nil` and returned it. The write silently no-opped and the
+caller's UI reported success. During a window that meant a librarian saving
+metadata, seeing no error, and losing the edit.
+
+`AtlasRb::Middleware::RaiseOnReadOnlyMode` now raises
+`AtlasRb::ReadOnlyModeError` on that pair, on every path and all three
+connection builders. It carries `#code` and `#retry_after` (from Atlas's
+`Retry-After` header).
+
+```ruby
+rescue AtlasRb::ReadOnlyModeError => e
+  e.retry_after  # => 900
+```
+
+It is keyed on the discriminator as well as the status, so a bodyless `503`
+from a reverse proxy while Atlas restarts still passes through untouched.
+
+`AtlasRb::Maintenance.read` / `.write` read and set the flag. `.read` sits on
+the authenticated read floor and is answered while the window is open, so a
+client can always see the flag it is honouring; `.write` is system-gated.
+
+A minor bump rather than a patch: a new exception can now raise where callers
+previously got `nil`.
+
+**This release requires Atlas 0.6.159 or newer** for the `/maintenance`
+endpoints. The middleware is inert against an older Atlas, which never sends
+the discriminator.
+
 ## 1.12.0
 
 ### Changed — index rows arrive flat

data/Gemfile.lock

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

data/README.md

@@ -497,6 +497,56 @@ caller reads `tombstoned`. And the typed `403` / `422` translations above still
 fire first, while `tombstone` / `destroy` / `complete` keep returning the raw
 Faraday response for the caller to read.
 
+### Maintenance mode (the read-only window)
+
+Atlas can be put into a repository-wide read-only window: reads keep being
+served, every write is refused, migrations run, the operator closes it. Three
+doors open the same window — Cerberus's admin hub, Atlas's `maintenance:open`
+rake task, and the deploy orchestrator.
+
+Refused writes raise on **every** binding and **every** path:
+
+```ruby
+begin
+  AtlasRb::Work.update("w-789", metadata)
+rescue AtlasRb::ReadOnlyModeError => e
+  e.retry_after  # => 900 (seconds, from Atlas's Retry-After header)
+  e.message      # => "Atlas is in maintenance mode; writes are refused"
+end
+```
+
+This is deliberately not `ForbiddenError`. Atlas answers `503`, not `403`,
+because a 403 is a statement about the caller's rights — during a migration
+window the caller's rights are fine, the repository is closed.
+
+Read the flag to render a banner before a caller trips it. The read is answered
+even while the window is open, so a client can always see the flag it honours:
+
+```ruby
+window = AtlasRb::Maintenance.read
+window["read_only"]    # => true
+window["source"]       # => "deploy" / "operator"
+window["message"]      # => "Scheduled maintenance until 10:00"
+window["retry_after"]  # => 900
+```
+
+Opening and closing is system-gated:
+
+```ruby
+AtlasRb::Maintenance.write(read_only: true, source: "deploy")
+AtlasRb::Maintenance.write(read_only: false, source: "deploy")
+```
+
+`source` carries one rule: a `"deploy"` close is refused when an `"operator"`
+opened the window, so a deploy that finishes cannot close a window a human
+opened by hand. The refusal is not an error — Atlas answers `200` with the
+*unchanged* state — so read `read_only` off the return value rather than
+assuming the write took. An `"operator"` close clears either.
+
+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.
+
 ## End-to-end example
 
 JSON responses come back as `AtlasRb::Mash` (a `Hashie::Mash` subclass), so

data/lib/atlas_rb/errors.rb

@@ -378,6 +378,48 @@ module AtlasRb
   # a caller that only wants "the write failed" can rescue the parent.
   class NotFoundError < ResourceError; end
 
+  # Raised when Atlas refuses a write because the repository-wide maintenance
+  # window is open: an HTTP `503` whose body carries
+  # `error: "read_only_mode"`.
+  #
+  # Deliberately NOT {ForbiddenError}. Atlas could have refused with a 403, but
+  # a 403 is a statement about the caller's rights, and Cerberus renders
+  # {ForbiddenError} as a permission-denied page. During a migration window that
+  # is a lie — the librarian's rights are fine, the repository is closed.
+  #
+  # Without this the failure mode is worse than an error: a 503 reaches neither
+  # {Middleware::RaiseOnStaleResource} (409-only) nor
+  # {Middleware::RaiseOnResourceError} (403/422-only), and the response body
+  # carries no `"work"` / `"collection"` key, so the binding unwraps `nil` and
+  # returns it. The write silently no-ops and the UI reports success — a
+  # librarian saves metadata, sees no error, and loses the edit.
+  #
+  #   rescue AtlasRb::ReadOnlyModeError => e
+  #     flash.now[:alert] = e.message
+  #     response.headers["Retry-After"] = e.retry_after.to_s if e.retry_after
+  #
+  # Read `GET /maintenance` ({AtlasRb::Maintenance.read}) to render a banner
+  # before a caller trips this; that endpoint stays answerable while the window
+  # is open, precisely so a client can see the flag it is honouring.
+  class ReadOnlyModeError < Error
+    # @return [String, nil] the envelope's `error` discriminator
+    #   (`"read_only_mode"`).
+    attr_reader :code
+
+    # @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 refusal description.
+    # @param code [String, nil] the envelope's `error` discriminator.
+    # @param retry_after [Integer, nil] seconds from the `Retry-After` header.
+    def initialize(message=nil, code: nil, retry_after: nil)
+      @code = code
+      @retry_after = retry_after
+      super(message || "Atlas is in maintenance mode; writes are refused")
+    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

@@ -109,6 +109,11 @@ module AtlasRb
         instrument(f)
         f.use AtlasRb::Middleware::RaiseOnStaleResource
         f.use AtlasRb::Middleware::RaiseOnResourceError
+        # Path-independent, unlike the pair above: a maintenance window refuses
+        # writes on EVERY path, and a 503 reaches neither of them. Registered on
+        # all three connection builders — a write that slips past it silently
+        # unwraps nil and reports success.
+        f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
         f.response :follow_redirects
         f.adapter Faraday.default_adapter
       end
@@ -153,6 +158,11 @@ module AtlasRb
         # unsupported_digest_algorithm) into a typed FixityMismatchError —
         # the JSON-connection path already carries this; uploads need it too.
         f.use AtlasRb::Middleware::RaiseOnResourceError
+        # Path-independent, unlike the pair above: a maintenance window refuses
+        # writes on EVERY path, and a 503 reaches neither of them. Registered on
+        # all three connection builders — a write that slips past it silently
+        # unwraps nil and reports success.
+        f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
         f.request :multipart
         f.request :url_encoded
       end
@@ -223,6 +233,11 @@ module AtlasRb
         # System::Token, and gives System::Work the same typed errors as #connection.
         f.use AtlasRb::Middleware::RaiseOnStaleResource
         f.use AtlasRb::Middleware::RaiseOnResourceError
+        # Path-independent, unlike the pair above: a maintenance window refuses
+        # writes on EVERY path, and a 503 reaches neither of them. Registered on
+        # all three connection builders — a write that slips past it silently
+        # unwraps nil and reports success.
+        f.use AtlasRb::Middleware::RaiseOnReadOnlyMode
         f.response :follow_redirects
         f.adapter Faraday.default_adapter
       end

data/lib/atlas_rb/maintenance.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # The repository-wide read-only window (`GET` / `PUT /maintenance`).
+  #
+  # An operator opens the window, Atlas keeps serving reads and refuses every
+  # write with a `503` carrying `error: "read_only_mode"`, migrations run, the
+  # operator closes it. Three doors open the same window: Cerberus's admin hub,
+  # Atlas's `maintenance:open` rake task, and the deploy orchestrator.
+  #
+  # ## Why the flag lives in Atlas
+  #
+  # A window has to hold across both apps. A Cerberus-held flag is bypassed by
+  # any direct API caller, including a personal-access token minted by
+  # `POST /nuid`, so the flag is a row in Atlas and the floor that enforces it
+  # is Atlas's own authorization layer.
+  #
+  # ## Reading versus writing
+  #
+  # {.read} sits on Atlas's authenticated read floor and is answered even while
+  # the window is open — a client that could not read the flag could not honour
+  # it. {.write} is `:system`-gated, matching how the token endpoints gate an
+  # operator action, so it goes out over {FaradayHelper#system_connection}.
+  #
+  # Refused writes surface as {AtlasRb::ReadOnlyModeError} via
+  # {Middleware::RaiseOnReadOnlyMode}, on every binding and every path. Poll
+  # {.read} to render a banner before a caller trips that.
+  class Maintenance
+    extend AtlasRb::FaradayHelper
+
+    # Read the window's state (`GET /maintenance`).
+    #
+    # Cheap and safe to poll behind a short-TTL cache; Cerberus renders its
+    # banner and its client-side write gate from this.
+    #
+    # @return [AtlasRb::Mash] `read_only` (Boolean), `source`
+    #   (`"operator"` / `"deploy"` / nil), `since` (ISO-8601 or nil), `message`
+    #   (String or nil), and `retry_after` (Integer seconds).
+    def self.read
+      AtlasRb::Mash.new(JSON.parse(connection({}).get("/maintenance").body))
+    end
+
+    # Open or close the window (`PUT /maintenance`). System-gated in Atlas.
+    #
+    # `source` names which door is acting, and Atlas enforces one rule with it:
+    # a `"deploy"` close is refused when an `"operator"` opened the window, so a
+    # deploy that finishes cannot close a window a human opened by hand. The
+    # refusal is not an error — Atlas answers `200` with the *unchanged* state,
+    # so read `read_only` off the return value rather than assuming the write
+    # took. An `"operator"` close clears either.
+    #
+    # @param read_only [Boolean] true to open the window, false to close it.
+    # @param source [String] `"operator"` (a human at the hub or the console) or
+    #   `"deploy"` (the deploy orchestrator).
+    # @param message [String, nil] operator note for the client-side banner.
+    # @param retry_after [Integer, nil] seconds a refused caller should wait;
+    #   Atlas mirrors it into the `Retry-After` header on every refusal.
+    # @return [AtlasRb::Mash] the window's state after the write — which is the
+    #   state *before* it when a deploy close was refused.
+    def self.write(read_only:, source:, message: nil, retry_after: nil)
+      body = { read_only: read_only, source: source }
+      body[:message] = message if message
+      body[:retry_after] = retry_after if retry_after
+
+      AtlasRb::Mash.new(JSON.parse(system_connection.put("/maintenance", body.to_json).body))
+    end
+  end
+end

data/lib/atlas_rb/middleware/raise_on_read_only_mode.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Middleware
+    # Translates Atlas's maintenance-window refusal into a typed Ruby exception.
+    #
+    # Atlas refuses every write-shaped action while the repository-wide
+    # read-only window is open, answering `503 Service Unavailable` with the
+    # discriminator `error: "read_only_mode"` and a `Retry-After` header. This
+    # middleware keys on the **status + discriminator pair** and raises
+    # {AtlasRb::ReadOnlyModeError}.
+    #
+    # ## Why path-independent
+    #
+    # Modelled on {RaiseOnStaleResource}, not {RaiseOnResourceError}. A
+    # maintenance window refuses writes on *every* path, so a path-keyed rule
+    # would have to enumerate the whole write surface and would go stale the
+    # moment Atlas grows an endpoint.
+    #
+    # ## Why the discriminator matters
+    #
+    # A 503 from a reverse proxy while Atlas restarts carries no JSON body. That
+    # is a different condition with a different remedy, and it keeps passing
+    # through untouched — only Atlas's own envelope raises.
+    class RaiseOnReadOnlyMode < Faraday::Middleware
+      # @param env [Faraday::Env] the completed response environment.
+      # @raise [AtlasRb::ReadOnlyModeError] on a 503 whose body carries
+      #   `error: "read_only_mode"`.
+      # @return [void]
+      def on_complete(env)
+        return unless env.status == 503
+
+        body = parse_json(env.body)
+        return unless body.is_a?(Hash) && body["error"] == "read_only_mode"
+
+        raise AtlasRb::ReadOnlyModeError.new(
+          body["message"],
+          code: body["error"],
+          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

@@ -11,6 +11,7 @@ require_relative "atlas_rb/errors"
 require_relative "atlas_rb/configuration"
 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/faraday_helper"
 require_relative "atlas_rb/mash"
 require_relative "atlas_rb/authentication"
@@ -33,6 +34,7 @@ require_relative "atlas_rb/system/user"
 require_relative "atlas_rb/system/token"
 require_relative "atlas_rb/system/work"
 require_relative "atlas_rb/audit_event"
+require_relative "atlas_rb/maintenance"
 
 # 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.12.0
+  version: 1.13.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -144,7 +144,9 @@ files:
 - lib/atlas_rb/errors.rb
 - lib/atlas_rb/faraday_helper.rb
 - lib/atlas_rb/file_set.rb
+- lib/atlas_rb/maintenance.rb
 - lib/atlas_rb/mash.rb
+- lib/atlas_rb/middleware/raise_on_read_only_mode.rb
 - lib/atlas_rb/middleware/raise_on_resource_error.rb
 - lib/atlas_rb/middleware/raise_on_stale_resource.rb
 - lib/atlas_rb/person.rb