atlas_rb 1.21.0 → 1.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0650d39388fca9d7fbdc0134ee4e76e4a82ed3c659f8c44ea96aac62a397d0c1
-  data.tar.gz: ab674da7f6274991b11921b60c43a93ea6e3e9f3a5ef121109fd3bc99c970cdc
+  metadata.gz: 8df0d572649e0456aa2a8e77b436114aa3a91a2fbfe0e6c05ce2a8426dd7c6ff
+  data.tar.gz: e368597905337f62111f4e649eb88a75f5e06c85202ff3dcf5cc3e99d283d948
 SHA512:
-  metadata.gz: 2c23136adc3f95ccf1b9e0e739f95a2a86b3ee33a1cf5a52f72af625fe5c2ab77cf63c9c78990d2b36ff0d285445f56bae620da21d86af0994d590f867defe51
-  data.tar.gz: edac22a77b8d592ae2e3a0d77117b9ac60d7516d3a13469747ff5cb7f90a782e774d5514218bb5d368818defc538d58158ed608abd400d2cca4aaa606bff9939
+  metadata.gz: 005ae8ac014dab468bbfb9c5da901c926ba2c746d78c3bedadda431e310d3d21b99f547b91f8e33563784ba45a782cefa4155c7fcfc35a09c11c8e9f43d9fe5b
+  data.tar.gz: 2d35888d562851ec0ad7cd9419faceee619568723f98c1a34e172ac01f33c56e2ae8491eedae2d851067969acfdd02bf6439364d3b2517448cfadb0a13436fa9

data/.version

@@ -1 +1 @@
-1.21.0
+1.23.0

data/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 1.23.0
+
+These bindings need Atlas 0.6.212 or later.
+
+### Added — `Work.withdrawn_assets`, the listing a Restore needs
+
+```ruby
+AtlasRb::Work.withdrawn_assets(work_id, nuid: admin_nuid).each do |asset|
+  AtlasRb::Admin::Resource.restore(asset.file_set, nuid: admin_nuid)
+end
+```
+
+A FileSet withdrawn with `Resource.tombstone` drops out of `Work.assets` and
+`Work.file_sets`, so nothing listed it. This read lists the assets of a Work's
+withdrawn FileSets, in the `Work.assets` shape plus the FileSet's
+`tombstoned_at` and `tombstoned_by`. Atlas allows it for the admin and
+devolved-admin tiers; anyone else gets a `403`, which raises `ResourceError`. A
+missing Work returns `nil`.
+
+### Documented — `file_set` on every `Work.assets` and `Work.file_sets` entry
+
+Each asset entry carries the NOID of the FileSet it is listed under. That is
+the id `Resource.tombstone` and `Admin::Resource.restore` take, so a caller no
+longer needs `Blob.ancestry` to find it. No reader change.
+
+## 1.22.0
+
+These bindings need Atlas 0.6.211 or later.
+
+### Added — `Blob.update(original_filename:)`, renaming the file on a replace
+
+```ruby
+AtlasRb::Blob.update(blob_id, "/tmp/upload.tmp", original_filename: "report.pdf")
+```
+
+A replacement of a different type used to keep the old name, so a `.docx`
+replaced by a `.pdf` downloaded as `.docx`. Atlas now records the name for the
+new revision and re-derives the MIME type from it. For the original file it also
+re-derives the label and the FileSet's classification. Omit the keyword to keep
+the current name. `Blob.rollback` needs no change: Atlas restores the revision's
+own name.
+
+### Added — `language:` and `track_label:` on `Blob.create` and `Blob.update`
+
+```ruby
+AtlasRb::Blob.create(work_id, "/tmp/es.vtt", "es.vtt", language: "es", track_label: "Español")
+```
+
+A caption's BCP 47 language and the name a player shows for it. Each is sent
+only when given, so an update keeps a value it does not mention, and `""`
+clears one. Atlas refuses a malformed value with a `422`, which raises
+`ResourceError`. `Work.assets` and `Work.file_sets` return both fields on Blob
+entries with no reader change.
+
+### Documented — tombstoning a FileSet, and the `original` image tier
+
+- `Resource.tombstone` and `Admin::Resource.restore` accept a FileSet id. That
+  withdraws a caption or other attached file reversibly. Atlas allows it for the
+  admin and devolved-admin tiers only. Despite its namespace,
+  `Admin::Resource.restore` is called by delegates too.
+- `Work.set_derivative_permissions` documents the image floor as `original`, not
+  `master`. Atlas accepts `master` on write for one release and stores it as
+  `original`.
+
 ## 1.21.0
 
 ### Added — `System::Work.remove_linked_member`, unlinking a showcase Work

data/Gemfile.lock

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

data/lib/atlas_rb/admin/resource.rb

@@ -53,6 +53,13 @@ module AtlasRb
       # stub. No `confirm:` marker — restoring is itself reversible, by
       # tombstoning again.
       #
+      # Accepts a FileSet id too (Atlas 0.6.211 or later), which puts a withdrawn
+      # caption or other attached file back in {Work.assets}.
+      #
+      # The devolved-admin tier calls this as well, although the namespace reads
+      # as admin-only. Atlas owns the gate; this namespace only marks the call as
+      # an operator action.
+      #
       # @param id [String] the resource's NOID.
       # @param nuid [String, nil] optional acting user's NUID.
       # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`

data/lib/atlas_rb/blob.rb

@@ -144,6 +144,12 @@ module AtlasRb
     # @param blob_path [String] path to the binary file on disk to upload.
     # @param original_filename [String] the user-facing filename Atlas
     #   should record (e.g. `"final_thesis.pdf"`).
+    # @param language [String, nil] optional BCP 47 language of a caption or
+    #   other text track (e.g. `"en"`, `"es-MX"`). Atlas checks the shape of the
+    #   tag, not the registry, and refuses a malformed one with `422`
+    #   `invalid_language` before storing anything. Needs Atlas 0.6.211 or later.
+    # @param track_label [String, nil] optional name a player shows for the track
+    #   (e.g. `"Español"`), at most 64 characters (`422 invalid_track_label`).
     # @param idempotency_key [String, nil] optional UUID. A repeat call with
     #   the same key returns the originally-created Blob instead of creating
     #   a new one. See {AtlasRb::Work.create} for full semantics.
@@ -178,11 +184,15 @@ module AtlasRb
     #   key = SecureRandom.uuid
     #   AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "thesis.pdf",
     #                        idempotency_key: key, expected_digest: "sha256:#{sha}")
-    def self.create(id, blob_path, original_filename, expected_digest: nil,
+    #
+    # @example A Spanish caption track
+    #   AtlasRb::Blob.create("w-789", "/tmp/es.vtt", "es.vtt", language: "es", track_label: "Español")
+    def self.create(id, blob_path, original_filename, expected_digest: nil, language: nil, track_label: nil,
                     idempotency_key: nil, nuid: nil, on_behalf_of: nil)
       with_file_part(blob_path) do |part|
+        # compact drops only nil, so an empty string still reaches Atlas.
         payload = { work_id: id, original_filename: original_filename, binary: part }
-        payload[:expected_digest] = expected_digest if expected_digest
+                  .merge({ expected_digest: expected_digest, language: language, track_label: track_label }.compact)
 
         AtlasRb::Mash.new(write_resource(
           multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
@@ -215,12 +225,22 @@ module AtlasRb
 
     # Replace the bytes of an existing Blob in-place.
     #
-    # The Blob ID is preserved; only the underlying content changes. The
-    # original filename is *not* updated by this call — use a new
-    # {.create} if you need a different `original_filename`.
+    # The Blob ID is preserved and a new revision is appended. Pass
+    # `original_filename` when the replacement is a different file, above all a
+    # different type: Atlas records the name for this revision, and re-derives
+    # the MIME type from it. For the original file it also re-derives the label
+    # and the FileSet's classification; a derivative keeps its tier label.
+    # {.rollback} restores a revision's own name, so it needs no name.
     #
     # @param id [String] the Blob ID.
     # @param blob_path [String] path to the replacement binary on disk.
+    # @param original_filename [String, nil] the replacement's own filename.
+    #   Omit it to keep the current name. Needs Atlas 0.6.211 or later; an older
+    #   Atlas ignores it and keeps the name.
+    # @param language [String, nil] a new BCP 47 language for the track. Omit it
+    #   to keep the current one; pass `""` to clear it. See {.create}.
+    # @param track_label [String, nil] a new display name for the track. Omit it
+    #   to keep the current one; pass `""` to clear it.
     # @param expected_digest [String, nil] optional verify-on-ingest checksum,
     #   `"<algorithm>:<hexvalue>"`. 422 ({AtlasRb::FixityMismatchError}) on mismatch.
     # @param idempotency_key [String, nil] optional UUID. A double-submit of the
@@ -249,10 +269,15 @@ module AtlasRb
     #
     # @example Retry-safe replace
     #   AtlasRb::Blob.update("b-321", "/tmp/revised.pdf", idempotency_key: SecureRandom.uuid)
-    def self.update(id, blob_path, expected_digest: nil, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
+    #
+    # @example Replace a Word file with a PDF
+    #   AtlasRb::Blob.update("b-321", "/tmp/upload.tmp", original_filename: "report.pdf")
+    def self.update(id, blob_path, original_filename: nil, expected_digest: nil, language: nil, track_label: nil,
+                    idempotency_key: nil, nuid: nil, on_behalf_of: nil)
       with_file_part(blob_path) do |part|
-        payload = { binary: part }
-        payload[:expected_digest] = expected_digest if expected_digest
+        # compact drops only nil, so `""` still reaches Atlas and clears a field.
+        payload = { binary: part, original_filename: original_filename, expected_digest: expected_digest,
+                    language: language, track_label: track_label }.compact
 
         AtlasRb::Mash.new(write_resource(
           multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
@@ -268,7 +293,8 @@ module AtlasRb
     # envelope: one descriptor per retained content revision, each carrying its
     # OCFL `version_id` label, the `file_identifier` appended for that revision,
     # the `created` timestamp, the `digest`/`size` recorded at that version,
-    # the stable `original_filename`, and actor attribution (`actor_nuid` /
+    # that revision's own `original_filename` (a replace can rename the file),
+    # and actor attribution (`actor_nuid` /
     # `on_behalf_of_nuid`, null when no audit event correlates).
     #
     # Server admin-gates this endpoint (it exposes edit attribution), so

data/lib/atlas_rb/resource_writes.rb

@@ -138,6 +138,12 @@ module AtlasRb
     # `has_live_children` — a legitimate answer the caller has to read, not an
     # error. Reversible via {.restore}.
     #
+    # Accepts a FileSet id as well as a Community, Collection or Work (Atlas
+    # 0.6.211 or later). That withdraws an attached file, such as a caption,
+    # reversibly: its Blobs ride along and it drops out of {Work.assets} and
+    # {Work.file_sets}. Atlas refuses a FileSet from anyone outside the admin and
+    # devolved-admin tiers with `403`, even a user who can edit the Work.
+    #
     # @param id [String] the resource's NOID.
     # @param nuid [String, nil] the acting user's NUID, stamped on the resource
     #   as `tombstoned_by`.

data/lib/atlas_rb/work.rb

@@ -328,7 +328,7 @@ module AtlasRb
     # Grouper group names, `[]` = private). Two media families:
     #
     # * the image ladder `small` / `medium` / `large` / `service` (deep-zoom) /
-    #   `master` (the original image), and
+    #   `original` (the deposited image), and
     # * independent media `audio` / `video` / `pdf`.
     #
     # Unlike {.set_image_derivatives} (which upserts URIs) this is a whole-object
@@ -340,18 +340,20 @@ module AtlasRb
     #
     # Atlas enforces: a tier may not be more visible than the Work, and — within
     # the image ladder — visibility must narrow as resolution grows
-    # (`master` ⊆ `service` ⊆ `large` ⊆ `medium` ⊆ `small`; independent media
+    # (`original` ⊆ `service` ⊆ `large` ⊆ `medium` ⊆ `small`; independent media
     # impose no ordering). The gate is advisory — it surfaces on {.assets} as
-    # `gated` / `permission` for BOTH Delegate (image tier) and Blob (master /
+    # `gated` / `permission` for BOTH Delegate (image tier) and Blob (original /
     # pdf / audio / video, classified by media type) entries, for the display
     # layer (Cerberus / the IIIF auth service; Cerberus's download :read check)
     # to enforce.
     #
     # @param id [String] the Work ID.
     # @param policy [Hash] tier => Array(read groups), e.g.
-    #   `{ large: ["northeastern:drs:repository:archives"], master: [...] }`.
+    #   `{ large: ["northeastern:drs:repository:archives"], original: [...] }`.
     #   Keys may be strings or symbols; recognized keys are `small` / `medium` /
-    #   `large` / `service` / `master` / `audio` / `video` / `pdf`.
+    #   `large` / `service` / `original` / `audio` / `video` / `pdf`. Atlas
+    #   0.6.211 renamed the image floor from `master`; for one release it still
+    #   accepts `master` on write and stores it as `original`.
     # @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`)
     #   path it is ignored (identity lives in the token).
@@ -435,6 +437,15 @@ module AtlasRb
     # authorized rather than fetched directly) and `permission` (the effective
     # read-group set, or `nil` for guests, to whom group names are withheld).
     #
+    # A Blob entry also carries `language` and `track_label`, set by {Blob.create}
+    # and {Blob.update} for a caption or other text track and `nil` otherwise
+    # (Atlas 0.6.211 or later). A FileSet withdrawn with {Resource.tombstone}
+    # drops out of this listing and {.file_sets}; {.withdrawn_assets} lists it.
+    #
+    # Every entry carries `file_set`, the NOID of the FileSet it is listed
+    # under (Atlas 0.6.212 or later). That is the id {Resource.tombstone} and
+    # {Admin::Resource.restore} take to withdraw or restore the file.
+    #
     # @param id [String] the Work ID.
     # @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`)
@@ -458,6 +469,44 @@ module AtlasRb
       end
     end
 
+    # List the assets of a Work's withdrawn FileSets, so they can be restored.
+    #
+    # Wraps `GET /works/<id>/withdrawn_assets` (Atlas 0.6.212 or later). A
+    # FileSet withdrawn with {Resource.tombstone} drops out of {.assets} and
+    # {.file_sets}; this is the listing that still names it. Each entry has the
+    # {.assets} shape, including `file_set` (the id to pass to
+    # {Admin::Resource.restore}), plus the FileSet's `tombstoned_at` and
+    # `tombstoned_by`.
+    #
+    # Atlas allows it for the admin and devolved-admin tiers only, the same
+    # tiers that may tombstone and restore a FileSet.
+    #
+    # @param id [String] the Work ID.
+    # @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`)
+    #   path it is ignored (identity lives in the token).
+    # @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 [Array<AtlasRb::Mash>, nil] one entry per asset of a withdrawn
+    #   FileSet; `[]` when nothing is withdrawn.
+    #
+    #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
+    #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
+    #   (a `403` for a caller below the delegate tier, a `5xx`, a proxy's
+    #   `503`), carrying Atlas's status and body so the failure is attributable
+    #   at the boundary.
+    # @example Offer Restore for a removed caption
+    #   AtlasRb::Work.withdrawn_assets("w-789", nuid: admin_nuid).each do |a|
+    #     AtlasRb::Admin::Resource.restore(a.file_set, nuid: admin_nuid)
+    #   end
+    def self.withdrawn_assets(id, nuid: nil, on_behalf_of: nil)
+      read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/withdrawn_assets')) do |body|
+        body.map { |entry| AtlasRb::Mash.new(entry) }
+      end
+    end
+
     # List a Work's page FileSets in order, each with its assets.
     #
     # Wraps `GET /works/<id>/file_sets` — the ordered, grouped sibling of
@@ -466,7 +515,7 @@ module AtlasRb
     # (`null`-position) FileSets last; metadata and derivative-container
     # FileSets are excluded as entries. Each entry nests its downloadable
     # assets — the page's content Blobs plus any per-page IIIF Delegates —
-    # in the same polymorphic shape {.assets} returns.
+    # in the same polymorphic shape {.assets} returns, `file_set` included.
     #
     # This is the read a IIIF Presentation manifest assembler needs: the
     # response is **unpaginated** by design, so the whole page sequence

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.21.0
+  version: 1.23.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday