atlas_rb 1.29.0 → 1.29.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 992d6ea2f49be14d9163123932c11e9f150751ced8e3261ef08c532879177230
-  data.tar.gz: 001b33d6eb73fb1b3cbcc2fc5e066ea0b1ccf5b0bae29455eafb1da0fd68036d
+  metadata.gz: 66d1cdefb1c1d3935fa8cd3721438b8b81b3bd89509317a11beefac39b55c9c9
+  data.tar.gz: d8b9bcea27ca0cb9ed3a40b64b31a944c0e6c22ba82aca5f32aa8f293cd16e6a
 SHA512:
-  metadata.gz: c12109d7c7cda3ab19f6b41d1849c8085fd30b54a1a638a0848fcc039e46f5745b14686fbfab3a2df8390be10122278e3693dc16eb2f5f9f681383715e7ba203
-  data.tar.gz: 0da824372eb26beccf7b0bbb5230a6b446bc0379142b7339b228bf1364580ac19a94f3021879cd9027270539e8ad4f9f0915a7a61fd8e7f1464e474445a7a479
+  metadata.gz: 4bf52d38cef2068881ee863d6f41fcd0d0149eab2714c1cec8d942f0f3f2ef422faeb52b92528579820e88149a5bf9613739e65091f9727df8f1151cdefd543f
+  data.tar.gz: dd88d74e36f72f186cbb5a0473b046cef6266b2fb5b45b48b2101db77e643df3d33cefa61048390134962fbbfadf537cb26759d964b1bbd9bf7ee97f84205721

data/.version

@@ -1 +1 @@
-1.29.0
+1.29.1

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.29.1
+
+Needs an Atlas that withholds the files beneath a tombstone (0.6.245 or later).
+Against an older Atlas nothing raises, because that Atlas still serves them.
+
+### Added — `AtlasRb::TombstonedError`
+
+Raised on Atlas's `410` with `error: "tombstoned"`: a file whose Blob, FileSet
+or Work is tombstoned, or a tombstoned Work's file list. A `ResourceError`
+subclass. `tombstoned_resource_id` and `tombstoned_resource_type` name the
+resource whose tombstone applies, and `work_retracted?` is true when that is
+the Work. `Work.assets`, `.file_sets` and `.file_revisions` raise it in place of
+mapping over the error envelope as if it were the list. A `410` carrying the
+resource's own body, as `find` gets, is still returned.
+
+### Changed — `Blob.content` and `Blob.version_content` yield only a 2xx body
+
+Faraday hands every chunk to `on_data` whatever the status, so an error
+envelope reached the block as file bytes. Now a chunk reaches the block only
+for a `2xx`. A tombstone refusal raises `TombstonedError` before any chunk; any
+other status is returned with no chunk yielded.
+
+`Blob.find` documents `tombstoned_in_effect`, `tombstoned_resource_id` and
+`tombstoned_resource_type`, and `Blob.ancestry` documents `file_set_tombstoned`
+and `work_tombstoned`.
+
 ## 1.29.0
 
 Requires an Atlas that serves `GET /works/:id/tombstoned_assets` (0.6.244 or

data/Gemfile.lock

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

data/README.md

@@ -737,11 +737,32 @@ rescue AtlasRb::ResourceError => e
 end
 ```
 
-A `410 Gone` is returned rather than raised, the same way `find` returns a
-tombstone. And the two streaming reads (`Blob.content`,
-`Blob.version_content`) hand you `{ status:, headers: }` instead of raising,
-because their chunks reach you as they arrive — check the status before you
-treat those bytes as a file.
+A `410 Gone` that carries the resource's own body is returned rather than
+raised, the same way `find` returns a tombstone. The two streaming reads
+(`Blob.content`, `Blob.version_content`) hand you `{ status:, headers: }`
+instead of raising. Only a `2xx` body reaches your block, so an error envelope
+never becomes the file; check the status to answer the request.
+
+#### A tombstone withholds files
+
+Atlas withholds a file when the Blob, its FileSet or its Work is tombstoned,
+and a tombstoned Work's file lists. It answers `410` with `error:
+"tombstoned"`, and the gem raises `AtlasRb::TombstonedError`, a
+`ResourceError`. `Blob.content` raises it before your block sees a chunk, and
+`Work.assets`, `.file_sets` and `.file_revisions` raise it in place of a list.
+Admins and the devolved-admin tier are still served.
+
+```ruby
+begin
+  AtlasRb::Blob.content(blob_id) { |chunk| response.stream.write(chunk) }
+rescue AtlasRb::TombstonedError => e
+  e.tombstoned_resource_type  # => "FileSet" (one file removed) or "Work"
+  e.work_retracted?           # => true when the whole Work is tombstoned
+end
+```
+
+To refuse before streaming, read `Blob.find`: `tombstoned_in_effect` and
+`tombstoned_resource_type` say the same thing. Needs Atlas 0.6.245 or later.
 
 A **write** raises `AtlasRb::NotFoundError`. The caller asked for a change and
 did not get one, so `nil` would invite the silent failure the read guard was
@@ -854,8 +875,9 @@ end
 
 It is not a `ResourceError`, which hosts treat as a refusal of the request.
 
-A streaming download (`Blob.content`, `Blob.version_content`) cannot raise
-this: its body has already gone to your block. Check the returned `status`.
+A streaming download (`Blob.content`, `Blob.version_content`) does not raise
+this. It returns the `status` and yields no chunk of the error body, so check
+the status.
 
 ### Atlas's own latency
 
@@ -909,8 +931,8 @@ AtlasRb::Work.assets(work.id)
 
 # 4. Stream the binary back without buffering it in memory.
 File.open("out.pdf", "wb") do |f|
-  headers = AtlasRb::Blob.content(blob.id) { |chunk| f.write(chunk) }
-  puts headers["content-type"]
+  res = AtlasRb::Blob.content(blob.id) { |chunk| f.write(chunk) }
+  puts res[:headers]["content-type"]
 end
 
 # 5. Look up the acting user and their groups.

data/lib/atlas_rb/blob.rb

@@ -29,6 +29,12 @@ module AtlasRb
     #   held bytes — reconciliation compares this against the v1 manifest
     #   without re-downloading), and a download URL — or `nil` when the Blob
     #   does not exist (`404`).
+    #
+    #   `"tombstoned_in_effect"` is true when the Blob, its FileSet or its Work
+    #   is tombstoned, and `"tombstoned_resource_type"` says which (`"FileSet"`
+    #   for a removed file, `"Work"` for a retracted Work). Atlas answers such a
+    #   Blob `410` with this body, which is returned, so a host can refuse a
+    #   download before it calls {.content}. Atlas 0.6.245 or later.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
     #
@@ -58,7 +64,9 @@ module AtlasRb
     #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
     #   omitted.
     # @return [AtlasRb::Mash, nil] `{ "file_set" => "<noid>", "work" => "<noid>" }`
-    #   (either value `nil` when unresolvable).
+    #   (either value `nil` when unresolvable), with `"file_set_tombstoned"` and
+    #   `"work_tombstoned"` beside them (Atlas 0.6.245 or later; each `nil` with
+    #   its noid).
     #
     #   `nil` when Atlas answers `404` — nothing is there to read, or, with a
     #   misconfigured `ATLAS_URL`, the route is not Atlas's at all.
@@ -114,6 +122,12 @@ module AtlasRb
     # @yieldparam chunk [String] the next chunk of binary data.
     # @return [Hash] `{ status: Integer, headers: Faraday::Utils::Headers }` for
     #   `GET /files/<id>/content` (`headers` is case-insensitive, hash-like).
+    #   Only a `2xx` body reaches `chunk_handler`. For any other status no chunk
+    #   is yielded, so an error envelope can never become the downloaded file;
+    #   the status is returned for the caller to answer with.
+    # @raise [AtlasRb::TombstonedError] when Atlas withholds the bytes because
+    #   the Blob, its FileSet or its Work is tombstoned (Atlas 0.6.245 or
+    #   later). Raised before any chunk is yielded.
     #
     # @example Stream the whole body to disk
     #   File.open("/tmp/out.pdf", "wb") do |f|
@@ -126,11 +140,7 @@ module AtlasRb
     #   res[:status]                       # => 206
     #   res[:headers]["content-range"]     # => "bytes 0-1048575/52428800"
     def self.content(id, range: nil, nuid: nil, on_behalf_of: nil, &chunk_handler)
-      response = connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{id}/content") do |req|
-        req.headers["Range"] = range if range
-        req.options.on_data = proc { |chunk, _bytes_received, _env| chunk_handler.call(chunk) }
-      end
-      { status: response.status, headers: response.headers }
+      stream("#{ROUTE}#{id}/content", range: range, nuid: nuid, on_behalf_of: on_behalf_of, &chunk_handler)
     end
 
     # Upload a new Blob attached to a Work.
@@ -395,28 +405,77 @@ module AtlasRb
     #   omitted.
     # @yieldparam chunk [String] the next chunk of binary data.
     # @return [Hash] `{ status:, headers: }` — the HTTP status and response
-    #   headers. The status is handed back rather than raised on, because
-    #   chunks reach the caller as they arrive: by the time the status could
-    #   be checked, an error body would already have been streamed. A caller
-    #   writing the chunks to an HTTP response (or a file) must consult it, or
-    #   an Atlas error page becomes the bytes of the downloaded file. Matches
-    #   {.content}'s contract.
+    #   headers. As with {.content}, only a `2xx` body reaches `chunk_handler`,
+    #   and any other status is returned with no chunk yielded.
+    # @raise [AtlasRb::TombstonedError] as {.content} does.
     #
     # @example Download a superseded version to disk
     #   File.open("/tmp/old.pdf", "wb") do |f|
     #     AtlasRb::Blob.version_content("b-321", "v1") { |chunk| f.write(chunk) }
     #   end
     def self.version_content(id, version_id, nuid: nil, on_behalf_of: nil, &chunk_handler)
-      headers = {}
-      response = connection({}, nuid, on_behalf_of: on_behalf_of)
-                 .get("#{ROUTE}#{id}/versions/#{version_id}/content") do |req|
-        req.options.on_data = proc do |chunk, _bytes_received, env|
-          headers = env.response_headers if headers.empty? && env
-          chunk_handler.call(chunk)
+      path = "#{ROUTE}#{id}/versions/#{version_id}/content"
+      stream(path, nuid: nuid, on_behalf_of: on_behalf_of, &chunk_handler)
+    end
+
+    # The most of an error body kept for the exception. Atlas's envelopes are a
+    # few hundred bytes; the cap only bounds a misbehaving proxy.
+    ERROR_BODY_LIMIT = 64 * 1024
+
+    # Faraday hands every chunk to `on_data` whatever the status, and a host
+    # streaming to a browser has sent its file headers before the first one
+    # arrives. So only a 2xx chunk reaches the caller. Any other body is kept
+    # back: a tombstone refusal raises from it, and every other status is
+    # returned with no chunk yielded.
+    #
+    # @api private
+    def self.stream(path, nuid:, on_behalf_of:, range: nil, &chunk_handler)
+      sink = StreamSink.new(chunk_handler)
+      response = connection({}, nuid, on_behalf_of: on_behalf_of).get(path) do |req|
+        req.headers["Range"] = range if range
+        # A Proc, not a Method: Faraday streams only when on_data is a Proc, and
+        # buffers the whole body otherwise.
+        req.options.on_data = sink.method(:receive).to_proc
+      end
+      raise_if_tombstoned(response, sink.error_body)
+      { status: response.status, headers: sink.headers || response.headers }
+    end
+    private_class_method :stream
+
+    # @api private
+    def self.raise_if_tombstoned(response, body)
+      return unless response.status == 410
+
+      envelope = AtlasRb::TombstonedError.envelope(body)
+      raise AtlasRb::TombstonedError.new(envelope, response: response, body: body) if envelope
+    end
+    private_class_method :raise_if_tombstoned
+
+    # Routes each streamed chunk by the status Faraday recorded before the first
+    # one: a 2xx chunk to the caller, any other into a bounded error body. An
+    # env with no status is passed on, because nothing says it is an error.
+    #
+    # @api private
+    class StreamSink
+      attr_reader :headers, :error_body
+
+      def initialize(chunk_handler)
+        @chunk_handler = chunk_handler
+        @headers = nil
+        @error_body = +""
+      end
+
+      def receive(chunk, _bytes_received, env)
+        @headers ||= env&.response_headers
+        status = env&.status
+        if status.nil? || (200..299).cover?(status)
+          @chunk_handler.call(chunk)
+        elsif @error_body.bytesize < ERROR_BODY_LIMIT
+          @error_body << chunk
         end
       end
-      { status: response.status, headers: headers }
     end
+    private_constant :StreamSink
 
     # Roll a Blob back to a prior version.
     #

data/lib/atlas_rb/errors.rb

@@ -378,6 +378,61 @@ module AtlasRb
   # a caller that only wants "the write failed" can rescue the parent.
   class NotFoundError < ResourceError; end
 
+  # Raised when Atlas withholds a file, or a Work's file list, because of a
+  # tombstone: an HTTP `410` whose body carries `error: "tombstoned"`.
+  #
+  # A tombstone does not cascade, so the resource that carries it can be an
+  # ancestor of the one requested. A Blob is withheld when its FileSet is
+  # tombstoned (one file removed) or when its Work is (the whole Work
+  # retracted). {#tombstoned_resource_type} tells the two apart, so a host can
+  # show "file not found" for the first and its "Removed" page for the second.
+  #
+  #   rescue AtlasRb::TombstonedError => e
+  #     e.work_retracted? ? render("errors/gone", status: :gone) : head(:not_found)
+  #
+  # Admins and the devolved-admin tier are still served, so they never see
+  # this. A `410` from a single-resource read such as {Work.find} is not this:
+  # that one carries the resource's own body, and the read returns it.
+  #
+  # A subclass of {ResourceError}, so a caller that only wants "the read
+  # failed" can rescue the parent. Needs Atlas 0.6.245 or later.
+  class TombstonedError < ResourceError
+    # The discriminator Atlas renders. An exact-match wire contract.
+    CODE = "tombstoned"
+
+    # @return [String, nil] NOID of the resource whose tombstone applies.
+    attr_reader :tombstoned_resource_id
+
+    # @return [String, nil] its type: `"Work"`, `"FileSet"` or `"Blob"`.
+    attr_reader :tombstoned_resource_type
+
+    # @param envelope [Hash] Atlas's parsed `410` body.
+    # @param response [Faraday::Response, nil] the originating response.
+    # @param body [String, nil] the raw body, when `response` cannot carry it
+    #   (a streamed read hands its body to `on_data`, not to the response).
+    def initialize(envelope, response: nil, body: nil)
+      super(envelope["message"] || "tombstoned", response: response)
+      @body = body if body
+      @tombstoned_resource_id = envelope["tombstoned_resource_id"]
+      @tombstoned_resource_type = envelope["tombstoned_resource_type"]
+    end
+
+    # @return [Boolean] true when the whole Work is tombstoned.
+    def work_retracted?
+      tombstoned_resource_type == "Work"
+    end
+
+    # @return [Hash, nil] the envelope when `body` is Atlas's tombstone
+    #   refusal, parsed; `nil` for any other body.
+    # @api private
+    def self.envelope(body)
+      parsed = body.is_a?(Hash) ? body : JSON.parse(body.to_s)
+      parsed if parsed.is_a?(Hash) && parsed["error"] == CODE
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
   # Raised when Atlas refuses a write because the repository-wide maintenance
   # window is open: an HTTP `503` whose body carries
   # `error: "read_only_mode"`.

data/lib/atlas_rb/faraday_helper.rb

@@ -412,8 +412,11 @@ module AtlasRb
     #   reason: a dependency outage can answer any request on any shape. It
     #   must run before the read guard, or an outage on a read becomes the
     #   generic {AtlasRb::ResourceError} a host treats as a refusal.
+    # - {Middleware::RaiseOnTombstoned} — a withheld file or file list. It must
+    #   run before the read guard too, which passes every `410` through.
     def error_middleware(builder, reads:)
       builder.use AtlasRb::Middleware::RaiseOnReadError if reads
+      builder.use AtlasRb::Middleware::RaiseOnTombstoned
       builder.use AtlasRb::Middleware::RaiseOnStaleResource
       builder.use AtlasRb::Middleware::RaiseOnResourceError
       builder.use AtlasRb::Middleware::RaiseOnReadOnlyMode

data/lib/atlas_rb/middleware/raise_on_tombstoned.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AtlasRb
+  module Middleware
+    # Translates Atlas's tombstone refusal into {AtlasRb::TombstonedError}.
+    #
+    # Atlas answers `410` with `error: "tombstoned"` when it withholds a file's
+    # bytes or a tombstoned Work's file list. Without this the refusal reaches
+    # {Middleware::RaiseOnReadError}, which lets every `410` through, and a list
+    # binding maps over the error envelope as if it were the list.
+    #
+    # Keyed on the **status + discriminator pair**. A `410` that carries the
+    # resource's own body — {AtlasRb::Work.find} on a tombstoned Work — is an
+    # answer, not a refusal, and passes through untouched.
+    #
+    # A streamed read never reaches here with a body: its chunks go to
+    # `on_data`. {AtlasRb::Blob.content} checks the status itself.
+    class RaiseOnTombstoned < Faraday::Middleware
+      # @param env [Faraday::Env] the completed response environment.
+      # @raise [AtlasRb::TombstonedError] on a `410` whose body carries
+      #   `error: "tombstoned"`.
+      # @return [void]
+      def on_complete(env)
+        return unless env.status == 410
+
+        envelope = AtlasRb::TombstonedError.envelope(env.body)
+        raise AtlasRb::TombstonedError.new(envelope, response: env.response) if envelope
+      end
+    end
+  end
+end

data/lib/atlas_rb/work.rb

@@ -466,6 +466,9 @@ module AtlasRb
     #
     #   `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::TombstonedError] when the Work is tombstoned and the
+    #   caller is below the admin and devolved-admin tiers (Atlas 0.6.245 or
+    #   later), so a retracted Work's files are never listed.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
     #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
     #   Atlas's status and body so the failure is attributable at the boundary.
@@ -543,6 +546,9 @@ module AtlasRb
     #
     #   `nil` when Atlas answers `404` — no such Work, or, with a misconfigured
     #   `ATLAS_URL`, the route is not Atlas's at all.
+    # @raise [AtlasRb::TombstonedError] when the Work is tombstoned and the
+    #   caller is below the admin and devolved-admin tiers (Atlas 0.6.245 or
+    #   later), so a retracted Work's files are never listed.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
     #   (a `403` for a caller who cannot read the Work, a `5xx`, a proxy's
     #   `503`), carrying Atlas's status and body so the failure is attributable
@@ -625,6 +631,9 @@ module AtlasRb
     #
     #   `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::TombstonedError] when the Work is tombstoned and the
+    #   caller is below the admin and devolved-admin tiers (Atlas 0.6.245 or
+    #   later), so a retracted Work's files are never listed.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`
     #   (an auth or validation envelope, a `5xx`, a proxy's `503`), carrying
     #   Atlas's status and body so the failure is attributable at the boundary.

data/lib/atlas_rb.rb

@@ -22,6 +22,7 @@ require_relative "atlas_rb/middleware/raise_on_stale_resource"
 require_relative "atlas_rb/middleware/raise_on_resource_error"
 require_relative "atlas_rb/middleware/raise_on_read_only_mode"
 require_relative "atlas_rb/middleware/raise_on_backend_unavailable"
+require_relative "atlas_rb/middleware/raise_on_tombstoned"
 require_relative "atlas_rb/faraday_helper"
 require_relative "atlas_rb/mash"
 require_relative "atlas_rb/authentication"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.29.0
+  version: 1.29.1
 platform: ruby
 authors:
 - David Cliff
@@ -177,6 +177,7 @@ files:
 - lib/atlas_rb/middleware/raise_on_read_only_mode.rb
 - lib/atlas_rb/middleware/raise_on_resource_error.rb
 - lib/atlas_rb/middleware/raise_on_stale_resource.rb
+- lib/atlas_rb/middleware/raise_on_tombstoned.rb
 - lib/atlas_rb/person.rb
 - lib/atlas_rb/resource.rb
 - lib/atlas_rb/resource_writes.rb