atlas_rb 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3406190d2c893eccbd1b8d47f20efe85ecb01d404145294352e1db61133406b
-  data.tar.gz: 0a178b48eee743a8e3275dcdf999451b3f811e3af214e163ba675eb4487e5d22
+  metadata.gz: 195a3c85a8653e6835bb472b7cda45847e254057075694e37ecfa779efe2dd39
+  data.tar.gz: ea58c157df06abcfa8d3f4c6b18fd00e5f87892a8b4231b526ac3e60a8e13510
 SHA512:
-  metadata.gz: bde03915384d45748a5c74c7235890e4f64116470f1146775e7480077aac9cf7778d867f526f24dc1470f481837b5b0933794234df3da0254f7eb8aff3ae1539
-  data.tar.gz: 86bb05b0b0d9b3be8ea8a3f219e1c6137548255312e80a7bf7eabbe809a110993a48dca16a4fe2aaf55def9cd8627389c0796a6e6ed218d054bc945b4068439b
+  metadata.gz: 2782eeb3e29454728e68e85144ba5046dd86d9b2ff58eea1cfd704bf2ce03e70f81e977a5b9ad5ffe4091d69d99225746ed2076e875891f358308038983cbfe6
+  data.tar.gz: 8dc180f51b17ffdb1feec818445573ec9c25eab3ee4e4245e9afb31f564a14dfbc93db40e3bd174a078e89f31bd57c240eb85b17f69828494ebaab3c0f23f9f4

data/.version

@@ -1 +1 @@
-1.1.0
+1.1.2

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.1.1
+
+### Added
+
+- **`depositor:` kwarg on `AtlasRb::Work.create`** — optional NUID
+  forwarded as the `depositor` query param on `POST /works`. When
+  omitted, behaviour is unchanged: Atlas defaults the depositor to the
+  acting user. When provided, Atlas stamps the named NUID as the Work's
+  `depositor` and records the acting user as the `proxy_uploader`.
+
+  Motivation: proxy deposit. Librarians and bulk-deposit jobs frequently
+  upload Works on behalf of a researcher who is the rightful credited
+  depositor. Until now there was no way to express that split through
+  the gem — callers had to choose between misattributing the deposit to
+  the librarian or dropping to a raw Faraday call. The depositor is
+  immutable post-create; there is no corresponding setter on the update
+  surface.
+
 ## 1.1.0
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.1.0)
+    atlas_rb (1.1.2)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -23,7 +23,7 @@ GEM
       net-http (~> 0.5)
     hashie (5.1.0)
       logger
-    json (2.19.5)
+    json (2.19.7)
     logger (1.7.0)
     multipart-post (2.4.1)
     net-http (0.9.1)

data/lib/atlas_rb/collection.rb

@@ -173,6 +173,9 @@ module AtlasRb
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
     # @return [AtlasRb::Mash] the parsed JSON response.
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
     #
     # @example
     #   AtlasRb::Collection.set_thumbnails(

data/lib/atlas_rb/community.rb

@@ -179,6 +179,9 @@ module AtlasRb
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
     # @return [AtlasRb::Mash] the parsed JSON response.
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
     #
     # @example
     #   AtlasRb::Community.set_thumbnails(

data/lib/atlas_rb/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Base error for atlas_rb. Subclassed for specific wire-level conditions
+  # that callers want to handle distinctly. Most non-2xx responses still
+  # flow through as Mashes today; we mint typed exceptions only where
+  # callers genuinely need to discriminate (currently: optimistic-lock
+  # conflicts that ActiveJob `retry_on` policies need to key on).
+  class Error < StandardError; end
+
+  # Raised when Atlas responds with HTTP 409 + `error: "stale_resource"`,
+  # indicating an optimistic-lock conflict that either (a) exhausted
+  # Atlas's internal retry budget for a retry-safe action, or (b) hit a
+  # retry-unsafe action and surfaced immediately.
+  #
+  # Callers (typically ActiveJob subclasses in Cerberus) handle this via:
+  #
+  #   retry_on AtlasRb::StaleResourceError, attempts: 5, wait: :polynomially_longer
+  #
+  # The exception carries the resource_id and action from Atlas's envelope
+  # so failure logs are useful without needing the full HTTP response.
+  class StaleResourceError < Error
+    # @return [String, nil] the conflicted resource's ID, from the envelope.
+    attr_reader :resource_id
+
+    # @return [String, nil] the controller action that conflicted, from the
+    #   envelope (e.g. `"update_thumbnails"`).
+    attr_reader :action
+
+    # @param message [String] human-readable conflict description.
+    # @param resource_id [String, nil] the conflicted resource's ID.
+    # @param action [String, nil] the controller action that conflicted.
+    def initialize(message, resource_id: nil, action: nil)
+      super(message)
+      @resource_id = resource_id
+      @action = action
+    end
+  end
+end

data/lib/atlas_rb/faraday_helper.rb

@@ -59,6 +59,7 @@ module AtlasRb
         params: params,
         headers: headers
       ) do |f|
+        f.use AtlasRb::Middleware::RaiseOnStaleResource
         f.response :follow_redirects
         f.adapter Faraday.default_adapter
       end
@@ -103,6 +104,7 @@ module AtlasRb
         url: ENV.fetch("ATLAS_URL", nil),
         headers: headers
       ) do |f|
+        f.use AtlasRb::Middleware::RaiseOnStaleResource
         f.request :multipart
         f.request :url_encoded
       end

data/lib/atlas_rb/middleware/raise_on_stale_resource.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  # Faraday middleware namespace.
+  module Middleware
+    # Translates Atlas's structured optimistic-lock conflict response into a
+    # typed Ruby exception.
+    #
+    # Atlas surfaces an exhausted-retry (or retry-unsafe) optimistic-lock
+    # conflict as an HTTP `409 Conflict` whose JSON body carries the
+    # discriminator `error: "stale_resource"`. This middleware keys on the
+    # **status + discriminator pair** and raises {AtlasRb::StaleResourceError},
+    # carrying the envelope's `resource_id` and `action` through so callers'
+    # failure logs are useful without the full response.
+    #
+    # It is intentionally narrow: any other status, or a 409 without the
+    # discriminator, passes through untouched so the caller still sees the
+    # response as a Mash (see {AtlasRb::StaleResourceError} for the rationale —
+    # atlas_rb stays a thin Faraday binding and translates only the one wire
+    # signal Cerberus jobs need to discriminate on).
+    class RaiseOnStaleResource < Faraday::Middleware
+      # @param env [Faraday::Env] the completed response environment.
+      # @raise [AtlasRb::StaleResourceError] on a 409 whose body carries
+      #   `error: "stale_resource"`.
+      # @return [void]
+      def on_complete(env)
+        return unless env.status == 409
+
+        body = parse_json(env.body)
+        return unless body.is_a?(Hash) && body["error"] == "stale_resource"
+
+        raise AtlasRb::StaleResourceError.new(
+          body["message"] || "Atlas reported a stale-resource conflict",
+          resource_id: body["resource_id"],
+          action: body["action"]
+        )
+      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/work.rb

@@ -93,6 +93,13 @@ 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 depositor [String, nil] optional NUID to stamp on the new Work's
+    #   `depositor` field. When omitted, Atlas defaults the depositor to the
+    #   acting user (`nuid:`); this kwarg is the proxy / batch escape hatch
+    #   where the librarian who uploaded the Work is distinct from the person
+    #   it should be attributed to. The acting user becomes the Work's
+    #   `proxy_uploader`. The depositor is immutable post-create; there is no
+    #   setter on the update surface.
     # @return [Hash] the created Work payload (post-update if `xml_path` was
     #   supplied).
     #
@@ -105,9 +112,15 @@ module AtlasRb
     # @example Retry-safe bulk-deposit create
     #   key = SecureRandom.uuid
     #   AtlasRb::Work.create("col-456", idempotency_key: key)
-    def self.create(id, xml_path = nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+    #
+    # @example Proxy deposit — librarian uploads on behalf of a researcher
+    #   AtlasRb::Work.create("col-456", depositor: "000000123")
+    def self.create(id, xml_path = nil, idempotency_key: nil, nuid: nil,
+                    on_behalf_of: nil, depositor: nil)
+      params = { collection_id: id }
+      params[:depositor] = depositor if depositor
       result = AtlasRb::Mash.new(JSON.parse(
-        connection({ collection_id: id }, nuid,
+        connection(params, nuid,
                    on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)&.body
       ))["work"]
       return result unless xml_path.present?
@@ -157,6 +170,9 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @return [Faraday::Response] the raw response. Status `200` on success.
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
     #
     # @example
     #   AtlasRb::Work.complete("w-789")
@@ -230,6 +246,9 @@ module AtlasRb
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
     # @return [AtlasRb::Mash] the parsed JSON response.
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
     #
     # @example
     #   AtlasRb::Work.set_thumbnails(
@@ -263,6 +282,9 @@ module AtlasRb
     #   `User:` header. Required for cerberus-token requests; legacy bearer
     #   tokens still resolve without it.
     # @return [AtlasRb::Mash] the parsed JSON response.
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
     #
     # @example
     #   AtlasRb::Work.set_image_derivatives(

data/lib/atlas_rb.rb

@@ -4,7 +4,9 @@ require "faraday"
 require "faraday/multipart"
 require "faraday/follow_redirects"
 require_relative "atlas_rb/version"
+require_relative "atlas_rb/errors"
 require_relative "atlas_rb/configuration"
+require_relative "atlas_rb/middleware/raise_on_stale_resource"
 require_relative "atlas_rb/faraday_helper"
 require_relative "atlas_rb/mash"
 require_relative "atlas_rb/authentication"
@@ -69,10 +71,8 @@ require_relative "atlas_rb/system/user"
 #     AtlasRb::Blob.content(blob["id"]) { |chunk| f.write(chunk) }
 #   end
 module AtlasRb
-  # Generic error raised by future code paths; not currently used by any
-  # resource class. Atlas errors today surface as raw `Faraday::Response`
-  # objects or `JSON::ParserError`s on malformed bodies.
-  class Error < StandardError; end
+  # The error hierarchy ({AtlasRb::Error}, {AtlasRb::StaleResourceError}) lives
+  # in `atlas_rb/errors.rb`, required above.
 
   # The gem-wide configuration instance. Lazily initialized — host
   # applications register defaults via {AtlasRb.configure}.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.2
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-26 00:00:00.000000000 Z
+date: 2026-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -125,9 +125,11 @@ files:
 - lib/atlas_rb/community.rb
 - lib/atlas_rb/configuration.rb
 - lib/atlas_rb/delegate.rb
+- lib/atlas_rb/errors.rb
 - lib/atlas_rb/faraday_helper.rb
 - lib/atlas_rb/file_set.rb
 - lib/atlas_rb/mash.rb
+- lib/atlas_rb/middleware/raise_on_stale_resource.rb
 - lib/atlas_rb/resource.rb
 - lib/atlas_rb/system/user.rb
 - lib/atlas_rb/version.rb