@spec copy(store(), path(), path()) :: :ok | {:error, term()}

Copy an object within storage (server-side).

Examples

:ok = ObjectStoreX.copy(store, "source.txt", "destination.txt")

@spec copy_if_not_exists(store(), path(), path()) :: :ok | {:error, term()}

Copy an object only if the destination doesn't exist (atomic where supported).

Provider support:

• Azure: ✅ Native atomic copy_if_not_exists
• GCS: ✅ Native atomic copy_if_not_exists
• Local: ✅ Atomic via filesystem operations
• Memory: ✅ Atomic via in-memory checks
• S3: ❌ Not supported (returns {:error, :not_supported})

For S3, use a manual check-then-copy pattern:

case ObjectStoreX.head(store, destination) do
  {:error, :not_found} ->
    ObjectStoreX.copy(store, source, destination)
  {:ok, _meta} ->
    {:error, :already_exists}
end

Examples

# Atomic copy (Azure/GCS/Local/Memory)
case ObjectStoreX.copy_if_not_exists(store, "source.txt", "backup.txt") do
  :ok -> :copied
  {:error, :already_exists} -> :destination_exists
  {:error, :not_supported} -> :use_manual_pattern
end

# Distributed lock backup
case ObjectStoreX.copy_if_not_exists(store, "lock.txt", "lock-backup.txt") do
  :ok -> :backup_created
  {:error, :already_exists} -> :backup_already_exists
end

@spec delete(store(), path()) :: :ok | {:error, term()}

Delete an object from storage.

Examples

:ok = ObjectStoreX.delete(store, "file.txt")

@spec delete_many(store(), [path()]) ::
  {:ok, non_neg_integer(), list()} | {:error, term()}

Delete multiple objects in bulk with automatic batching.

Provider-specific batching:

• S3: Up to 1000 objects per request
• Azure: Individual deletes (parallelized)
• GCS: Batch API (up to 100 objects per request)

Examples

# Delete many objects
paths = ["file1.txt", "file2.txt", "file3.txt"]
{:ok, 3, []} = ObjectStoreX.delete_many(store, paths)

# Handle partial failures
result = ObjectStoreX.delete_many(store, paths)
case result do
  {:ok, succeeded, failed} ->
    IO.puts("Deleted: #{succeeded}, Failed: #{length(failed)}")
  {:error, reason} ->
    IO.puts("Error: #{reason}")
end

@spec get(store(), path(), keyword()) ::
  {:ok, binary()} | {:ok, binary(), metadata()} | {:error, term()}

Download an object from storage with optional conditional requests.

Options

Supports HTTP-style conditional requests for caching and consistency:

• :if_match - Only return if ETag matches (HTTP If-Match)
• :if_none_match - Only return if ETag differs (HTTP If-None-Match)
• :if_modified_since - Only return if modified after date (DateTime or Unix timestamp)
• :if_unmodified_since - Only return if not modified since date (DateTime or Unix timestamp)
• :range - Byte range {start, end} or %ObjectStoreX.Range{}
• :version - Specific object version
• :head - Return metadata only (no content)

Examples

# Simple get
{:ok, data} = ObjectStoreX.get(store, "file.txt")

# HTTP cache validation
case ObjectStoreX.get(store, "file.txt", if_none_match: cached_etag) do
  {:ok, data, meta} -> {:modified, data, meta}
  {:error, :not_modified} -> :use_cache
end

# Consistent read with ETag
{:ok, meta} = ObjectStoreX.head(store, "config.json")
case ObjectStoreX.get(store, "config.json", if_match: meta[:etag]) do
  {:ok, data, _meta} -> {:ok, data}
  {:error, :precondition_failed} -> :retry
end

# Range read
{:ok, data, meta} = ObjectStoreX.get(store, "large.bin", range: {0, 1000})

# Head-only (metadata without content)
{:ok, _empty, meta} = ObjectStoreX.get(store, "file.txt", head: true)

@spec get_ranges(store(), path(), [{non_neg_integer(), non_neg_integer()}]) ::
  {:ok, [binary()]} | {:error, term()}

Fetch multiple byte ranges from an object in a single operation.

Useful for reading file headers, footers, and metadata without downloading the entire file (e.g., Parquet files, video files).

Examples

# Read header and footer
{:ok, [header, footer]} = ObjectStoreX.get_ranges(store, "data.parquet", [
  {0, 1000},           # First 1000 bytes
  {9000, 10000}        # Bytes 9000-10000
])

# Read specific sections
{:ok, chunks} = ObjectStoreX.get_ranges(store, "video.mp4", [
  {0, 100},            # Header
  {500, 600},          # Metadata
  {1000, 2000}         # Preview section
])

@spec head(store(), path()) :: {:ok, metadata()} | {:error, term()}

Get object metadata without downloading content.

Examples

{:ok, meta} = ObjectStoreX.head(store, "file.txt")
# %{location: "file.txt", size: 1024, ...}

@spec list_with_delimiter(
  store(),
  keyword()
) :: {:ok, [metadata()], [String.t()]} | {:error, term()}

List objects with delimiter, returning objects and common prefixes separately.

This simulates a directory structure by grouping objects by common prefixes. The delimiter is always "/" (forward slash).

Examples

{:ok, objects, prefixes} = ObjectStoreX.list_with_delimiter(store, prefix: "data/")

# objects = [%{location: "data/file.txt", ...}]
# prefixes = ["data/2024/", "data/2025/"]

# List root level
{:ok, objects, prefixes} = ObjectStoreX.list_with_delimiter(store)

Options

• :prefix - Optional prefix to filter objects (default: nil)

Returns

A tuple of {:ok, objects, prefixes} where:

• objects is a list of metadata maps for objects at the current level
• prefixes is a list of string prefixes (subdirectories)

@spec new(provider()) :: {:ok, store()} | {:error, term()}

@spec new(:memory) :: {:ok, store()} | {:error, term()}

Create an in-memory storage provider (shorthand for testing).

This is a convenience function equivalent to new(:memory, []).

Examples

{:ok, store} = ObjectStoreX.new(:memory)

@spec new(
  provider(),
  keyword()
) :: {:ok, store()} | {:error, term()}

Create a new storage provider.

Examples

# S3
{:ok, store} = ObjectStoreX.new(:s3,
  bucket: "my-bucket",
  region: "us-east-1",
  access_key_id: System.get_env("AWS_ACCESS_KEY_ID"),
  secret_access_key: System.get_env("AWS_SECRET_ACCESS_KEY")
)

# S3-compatible (Wasabi, MinIO, Cloudflare R2)
{:ok, store} = ObjectStoreX.new(:s3,
  bucket: "my-bucket",
  region: "eu-central-1",
  endpoint: "https://s3.eu-central-1.wasabisys.com",
  access_key_id: System.get_env("AWS_ACCESS_KEY_ID"),
  secret_access_key: System.get_env("AWS_SECRET_ACCESS_KEY")
)

# Azure
{:ok, store} = ObjectStoreX.new(:azure,
  account: "myaccount",
  container: "mycontainer",
  access_key: System.get_env("AZURE_STORAGE_KEY")
)

# GCS
{:ok, store} = ObjectStoreX.new(:gcs,
  bucket: "my-gcs-bucket",
  service_account_key: File.read!("credentials.json")
)

# Local filesystem
{:ok, store} = ObjectStoreX.new(:local, path: "/tmp/storage")

# In-memory (for testing)
{:ok, store} = ObjectStoreX.new(:memory)

@spec put(store(), path(), binary(), keyword()) ::
  :ok | {:ok, put_result()} | {:error, term()}

Upload an object to storage.

Options

• :mode - Write mode (default: :overwrite)
  • :overwrite - Always write, overwriting any existing object
  • :create - Only write if the object doesn't exist (returns {:error, :already_exists} if exists)
  • {:update, %{etag: ..., version: ...}} - CAS operation, only write if version matches
• :content_type - MIME type (e.g., "application/json")
• :content_encoding - Encoding (e.g., "gzip")
• :content_disposition - Download behavior (e.g., "attachment; filename=file.pdf")
• :cache_control - Cache directives (e.g., "max-age=3600")
• :content_language - Language (e.g., "en-US")
• :tags - Object tags as a map (AWS/GCS only)

Examples

# Simple put (overwrite)
:ok = ObjectStoreX.put(store, "file.txt", "Hello, World!")

# Create only (distributed lock)
case ObjectStoreX.put(store, "lock.txt", "locked", mode: :create) do
  {:ok, _meta} -> :acquired
  {:error, :already_exists} -> :already_locked
end

# Compare-and-swap (optimistic locking)
{:ok, meta} = ObjectStoreX.head(store, "counter.json")
case ObjectStoreX.put(store, "counter.json", new_data,
                      mode: {:update, %{etag: meta[:etag], version: meta[:version]}}) do
  {:ok, _meta} -> :success
  {:error, :precondition_failed} -> :retry
end

# Upload with content type
ObjectStoreX.put(store, "data.json", json_data, content_type: "application/json")

# Upload with attributes
ObjectStoreX.put(store, "report.pdf", pdf_data,
  content_type: "application/pdf",
  content_disposition: "attachment; filename=report.pdf",
  cache_control: "max-age=3600"
)

# Upload with tags (AWS/GCS)
ObjectStoreX.put(store, "backup.zip", data,
  tags: %{"environment" => "production", "backup-type" => "daily"}
)

@spec rename(store(), path(), path()) :: :ok | {:error, term()}

Rename an object (server-side move).

Examples

:ok = ObjectStoreX.rename(store, "old.txt", "new.txt")

@spec rename_if_not_exists(store(), path(), path()) :: :ok | {:error, term()}

Rename an object only if the destination doesn't exist (atomic where supported).

This is implemented as copy_if_not_exists followed by delete of the source. The operation is only atomic if the underlying provider supports atomic copy_if_not_exists.

Provider support:

• Azure: ✅ Atomic
• GCS: ✅ Atomic
• Local: ✅ Atomic
• Memory: ✅ Atomic
• S3: ❌ Not supported (returns {:error, :not_supported})

Examples

# Atomic rename (Azure/GCS/Local/Memory)
case ObjectStoreX.rename_if_not_exists(store, "old.txt", "new.txt") do
  :ok -> :renamed
  {:error, :already_exists} -> :destination_exists
  {:error, :not_supported} -> :use_manual_pattern
end

# Safe rename with collision detection
case ObjectStoreX.rename_if_not_exists(store, "temp.txt", "final.txt") do
  :ok -> :moved
  {:error, :already_exists} -> :collision
  {:error, :not_found} -> :source_missing
end