atom

Module lock

Source
Expand description

§Atom Lockfile Format

This module provides the types and structures for working with Atom lockfiles. Lockfiles capture the exact versions and revisions of dependencies for reproducible builds, similar to Cargo.lock or flake.lock but designed for the Atom ecosystem.

§Overview

The lockfile format uses TOML with tagged enums for type safety while maintaining portability across different tools and languages. Each dependency is represented as a tagged union that can represent different types of dependencies:

  • Atom dependencies (atom) - References to other atoms by label, version, and cryptographic ID
  • Direct Nix dependencies (nix, nix+git, nix+tar, nix+build) - Direct references to external sources with integrity verification

§Key Types

  • Lockfile - The root structure containing all resolved dependencies and sets
  • Dep - Enum representing different types of locked dependencies
  • AtomDep - Structure for locked atom dependencies with cryptographic verification
  • NixDep, NixGitDep, NixTarDep, BuildSrc - Structures for different Nix fetcher types

Note: Some types are marked as pub(crate) for internal use within the atom crate.

§Lockfile Structure

version = 1

[sets.<root-hash>]
tag = "company-atoms"
mirrors = ["git@github.com:our-company/atoms", "https://mirror.com/atoms"]

[[deps]]
type = "atom"
label = "auth-service"
version = "1.5.2"
set = "<root-hash>"
rev = "<commit-hash>"
id = "<blake3-hash>"

[[deps]]
type = "nix+git"
name = "nixpkgs"
url = "https://github.com/NixOS/nixpkgs"
rev = "<commit-hash>"

[[deps]]
type = "nix+tar"
name = "master"
url = "https://github.com/ekala-project/atom/archive/master.tar.gz"
hash = "sha256:..."

[[deps]]
type = "nix+build"
name = "source-archive"
url = "https://dist.company.com/my-atom/0.2.0/source.tar.gz"
hash = "sha256:..."

§Security Features

  • Cryptographic identity using BLAKE3 hashes for atom identification
  • Backend-dependent content verification (currently SHA1 for Git, will migrate to SHA256)
  • Nix-compatible hashing for tarballs and archives with SHA256
  • Strict field validation with #[serde(deny_unknown_fields)]
  • Type-safe dependency resolution preventing invalid configurations
  • Repository root hash verification for atom set integrity

Structs§

AtomDep 🔒
Represents a locked atom dependency, referencing a verifiable repository slice.
BuildSrc
Represents a locked build-time source, such as a registry or configuration.
DepMap 🔒
A wrapper for BTreeMap that ensures consistent ordering for serialization and minimal diffs in the lockfile. It maps dependency names to their locked representations.
Lockfile
The root structure for the lockfile, containing resolved dependencies and sources.
NixDep
Represents a direct pin to an external source, such as a URL or tarball.
NixGitDep
Represents a pinned Git repository with a specific revision.
NixTarDep
Represents a pinned tarball or archive source.
SetDetails
The set of locked mirrors from the manifest
WrappedNixHash 🔒
A wrapper around NixHash to provide custom serialization behavior for TOML.

Enums§

Dep 🔒
Enum representing the different types of locked dependencies, serialized as tagged TOML tables.
GitDigest
Represents different types of Git commit hashes.
LockError 🔒
NixUrls 🔒
An enum to handle different URL types for filename extraction.

Statics§

SEMVER_REGEX 🔒

Functions§

extract_and_parse_semver 🔒
get_url_filename 🔒
Extracts a filename from a URL, suitable for use as a dependency name.
url_filename_as_tag 🔒

Type Aliases§

BoxError 🔒
A type alias for a boxed error that is sendable and syncable.
DepKey 🔒
PinFetcher 🔒
A type alias for the fetcher used for pinned dependencies.