moon_storage — moon docs

moon_storage.storage

struct StorageItem#

Metadata for one stored key.

`key: string`	Root-relative POSIX key naming the file.
`name: string`	Final path component of the key.
`size: int`	File length in bytes.
`modified_ms: int`	Last modification time in milliseconds since the Unix epoch.
`content_type: string`	MIME type guessed from the extension.

struct DiskSpace#

Total and available bytes for a storage filesystem.

`total_bytes: int`	Capacity of the filesystem holding the root.
`available_bytes: int`	Bytes still writable on it.

struct Adapter#

Filesystem-backed adapter rooted at one directory.

`base_path: string`	Absolute directory every key of this adapter resolves under.

struct MultiAdapter#

Ordered collection of storage roots with deterministic key placement.

`adapters: [Adapter]`	The roots in priority order; the first one is where writes land.

fn absolute(value: string) -> string#

path.resolve(value): absolute, lexically normalized.

value: Path to resolve against the current directory.

fn create(base_path: string) -> Result<Adapter, Error>#

Creates the directory (recursively) and returns a rooted adapter.

base_path: Directory to root the adapter at, created along with its parents.

use moon_storage.storage

fn main() {
  let files = storage.create(".moon/storage").unwrap()
  files.write("notes/moon.txt", "moon\n").unwrap()
  files.append("notes/moon.txt", "Tour\n").unwrap()
  println(files.exists("notes/moon.txt"))
  println(files.read("notes/moon.txt").unwrap())
  println(files.stat_item("notes/moon.txt").unwrap().size)
  println(files.list("notes").unwrap().len())
  files.rename("notes/moon.txt", "notes/tour.txt").unwrap()
  files.truncate("notes/tour.txt", 4).unwrap()
  files.delete("notes/tour.txt").unwrap()
}

fn create_multi(directories: [string]) -> Result<MultiAdapter, Error>#

Creates a multi-root adapter after validating the supplied directories.

directories: Roots in priority order; the first is the write target.

use moon_storage.storage

async fn main() {
  let files = storage.create_multi(["/mnt/fast", "/mnt/archive"]).unwrap()
  println(files.base_path())
  println(files.base_paths())
  files.write("video/moon.mp4", "bytes").unwrap()
  println(files.adapter_for("video/moon.mp4").is_some())
  println((await files.list("video")).unwrap())
  let capacity = files.disk_space()
  println(capacity.total_bytes)
  println(capacity.available_bytes)
}

fn contains_path(root: string, candidate: string) -> bool#

True when candidate is root itself or lies beneath it, comparing whole path segments rather than raw string prefixes.

root: Directory that must contain the candidate.
candidate: Path to test, compared segment by segment.

let root = moon_storage.storage.absolute(".moon/storage")
println(moon_storage.storage.contains_path(root, root + "/notes/moon.txt"))
println(moon_storage.storage.contains_path(root, root + "-backup/file"))
println(moon_storage.storage.disk_space_of(root).available_bytes)

impl Adapter#

fn resolve_path(self: Adapter, key: string) -> Result<string, Error>#

resolvePath: the absolute path for a key, or a validation error when the key escapes the base directory.

key: Storage key, relative to the root and never escaping it.

fn exists(self: Adapter, key: string) -> bool#

Reports whether the key exists in the selected storage root.

key: Storage key, relative to the root and never escaping it.

fn stat_item(self: Adapter, key: string) -> Optional<StorageItem>#

stat(key): the storage item, or none when the key does not exist.

key: Storage key, relative to the root and never escaping it.

fn list(self: Adapter, prefix: string) -> Result<[StorageItem], Error>#

Every file under prefix, recursively, skipping dot-directories — the same traversal list() performs.

prefix: Key prefix to walk under; empty lists the whole root.

fn read(self: Adapter, key: string) -> Optional<string>#

Reads the key, returning none when it does not exist.

key: Storage key, relative to the root and never escaping it.

fn write(self: Adapter, key: string, data: string) -> Result<int, Error>#

Replaces a key's contents and returns the bytes written.

key: Storage key, relative to the root and never escaping it.
data: Bytes to write.

fn append(self: Adapter, key: string, data: string) -> Result<int, Error>#

Appends data to a key and returns the bytes written.

key: Storage key, relative to the root and never escaping it.
data: Bytes to append.

fn truncate(self: Adapter, key: string, size: int) -> Result<int, Error>#

Truncates a key to the requested byte size.

key: Storage key, relative to the root and never escaping it.
size: Byte length to cut the file to.

fn delete(self: Adapter, key: string) -> Result<int, Error>#

Deletes a key from storage.

key: Storage key, relative to the root and never escaping it.

fn rename(self: Adapter, old_key: string, new_key: string) -> Result<int, Error>#

Renames a key within storage.

old_key: Existing key.
new_key: Key to move it to, within the same root.

fn disk_space(self: Adapter) -> DiskSpace#

Returns capacity and available bytes for the storage root.

fn device_id(self: Adapter) -> string#

The device id of the base path, so a multi-adapter counts one filesystem once even when several video directories live on it.

fn disk_space_of(directory: string) -> DiskSpace#

df -Pk <path> — POSIX output: Filesystem, 1024-blocks, Used, Available.

directory: Path whose filesystem is measured.

impl MultiAdapter#

fn base_path(self: MultiAdapter) -> string#

Returns the primary storage base path.

fn base_paths(self: MultiAdapter) -> [string]#

Returns all configured storage base paths.

fn disk_space(self: MultiAdapter) -> DiskSpace#

Combined capacity, counting each filesystem once.

async fn list(self: MultiAdapter, prefix: string) -> Result<[StorageItem], Error>async#

Union of every adapter's listing; the first adapter holding a key wins.

First-adapter-wins is carried by the merge order, not the walk order: join_all returns results in input order, so the dedup loop below sees the adapters in exactly the sequence the old serial loop did. The returned error is likewise the first in adapter order, matching the ? this replaced. What does change is failure coverage: a middle adapter's error no longer stops the later roots from being read. They run anyway and their results are dropped. Listing is read-only, so that is wasted work on the error path and nothing more.

It remains true that the fix that works best is upstream, in not calling this: a caller that knows which keys changed patches those entries (stat_item) instead of asking for the whole namespace again.

prefix: Key prefix to walk under in every root.

fn adapter_for(self: MultiAdapter, key: string) -> Optional<Adapter>#

Returns the storage adapter selected for a key.

key: Storage key to place; the first root holding it wins.

fn exists(self: MultiAdapter, key: string) -> bool#

Reports whether the key exists in the selected storage root.

key: Storage key, relative to the root and never escaping it.

fn stat_item(self: MultiAdapter, key: string) -> Optional<StorageItem>#

Returns metadata for a stored key when present.

key: Storage key, relative to the root and never escaping it.

fn path_of(self: MultiAdapter, key: string) -> Optional<string>#

The absolute path of a key, wherever it lives.

key: Storage key, relative to the root and never escaping it.

fn read(self: MultiAdapter, key: string) -> Optional<string>#

Reads the key, returning none when it does not exist.

key: Storage key, relative to the root and never escaping it.

fn write(self: MultiAdapter, key: string, data: string) -> Result<int, Error>#

Writes always land in the first directory.

key: Storage key, relative to the root and never escaping it.
data: Bytes to write.

fn append(self: MultiAdapter, key: string, data: string) -> Result<int, Error>#

Appends data to a key and returns the bytes written.

key: Storage key, relative to the root and never escaping it.
data: Bytes to append.

fn truncate(self: MultiAdapter, key: string, size: int) -> Result<int, Error>#

Truncates a key to the requested byte size.

key: Storage key, relative to the root and never escaping it.
size: Byte length to cut the file to.

fn delete(self: MultiAdapter, key: string) -> Result<int, Error>#

Deletes a key from storage.

key: Storage key, relative to the root and never escaping it.

fn rename(self: MultiAdapter, old_key: string, new_key: string) -> Result<int, Error>#

Renames a key within storage.

old_key: Existing key.
new_key: Key to move it to.

fn write_adapter(self: MultiAdapter) -> Adapter#

The write target for a new key: the first directory.