Storage manager for handling file operations with redundancy and failover.
This module coordinates file storage across multiple buckets with automatic redundancy, failover, and variant generation.
Where an object is read from (V204)
Reads, existence checks, public URLs and serving go to the buckets the
object's location rows name first (PhoenixKit.Modules.Storage.Locations),
in the usual order: local buckets, then by priority. Only when none of
them has it are the other enabled buckets tried, and a bucket found to
hold it that way is recorded as a location. Writes still pick buckets by
priority and redundancy; deletes still remove an unreferenced key from
every enabled bucket.
Summary
Functions
Deletes a file from all storage buckets.
Checks if a file exists in any storage bucket.
Returns file access info based on bucket access_type.
Returns the local filesystem path for a file if stored locally.
Drops the cached list of enabled buckets, so the next read sees the database. Called whenever a bucket is created, updated or deleted. The cache only spares a query per file request; it expires on its own after five minutes, which is how long a bucket edit used to take to apply.
Gets a public URL for a file from the highest priority bucket that has it.
Replicates a file to specific target buckets.
Retrieves a file from storage with failover.
Stores a file across multiple buckets based on redundancy settings.
Functions
Deletes a file from all storage buckets.
Checks if a file exists in any storage bucket.
Returns file access info based on bucket access_type.
Determines how a file should be served based on its storage location:
- Local files are always served directly
- Remote files depend on bucket's access_type setting
Returns
{:local, path}- File is local, serve directly from filesystem{:redirect, url}- Redirect to public URL (for public buckets){:signed_redirect, url}- Redirect to a short-lived signed URL (a public bucket, with:downloadgiven){:proxy, file_name}- Download and proxy through server (for private buckets){:error, :not_found}- File not found in any bucket
Options
:download- response headers (:disposition,:content_type) for a file that must download rather than render. A public bucket's plain object URL answers with the object's stored headers, so for such a file a public bucket hands out a signed URL that overrides them (PhoenixKit.Modules.Storage.Provider.signed_download_url/3), or is proxied when its provider cannot sign one.
Returns the local filesystem path for a file if stored locally.
This function checks enabled buckets with "local" provider and returns the direct path to the file if it exists. This allows serving files directly without copying to a temp file first.
Returns
{:ok, path}- File exists at the local path{:error, :not_local}- No local bucket contains the file
Drops the cached list of enabled buckets, so the next read sees the database. Called whenever a bucket is created, updated or deleted. The cache only spares a query per file request; it expires on its own after five minutes, which is how long a bucket edit used to take to apply.
Gets a public URL for a file from the highest priority bucket that has it.
Replicates a file to specific target buckets.
Retrieves the file from any available bucket, then stores it to each target bucket. Returns the list of bucket UUIDs that succeeded.
Retrieves a file from storage with failover.
Tries each bucket in priority order until the file is found.
Stores a file across multiple buckets based on redundancy settings.
Options
:redundancy_copies- Number of copies to store (default: from settings):priority_buckets- List of specific bucket IDs to use (default: auto-select):force_bucket_ids- List of specific bucket IDs to use (overrides priority_buckets):generate_variants- Whether to generate variants (default: from settings)
Returns
{:ok, file_result}- File stored successfully with locations{:error, reason}- Failed to store file