Crate cargo_athena 

cargo-athena — compile regular Rust into Argo Workflow YAML.

This facade is the only crate users depend on. It re-exports the runtime (cargo_athena_core) and the proc macros (cargo_athena_macros) behind one stable ::cargo_athena path, which is also the path the generated code targets.

use cargo_athena::{workflow, container};   // `host!` is used path-qualified

#[workflow]
fn run_foo() {
    let a = some_other_workflow("asdf".to_string());
    run_a_container(a);
}

#[container(image = "ghcr.io/acme/app:latest")]
fn run_a_container(a: String) {
    let cfg = cargo_athena::host!("/etc/myapp");  // -> hostPath volume; compile error outside #[container]/#[fragment]
    println!("{cfg} {a}");
}

// entrypoint is a *type*; referencing it force-links the closure.
fn main() { cargo_athena::entrypoint::<run_foo>(); }

Modules

api

Argo Workflows API types — a hand-owned, curated subset.

inventory

github crates-io docs-rs

rt

Runtime shims referenced by the declaration macros. Artifact ports are plain files at fixed paths; Argo moves them (no S3 from us).

serde_json

Serde JSON

serde_norway

![github] ![crates-io] ![docs-rs]

Macros

host

host!("/lit/path") — declare a hostPath volume for the enclosing container, evaluating to the (already-mounted) path at runtime.

load_artifact

Declare an Argo input artifact port and read it (bytes) at runtime.

load_artifact_str

Declare an Argo input artifact port and read it (UTF-8) at runtime.

save_artifact

Declare an Argo output artifact port and write bytes to it at runtime.

save_artifact_str

Declare an Argo output artifact port and write a string at runtime.

Structs

ArtifactRef

One artifact bound into the container at path, backed by S3.

ArtifactRepository

ArtifactSpec

AthenaConfig

athena.toml — required by cargo athena at emit time. Mirrors the parts of Argo’s S3 ArtifactRepository we inject, plus bootstrap config.

Bootstrap

BuildCtx

Fragment registry snapshot, passed to container builds.

Collector

Accumulates the reachable templates (as WorkflowTemplates) and the run-mode dispatch table while Template::collect walks the closure.

ContainerDelivery

What container_delivery produces for one #[container] template.

ContainerRunMeta

Purpose-built introspection of one #[container], derived from the same Template::build() emit uses (so it never drifts), but expressed in the runner’s vocabulary instead of Argo’s. Emitted as JSON by the binary when CARGO_ATHENA_DESCRIBE=<name> is set; consumed by cargo athena container run to realize the spec under docker/podman locally. Also the basis for a future cargo athena container describe.

Defaults

FragmentReg

A #[fragment]: a plain helper carrying host! decls. Still inventory-based — a container’s real body actually calls its fragments, so the symbol reference exists and DCE is not a concern.

ParamRef

An input parameter, the env var the bootstrap reads it from, and its stringified Rust type ("" if unknown — synthetic templates).

S3Ref

Resolved S3 coordinates for one artifact (creds are supplied locally, e.g. via AWS env vars — cargo athena container run uses object_store; the in-cluster path uses the k8s Secret refs).

S3Repo

SecretRef

Enums

TemplateKind

What kind of Argo template a type produces.

Constants

ATHENA_BIN_DIR

Where Argo’s executor (init container) extracts the per-arch binaries from our .tar.gz input artifact. We rely on Argo’s built-in tarball auto-extraction (no archive: none, no tar in the main container’s image — see container_delivery).

ATHENA_DIR

Pod-scoped scratch root, backed by an emptyDir on every container template so all athena paths are writable regardless of the image (distroless / read-only rootfs) and shared with Argo’s init/wait containers for artifact load/collect.

ATHENA_DIST_ARTIFACT

Argo input-artifact name of the binary tarball emit injects.

ATHENA_PARAM_PREFIX

Env-var prefix the in-pod bootstrap reads each input parameter from.

SCRATCH_VOLUME

Name of the scratch emptyDir volume.

Traits

AthenaList

Fan-out: list.fan_out(|x| template(x, ..)) runs template once per element (Argo withParam); the binding is the aggregated Vec<U> of the per-element returns. This trait exists only so the ghost type-checks the element type, the closure, and the resulting Vec<U>; the macro lowers the call to Argo and it never runs.

Template

The cross-crate identity of a template, implemented by the unit struct the #[workflow]/#[container] macros generate.

Functions

artifact_inputs

load_artifact!("key") input ports: Argo pulls the exact S3 object key from the configured repo into the pod (raw, archive: none).

artifact_outputs

save_artifact!("key") output ports: Argo pushes the written file to the exact S3 object key in the configured repo (raw, archive: none).

container_delivery

The arch-resolving bootstrap + the S3 binary artifact for one container template. Called from macro-generated Template::build (emit only).

container_volumes

Every container template’s volumes/mounts: the always-present emptyDir scratch at ATHENA_DIR (binary tarball, in/out artifact ports, extraction, result — all writable on any image) followed by the declared hostPaths.

entrypoint

The entrypoint a user’s main calls, parameterised by the root workflow type. Referencing E force-links the entire reachable closure (each collect calls callees’ collect directly).

host_path_volumes

volumes + volumeMounts for a set of hostPaths (from host!).

kebab

kebab-case an Argo identifier (DNS-1123-ish) from a Rust ident.

s3_loc

Build an Argo S3 location (artifact-repository creds from athena.toml) for an exact object key.

service_account

Resolve a container template’s ServiceAccount: the #[container(service_account=...)] override, else [defaults].

wrap_workflow_template

Wrap one inner Argo template as a standalone WorkflowTemplate whose resource name == the inner template name == its entrypoint.

Attribute Macros

container

#[container]

fragment

A plain helper function (not a template) that carries pod-resource declarations (host!, artifact ports) across function boundaries into every #[container] that transitively calls it. It runs as ordinary Rust inside the caller’s pod and cannot be called from a #[workflow]. See the #[fragment] section of the container docs (CONTAINER.md) for the full model.

workflow

#[workflow]