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
Local only - Created from a file or upload, not yet stored remotely
stored?: false
location: %Buckets.Location.NotConfigured{}
data: {:file, path}
or{:data, binary}
Stored remotely - Uploaded to cloud storage
stored?: true
location: %Buckets.Location{}
data: nil
(unless loaded)
Loaded - Remote object with data fetched
stored?: true
location: %Buckets.Location{}
data: {:file, path}
or{:data, binary}
Creating Objects
Objects can be created from:
- Files on disk:
from_file/1
- Plug uploads:
from_upload/1
with%Plug.Upload{}
- LiveView uploads:
from_upload/1
with%Phoenix.LiveView.UploadEntry{}
- Manually:
new/3
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
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.
Creates a new Object with the given UUID, filename, and options.
Parameters
uuid
- Unique identifier for the objectfilename
- Original filenameopts
- 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.