Module store

Atom Store Interface

This module defines the core traits and interfaces for implementing storage backends for atoms. The store abstraction allows atoms to be stored and retrieved from different types of storage systems.

Architecture

The store system is designed around four core traits:

• Init - Handles store initialization and root calculation
• QueryStore - Queries references from remote stores (most important for store operations)
• QueryVersion - Provides high-level atom version querying and filtering
• NormalizeStorePath - Normalizes paths relative to store roots

Storage Backends

Currently supported backends:

• Git - Stores atoms as Git objects in repositories (when git feature is enabled)

Future backends may include:

• HTTP/HTTPS - Remote storage over HTTP APIs
• Local filesystem - Direct filesystem storage
• S3-compatible - Cloud storage backends

Key Concepts

Store Root: A unique identifier that represents the base commit or state of the store. This is used as part of atom identity calculation.

Reference Querying: The ability to efficiently query references from remote stores with different network strategies - lightweight queries for metadata or full fetches for complete store access.

Version Management: High-level operations for discovering, filtering, and selecting atom versions based on semantic version constraints and tags.

Path Normalization: Converting user-provided paths to canonical paths relative to the store root, handling both relative and absolute paths correctly.

Usage

use atom::AtomTag;
use atom::store::git::Root;
use atom::store::{Init, NormalizeStorePath, QueryStore, QueryVersion};
use gix::{Remote, Url};
use semver::VersionReq;

// Initialize a Git store
let repo = gix::open(".")?;
let remote = repo.find_remote("origin")?;
remote.ekala_init(None)?;
let root = remote.ekala_root(None)?;

// Query references from a remote store
let url = gix::url::parse("https://github.com/example/repo.git".into())?;
let refs = url.get_refs(["main", "refs/tags/v1.0"], None)?;
for ref_info in refs {
    let (name, target, peeled) = ref_info.unpack();
    println!("Ref: {}, Target: {}", name, peeled.or(target).unwrap());
}

// Query atom versions from a remote store
let atoms = url.get_atoms(None)?;
for (tag, version, id) in atoms {
    println!("Atom: {} v{} -> {}", tag, version, id);
}

// Find highest version matching requirements
let req = VersionReq::parse(">=1.0.0,<2.0.0")?;
if let Some((version, id)) = url.get_highest_match(&AtomTag::try_from("mylib")?, &req, None) {
    println!("Selected version {} with id {}", version, id);
}

// Normalize a path
let normalized = repo.normalize("path/to/atom")?;

Modules

git

Atom Git Store

Traits

Init

A trait representing the methods required to initialize an Ekala store.

NormalizeStorePath

A trait containing a path normalization method, to normalize paths in an Ekala store relative to its root.

QueryStore

A trait for querying remote stores to retrieve references.

QueryVersion

A trait for querying version information about atoms in remote stores.

UnpackRef

A trait for unpacking atom references into structured version information.