Crate shipper_core 

shipper-core

A reliability layer around cargo publish for Rust workspaces — library only.

shipper-core provides deterministic, resumable crate publishing with comprehensive safety checks and evidence collection. It makes cargo publish safe to start and safe to re-run for multi-crate workspaces.

This crate contains no CLI code. The shipper CLI lives in the shipper-cli crate, and the installable binary is published as shipper — which is what users should cargo install.

Features

• Deterministic ordering — Crates publish in a reproducible order based on the dependency graph, ensuring dependencies are always published before dependents.
• Preflight verification — Catch issues before publishing: git cleanliness, registry reachability, dry-run compilation, version existence, and ownership checks.
• Readiness verification — Confirm crates are visible on the registry after publishing, with configurable polling and backoff strategies.
• Resumable execution — Interrupted publishes can be resumed from where they left off, with state persisted to disk.
• Evidence capture — Receipts and event logs provide audit trails for every publish operation, including attempt counts, durations, and error classifications.
• Parallel publishing — Independent crates can be published concurrently for faster workspace releases (opt-in via types::ParallelConfig).
• Multiple authentication methods — Supports token-based authentication and GitHub Trusted Publishing.

Pipeline

The core flow is plan → preflight → publish → (resume if interrupted):

1. plan::build_plan reads the workspace via cargo_metadata, filters publishable crates, and topologically sorts them.
2. engine::run_preflight validates git cleanliness, registry reachability, dry-run, version existence, and optional ownership.
3. engine::run_publish executes the plan with retry/backoff, verifying registry visibility after each crate.
4. engine::run_resume reloads persisted state and continues from the first pending or failed package.

Example

use std::path::PathBuf;
use shipper_core::{plan, engine, types};

// Build a publish plan from the workspace
let spec = types::ReleaseSpec {
    manifest_path: PathBuf::from("Cargo.toml"),
    registry: types::Registry::crates_io(),
    selected_packages: None,
};
let workspace = plan::build_plan(&spec)?;

// Configure runtime options (all fields must be provided)
let opts = types::RuntimeOptions { /* ... */ };

Key Types

• ReleaseSpec — Input specification (manifest path, registry, package filter)
• ReleasePlan — Deterministic, SHA256-identified publish plan
• RuntimeOptions — All runtime knobs (retry, readiness, policy, etc.)
• Receipt — Audit receipt with evidence for each published crate
• PreflightReport — Preflight assessment with finishability verdict
• PublishPolicy — Policy presets for safety vs. speed tradeoffs

Modules

• plan — Workspace analysis and topological plan generation
• engine — Core publish, preflight, and resume logic
• engine::parallel — Wave-based parallel publishing engine
• types — Domain types: specs, plans, options, receipts, errors
• config — Configuration file (.shipper.toml) loading and merging
• auth — Token resolution and authentication detection
• registry — Registry API and sparse-index client
• state — Layer 3 persistence: state, events, receipts
• git — Git operations (cleanliness check, context capture)
• lock — Distributed lock to prevent concurrent publishes
• store — StateStore trait for pluggable persistence backends
• cargo — Workspace metadata via cargo_metadata
• cargo_failure — Cargo publish failure classification heuristics
• webhook — Webhook notifications for publish events

Stability

The library API is subject to change before v1.0.0. Breaking changes will be documented in the changelog.

CLI Usage

For command-line usage, cargo install shipper --locked or see the shipper-cli crate if you need to embed the CLI frontend programmatically.

Re-exports

pub use shipper_registry as registry;

pub use shipper_retry as retry;

pub use shipper_cargo_failure as cargo_failure;

Modules

auth

Token resolution: CARGO_REGISTRY_TOKEN → CARGO_REGISTRIES_<NAME>_TOKEN → $CARGO_HOME/credentials.toml.

cargo

Workspace metadata and publish execution via cargo.

config

Configuration file (.shipper.toml) loading and merging.

encryption

State file encryption module.

engine

Core publish, preflight, and resume logic.

git

Git operations (cleanliness check, context capture). Public façade for git operations.

lock

Distributed lock to prevent concurrent publishes.

plan

Workspace analysis and topological plan generation.

runtime

Layer 2: runtime context (pure data). Houses runtime::policy, runtime::execution, etc. Layer 2: runtime context (pure data). Environment fingerprint, policy, execution context.

state

Layer 3: persistence. State, events, receipts. Layer 3: persistence. State, events, receipts, and the StateStore trait.

store

StateStore trait for pluggable persistence backends.

types

Domain types: specs, plans, options, receipts, errors.

webhook

Webhook notifications for publish events. Webhook notifications backed by the shipper-webhook microcrate.