Module storage 

Storage Engine — NAP Asset Ingestion & Content-Addressed Storage

A unified storage abstraction over local-filesystem and S3-compatible backends (including Cloudflare R2, MinIO, and generic S3 providers).

Architecture

The StorageEngine is initialised once (lazily via get_engine) and reused across all FFI calls. The engine selects the backend at runtime based on the NAP_STORAGE_BACKEND environment variable:

Value	Backend	Required env vars
local	Local filesystem	NAP_DIR (default: ~/.nap)
s3	S3-compatible object store	NAP_S3_BUCKET, AWS creds

Gotchas Handled

• S3 Endpoint Parsing — The builder reads AWS_ENDPOINT_URL_S3 (and falls back to AWS_ENDPOINT_URL) for R2/MinIO compatibility. HTTP endpoints automatically enable with_allow_http(true).
• Cross-platform paths — All local paths use PathBuf; never string concatenation with / or \.
• Idempotency — ingest_media issues a HEAD before PUT; if the object already exists, the write is skipped and the hash is returned immediately.
• Gitignore — The local initialiser ensures .nap-assets/ is present in <NAP_DIR>/.gitignore so raw binaries never enter the Git graph.

Structs

StorageConfig

Runtime configuration of the storage engine.

StorageEngine

Thread-safe, lazily-initialised storage engine.

Enums

StorageBackend

Storage backend variant selected at runtime.

StorageError

Unified error type for all storage operations.

Functions

get_engine

Return a reference to the globally-initialised StorageEngine.

Type Aliases

StorageResult

Convenience alias for storage results.