Module publish

Atom Publishing

This module provides the types and logic necessary to efficiently publish atoms to store implementations. The publishing system is designed to be safe, atomic, and provide detailed feedback about the publishing process.

Architecture

The publishing system is built around two main traits:

• Builder - Constructs and validates publishers before publishing
• Publish - Handles the actual publishing of atoms to stores

Publishing Process

1. Validation - All atoms in the workspace are validated for consistency
2. Deduplication - Duplicate atoms are detected and skipped
3. Publishing - Valid atoms are published to the target store
4. Reporting - Detailed statistics and results are provided

Key Types

• Record - Contains the result of publishing a single atom
• Stats - Aggregated statistics for a publishing operation
• [PublishOutcome] - Result type for individual atom publishing attempts
• Content - Backend-specific content information

Current Backends

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

Future Backends

The architecture is designed to support additional backends:

• HTTP/HTTPS - REST APIs for atom storage
• S3-compatible - Cloud storage backends
• IPFS - Distributed storage networks

Safety Features

• Atomic operations - Failed publishes don’t leave partial state
• Duplicate detection - Prevents accidental overwrites
• Comprehensive validation - Ensures atom consistency before publishing
• Detailed error reporting - Clear feedback on what succeeded or failed

Example Usage

use std::path::PathBuf;

use atom::publish::git::GitPublisher;
use atom::publish::{Builder, Publish, Stats};
use atom::store::QueryVersion;
use atom::store::git::Root;

let repo = gix::open(".")?;
// Create a publisher for a Git repository
let progress_span = tracing::info_span!("test");
let publisher = GitPublisher::new(&repo, "origin", "main", &progress_span)?;

// Build and validate the publisher
let (valid_atoms, publisher) = publisher.build()?;

// query upstream store for remote atom refs to compare against
let remote = publisher.remote();
let remote_atoms = remote.remote_atoms(None);

// Publish all atoms
let results = publisher.publish(vec![PathBuf::from("/path/to/atom")], remote_atoms);

// Check results
let stats = Stats::default();
for result in results {
    match result {
        Ok(outcome) => todo!(), // e.g. log `outcome`
        Err(e) => println!("Failed: {:?}", e),
    }
}

Modules

error

Publishing Errors

git

Atom Publishing for a Git Store

Structs

Record

The results of Atom publishing, for reporting to the user.

Stats

Basic statistics collected during a publishing request.

Enums

Content

Contains the content pertinent to a specific implementation for reporting results to the user.

Statics

ATOM_REFS

the default location where atom refs are stored

Traits

Builder

A Builder produces a Publish implementation, which has no other constructor. This is critical to ensure that vital invariants necessary for maintaining a clean and consistent state in the Ekala store are verified before publishing can occur.

Publish

The trait primarily responsible for exposing Atom publishing logic for a given store.