atlas_rb 1.26.0 → 1.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74f74d6af596e2f817ba6991018efd21cb158f897efa39ffc572367a27a3c968
-  data.tar.gz: 26b52d5a67e30cac921695e31aba127338fe77095218a1277f6c04049c1dde5e
+  metadata.gz: 2c1b0723d54145c8be9868a1849502cf80adbc1a30b2f7b1ee39aadbfa1a2f3b
+  data.tar.gz: 7ab2bb5a662b02dd48275e645f9c6b3c1226d6bc995231766bd5a4252f17b25a
 SHA512:
-  metadata.gz: 692f82797f41797a10b06b1c6fb79624a03437711c1781afd3e7a0d1f8711eb5964c42197dd6b411e4c1b0df84115a609c7f26091d736f02faacb72a40dc22f3
-  data.tar.gz: fffef87ace94444d2f9b82f5347ad342e8a908f05541fd4c4b4feced02b63cc6ecc5eff57ca2c0824439fb5c133fa3a4389655c157e8809aafc472236fc9eb60
+  metadata.gz: 64f43d675ad66dac85657c0460702f53f95c99760e7a44ce6f0dec019e375f41b197c214ca3dc4d89a94a1e0b829fa9d377fd4dd9432fe68cdc53d9aa490e38e
+  data.tar.gz: dfc0ade69d92b8b100698091f6ec22d90eb428769bb61aebdc79a9e842840036bc45875bc330531be335d5a11459c823ff13a1ccd78e1b143b11009f083ca54b

data/.version

@@ -1 +1 @@
-1.26.0
+1.27.1

data/CHANGELOG.md

@@ -1,5 +1,70 @@
 # 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`
+
+Callers no longer turn a type string into a class themselves. Replace
+
+```ruby
+AtlasRb::Resource.class_for(found.klass)
+```
+
+with
+
+```ruby
+found.resource_class
+```
+
+The lookup no longer accepts `"File_set"`, the spelling `find` emitted
+before 1.17.0, or `"compilation"` / `"Compilation"`, which no Atlas payload
+reports: the resolver covers Valkyrie-backed types only. Each now raises
+`ArgumentError`. `lib/atlas_rb/resource_types.rb` is gone.
+
+### Added — `Mash#resource_class`
+
+```ruby
+AtlasRb::Resource.find(id).resource_class                # => AtlasRb::FileSet
+AtlasRb::Resource.search("whaling").results.first.resource_class
+```
+
+Every Atlas payload that names a type carries it as `"klass"`, so the method
+lives on the shared `Mash` and covers `find`, `find_many`, `ancestors` nodes
+and the Solr digests. `klass` itself is unchanged.
+
+### Added — `Resource.unresolvable!`
+
+Every `Resource` subclass now registers itself when it is defined, under its
+class name and its snake-cased wire key. A subclass that Atlas never names in
+a payload opts out by calling `unresolvable!` in its body. `Compilation` is
+the only one.
+
+### Added — `mods_editable?`
+
+`true` for `Work`, `Collection` and `Community`, `false` for every other
+type. It matches Atlas's `ResourcesController::TYPED_IVARS`, which Atlas
+does not expose on the wire.
+
 ## 1.26.0
 
 These bindings need Atlas 0.6.221 or later.

data/Gemfile.lock

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

data/README.md

@@ -615,34 +615,37 @@ Writes that address something only one type has stay typed — `create`, the
 Work-only lifecycle and derivative writes, `Collection.set_featured`, and the
 FileSet, Blob and Compilation writes.
 
-### Resolving one id of unknown type (`Resource.find` and `Resource.class_for`)
+### Resolving one id of unknown type (`Resource.find` and `resource_class`)
 
 When a NOID arrives as runtime data and you do not know its type, resolve
 it generically and dispatch on the reported type:
 
 ```ruby
 found = AtlasRb::Resource.find("b8gtjvk")
-found["klass"]                                   # => "FileSet"
-klass = AtlasRb::Resource.class_for(found["klass"])  # => AtlasRb::FileSet
-klass.find(found["resource"]["id"])
-```
-
-`class_for` is the supported way to turn a type string into a class. Do not
-`const_get` into the `AtlasRb` namespace: the mapping is a stated, closed
-set (`Resource::TYPE_MAP`), not a naming rule — `Blob`'s route is `/files/`,
-and a wire key like `file_set` is not the class name.
-
-It accepts every spelling the DRS stack produces for a type, because a
-caller cannot tell which one it is holding:
-
-| Spelling      | Where it comes from                        |
-|---------------|--------------------------------------------|
-| `"file_set"`  | Atlas's JSON wire key                      |
-| `"FileSet"`   | Solr's `internal_resource`, and `find`'s `"klass"` |
-| `"File_set"`  | a `"klass"` read from a gem before 1.17.0  |
-
-An unknown type raises `ArgumentError` rather than returning `nil`, so a
-type this gem does not model fails where the cause is.
+found.klass                             # => "FileSet"
+found.resource_class                    # => AtlasRb::FileSet
+found.resource_class.find(found.resource.id)
+```
+
+`resource_class` is the supported way to get from a result to its class.
+It works on every Atlas payload that carries a `"klass"`: `find`,
+`find_many`, `ancestors` nodes, and the `search`, `descendant_works` and
+`Compilation.contents` digests. Keep `klass` when the type has to be
+serialized — a job argument, a log line — and use `resource_class` when
+you act on it. Do not `const_get` into the `AtlasRb` namespace.
+
+Every `Resource` subclass registers itself when it is defined, under its
+class name and the key Atlas wraps its JSON in (`FileSet` → `"file_set"`).
+`Compilation` opts out with `unresolvable!`, because the resolver never
+returns one.
+A row naming a type no class registers raises `ArgumentError` rather than
+returning `nil`, so a type this gem does not model fails where the cause
+is.
+
+To ask whether a type has an editable MODS document, use
+`mods_editable?`: it is true for `Work`, `Collection` and `Community` only.
+`Resource.mods` answers for every type, so a successful read does not mean
+a write will be accepted.
 
 **What the resolver covers.** Atlas answers `/resources/:id` for its
 Valkyrie-backed types only: `Work`, `Collection`, `Community`, `FileSet`,
@@ -682,7 +685,7 @@ result = AtlasRb::Resource.search("whaling logbook", type: "Work", per_page: 50)
 result.pagination.total                 # => 12
 hit = result.results.first
 hit.title                               # => "Whaling logbook, 1851"
-AtlasRb::Resource.class_for(hit.klass).find(hit.noid)
+hit.resource_class.find(hit.noid)
 ```
 
 It searches Works, Collections, Communities and People, most relevant first.
@@ -816,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/collection.rb

@@ -16,6 +16,11 @@ module AtlasRb
     # @api private
     ROUTE = "/collections/"
 
+    # Atlas accepts a MODS write for this type. See {Resource.mods_editable?}.
+    def self.mods_editable?
+      true
+    end
+
     # Fetch a single Collection by ID.
     #
     # @param id [String] the Collection ID.

data/lib/atlas_rb/community.rb

@@ -14,6 +14,11 @@ module AtlasRb
     # @api private
     ROUTE = "/communities/"
 
+    # Atlas accepts a MODS write for this type. See {Resource.mods_editable?}.
+    def self.mods_editable?
+      true
+    end
+
     # Fetch a single Community by ID.
     #
     # @param id [String] the Community ID.

data/lib/atlas_rb/compilation.rb

@@ -24,6 +24,9 @@ module AtlasRb
     # Atlas REST endpoint prefix for this resource.
     # @api private
     ROUTE = "/compilations/"
+    # Atlas's resolver covers Valkyrie-backed types only, and a Compilation is
+    # an ActiveRecord row there, so no Atlas payload names one as its klass.
+    unresolvable!
 
     # Fetch a single Compilation by ID.
     #

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/mash.rb

@@ -12,5 +12,23 @@ module AtlasRb
   # `type`, `id`).
   class Mash < Hashie::Mash
     disable_warnings
+
+    # The AtlasRb class named by this row's `"klass"`.
+    #
+    # Every Atlas payload that names a type carries it as `"klass"`, in the
+    # class-name spelling: {Resource.find}, {Resource.find_many}, `ancestors`
+    # nodes, and the Solr digests from {Resource.search},
+    # {Resource.descendant_works} and {Compilation.contents}. Nested hashes
+    # are Mashes too, so an `ancestors` node answers this as well.
+    #
+    # @return [Class] the AtlasRb resource class.
+    # @raise [ArgumentError] when the row has no `"klass"`, or names a type
+    #   this gem does not register.
+    # @example Load a search hit as its full resource
+    #   hit = AtlasRb::Resource.search("whaling").results.first
+    #   hit.resource_class.find(hit.noid)
+    def resource_class
+      Resource.resolve_type(self["klass"])
+    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/resource.rb

@@ -18,6 +18,73 @@ module AtlasRb
   class Resource
     extend AtlasRb::FaradayHelper
 
+    # Every type the Atlas resolver can answer with, filled by {inherited} as
+    # each subclass loads and frozen in `atlas_rb.rb` once they all have. Keyed
+    # by both spellings Atlas produces: the wire key (`"file_set"`) and the
+    # class name Solr indexes as `internal_resource` (`"FileSet"`).
+    # @api private
+    TYPES = {}
+
+    # Registers every subclass as a type the resolver can answer with, unless
+    # it opts out with {unresolvable!}.
+    #
+    # The wire key is the class name in snake case, which is the root key
+    # Atlas wraps the type's JSON in (`json.file_set do`). That holds for every
+    # type today; a type whose wire name ever differs would need a way to say
+    # so.
+    #
+    # An anonymous class, or one defined after the gem has loaded, is not
+    # registered: the set of Atlas types is the gem's, and `TYPES` is frozen
+    # by then.
+    #
+    # @api private
+    # @return [void]
+    def self.inherited(subclass)
+      super
+      return if subclass.name.nil? || TYPES.frozen?
+
+      class_name = subclass.name.split("::").last
+      TYPES[class_name.gsub(/(?<!\A)([A-Z])/, '_\1').downcase] = subclass
+      TYPES[class_name] = subclass
+    end
+
+    # Removes this class from the types the resolver can answer with. For a
+    # subclass that Atlas never names in a payload.
+    #
+    # @return [void]
+    def self.unresolvable!
+      TYPES.delete_if { |_, klass| klass == self }
+    end
+
+    # The class registered for a type string, in either spelling.
+    #
+    # An unknown type raises rather than answering `nil`, so a caller holding a
+    # type this gem does not define hears about it here instead of at a
+    # `NoMethodError` a few frames later.
+    #
+    # @api private
+    # @param name [String, Symbol] a wire key or class name.
+    # @return [Class]
+    # @raise [ArgumentError] when no class is registered for that type.
+    def self.resolve_type(name)
+      TYPES.fetch(name.to_s) do
+        raise ArgumentError, "unknown Atlas resource type: #{name.inspect}"
+      end
+    end
+
+    # Whether Atlas accepts a MODS write for this type.
+    #
+    # {Resource.mods} is defined here on the base class, so every type answers
+    # the read — a FileSet's succeeds and returns nothing a curator can edit.
+    # Only {Work}, {Collection} and {Community} take a write, the same set as
+    # Atlas's `ResourcesController::TYPED_IVARS`. Atlas does not expose that
+    # set on the wire, so it is stated here.
+    #
+    # @return [Boolean]
+    def self.mods_editable?
+      false
+    end
+
     # Resolve any Atlas resource by ID without knowing its type up front.
     #
     # The Atlas server returns a single-key JSON object whose key names the
@@ -45,12 +112,12 @@ module AtlasRb
     #   when the id resolves to nothing (`404`):
     #   - `"klass"` — the resource type as its class name, e.g. `"Work"`,
     #     `"FileSet"`. That is the spelling Solr carries as
-    #     `internal_resource`, and {Resource.class_for} turns it into the class.
+    #     `internal_resource`, and {Mash#resource_class} turns it into the class.
     #   - `"resource"` — the resource payload as a Hash.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
-    # @raise [ArgumentError] when Atlas names a type this gem defines no class
-    #   for. See {Resource.class_for}.
+    # @raise [ArgumentError] when Atlas names a type this gem registers no class
+    #   for. See {Resource.inherited}.
     #
     # @example Polymorphic lookup
     #   AtlasRb::Resource.find("abc123")
@@ -62,7 +129,7 @@ module AtlasRb
       # The class's own name, never `capitalize` over the wire key: `capitalize`
       # answers `"File_set"` for a `file_set`, which is not a constant in this
       # namespace, and callers resolve this string to a class.
-      AtlasRb::Mash.new("klass" => class_for(result.first[0]).name.split("::").last,
+      AtlasRb::Mash.new("klass" => resolve_type(result.first[0]).name.split("::").last,
                         "resource" => result.first[1])
     end
 
@@ -167,8 +234,8 @@ module AtlasRb
     # Each row is a digest read off Solr, not a resource: `{ "id", "noid",
     # "klass", "title", "creators", "year", "thumbnail", "in_progress",
     # "embargoed", "incomplete" }`. `klass` is one of the four type names
-    # above, which {class_for} accepts, so a caller loads the full resource
-    # with `class_for(hit.klass).find(hit.noid)`.
+    # above, so a caller loads the full resource with
+    # `hit.resource_class.find(hit.noid)`.
     #
     # @param query [String, nil] the search text. Omit or pass blank to browse
     #   everything the user may read, newest first.
@@ -189,7 +256,7 @@ module AtlasRb
     # @example Find a Work by a word in its title, then load it
     #   result = AtlasRb::Resource.search("whaling logbook", type: "Work")
     #   hit    = result.results.first
-    #   AtlasRb::Resource.class_for(hit.klass).find(hit.noid)
+    #   hit.resource_class.find(hit.noid)
     # @example Page through every match
     #   (1..AtlasRb::Resource.search("whaling").pagination.pages).flat_map do |page|
     #     AtlasRb::Resource.search("whaling", page: page).results

data/lib/atlas_rb/resource_writes.rb

@@ -5,9 +5,7 @@ module AtlasRb
   # as a verb on the `/resources/{id}` sub-resource that already serves its
   # `GET`, so a caller holding only a NOID never resolves the type first.
   #
-  # Loaded after the subclasses because the typed writes delegate here, and
-  # because {Resource::TYPE_MAP} in `resource_types.rb` has the same ordering
-  # requirement.
+  # Loaded after the subclasses because the typed writes delegate here.
   #
   # **The names are deliberately not `update` and `metadata`.** Neither typed
   # name says which document it writes, and `Resource.mods` / `.permissions`

data/lib/atlas_rb/work.rb

@@ -13,6 +13,11 @@ module AtlasRb
     # @api private
     ROUTE = "/works/"
 
+    # Atlas accepts a MODS write for this type. See {Resource.mods_editable?}.
+    def self.mods_editable?
+      true
+    end
+
     # Fetch a single Work by ID.
     #
     # @param id [String] the Work ID.

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"
@@ -33,9 +34,9 @@ require_relative "atlas_rb/blob"
 require_relative "atlas_rb/delegate"
 require_relative "atlas_rb/compilation"
 require_relative "atlas_rb/person"
-# Must follow every Resource subclass above: it names them in a map.
-require_relative "atlas_rb/resource_types"
-# Same ordering requirement as resource_types: the typed writes delegate here.
+# Every resolvable type has registered itself by now.
+AtlasRb::Resource::TYPES.freeze
+# Must follow every Resource subclass above: the typed writes delegate here.
 require_relative "atlas_rb/resource_writes"
 require_relative "atlas_rb/user"
 require_relative "atlas_rb/admin"
@@ -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.26.0
+  version: 1.27.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-08 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -170,15 +170,16 @@ 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
 - lib/atlas_rb/middleware/raise_on_stale_resource.rb
 - lib/atlas_rb/person.rb
 - lib/atlas_rb/resource.rb
-- lib/atlas_rb/resource_types.rb
 - lib/atlas_rb/resource_writes.rb
 - lib/atlas_rb/system.rb
 - lib/atlas_rb/system/token.rb

data/lib/atlas_rb/resource_types.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module AtlasRb
-  # Reopens {Resource} with the resource-type vocabulary. This lives in its own
-  # file, required after the eight subclasses, because the map holds the classes
-  # themselves and every one of them subclasses {Resource} — so none of them is
-  # defined yet while `resource.rb` is loading.
-  class Resource
-    # Every type the Atlas resolver can answer with, keyed by each spelling the
-    # DRS stack produces for it: Atlas's wire key (`"file_set"`), the Ruby class
-    # name Solr indexes as `internal_resource` (`"FileSet"`), and the
-    # capitalize-of-the-wire-key form (`"File_set"`) that a caller can still be
-    # holding from a value this gem emitted before {Resource.class_for} existed.
-    # A caller cannot tell which of the three it holds, so all three resolve.
-    #
-    # Stated rather than derived: {Blob}'s `ROUTE` is `/files/`, so nothing in
-    # the routes turns a type into its class either.
-    TYPE_MAP = {
-      "work" => Work, "Work" => Work,
-      "collection" => Collection, "Collection" => Collection,
-      "community" => Community, "Community" => Community,
-      "compilation" => Compilation, "Compilation" => Compilation,
-      "file_set" => FileSet, "FileSet" => FileSet, "File_set" => FileSet,
-      "blob" => Blob, "Blob" => Blob,
-      "delegate" => Delegate, "Delegate" => Delegate,
-      "person" => Person, "Person" => Person
-    }.freeze
-
-    # Resolve a resource-type string to the class that models it.
-    #
-    # Use this on any type that arrives as runtime data — {Resource.find}'s
-    # `"klass"`, a Solr `internal_resource` value, or Atlas's wire key — rather
-    # than reaching into this namespace with `const_get`. The set is closed and
-    # stated in {TYPE_MAP}; it is not a naming rule.
-    #
-    # An unrecognized type raises instead of resolving to `nil` or to whatever
-    # constant happens to bear that name. A caller holding a type this gem does
-    # not define has to hear about it here, where the cause is, rather than at
-    # the `NoMethodError` a few frames later.
-    #
-    # @param name [String, Symbol] a resource type in any of the three
-    #   spellings {TYPE_MAP} accepts.
-    # @return [Class] the AtlasRb class for that type.
-    # @raise [ArgumentError] when the gem defines no class for that type.
-    #
-    # @example Dispatching on a type that arrives as data
-    #   found = AtlasRb::Resource.find("b8gtjvk")
-    #   AtlasRb::Resource.class_for(found["klass"]).find(found["resource"]["id"])
-    #
-    # @example Every spelling of one type
-    #   AtlasRb::Resource.class_for("file_set") # => AtlasRb::FileSet
-    #   AtlasRb::Resource.class_for("FileSet")  # => AtlasRb::FileSet
-    #   AtlasRb::Resource.class_for("File_set") # => AtlasRb::FileSet
-    def self.class_for(name)
-      TYPE_MAP.fetch(name.to_s) do
-        raise ArgumentError, "unknown Atlas resource type: #{name.inspect}"
-      end
-    end
-  end
-end