atlas_rb 1.10.1 → 1.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d8edc13167cb16fb5482d6a5cd19760bf323f67bf1a23f00a9508f8320bf798
-  data.tar.gz: e86459ce460b8eb30cffcfaaed75b06c750649aa57559e33d5ea277ce0bd2d8c
+  metadata.gz: 7bacb5eb215d1dd6d3df935abd82d74909ca81d1ce91f44de67f370846dbbd80
+  data.tar.gz: c6ea26efb6d7b083d2ede1455a126901bae8f446ece2997b441d7e593fdaba51
 SHA512:
-  metadata.gz: 06a66bf273c655ae075c821d158555139094714e3b5d0f3ca15296657afe067267ef781190c4804d5a97d3576237a11d664141f28256702df4151fefde515255
-  data.tar.gz: dfd113525542142a75e0789a5e9ed34424485e1ac69359f5e4c505e24d3752e9eda54e756804f13f195588f6079d0c828426e0a5b937d8ad53c2ef8708eaff00
+  metadata.gz: a9cc966ec7e7505b26ca5e5adaeacb78201b8f83c141d77a63c6ece959fce7de3c421e26274b7b943b964ad43ff32899a3da189ac4d9fdaebf43ed7cb9e5249c
+  data.tar.gz: 366a253542dfcf24f9e44ba4482c013ff426ec9b361b56636c2e2b96020a9b1ca738a93fa6f97d696b3b8bbd2e873ae761c7ceb4f8b8a5ef086bcf7c93ba2b5d

data/.version

@@ -1 +1 @@
-1.10.1
+1.11.1

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 1.11.0
+
+### Added — `Work.associations` / `.associate` / `.disassociate`
+
+DRS v1 let a depositor declare that one object is the codebook, figure,
+transcription, instructional material or supplemental material **for** another.
+The two objects stayed separate records, and each one's page showed the link
+from its own end. Atlas now records this again, and these three bindings reach
+it.
+
+```ruby
+AtlasRb::Work.associate(codebook_id, dataset_id, type: "is_codebook_for")
+AtlasRb::Work.associations(dataset_id)
+# => {"outbound" => {}, "inbound" => {"is_codebook_for" => ["w-codebook"]}}
+AtlasRb::Work.disassociate(codebook_id, dataset_id, type: "is_codebook_for")
+```
+
+All three return the same shape, so a mutation needs no follow-up read.
+`outbound` is what the Work asserts; `inbound` is what other Works assert about
+it. The edge is stored once, on the asserting Work, and Atlas derives the other
+direction — so the two can never drift apart.
+
+The five predicates are in `AtlasRb::Work::ASSOCIATION_TYPES`, for building a
+select box without hard-coding the vocabulary. A sixth needs an Atlas release,
+so the list cannot get ahead of the server.
+
+Writes are admin / devolved-admin only: the claim renders on the target's page
+too, and the asserter often holds no rights over it.
+
+### Added — `WorkAssociationError`
+
+A `422` on an association path now raises a typed error carrying `#code`
+(`invalid_type`, `target_not_found`, `invalid_target_type`,
+`self_association`, `tombstoned_work`, `tombstoned_target`). A `403` raises the
+existing `ForbiddenError`. Without these the binding would return the envelope
+as if it were a success and the rejection would be silently discarded.
+
+### Changed — the `destroy` docstrings now describe a purge
+
+`Admin::{Work,Collection,Community}.destroy`, `FileSet.destroy` and
+`Blob.destroy` previously promised more than the server did: the docstrings
+claimed a cascade and removal "from Atlas storage" while the server deleted one
+Postgres row and one Solr document, leaving every byte on disk.
+
+Atlas has since made `destroy` mean what the docstrings said, and they are
+updated to match what it now does — including the parts they never mentioned:
+
+- Deleting a Blob or a FileSet removes the **whole OCFL object**, so every
+  retained revision goes, not only the current one. `versions` and `rollback`
+  have nothing left to work with afterwards.
+- `Admin::Collection.destroy` and `Admin::Community.destroy` refuse with a
+  `422` (`has_children`) while the container still holds a member, **including
+  a tombstoned one**. That is stricter than `tombstone`, which counts only live
+  members: a purge cannot be undone, so a member left behind is orphaned for
+  good.
+
+No signature changed; this release is additive.
+
 ## 1.10.1
 
 ### Added — `Work.mark_incomplete` / `Work.clear_incomplete`

data/Gemfile.lock

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

data/lib/atlas_rb/admin/collection.rb

@@ -13,10 +13,18 @@ module AtlasRb
       # @api private
       ROUTE = "/collections/"
 
-      # Hard-delete a Collection.
+      # Hard-delete a Collection — a purge, not a withdrawal.
       #
+      # Removes the Collection's metadata, its descriptive-metadata
+      # FileSet, and the OCFL objects holding the preserved bytes.
       # Unrecoverable — prefer {AtlasRb::Collection.tombstone} for
-      # user-visible withdrawal. Operator-only.
+      # user-visible withdrawal. Admin-only.
+      #
+      # Atlas refuses with a `422` (`has_children`) while the Collection
+      # still holds a Work or a sub-container, **including tombstoned
+      # ones**. That is stricter than tombstone, which counts only live
+      # members: a member left behind by a purge is orphaned for good.
+      # Empty the tree leaf-first.
       #
       # @param id [String] the Collection ID.
       # @param confirm [Symbol] must be `:i_understand`. Any other value

data/lib/atlas_rb/admin/community.rb

@@ -13,10 +13,18 @@ module AtlasRb
       # @api private
       ROUTE = "/communities/"
 
-      # Hard-delete a Community.
+      # Hard-delete a Community — a purge, not a withdrawal.
       #
+      # Removes the Community's metadata, its descriptive-metadata
+      # FileSet, and the OCFL objects holding the preserved bytes.
       # Unrecoverable — prefer {AtlasRb::Community.tombstone} for
-      # user-visible withdrawal. Operator-only.
+      # user-visible withdrawal. Admin-only.
+      #
+      # Atlas refuses with a `422` (`has_children`) while the Community
+      # still holds a Collection or a sub-community, **including
+      # tombstoned ones**. That is stricter than tombstone, which counts
+      # only live members: a member left behind by a purge is orphaned
+      # for good. Empty the tree leaf-first.
       #
       # @param id [String] the Community ID.
       # @param confirm [Symbol] must be `:i_understand`. Any other value

data/lib/atlas_rb/admin/work.rb

@@ -13,11 +13,16 @@ module AtlasRb
       # @api private
       ROUTE = "/works/"
 
-      # Hard-delete a Work.
+      # Hard-delete a Work — a purge, not a withdrawal.
       #
-      # Removes the Work, its FileSets, and their Blobs from Atlas
-      # storage. Unrecoverable — prefer {AtlasRb::Work.tombstone} for
-      # the user-visible withdrawal path. This is operator-only.
+      # Removes the Work's metadata, cascades into its FileSets and their
+      # Blobs, and removes the OCFL objects holding the preserved bytes:
+      # every retained revision, not only the current one. Nothing
+      # survives but the audit row, which records the NOIDs it removed.
+      #
+      # Unrecoverable — prefer {AtlasRb::Work.tombstone} for the
+      # user-visible withdrawal path, which keeps everything and can be
+      # reversed. Admin-only.
       #
       # @param id [String] the Work ID.
       # @param confirm [Symbol] must be `:i_understand`. Any other value

data/lib/atlas_rb/blob.rb

@@ -186,7 +186,12 @@ module AtlasRb
       end
     end
 
-    # Delete a Blob (the bytes *and* the metadata record).
+    # Delete a Blob: the metadata record **and** the bytes.
+    #
+    # Atlas removes the whole OCFL object, so **every retained revision** goes,
+    # not only the current one — {.versions} and {.rollback} have nothing left
+    # to work with afterwards. Unrecoverable, and admin-only. The Blob is also
+    # unlinked from its FileSet, whose METS is rebuilt.
     #
     # @param id [String] the Blob ID.
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing

data/lib/atlas_rb/errors.rb

@@ -101,6 +101,38 @@ module AtlasRb
     end
   end
 
+  # Raised when Atlas rejects a Work-association write
+  # (`POST` / `DELETE /works/:id/associations...`) with a `422` carrying a
+  # machine-readable `error` discriminator — `invalid_type` (not one of the
+  # five predicates), `target_not_found`, `invalid_target_type` (the target is
+  # not a Work), `self_association`, `tombstoned_work`, or `tombstoned_target`.
+  #
+  # The association sibling of {LinkedMemberError}; same shape, same rationale
+  # (the binding would otherwise discard the envelope on a non-2xx).
+  #
+  #   rescue AtlasRb::WorkAssociationError => e
+  #     flash.now[:alert] = t("associations.errors.#{e.code}", default: e.message)
+  #
+  # @note Authorization failures surface as {ForbiddenError} (HTTP 403) —
+  #   asserting an association is admin / devolved-admin only.
+  class WorkAssociationError < Error
+    # @return [String, nil] the machine-readable error code from the envelope,
+    #   suitable for keying an i18n map.
+    attr_reader :code
+
+    # @return [String, nil] the rejected Work's ID, from the envelope.
+    attr_reader :resource_id
+
+    # @param message [String] human-readable rejection description.
+    # @param code [String, nil] the envelope's `error` discriminator.
+    # @param resource_id [String, nil] the rejected Work's ID.
+    def initialize(message, code: nil, resource_id: nil)
+      super(message)
+      @code = code
+      @resource_id = resource_id
+    end
+  end
+
   # Raised when Atlas rejects a Compilation (Set) write with a `422`
   # carrying a machine-readable `error` discriminator — a blank title on
   # create/update (`invalid_record`), or a membership add whose noid does

data/lib/atlas_rb/file_set.rb

@@ -84,7 +84,12 @@ module AtlasRb
       ))["file_set"]
     end
 
-    # Delete a FileSet.
+    # Delete a FileSet, its Blobs, and their bytes.
+    #
+    # Atlas cascades into the FileSet's Blobs and removes each one's OCFL
+    # object, so every retained revision of those binaries goes too.
+    # Unrecoverable, and admin-only. The parent Work's METS structMap is
+    # rebuilt without the removed pages.
     #
     # @param id [String] the FileSet ID.
     # @param nuid [String, nil] optional acting user's NUID. On the relay-signing

data/lib/atlas_rb/middleware/raise_on_resource_error.rb

@@ -15,7 +15,8 @@ module AtlasRb
     # {RaiseOnStaleResource}.
     #
     # It is intentionally narrow — it only fires on the re-parent
-    # (`.../parent`) and linked-member (`.../linked_members...`) write paths,
+    # (`.../parent`), linked-member (`.../linked_members...`) and association
+    # (`.../associations...`) write paths,
     # the Compilation surface (`/compilations...`), the derivative-permissions
     # write (`.../derivative_permissions`), the container-create endpoints
     # ({CREATE_PATHS}), and binary uploads (`/files...`, `/file_sets...`), and
@@ -37,6 +38,7 @@ module AtlasRb
     # - `403` on a re-parent/linked/Compilation/derivative-permissions/create path → {AtlasRb::ForbiddenError}
     # - `422` on `.../parent` → {AtlasRb::ReparentError} (`error`/`resource_id`)
     # - `422` on `.../linked_members...` → {AtlasRb::LinkedMemberError}
+    # - `422` on `.../associations...` → {AtlasRb::WorkAssociationError}
     # - `422` on `/compilations...` → {AtlasRb::CompilationError}
     # - `422` on `.../derivative_permissions` → {AtlasRb::DerivativePermissionsError}
     # - `422` + an ACL discriminator anywhere → {AtlasRb::PermissionsError}
@@ -63,6 +65,7 @@ module AtlasRb
       # @raise [AtlasRb::ForbiddenError] on a 403 to a re-parent/linked/Compilation/create path.
       # @raise [AtlasRb::ReparentError] on a 422 to a re-parent path.
       # @raise [AtlasRb::LinkedMemberError] on a 422 to a linked-member path.
+      # @raise [AtlasRb::WorkAssociationError] on a 422 to an association path.
       # @raise [AtlasRb::CompilationError] on a 422 to a Compilation path.
       # @raise [AtlasRb::DerivativePermissionsError] on a 422 to a derivative-permissions path.
       # @raise [AtlasRb::PermissionsError] on a 422 carrying an ACL-invariant discriminator.
@@ -74,6 +77,7 @@ module AtlasRb
         path        = env.url&.path.to_s
         reparent    = path.end_with?("/parent")
         linked      = path.include?("/linked_members")
+        association = path.include?("/associations")
         compilation = path.start_with?("/compilations")
         deriv_perms = path.end_with?("/derivative_permissions")
         create      = env.method.to_s == "post" && CREATE_PATHS.include?(path.chomp("/"))
@@ -92,11 +96,11 @@ module AtlasRb
           )
         end
 
-        return unless reparent || linked || compilation || deriv_perms || create || upload
+        return unless reparent || linked || association || compilation || deriv_perms || create || upload
 
         if env.status == 403
           # 403s on upload paths stay raw — acting-as/authz isn't an upload concern here.
-          return unless reparent || linked || compilation || deriv_perms || create
+          return unless reparent || linked || association || compilation || deriv_perms || create
 
           raise AtlasRb::ForbiddenError.new(
             body["message"] || "Atlas refused the request",
@@ -116,6 +120,12 @@ module AtlasRb
             code: body["error"],
             resource_id: body["resource_id"]
           )
+        elsif association
+          raise AtlasRb::WorkAssociationError.new(
+            body["message"] || "Atlas rejected the association write",
+            code: body["error"],
+            resource_id: body["resource_id"]
+          )
         elsif compilation
           raise AtlasRb::CompilationError.new(
             body["message"] || "Atlas rejected the compilation write",

data/lib/atlas_rb/work.rb

@@ -58,7 +58,10 @@ module AtlasRb
     #   omitted.
     # @return [AtlasRb::Mash] `{ "works" => [...], "pagination" => {...} }`.
     #   Each entry in `"works"` is a Work summary (`id`, `title`,
-    #   `description`, `in_progress`, `incomplete`, `incomplete_reason`).
+    #   `description`, `in_progress`, `incomplete`, `incomplete_reason`,
+    #   `handle`). `handle` is carried on the summary, not just the detail
+    #   read, so "which Works never minted?" is answerable from one page
+    #   rather than a fetch per row.
     #
     # @example Find stuck deposits
     #   AtlasRb::Work.list(in_progress: true)
@@ -220,11 +223,28 @@ module AtlasRb
     # "stuck" list.
     #
     # Idempotent on the server: calling `complete` on an already-complete
-    # Work is a no-op — Atlas simply re-saves with `in_progress: false`.
+    # Work is a no-op — Atlas re-saves with `in_progress: false`.
     # Atlas does not currently stamp a `completed_by` audit field; the
     # `nuid:` parameter is plumbed through for parity with the other
     # lifecycle bindings and in case Atlas adds completion audit later.
     #
+    # **This call also mints the Work's persistent identifier.** Atlas
+    # registers `<prefix>/<noid>` with its Handle service, pointed at the
+    # public Work page, and records it as `handle` on the Work. Two
+    # consequences for a caller:
+    #
+    # * **Minting can never fail the call.** A handle server that is down,
+    #   slow or unconfigured leaves `handle` null and the Work still
+    #   complete — never a non-2xx. So a `200` does not promise a handle:
+    #   the response body carries the Work, so check `handle` on it rather
+    #   than assuming success minted one.
+    # * **Re-completing is safe.** Atlas mints only when `handle` is empty,
+    #   and the underlying registration is keyed by handle name, so a repeat
+    #   call re-points rather than minting a second identifier.
+    #
+    # A deployment with no handle server configured mints nothing at all,
+    # which is the normal state for a stack brought up without it.
+    #
     # @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`
@@ -799,5 +819,128 @@ module AtlasRb
           .delete(ROUTE + work_id + '/linked_members/' + collection_id)
       )
     end
+
+    # The five relationship predicates Atlas accepts, carried here so a caller
+    # can build a select box without hard-coding the vocabulary. Adding a sixth
+    # needs an Atlas release, so this list cannot drift ahead of the server.
+    ASSOCIATION_TYPES = %w[
+      is_codebook_for
+      is_figure_for
+      is_instructional_material_for
+      is_supplemental_material_for
+      is_transcription_of
+    ].freeze
+
+    # List a Work's typed associations with other Works.
+    #
+    # Wraps `GET /works/<id>/associations`. An association is DRS v1's
+    # "associated works": a directed claim that one object is the codebook,
+    # figure, transcription, instructional material or supplemental material
+    # **for** another. Both objects stay separate records — this is not
+    # membership, and nothing moves in the containment tree.
+    #
+    # The edge is stored once, on the Work that asserts it. Atlas derives the
+    # other direction, so `outbound` and `inbound` can never disagree.
+    #
+    # @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 [Hash] `{"outbound" => {predicate => [noid, …]}, "inbound" => {…}}`.
+    #   `outbound` is what this Work asserts, `inbound` what other Works assert
+    #   about it. Predicates holding no edges are omitted, so both maps are
+    #   `{}` for an unassociated Work.
+    #
+    # @example
+    #   AtlasRb::Work.associations("w-789")
+    #   # => {"outbound" => {"is_codebook_for" => ["w-123"]}, "inbound" => {}}
+    def self.associations(id, nuid: nil, on_behalf_of: nil)
+      JSON.parse(
+        connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/associations')&.body
+      )
+    end
+
+    # Assert that this Work stands in a typed relationship to another Work.
+    #
+    # Wraps `POST /works/<id>/associations` with a `work_id` + `type` body.
+    # The edge is stored on **this** Work only; `target` reports the same edge
+    # under `inbound`. Asserting an edge that already exists is a no-op, and
+    # two Works can hold several different edges at once.
+    #
+    # A cycle is permitted and meaningful — "A is a transcription of B" and
+    # "B is a figure for A" can both be true.
+    #
+    # @param work_id [String] the asserting Work's ID (the codebook, figure, …).
+    # @param target_id [String] the Work being pointed at (the dataset, article, …).
+    # @param type [String] one of {ASSOCIATION_TYPES}.
+    # @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 [Hash] the Work's associations *after* the add, in the
+    #   {.associations} shape — so no follow-up GET is needed.
+    # @raise [AtlasRb::WorkAssociationError] if Atlas rejects the claim (HTTP
+    #   422): unknown type, unresolvable target, a non-Work target, the Work
+    #   itself, or either end tombstoned. The envelope's `error` code is
+    #   exposed as `#code`.
+    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the write (HTTP 403).
+    #   Associating is admin / devolved-admin only, because the claim renders
+    #   on the target's page too.
+    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no
+    #   such Work, so the write did not happen.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's
+    #   status and body.
+    #
+    # @example
+    #   AtlasRb::Work.associate("w-789", "w-123", type: "is_codebook_for")
+    #   # => {"outbound" => {"is_codebook_for" => ["w-123"]}, "inbound" => {}}
+    def self.associate(work_id, target_id, type:, nuid: nil, on_behalf_of: nil)
+      write_resource(
+        connection({ work_id: target_id, type: type }, nuid, on_behalf_of: on_behalf_of)
+          .post(ROUTE + work_id + '/associations')
+      )
+    end
+
+    # Retract one typed relationship between two Works.
+    #
+    # Wraps `DELETE /works/<id>/associations/<type>/<target_id>` — the type is
+    # a path segment because it is part of the edge's identity, so retracting
+    # the figure claim leaves a transcription claim between the same two Works
+    # standing. Idempotent: retracting an edge that was never asserted is a
+    # no-op.
+    #
+    # @param work_id [String] the asserting Work's ID.
+    # @param target_id [String] the associated Work to drop.
+    # @param type [String] the predicate to retract, one of {ASSOCIATION_TYPES}.
+    # @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 [Hash] the Work's remaining associations, in the {.associations}
+    #   shape.
+    # @raise [AtlasRb::WorkAssociationError] if Atlas rejects the write (HTTP
+    #   422) — an unresolvable target is the usual cause here.
+    # @raise [AtlasRb::ForbiddenError] if Atlas refuses the write (HTTP 403).
+    # @raise [AtlasRb::NotFoundError] if Atlas answers `404` — the id names no
+    #   such Work, so the write did not happen.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx, carrying Atlas's
+    #   status and body.
+    #
+    # @example
+    #   AtlasRb::Work.disassociate("w-789", "w-123", type: "is_codebook_for")
+    #   # => {"outbound" => {}, "inbound" => {}}
+    def self.disassociate(work_id, target_id, type:, nuid: nil, on_behalf_of: nil)
+      write_resource(
+        connection({}, nuid, on_behalf_of: on_behalf_of)
+          .delete(ROUTE + work_id + '/associations/' + type.to_s + '/' + target_id)
+      )
+    end
   end
 end

metadata

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