atlas_rb 1.9.4 → 1.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 808bf4695fcba808f36a2c808885529bdff8b8dae50ddfed71cd605115aa9014
-  data.tar.gz: 532e5bac353cceeff1806829f4e8d8f2421051799b3a249bf3119c4001c144fc
+  metadata.gz: 6d8edc13167cb16fb5482d6a5cd19760bf323f67bf1a23f00a9508f8320bf798
+  data.tar.gz: e86459ce460b8eb30cffcfaaed75b06c750649aa57559e33d5ea277ce0bd2d8c
 SHA512:
-  metadata.gz: 177bfa1e9c486473285eba7fac243719f08af97ad58999fdb08c9d08725981ba8dce66143943768ff12a8e08d994ca34eb02a791cd567b7f98294732fd461a2a
-  data.tar.gz: 0eba14aa8d5ac54b4153fd48810c90fb979ac608cc3bf2b0fb68bdb039ed9b4db763d6610839a0656374f684fc9821bde4d3f7ae336f58ac9f894aa4aee2ad81
+  metadata.gz: 06a66bf273c655ae075c821d158555139094714e3b5d0f3ca15296657afe067267ef781190c4804d5a97d3576237a11d664141f28256702df4151fefde515255
+  data.tar.gz: dfd113525542142a75e0789a5e9ed34424485e1ac69359f5e4c505e24d3752e9eda54e756804f13f195588f6079d0c828426e0a5b937d8ad53c2ef8708eaff00

data/.version

@@ -1 +1 @@
-1.9.4
+1.10.1

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 1.10.1
+
+### Added — `Work.mark_incomplete` / `Work.clear_incomplete`
+
+A Work can now carry a second lifecycle state. `complete` says the deposit
+finished; `incomplete` says something downstream of it gave up. Before this
+there was no way to record that at all: every give-up handler wrote a
+`Rails.logger.warn` and nothing else, so a deposit whose PDF rendition
+exhausted its retries ended up with no rendition and no thumbnail, the
+depositor was not told, and no surface listed it.
+
+```ruby
+AtlasRb::Work.mark_incomplete(work_id, reason: "pdf_rendition_gave_up")
+AtlasRb::Work.clear_incomplete(work_id)
+```
+
+`reason` is a machine token, one per give-up handler. Atlas holds it as an
+opaque string and does **not** validate it against a list, so the vocabulary
+belongs to the caller and a new token needs no Atlas release. Map it to display
+text at the point of use, with a fallback for a token the view has not been
+taught.
+
+The flag **never hides** the Work. A record with its file, title and metadata
+but one missing derivative is degraded, not broken, and stays readable.
+
+Both bindings return the updated Work. `mark_incomplete` is idempotent and the
+last reason wins; `clear_incomplete` is idempotent too, and clears the flag and
+the reason together. Call it when a later run of the same job succeeds, which
+makes the state self-healing.
+
+### Added — `incomplete:` filter on `Work.list`
+
+`AtlasRb::Work.list(incomplete: true)` is the staff list of Works whose
+pipeline gave up, the sibling of the existing `in_progress:` "what's stuck?"
+view. The two are independent and combine: `in_progress: false, incomplete:
+true` reads as "finished, but degraded".
+
+Work summaries in the response now carry `incomplete` and `incomplete_reason`
+alongside `in_progress`.
+
+## 1.10.0
+
+### Removed — `title` on `Person.create` and `Person.update`
+
+Atlas no longer holds a job title on a Person. The attribute claimed
+Blacklight's title namespace, where display and sorting expect the Person's
+name, so Atlas dropped it rather than renamed it: the field was display-only,
+optional, and absent from v1.
+
+The parameter therefore had nothing to write to. Atlas ignores an unknown key in
+a write body, so a caller that kept passing `title:` had its value discarded
+with no error and nothing in a log. That is the reason to remove the parameter
+rather than leave it accepted and inert.
+
+**Breaking.** `Person.create(…, title: "Professor")` now raises
+`ArgumentError: unknown keyword: :title`. Drop the argument at the call site;
+there is no replacement field.
+
 ## 1.9.4
 
 ### Fixed — write bindings parsed the response body without checking the status

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.9.4)
+    atlas_rb (1.10.1)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -25,7 +25,7 @@ GEM
       net-http (~> 0.5)
     hashie (5.1.0)
       logger
-    json (2.21.1)
+    json (2.21.2)
     jwt (2.10.3)
       base64
     logger (1.7.0)

data/README.md

@@ -255,6 +255,28 @@ AtlasRb::Work.list(in_progress: false, page: 2)   # completed deposits, page 2
 AtlasRb::Work.complete("w-789")                   # mark w-789 done
 ```
 
+A Work carries a second, independent lifecycle state for the other kind of
+failure. `complete` says the deposit finished; `incomplete` says something
+downstream of it gave up — a rendition, the derivatives, the full-text
+extraction — after that job exhausted its retries. Call `mark_incomplete`
+from the give-up handler, and `clear_incomplete` when a later run succeeds,
+which makes the state self-healing.
+
+```ruby
+AtlasRb::Work.mark_incomplete("w-789", reason: "pdf_rendition_gave_up")
+AtlasRb::Work.clear_incomplete("w-789")
+AtlasRb::Work.list(incomplete: true)                       # the staff repair list
+AtlasRb::Work.list(in_progress: false, incomplete: true)   # finished, but degraded
+```
+
+`reason` is a machine token, one per give-up handler. Atlas stores it as an
+opaque string and does not validate it against a list, so the vocabulary is
+yours and a new token needs no Atlas release. Map it to display text at the
+point of use, with a fallback for a token the view has not been taught.
+
+The flag never hides the Work. A record with its file, title and metadata but
+one missing derivative is degraded, not broken, and stays readable.
+
 ### Audit-event history
 
 `Resource.history` wraps Atlas's `GET /resources/<id>/history` endpoint

data/lib/atlas_rb/person.rb

@@ -85,7 +85,6 @@ module AtlasRb
     # @param display_name [String] authoritative display name.
     # @param bio [String, nil]
     # @param orcid [String, nil]
-    # @param title [String, nil]
     # @param on_behalf_of [String, nil] acting-as target (the acting principal
     #   itself comes from the ambient AtlasRb.config.default_nuid).
     # @return [AtlasRb::Mash] the unwrapped `"person"` object.
@@ -93,8 +92,8 @@ module AtlasRb
     #   resource, so the write did not happen.
     # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
     #   and body.
-    def self.create(nuid:, display_name:, bio: nil, orcid: nil, title: nil, on_behalf_of: nil)
-      body = { nuid: nuid, display_name: display_name, bio: bio, orcid: orcid, title: title }.compact
+    def self.create(nuid:, display_name:, bio: nil, orcid: nil, on_behalf_of: nil)
+      body = { nuid: nuid, display_name: display_name, bio: bio, orcid: orcid }.compact
       AtlasRb::Mash.new(write_resource(
         connection({}, nil, on_behalf_of: on_behalf_of).post(ROUTE, JSON.dump(body))
       ))["person"]
@@ -107,7 +106,6 @@ module AtlasRb
     # @param display_name [String, nil]
     # @param bio [String, nil]
     # @param orcid [String, nil]
-    # @param title [String, nil]
     # @param nuid [String, nil] acting principal.
     # @param on_behalf_of [String, nil] acting-as target.
     # @return [AtlasRb::Mash] the unwrapped, updated `"person"` object.
@@ -115,8 +113,8 @@ module AtlasRb
     #   resource, so the write did not happen.
     # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
     #   and body.
-    def self.update(id, display_name: nil, bio: nil, orcid: nil, title: nil, nuid: nil, on_behalf_of: nil)
-      body = { display_name: display_name, bio: bio, orcid: orcid, title: title }.compact
+    def self.update(id, display_name: nil, bio: nil, orcid: nil, nuid: nil, on_behalf_of: nil)
+      body = { display_name: display_name, bio: bio, orcid: orcid }.compact
       AtlasRb::Mash.new(write_resource(
         connection({}, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, JSON.dump(body))
       ))["person"]

data/lib/atlas_rb/work.rb

@@ -43,6 +43,11 @@ module AtlasRb
     #
     # @param in_progress [Boolean, nil] when set, filter to Works whose
     #   `in_progress` flag matches. Omit (or pass `nil`) for "all works".
+    # @param incomplete [Boolean, nil] when set, filter to Works whose
+    #   `incomplete` flag matches — the staff list of Works whose enrichment
+    #   pipeline gave up (see {.mark_incomplete}). Independent of
+    #   `in_progress:`, and the two combine: `in_progress: false,
+    #   incomplete: true` reads as "finished, but degraded".
     # @param page [Integer, nil] 1-indexed page number.
     # @param per_page [Integer, nil] page size override.
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
@@ -53,16 +58,20 @@ module AtlasRb
     #   omitted.
     # @return [AtlasRb::Mash] `{ "works" => [...], "pagination" => {...} }`.
     #   Each entry in `"works"` is a Work summary (`id`, `title`,
-    #   `description`, `in_progress`).
+    #   `description`, `in_progress`, `incomplete`, `incomplete_reason`).
     #
     # @example Find stuck deposits
     #   AtlasRb::Work.list(in_progress: true)
     #
+    # @example Find works whose pipeline gave up
+    #   AtlasRb::Work.list(incomplete: true)
+    #
     # @example Page through all works
     #   AtlasRb::Work.list(page: 2, per_page: 50)
-    def self.list(in_progress: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
+    def self.list(in_progress: nil, incomplete: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
       params = {}
       params[:in_progress] = in_progress unless in_progress.nil?
+      params[:incomplete]  = incomplete  unless incomplete.nil?
       params[:page]        = page        if page
       params[:per_page]    = per_page    if per_page
       AtlasRb::Mash.new(JSON.parse(
@@ -232,6 +241,88 @@ module AtlasRb
       connection({}, nuid, on_behalf_of: on_behalf_of).post(ROUTE + id + '/complete')
     end
 
+    # Flag a Work whose enrichment pipeline gave up.
+    #
+    # The counterpart to {.complete}, for the other half of the lifecycle:
+    # `complete` says the deposit finished, this says something downstream of
+    # it did not. Call it from a work-scoped job's give-up handler — the PDF or
+    # media rendition, the derivatives, the full-text extraction — once that
+    # job has exhausted its retries. Atlas's `GET /works?incomplete=true` then
+    # lists the Work for staff, and `incomplete_bsi` on its Solr document lets
+    # a result row render a pill without a per-row fetch.
+    #
+    # The flag **never hides** the Work. A record with its file, title and
+    # metadata but one missing derivative is degraded, not broken, and stays
+    # readable — enrichment does not fail a deposit.
+    #
+    # Idempotent on the server; the last reason wins. Clear it with
+    # {.clear_incomplete} when a later run of the same job succeeds, which
+    # makes the state self-healing.
+    #
+    # @param id [String] the Work ID.
+    # @param reason [String, nil] a machine token naming the cause — one per
+    #   give-up handler, e.g. `"pdf_rendition_gave_up"`,
+    #   `"media_rendition_gave_up"`, `"ingest_gave_up"`. Atlas stores it as an
+    #   opaque string and does **not** validate it against a list, so the
+    #   vocabulary is the caller's and a new token needs no Atlas release. Map
+    #   it to display text at the point of use, with a fallback for a token the
+    #   view has not been taught. A blank reason still sets the flag.
+    # @param nuid [String, nil] optional NUID of the acting user.
+    # @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.
+    # @return [Hash] the updated Work, the same shape {.find} returns, carrying
+    #   `incomplete` and `incomplete_reason`.
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
+    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
+    #   resource, so the write did not happen.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
+    #   and body.
+    #
+    # @example In a give-up handler
+    #   AtlasRb::Work.mark_incomplete(work_id, reason: "pdf_rendition_gave_up")
+    def self.mark_incomplete(id, reason:, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(write_resource(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + id + '/incomplete', JSON.dump(reason: reason))
+      ))["work"]
+    end
+
+    # Clear the incomplete flag and its reason.
+    #
+    # The repair half of {.mark_incomplete}: call it from the same job when a
+    # later run succeeds, or by hand once an operator has fixed the Work. Both
+    # fields clear together — a reason without a flag would leave a stale cause
+    # on the Solr document.
+    #
+    # Idempotent: clearing a Work that was never flagged is a no-op.
+    #
+    # @param id [String] the Work ID.
+    # @param nuid [String, nil] optional NUID of the acting user.
+    # @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.
+    # @return [Hash] the updated Work, the same shape {.find} returns, with
+    #   `incomplete` false and `incomplete_reason` null.
+    # @raise [AtlasRb::StaleResourceError] if Atlas reports an optimistic-lock
+    #   conflict that exhausted its internal retry budget (HTTP 409 with
+    #   `error: "stale_resource"`).
+    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no such
+    #   resource, so the write did not happen.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's status
+    #   and body.
+    #
+    # @example On a later successful run
+    #   AtlasRb::Work.clear_incomplete(work_id)
+    def self.clear_incomplete(id, nuid: nil, on_behalf_of: nil)
+      AtlasRb::Mash.new(write_resource(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + id + '/incomplete')
+      ))["work"]
+    end
+
     # Replace a Work's metadata by uploading a MODS XML document.
     #
     # @param id [String] the Work ID.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.9.4
+  version: 1.10.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-03 00:00:00.000000000 Z
+date: 2026-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday