atlas_rb 1.16.0 → 1.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed32d60a2b3c2a562ee64d095a266c6b45848122ce4d75a0201c6736aeb52c2f
-  data.tar.gz: 229e5722c7b2036e490df5c06a5ad7afe496164fe7105a2ee232b7cb64f5d970
+  metadata.gz: 3a418fc64c12474c618d8bcffbaf01f116f0bb7c80c999f4c3bd4514cf47c879
+  data.tar.gz: ebfa9f0d7e85b884f6f96a16dd59861d01a0d03bbf6a25c94a0e92665add8d2d
 SHA512:
-  metadata.gz: e63d081a6b2f67297e95e2feb361ed232e585b3c22a84b68c0d35dd0a816aae1cfca0106613ddc9f097644bd8b02a098285ce48f7ee930126102037c2dff808c
-  data.tar.gz: 70931eed6c2ceaf7fd901a07005df4dec7570a5f90649b0bfb277826f927922bfb3ad30f73a226254d8059fb1c82f4e114e11a4a7977ddd1ff7d7e291e846d8f
+  metadata.gz: 1e2541b872b918215dd73155ae55fc8d841a7da7fce77f6b984dc82187148dce0a4698ee2b8aaa561b659d1fd253f2077f614cb8d592edaa54a10a343ea8664a
+  data.tar.gz: c0bb9652d3a1cfe08485d6057f23db0e7c493fefe4bfd23be7796e825e1a0bc998b4b02e625c2475e87b247ffc49ffb229469c35adb3b770010bda4cb42c1220

data/.version

@@ -1 +1 @@
-1.16.0
+1.17.0

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 1.17.0
+
+### Fixed — `Resource.find` emitted a type string this namespace cannot resolve
+
+`find` derived its `"klass"` with `String#capitalize` over Atlas's JSON key,
+and `capitalize` is not the inverse of a Ruby class name once the type has two
+words. Atlas answers `{"file_set": {...}}`, and `"file_set".capitalize` is
+`"File_set"`. There is no `AtlasRb::File_set`.
+
+The doc comment stated the convention as a promise — *"the resource type,
+capitalized (e.g. `"Work"`)"* — and `"Work"` is the one shape where
+capitalizing happens to work. Every other consumer read that as "`const_get`
+this", so a FileSet NOID put a `NameError` in the caller's stack:
+
+```
+uninitialized constant AtlasRb::File_set
+```
+
+`find` now reports the class's own name, so a FileSet is `"FileSet"`.
+
+**This changes one value on the wire**: `"File_set"` becomes `"FileSet"`. That
+is the spelling Solr already carries as `internal_resource`, so a consumer fed
+by both sources now sees one vocabulary instead of two.
+
+### Added — `Resource.class_for`, the supported type-string → class lookup
+
+```ruby
+AtlasRb::Resource.class_for("file_set") # => AtlasRb::FileSet
+AtlasRb::Resource.class_for("FileSet")  # => AtlasRb::FileSet
+AtlasRb::Resource.class_for("File_set") # => AtlasRb::FileSet
+```
+
+Closing the loop on `find` used to mean reaching into this namespace by string
+on a naming convention the gem never promised. `class_for` reads a stated,
+closed set — `Resource::TYPE_MAP`, covering the eight `Resource` subclasses —
+and accepts all three spellings the DRS stack produces for a type: Atlas's
+wire key, Solr's `internal_resource`, and the pre-1.17.0 `"klass"` a caller
+can still be holding.
+
+The set is stated rather than derived because there is no rule to derive:
+`Blob`'s `ROUTE` is `/files/`.
+
+An unrecognized type raises `ArgumentError` — never `nil`, and never
+`const_get`, which would resolve an arbitrary constant in this namespace. Same
+argument `Middleware::RaiseOnReadError` settled for the read path: keep the
+failure where the cause is.
+
+### Documented — what the generic resolver actually covers
+
+Atlas answers `/resources/:id` for its Valkyrie-backed types only: `Work`,
+`Collection`, `Community`, `FileSet`, `Blob`, `Delegate` and `Person`. A
+`Compilation` is an ActiveRecord row in Atlas rather than a Valkyrie resource,
+so the resolver never finds one, though `Compilation.find` does. `nil` from
+`Resource.find` is therefore ambiguous: it means "no such id" **or** "that id
+names a Compilation". `Resource.find`'s YARD and the README both say so now.
+
 ## 1.16.0
 
 ### Fixed — every read binding consults the HTTP status before it reads the body

data/Gemfile.lock

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

data/README.md

@@ -531,6 +531,42 @@ The two mutations raise the same way `reparent` does — `LinkedMemberError`
 on a structural `422` (carrying the envelope's `error` code as `#code`) and
 `ForbiddenError` on a `403` — instead of swallowing the envelope.
 
+### Resolving one id of unknown type (`Resource.find` and `Resource.class_for`)
+
+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.
+
+**What the resolver covers.** Atlas answers `/resources/:id` for its
+Valkyrie-backed types only: `Work`, `Collection`, `Community`, `FileSet`,
+`Blob`, `Delegate` and `Person`. A `Compilation` is an ActiveRecord row in
+Atlas rather than a Valkyrie resource, so the generic resolver never finds
+one — use `AtlasRb::Compilation.find` for those. That makes `nil` ambiguous
+here: it means "no such id" **or** "that id names a Compilation".
+
 ### Batch resolve (`Resource.find_many`)
 
 When you have a *set* of NOIDs and only need each one's title / klass /

data/lib/atlas_rb/collection.rb

@@ -220,6 +220,9 @@ 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.
+    # @param origin [String, nil] free-text tag naming the surface that made this
+    #   edit (e.g. `"metadata_form"`, `"xml_editor"`). Atlas records it verbatim
+    #   on the audit event; omit it and the event carries no origin.
     # @return [Hash] the parsed JSON response from the patch.
     # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
     #   resource, so the write did not happen.
@@ -228,12 +231,13 @@ module AtlasRb
     #
     # @example
     #   AtlasRb::Collection.update("col-456", "/tmp/collection-mods.xml")
-    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil)
-      payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
-                                                           "application/xml",
-                                                           File.basename(xml_path)) }
+    #
+    # @example Recording which editing surface made the change
+    #   AtlasRb::Collection.update("col-456", "/tmp/collection-mods.xml", origin: "xml_editor")
+    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
       AtlasRb::Mash.new(write_resource(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)
+        multipart(nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id, mods_upload_payload(xml_path, origin))
       ))
     end
 

data/lib/atlas_rb/community.rb

@@ -199,6 +199,9 @@ 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.
+    # @param origin [String, nil] free-text tag naming the surface that made this
+    #   edit (e.g. `"metadata_form"`, `"xml_editor"`). Atlas records it verbatim
+    #   on the audit event; omit it and the event carries no origin.
     # @return [Hash] the parsed JSON response from the patch.
     # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
     #   resource, so the write did not happen.
@@ -207,12 +210,13 @@ module AtlasRb
     #
     # @example
     #   AtlasRb::Community.update("c-123", "/tmp/community-mods.xml")
-    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil)
-      payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
-                                                           "application/xml",
-                                                           File.basename(xml_path)) }
+    #
+    # @example Recording which editing surface made the change
+    #   AtlasRb::Community.update("c-123", "/tmp/community-mods.xml", origin: "xml_editor")
+    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
       AtlasRb::Mash.new(write_resource(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)
+        multipart(nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id, mods_upload_payload(xml_path, origin))
       ))
     end
 

data/lib/atlas_rb/resource.rb

@@ -25,6 +25,15 @@ module AtlasRb
     # method splits that into a normalized `{ "klass" => ..., "resource" => ... }`
     # pair so callers can dispatch on type.
     #
+    # ## What the resolver covers
+    #
+    # Atlas answers `/resources/:id` for its Valkyrie-backed types only:
+    # {Work}, {Collection}, {Community}, {FileSet}, {Blob}, {Delegate} and
+    # {Person}. A {Compilation} is an ActiveRecord row in Atlas rather than a
+    # Valkyrie resource, so the resolver never finds one — use
+    # {Compilation.find} for those. That makes `nil` ambiguous: it means "no
+    # such id" **or** "that id names a Compilation".
+    #
     # @param id [String] an Atlas resource ID of any type.
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
     #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
@@ -34,10 +43,14 @@ module AtlasRb
     #   omitted.
     # @return [Hash{String => String, Hash}, nil] hash with two keys, or `nil`
     #   when the id resolves to nothing (`404`):
-    #   - `"klass"` — the resource type, capitalized (e.g. `"Work"`).
+    #   - `"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.
     #   - `"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}.
     #
     # @example Polymorphic lookup
     #   AtlasRb::Resource.find("abc123")
@@ -46,7 +59,10 @@ module AtlasRb
       result = fetch_resource('/resources/' + id, nuid: nuid, on_behalf_of: on_behalf_of)
       return nil if result.nil?
 
-      AtlasRb::Mash.new("klass" => result.first[0].capitalize,
+      # 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,
                         "resource" => result.first[1])
     end
 
@@ -431,5 +447,29 @@ module AtlasRb
       JSON.parse(resp.body)
     end
     private_class_method :write_resource
+
+    # The multipart body behind {Work.update} / {Collection.update} /
+    # {Community.update}: the MODS document, plus the optional `origin` tag
+    # naming the surface that produced the edit.
+    #
+    # Atlas records `origin` verbatim on the audit event and never branches on
+    # it, so a host names its own surfaces (Cerberus sends `metadata_form`,
+    # `advanced_form`, `xml_editor`). A `nil` origin is left out of the body
+    # entirely rather than sent empty, so the audit event of a host that does
+    # not set one looks exactly like every event recorded before the field
+    # existed.
+    #
+    # @param xml_path [String] path to a MODS XML file on disk.
+    # @param origin [String, nil] the edit-origin tag, or `nil` to send none.
+    # @return [Hash] the multipart payload.
+    # @api private
+    def self.mods_upload_payload(xml_path, origin)
+      payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
+                                                           "application/xml",
+                                                           File.basename(xml_path)) }
+      payload[:origin] = origin.to_s unless origin.nil? || origin.to_s.empty?
+      payload
+    end
+    private_class_method :mods_upload_payload
   end
 end

data/lib/atlas_rb/resource_types.rb

@@ -0,0 +1,60 @@
+# 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

data/lib/atlas_rb/work.rb

@@ -358,6 +358,9 @@ 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.
+    # @param origin [String, nil] free-text tag naming the surface that made this
+    #   edit (e.g. `"metadata_form"`, `"xml_editor"`). Atlas records it verbatim
+    #   on the audit event; omit it and the event carries no origin.
     # @return [Hash] the parsed JSON response from the patch.
     # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
     #   resource, so the write did not happen.
@@ -366,12 +369,13 @@ module AtlasRb
     #
     # @example
     #   AtlasRb::Work.update("w-789", "/tmp/work-mods.xml")
-    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil)
-      payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
-                                                           "application/xml",
-                                                           File.basename(xml_path)) }
+    #
+    # @example Recording which editing surface made the change
+    #   AtlasRb::Work.update("w-789", "/tmp/work-mods.xml", origin: "xml_editor")
+    def self.update(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
       AtlasRb::Mash.new(write_resource(
-        multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)
+        multipart(nuid, on_behalf_of: on_behalf_of)
+          .patch(ROUTE + id, mods_upload_payload(xml_path, origin))
       ))
     end
 

data/lib/atlas_rb.rb

@@ -33,6 +33,8 @@ 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"
 require_relative "atlas_rb/user"
 require_relative "atlas_rb/admin"
 require_relative "atlas_rb/admin/work"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.16.0
+  version: 1.17.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -180,6 +180,7 @@ files:
 - 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/system.rb
 - lib/atlas_rb/system/token.rb
 - lib/atlas_rb/system/user.rb