Class: AtlasRb::Blob

Inherits:
Resource show all
Defined in:
lib/atlas_rb/blob.rb

Overview

The binary content backing a FileSet (or attached directly to a Work).

Blobs are the bytes-on-disk layer of the hierarchy. Operations on this class deal with raw octet streams: uploading new content, replacing content on an existing Blob, and streaming downloads via a chunk handler so very large files don't have to be buffered in memory.

See also: Work, FileSet.

Constant Summary collapse

ROUTE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Atlas REST endpoint prefix for this resource.

"/files/"

Class Method Summary collapse

Methods inherited from Resource

permissions, preview

Methods included from FaradayHelper

#connection, #multipart, #system_connection

Class Method Details

.content(id, nuid: nil, on_behalf_of: nil) {|chunk| ... } ⇒ Hash

Stream the Blob's binary content through a caller-supplied block.

The body is not buffered — each chunk Faraday receives is yielded to chunk_handler immediately, making this safe for files larger than available memory. The first chunk's response headers are captured and returned so callers can inspect Content-Type, Content-Length, etc.

Examples:

Stream to disk

File.open("/tmp/out.pdf", "wb") do |f|
  headers = AtlasRb::Blob.content("b-321") { |chunk| f.write(chunk) }
  puts headers["content-type"]
end

Parameters:

  • id (String) —

    the Blob ID.

  • nuid (String, nil) (defaults to: nil) —

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

  • on_behalf_of (String, nil) (defaults to: nil) —

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Yield Parameters:

  • chunk (String) —

    the next chunk of binary data.

Returns:

  • (Hash) —

    the response headers from GET /files/<id>/content.



60
61
62
63
64
65
66
67
68
69
 
# File 'lib/atlas_rb/blob.rb', line 60

def self.content(id, nuid: nil, on_behalf_of: nil, &chunk_handler)
  headers = {}
  connection({}, nuid, on_behalf_of: on_behalf_of).get("#{ROUTE}#{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)
    end
  end
  headers
end

.create(id, blob_path, original_filename, idempotency_key: nil, nuid: nil, on_behalf_of: nil) ⇒ Hash

Upload a new Blob attached to a Work.

original_filename is preserved separately from the upload's File.basename(blob_path) because the on-disk path is often a temp file name (RackMultipart...tmp) — Atlas needs the user-facing name for download UX.

Examples:

AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "final_thesis.pdf")
# => { "id" => "b-321", "original_filename" => "final_thesis.pdf", ... }

Retry-safe bulk-deposit create

key = SecureRandom.uuid
AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "thesis.pdf",
                     idempotency_key: key)

Parameters:

  • id (String) —

    the parent Work ID.

  • blob_path (String) —

    path to the binary file on disk to upload.

  • original_filename (String) —

    the user-facing filename Atlas should record (e.g. "final_thesis.pdf").

  • idempotency_key (String, nil) (defaults to: nil) —

    optional UUID. A repeat call with the same key returns the originally-created Blob instead of creating a new one. See Work.create for full semantics.

  • nuid (String, nil) (defaults to: nil) —

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

  • on_behalf_of (String, nil) (defaults to: nil) —

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the created "blob" payload, including its "id".



101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/atlas_rb/blob.rb', line 101

def self.create(id, blob_path, original_filename, idempotency_key: nil, nuid: nil, on_behalf_of: nil)
  payload = { work_id: id,
              original_filename: original_filename,
              binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
                                                      "application/octet-stream",
                                                      File.basename(blob_path)) }

  AtlasRb::Mash.new(JSON.parse(
    multipart(nuid, on_behalf_of: on_behalf_of, idempotency_key: idempotency_key)
      .post(ROUTE, payload)&.body
  ))['blob']
end

.destroy(id, nuid: nil, on_behalf_of: nil) ⇒ Faraday::Response

Delete a Blob (the bytes and the metadata record).

Examples:

AtlasRb::Blob.destroy("b-321")

Parameters:

  • id (String) —

    the Blob ID.

  • nuid (String, nil) (defaults to: nil) —

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

  • on_behalf_of (String, nil) (defaults to: nil) —

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Faraday::Response) —

    the raw delete response.



127
128
129
 
# File 'lib/atlas_rb/blob.rb', line 127

def self.destroy(id, nuid: nil, on_behalf_of: nil)
  connection({}, nuid, on_behalf_of: on_behalf_of).delete(ROUTE + id)
end

.find(id, nuid: nil, on_behalf_of: nil) ⇒ Hash

Fetch a single Blob's metadata record (not its bytes — see content).

Examples:

AtlasRb::Blob.find("b-321")
# => { "id" => "b-321", "original_filename" => "scan.pdf", ... }

Parameters:

  • id (String) —

    the Blob ID.

  • nuid (String, nil) (defaults to: nil) —

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

  • on_behalf_of (String, nil) (defaults to: nil) —

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the "blob" object, already unwrapped — typically includes "id", "original_filename", "size", and a download URL.



32
33
34
35
36
 
# File 'lib/atlas_rb/blob.rb', line 32

def self.find(id, nuid: nil, on_behalf_of: nil)
  AtlasRb::Mash.new(JSON.parse(
    connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id)&.body
  ))['blob']
end

.update(id, blob_path, nuid: nil, on_behalf_of: nil) ⇒ Hash

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.

Examples:

AtlasRb::Blob.update("b-321", "/tmp/revised.pdf")

Parameters:

  • id (String) —

    the Blob ID.

  • blob_path (String) —

    path to the replacement binary on disk.

  • nuid (String, nil) (defaults to: nil) —

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

  • on_behalf_of (String, nil) (defaults to: nil) —

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the parsed JSON response from the patch.



149
150
151
152
153
154
155
156
 
# File 'lib/atlas_rb/blob.rb', line 149

def self.update(id, blob_path, nuid: nil, on_behalf_of: nil)
  payload = { binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
                                                      "application/octet-stream",
                                                      File.basename(blob_path)) }
  AtlasRb::Mash.new(JSON.parse(
    multipart(nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, payload)&.body
  ))
end