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 (internal)
• Content - Backend-specific content information

Backends

The architecture is designed to support multiple backends.

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

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

private 🔒

Structs

Record

Represents the result of publishing a single atom, for reporting to the user.

Stats

Basic statistics collected during a publishing request.

Enums

Content

Contains backend-specific content information for reporting results to the user.

Constants

ATOM_FORMAT_VERSION 🔒

ATOM_MANIFEST 🔒

ATOM_META_REF 🔒

ATOM_ORIGIN 🔒

ATOM_REF 🔒

EMPTY_SIG 🔒

STORE_ROOT 🔒

Statics

ATOM_REFS

The default location where atom refs are stored.

META_REFS 🔒

REF_ROOT 🔒

Traits

Builder

A builder for a Publish implementation.

Publish

The primary trait for exposing atom publishing logic for a given store.

StateValidator 🔒

Validates the state of the atom source.

Type Aliases

MaybeSkipped 🔒

A Result indicating that an atom may have been skipped.

PublishOutcome 🔒

The outcome of an attempt to publish a single atom.

ValidAtoms 🔒

A HashMap containing all valid atoms in the current workspace.