View Source Buckets.Object (Buckets v1.0.0-rc.3)

Represents a file object in the Buckets storage system.

An Object encapsulates file data, metadata, and location information. Objects can exist in various states:

Object States

  1. Local only - Created from a file or upload, not yet stored remotely

    • stored?: false
    • location: %Buckets.Location.NotConfigured{}
    • data: {:file, path} or {:data, binary}
  2. Stored remotely - Uploaded to cloud storage

    • stored?: true
    • location: %Buckets.Location{}
    • data: nil (unless loaded)
  3. Loaded - Remote object with data fetched

    • stored?: true
    • location: %Buckets.Location{}
    • data: {:file, path} or {:data, binary}

Creating Objects

Objects can be created from:

Metadata

Objects store metadata including:

  • :content_type - MIME type of the file
  • :content_size - Size in bytes
  • Custom metadata can be added as needed

Example Usage

# Create from file
object = Buckets.Object.from_file("/path/to/document.pdf")

# Upload to storage
{:ok, stored} = MyApp.Cloud.insert(object)

# Read data from stored object
{:ok, data} = MyApp.Cloud.read(stored)

# Load remote object data
{:ok, loaded} = MyApp.Cloud.load(stored)
{:ok, data} = Buckets.Object.read(loaded)

Summary

Functions

Creates an Object from a file on disk.

Creates an Object from various upload types.

Creates a new Object with the given UUID, filename, and options.

Reads the data from an object.

Reads the data from an object, raising on error.

Types

@type t() :: %Buckets.Object{
  data: nil | {:data, binary()} | {:file, String.t()},
  filename: String.t(),
  location: Buckets.Location.t() | %Buckets.Location.NotConfigured{},
  metadata: map(),
  stored?: boolean(),
  uuid: String.t()
}

Functions

Creates an Object from a file on disk.

Automatically generates a UUID and extracts metadata including content type (from file extension) and content size.

Parameters

  • path - Path to the file on disk

Raises

Raises if the file does not exist.

Examples

object = Buckets.Object.from_file("/tmp/upload.pdf")
# %Buckets.Object{
#   uuid: "generated-uuid",
#   filename: "upload.pdf",
#   data: {:file, "/tmp/upload.pdf"},
#   metadata: %{
#     content_type: "application/pdf",
#     content_size: 12345
#   },
#   stored?: false
# }

Creates an Object from various upload types.

This function has multiple clauses to handle different upload scenarios:

Plug.Upload

Creates an Object from a %Plug.Upload{} struct (Phoenix controller uploads). Automatically extracts metadata including content type and size.

def create(conn, %{"file" => upload}) do
  object = Buckets.Object.from_upload(upload)
  {:ok, stored} = MyApp.Cloud.insert(object)
end

LiveView UploadEntry (incomplete)

Creates an Object from a %Phoenix.LiveView.UploadEntry{} that is not yet complete. Used for generating signed URLs for direct uploads.

# In LiveView for generating upload URLs
object = Buckets.Object.from_upload(entry)
{:ok, config} = MyApp.Cloud.live_upload(entry)

Raises if called with a completed upload entry without metadata.

LiveView UploadEntry (completed)

Creates an Object from a completed upload with metadata tuple {entry, meta}. The metadata typically includes the uploaded file path and/or signed URL.

# After LiveView upload completes
consume_uploaded_entries(socket, :avatar, fn %{path: path}, entry ->
  object = Buckets.Object.from_upload({entry, %{path: path}})
  {:ok, object}
end)

Raises if called with an incomplete upload entry.

Link to this function

new(uuid, filename, opts)

View Source

Creates a new Object with the given UUID, filename, and options.

Parameters

  • uuid - Unique identifier for the object
  • filename - Original filename
  • opts - Keyword list of options:
    • :location - Either {path, config} tuple or %Buckets.Location{} struct
    • :metadata - Map of metadata (defaults to %{})

Examples

# Basic object
object = Buckets.Object.new("123", "document.pdf", [])

# With location
object = Buckets.Object.new("123", "document.pdf",
  location: {"uploads/123/document.pdf", MyApp.Cloud}
)

# With metadata
object = Buckets.Object.new("123", "document.pdf",
  metadata: %{content_type: "application/pdf", author: "John"}
)

Reads the data from an object.

Returns {:ok, data} if the object has data loaded, either in memory or from a file. Returns {:error, :not_loaded} if no data is available.

Examples

# Object with data in memory
{:ok, binary_data} = Buckets.Object.read(object)

# Object without loaded data
{:error, :not_loaded} = Buckets.Object.read(remote_object)

Note

For remote objects without loaded data, use Cloud.load/2 first to fetch the data from storage.

Reads the data from an object, raising on error.

Same as read/1 but raises an exception if the data cannot be read.

Raises

  • Raises if the object has no data loaded
  • Raises if the file cannot be read from disk

Examples

# Success case
binary_data = Buckets.Object.read!(object)

# Raises for unloaded object
Buckets.Object.read!(remote_object)
# ** (RuntimeError) Called `read!/1` with object that does not have data loaded.