atlas_rb 1.10.0 → 1.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 568ae8b7b6c4f459c528c79d358e5969333b0d35201c5b5f8342931bff232d00
-  data.tar.gz: bbfa0f0f70bafc15c5fb402ce3051795250716e3229b8cb3b70e9fec5b62af19
+  metadata.gz: 6d8edc13167cb16fb5482d6a5cd19760bf323f67bf1a23f00a9508f8320bf798
+  data.tar.gz: e86459ce460b8eb30cffcfaaed75b06c750649aa57559e33d5ea277ce0bd2d8c
 SHA512:
-  metadata.gz: 22976962a78e3aa7c53253db913daa0306a27c8d378490443a774acaeac6afb83d6ec7b0da15942ad9c276dd7dd454ce9ccae26880189b61fa94dfbdf8977fc9
-  data.tar.gz: 634edc0528a3872d201b67506030d0ed88d5956da985336ba9cebf7b78cc49a997a5806dc2b51ec2071774b499ac2f4c1f2235f25dfc784a1d04e7cf0c9b9123
+  metadata.gz: 06a66bf273c655ae075c821d158555139094714e3b5d0f3ca15296657afe067267ef781190c4804d5a97d3576237a11d664141f28256702df4151fefde515255
+  data.tar.gz: dfd113525542142a75e0789a5e9ed34424485e1ac69359f5e4c505e24d3752e9eda54e756804f13f195588f6079d0c828426e0a5b937d8ad53c2ef8708eaff00

data/.version

@@ -1 +1 @@
-1.10.0
+1.10.1

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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`

data/Gemfile.lock

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

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/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.10.0
+  version: 1.10.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday