Calculates free space for a bucket.

For local storage, checks actual disk space. For cloud storage, returns the configured max_size_mb minus usage.

Calculates storage usage for a bucket in MB.

Returns total size of all files stored in this bucket by summing up all file instances that have locations in this bucket.

Calculates user-specific file checksum (salted with user_id).

This creates a unique checksum per user+file combination for duplicate detection, while preserving the original file checksum for popularity queries.

Parameters

• user_id: The user ID (integer or string)
• file_checksum: The SHA256 checksum of the file content

Returns

String representing the SHA256 checksum of "user_id + file_checksum"

Returns an %Ecto.Changeset{} for tracking bucket changes.

Returns an %Ecto.Changeset{} for tracking dimension changes.

Returns an %Ecto.Changeset{} for tracking file changes.

Returns an %Ecto.Changeset{} for tracking file instance changes.

Creates a new bucket.

Examples

iex> create_bucket(%{name: "Local Storage", provider: "local"})
{:ok, %Bucket{}}

iex> create_bucket(%{name: nil})
{:error, %Ecto.Changeset{}}

Creates a new dimension.

Examples

iex> create_dimension(%{name: "thumbnail", width: 150, height: 150})
{:ok, %Dimension{}}

iex> create_dimension(%{name: nil})
{:error, %Ecto.Changeset{}}

Creates a directory if it doesn't exist.

Creates a new file record.

This only creates the database record. Use store_file/4 to actually store the file data in storage buckets.

Creates a new file instance.

Creates file locations for a file instance across specified buckets.

Returns {:ok, locations} on success or {:error, :file_locations_failed, errors} if any insertions fail.

Parameters

• file_instance_id - The ID of the file instance
• bucket_ids - List of bucket IDs to create locations for
• file_path - The storage path for the file

Examples

iex> create_file_locations_for_instance(instance_id, [bucket_id], "path/to/file")
{:ok, [%FileLocation{}]}

iex> create_file_locations_for_instance(instance_id, [invalid_bucket], "path")
{:error, :file_locations_failed, [{bucket_id, changeset}]}

Deletes a bucket.

Examples

iex> delete_bucket(bucket)
{:ok, %Bucket{}}

iex> delete_bucket(bucket)
{:error, %Ecto.Changeset{}}

Deletes a dimension.

Examples

iex> delete_dimension(dimension)
{:ok, %Dimension{}}

iex> delete_dimension(dimension)
{:error, %Ecto.Changeset{}}

Deletes a file.

This only removes the database record. Use delete_file_data/1 to remove the actual file data from storage buckets.

Deletes file data from all storage buckets.

Deletes a file instance.

Ensures at least one default bucket exists.

If no buckets exist, creates a default local storage bucket.

Returns

• {:created, bucket} - If a new bucket was created
• :exists - If buckets already exist

Examples

iex> ensure_default_bucket_exists()
{:created, %Bucket{name: "Local Storage"}}

iex> ensure_default_bucket_exists()
:exists

Checks if a file exists in storage.

Gets the absolute path for local storage.

Gets a single bucket by ID.

Returns nil if bucket does not exist.

Gets a bucket by name.

Gets the current storage configuration.

Gets the default storage path for local file uploads (relative path).

Returns the configured relative path or the default "priv/uploads" if not set.

Gets a single dimension by ID.

Gets a dimension by name.

Gets a single file by ID.

Gets a file by its original content checksum (file_checksum).

This can find files uploaded by any user with the same content. Useful for popularity queries.

Gets a file by its user-specific checksum.

This checks for duplicates for a specific user.

Gets a single file instance by ID.

Gets the bucket IDs where a file instance is stored.

Returns a list of bucket IDs from the file_locations for the given file instance.

Gets a file instance by file ID and variant name.

Gets a public URL for a file.

Gets a public URL for a file by file ID.

Convenience function that fetches the file and returns its URL.

Examples

iex> get_public_url_by_id("018e3c4a-9f6b-7890-abcd-ef1234567890")
"https://cdn.example.com/12/a1/a1b2c3d4e5f6/a1b2c3d4e5f6_original.jpg"

iex> get_public_url_by_id("invalid-id")
nil

Gets a public URL for a specific file variant by file ID.

Examples

iex> get_public_url_by_id("018e3c4a-9f6b-7890-abcd-ef1234567890", "thumbnail")
"https://cdn.example.com/12/a1/a1b2c3d4e5f6/a1b2c3d4e5f6_thumbnail.jpg"

Gets a public URL for a specific file variant.

Variants

For images: "original", "thumbnail", "small", "medium", "large" For videos: "original", "360p", "720p", "1080p", "video_thumbnail"

Examples

iex> get_public_url_by_variant(file, "thumbnail")
"https://cdn.example.com/12/a1/a1b2c3d4e5f6/a1b2c3d4e5f6_thumbnail.jpg"

iex> get_public_url_by_variant(file, "medium")
"https://cdn.example.com/12/a1/a1b2c3d4e5f6/a1b2c3d4e5f6_medium.jpg"

Returns a list of all storage buckets, ordered by priority.

Returns a list of all dimensions, ordered by size (width x height).

Returns enabled dimensions for a specific file type.

Gets enabled buckets, ordered by priority.

Returns a list of file instances for a given file.

Returns a list of files, optionally filtered by bucket.

Options

• :bucket_id - Filter by bucket ID
• :limit - Maximum number of results
• :offset - Number of results to skip
• :order_by - Ordering (default: [desc: :inserted_at])

Checks if the Storage module is enabled.

This module is always enabled and cannot be disabled.

Examples

iex> PhoenixKit.Modules.Storage.module_enabled?()
true

Repairs the storage module by resetting configuration to defaults.

This is a safe, non-destructive operation that:

1. Creates a default local bucket if no buckets exist
2. Resets dimensions to 8 defaults (4 image + 4 video)
3. Resets storage settings to recommended defaults

All existing files are preserved.

Returns

• {:ok, repairs} - List of repairs performed
• {:error, reason} - If repair failed

Examples

iex> repair_storage_module()
{:ok, [{:bucket_created, "Local Storage"}, {:dimensions_reset, 8}, {:settings_reset, 3}]}

Resets all dimensions to default seeded values. Deletes all current dimensions and recreates the 8 default ones.

Resets storage settings to their default values.

Resets:

• storage_redundancy_copies to "1"
• storage_auto_generate_variants to "true"
• storage_default_bucket_id to nil

Returns

• :ok

Retrieves a file from storage by file ID.

Will try buckets in priority order until the file is found.

Retrieves a file by its hash.

Stores a file in the storage system.

This will:

1. Store the file in multiple buckets based on redundancy settings
2. Generate variants if enabled
3. Create database records for the file and its variants

Options

• :filename - Original filename (required)
• :content_type - MIME type (required)
• :size_bytes - File size in bytes (required)
• :user_id - User ID who owns the file
• :metadata - Additional metadata map

Stores a file in buckets with hierarchical path structure.

Path Structure

Files are stored using the pattern: {user_id[0..1]}/{hash[0..1]}/{full_hash}/{full_hash}_{variant}.{format}

Examples

User ID: "12345678" File hash: "a1b2c3d4e5f6..." Original: "12/a1/a1b2c3d4e5f6/a1b2c3d4e5f6_original.jpg" Thumbnail: "12/a1/a1b2c3d4e5f6/a1b2c3d4e5f6_thumbnail.jpg"

Updates a bucket.

Examples

iex> update_bucket(bucket, %{name: "New Name"})
{:ok, %Bucket{}}

iex> update_bucket(bucket, %{name: nil})
{:error, %Ecto.Changeset{}}

Updates the default storage path.

Updates a dimension.

Examples

iex> update_dimension(dimension, %{name: "New Name"})
{:ok, %Dimension{}}

iex> update_dimension(dimension, %{name: nil})
{:error, %Ecto.Changeset{}}

Updates a file.

Updates a file instance.

Updates a file instance's processing status.

Updates a file instance with file information after processing.

Validates and normalizes a storage path.

Returns {:ok, relative_path} if valid, or error tuple if invalid.