API Reference

This section documents the internal components of darca-storage, including storage clients, connectors, file backends, scoping logic, and exception types.

---

Storage Client

class darca_storage.client.StorageClient(backend: FileBackend, *, session_metadata: Dict[str, Any] | None = None, user: str | None = None, credentials: Dict[str, str] | None = None)

Bases: FileBackend

Session-aware client wrapping a ScopedFileBackend.

Implements the full FileBackend interface with added support for:

• Session metadata

• Optional user and credential context

• Introspection and future hooks (e.g. refresh, flush, presign_url)

All paths are relative to the scoped root directory enforced by the backend.

property backend: FileBackend

Access the underlying backend (for diagnostics or chaining).

context() → Dict[str, Any]

Return contextual information for debugging or observability. Redacts credentials by default.

property credentials: Dict[str, str]

Credentials associated with this session (if any).

async delete(relative_path: str) → None

Remove a regular file.

async exists(relative_path: str) → bool

Return True if path exists (file or directory).

async flush() → None

Hook for flushing buffered data to storage. Useful for future implementations (e.g., batching or append-only logs).

async list(relative_path: str = '.', *, recursive: bool = False) → List[str]

List directory base_path.

Returns:

List of paths, relative to base_path when recursive=True, otherwise direct children.

async mkdir(relative_path: str, *, parents: bool = True, permissions: int | None = None, user: str | None = None) → None

Create directory path (and parents if requested).

async presign_url(relative_path: str, expires_in: int) → str | None

Generate a presigned download URL (only meaningful for cloud backends).

Returns:

URL string or None (default no-op).

async read(relative_path: str, *, binary: bool = False) → str | bytes

Return the full contents of path.

Parameters:

• path – Absolute path of the file.

• binary – If True, return bytes; otherwise decode as text.

async refresh() → None

Hook for refreshing credentials, tokens, or connections. Override in cloud-capable subclasses.

async rename(src_relative: str, dest_relative: str) → None

Move or rename a file/directory.

async rmdir(relative_path: str) → None

Recursively remove directory path.

property session: Dict[str, Any]

Arbitrary metadata describing the active storage session.

async stat_mtime(relative_path: str) → float

Return last-modified time (UNIX epoch seconds) for path.

Raises:

FileUtilsException if path does not exist. –

property user: str | None

Logical user this session may be scoped to.

async write(relative_path: str, content: str | bytes, *, binary: bool = False, permissions: int | None = None, user: str | None = None) → None

Overwrite or create path with content.

Optional:

permissions - chmod bits (e.g. 0o644) user - chown to given username (requires privilege)

---

Factory

StorageConnectorFactory

Resolves URL-based schemes (e.g. file:///data) into a connected, scoped StorageClient.

This factory guarantees that all returned clients operate over a ScopedFileBackend, preventing directory traversal and enforcing per-root isolation.

class darca_storage.factory.StorageConnectorFactory

Entrypoint for resolving a URL into a ready-to-use StorageClient.

Guarantees that the returned client uses a securely scoped backend.

async static from_url(url: str, *, session_metadata: Dict[str, Any] | None = None, credentials: Dict[str, str] | None = None, parameters: Dict[str, str] | None = None) → StorageClient

Parse a URL and return a connected, scoped StorageClient.

Parameters:

• url (str) – A storage URL (e.g., file:///data)

• session_metadata (dict, optional) – Metadata associated with

• credentials (this session) – Credential map

• (e.g. – “…”, “token”: “…”})

• {"user" – “…”, “token”: “…”})

• parameters (dict, optional) – Additional connection parameters

Returns:

Session-aware client wrapping a ScopedFileBackend

Return type:

StorageClient

Raises:

• ValueError – If the scheme is unsupported

• RuntimeError – If backend returned is not safely scoped

• PermissionError – If access to the base path is denied

---

Connectors

Async connector for a local-filesystem backend.

• Performs reachability and access probes without blocking the event-loop (asyncio.to_thread).

• Returns a ready-scoped async StorageClient.

• Supports credential injection (e.g. posix_user) via CredentialAware interface.

class darca_storage.connectors.local.LocalStorageConnector(base_path: str, credentials: Dict[str, str] | None = None, parameters: Dict[str, str] | None = None)

Bases: StorageConnector, CredentialAware

property base_path: str

Absolute root directory this connector targets.

async connect() → ScopedFileBackend

Return a SCOPED FileBackend instance, ready for use.

Raises:

• RuntimeError - backend not reachable –

• PermissionError - access denied –

Implementations MUST wrap raw backends with ScopedFileBackend (or equivalent) to enforce path confinement and prevent directory escape.

inject_credentials(credentials: Dict[str, str]) → None

Store credentials for downstream use (e.g., POSIX identity, audit context).

async verify_access(*, user: str | None = None, permissions: int | None = None) → bool

Attempt mkdir / touch / rm to prove we have RW access.

Uses injected credentials if available (e.g. posix_user).

async verify_connection() → bool

True if the directory exists.

---

Backends

Async local-disk backend that delegates to darca_file_utils under the hood, executed via asyncio.to_thread so the event-loop remains free.

class darca_storage.backends.local_file_backend.LocalFileBackend(*args, **kwargs)

Bases: FileBackend

async delete(path: str) → None

Remove a regular file.

async exists(path: str) → bool

Return True if path exists (file or directory).

async list(base_path: str, *, recursive: bool = False) → List[str]

List directory base_path.

Returns:

List of paths, relative to base_path when recursive=True, otherwise direct children.

async mkdir(path: str, *, parents: bool = True, permissions: int | None = None, user: str | None = None) → None

Create directory path (and parents if requested).

async read(path: str, *, binary: bool = False) → str | bytes

Return the full contents of path.

Parameters:

• path – Absolute path of the file.

• binary – If True, return bytes; otherwise decode as text.

async rename(src: str, dest: str) → None

Move or rename a file/directory.

async rmdir(path: str) → None

Recursively remove directory path.

async stat_mtime(path: str) → float

Return last-modified time (UNIX epoch seconds) for path.

Raises:

FileUtilsException if path does not exist. –

async write(path: str, content: str | bytes, *, binary: bool = False, permissions: int | None = None, user: str | None = None) → None

Overwrite or create path with content.

Optional:

permissions - chmod bits (e.g. 0o644) user - chown to given username (requires privilege)

---

Scoped Backend

class darca_storage.decorators.scoped_backend.ScopedFileBackend(backend: FileBackend, base_path: str)

Bases: FileBackend

Scoped façade over a FileBackend.

Every path the caller supplies is interpreted relative to base_path and is first normalised through _full_path to prevent path-escape attacks.

async delete(relative_path: str) → None

Remove a regular file.

async exists(relative_path: str) → bool

Return True if path exists (file or directory).

async list(relative_path: str = '.', *, recursive: bool = False) → List[str]

List directory base_path.

Returns:

List of paths, relative to base_path when recursive=True, otherwise direct children.

async mkdir(relative_path: str, *, parents: bool = True, permissions: int | None = None, user: str | None = None) → None

Create directory path (and parents if requested).

async read(relative_path: str, *, binary: bool = False) → str | bytes

Return the full contents of path.

Parameters:

• path – Absolute path of the file.

• binary – If True, return bytes; otherwise decode as text.

async rename(src_relative: str, dest_relative: str) → None

Move or rename a file/directory.

async rmdir(relative_path: str) → None

Recursively remove directory path.

async stat_mtime(relative_path: str) → float

Return last-modified time (UNIX epoch seconds) for path.

Raises:

FileUtilsException if path does not exist. –

async write(relative_path: str, content: str | bytes, *, binary: bool = False, permissions: int | None = None, user: str | None = None) → None

Overwrite or create path with content.

Optional:

permissions - chmod bits (e.g. 0o644) user - chown to given username (requires privilege)

---

Interfaces

class darca_storage.interfaces.file_backend.FileBackend(*args, **kwargs)

Async-first contract for storage back-ends.

All operations are coroutines. Concrete implementations may delegate to thread-pool helpers or native async SDKs, but callers can always:

await backend.read(…)

async delete(path: str) → None

Remove a regular file.

async exists(path: str) → bool

Return True if path exists (file or directory).

async list(base_path: str, *, recursive: bool = False) → List[str]

List directory base_path.

Returns:

List of paths, relative to base_path when recursive=True, otherwise direct children.

async mkdir(path: str, *, parents: bool = True, permissions: int | None = None, user: str | None = None) → None

Create directory path (and parents if requested).

async read(path: str, *, binary: bool = False) → str | bytes

Return the full contents of path.

Parameters:

• path – Absolute path of the file.

• binary – If True, return bytes; otherwise decode as text.

async rename(src: str, dest: str) → None

Move or rename a file/directory.

async rmdir(path: str) → None

Recursively remove directory path.

async stat_mtime(path: str) → float

Return last-modified time (UNIX epoch seconds) for path.

Raises:

FileUtilsException if path does not exist. –

async write(path: str, content: str | bytes, *, binary: bool = False, permissions: int | None = None, user: str | None = None) → None

Overwrite or create path with content.

Optional:

permissions - chmod bits (e.g. 0o644) user - chown to given username (requires privilege)

Async interface for creating scoped StorageClient instances.

A connector encapsulates whatever is needed to reach a given storage backend (local path, S3 bucket, in-memory store…). Implementations must: - Verify the backend is reachable (verify_connection) - Verify the caller has access rights (verify_access) - Produce a ready-to-use StorageClient (connect) All three operations are coroutines so event-loop callers remain non-blocking.

class darca_storage.interfaces.storage_connector.StorageConnector

Abstract contract for connecting to any storage backend.

Concrete implementations typically carry configuration (e.g. base_path for local disk, bucket + credentials for S3) and perform lightweight health checks before handing back a StorageClient.

abstractmethod async connect() → LocalFileBackend

Return a SCOPED FileBackend instance, ready for use.

Raises:

• RuntimeError - backend not reachable –

• PermissionError - access denied –

Implementations MUST wrap raw backends with ScopedFileBackend (or equivalent) to enforce path confinement and prevent directory escape.

abstractmethod async verify_access(*, user: str | None = None, permissions: int | None = None) → bool

Verify caller can create, write, and delete inside the backend root.

Parameters:

• user – POSIX username to test chown operations (optional)

• permissions – chmod bits to test permission propagation (optional)

abstractmethod async verify_connection() → bool

Lightweight check: does the backend exist / respond?

Examples

• Local path exists

• S3 bucket HeadBucket succeeds

class darca_storage.interfaces.credential_aware.CredentialAware

Interface for backends or connectors that accept runtime credentials.

Implementations may use credentials for authentication, authorization, token exchange, scoped access, or other runtime configuration.

abstractmethod inject_credentials(credentials: Dict[str, str]) → None

Provide credential material to the backend or connector.

Parameters:

credentials (dict) – Key-value credential map

---

Exceptions

exception darca_storage.exceptions.StorageClientPathViolation(attempted_path: str, base_path: str)

Bases: DarcaException

Raised when a requested path escapes the storage client’s base boundary.