lm_provision_driver/lib.rs
1//! # lm-provision-driver
2//!
3//! ## Architecture
4//!
5//! The operator / pod-manager half of the push driver protocol
6//! (08-push-driver-protocol.md) plus the append-only apply ledger it
7//! feeds (09-apply-report-and-ledger.md §Ledger) — the Phase G build
8//! target. The crate split from `lm-provision` itself is an
9//! implementation judgment 08 §Stability leaves open ("driver
10//! implementation home ... internal — the protocol, not the caller, is
11//! the contract").
12//!
13//! **Applying a profile happens on the pod, never here.** That is
14//! driven through the already-frozen CLI contract (07-cli.md) of the
15//! Phase F provisioner binary (`lm-provisioner`), from the outside, over the
16//! transport-agnostic upload / invoke / collect shape 08 defines — so
17//! no effect an apply causes is an effect this crate performs. The
18//! effects this crate does perform itself are the machine ones:
19//! [`infra::acquire`] runs the provider's CLI and creates a billable
20//! machine, and [`infra::Acquired`]'s release destroys one.
21//!
22//! What it does read from the library is the part an operator host has
23//! to know before it connects: [`session`] parses, validates and hashes
24//! the profile in process, because the host cannot run the musl
25//! artifact it is about to push and the hash has to be comparable to
26//! the pod's; [`infra`] reads the profile's machine requirements to
27//! decide what to acquire. The first is a question about a profile
28//! rather than execution of one; the second is where rendering ends
29//! and acquiring — the spending call — begins.
30//!
31//! ## Modules
32//!
33//! - [`transport`] — the [`transport::Transport`] trait plus the shared
34//! [`transport::PodPaths`] / [`transport::ExecOutput`] /
35//! [`transport::TransportError`] types every implementation shares
36//! (08 §Driver steps: "transport-agnostic ... SSH, provider exec API,
37//! `docker exec` all satisfy it").
38//! Two implementations ship: [`local_exec`] and [`ssh`]. A
39//! `docker exec` transport is a documented extension point and is
40//! not among them.
41//! - [`local_exec`] — [`local_exec::LocalExecTransport`], which runs
42//! the provisioner binary on the driver's own host.
43//! - [`driver`] — [`driver::run`], the upload → hash-integrity-check →
44//! invoke → collect sequence (08 §Driver steps) driven against any
45//! [`transport::Transport`], plus [`driver::hash_locally`] for the
46//! operator-side pre-upload hash 08 describes running "locally
47//! first".
48//! - [`ledger`] — the append-only ledger (09-apply-report-and-ledger.md
49//! §Ledger): [`ledger::append`] / [`ledger::list`] / [`ledger::get`].
50//! The module itself now lives in `lm-provision-protocol`, the
51//! neutral permissive side of the license boundary, because the AGPL
52//! control plane takes custody of the same file; it is re-exported
53//! here, so every `lm_provision_driver::ledger::*` path a caller
54//! already writes keeps resolving.
55//! - [`acquisition`] — the append-only acquisitions record
56//! (09-apply-report-and-ledger.md §Acquisitions record): one row per
57//! machine `acquire` created, one per machine given back, and
58//! [`acquisition::outstanding`], the list a sweep works from. It
59//! lives in `lm-provision-protocol` for the same reason the ledger
60//! does — the control plane reads the same file — and is re-exported
61//! here beside it.
62//! - [`ssh`] — [`ssh::SshTransport`], the SSH realization of the seam
63//! (08 §Session contract `ConnectionSpec`): scp upload, explicit
64//! identity file, secrets over stdin (08 §Secret delivery).
65//! - [`session`] — [`session::run`], the session contract's steps 0-5
66//! with per-step gates ([`session::StepPlan`]); the shape
67//! `lm-provision apply` exposes as a one-shot CLI.
68//! - [`infra`] — [`infra::Infra`], the target a machine is placed on,
69//! with one implementation per target: what it can provide, the
70//! request that would obtain a machine meeting a profile's
71//! requirements, and how to read one back and give it up — plus
72//! [`infra::acquire`] and [`infra::Acquired`], which send that
73//! request and later destroy the machine: the crate's two calls
74//! that create and stop bills.
75//! - [`inventory`] — what a platform says it is running, read through
76//! [`infra`] and rendered as the one JSON document both the operator
77//! CLI's `machine list` and the MCP `lm_machine_list` tool return. A
78//! read: it has no release path at all.
79//! - [`prices`] — the price record's writer (09 §Price record): ask a
80//! platform what its models cost and append what changed, so the
81//! inventory's join has something to stand on. It writes that one
82//! file and reaches no machine.
83//! - [`credentials`] — where a target's credential is resolved from,
84//! and what is reported when it is not there.
85//! - [`balance`] — what a platform this tool spends from says is left
86//! on the account (09 §Endpoint inventory, `balance`): RunPod, Vast
87//! and DeepInfra say, each in its own shape and sign; Together does
88//! not, and a name this tool has no adapter for is not asked at all —
89//! `Ok(None)` is that answer rather than a failure to ask. A read,
90//! over the platform's own HTTP API, with the key travelling by name.
91//! - [`probe`] — one token, now: the one-token completion that finds an
92//! exhausted account (402) or a dead key (401) before a run does.
93//! **It spends money**, which is why nothing here runs unless asked
94//! for.
95//! - [`cost`] — what a run cost: one `usage` document (in the shape the
96//! platform states it, translated at the door) priced by the record's
97//! row for its (provider, model) at an instant. A reading, like
98//! [`inventory`]: it writes nothing and reaches no machine.
99//! - [`image`] — whether the image a profile names exists in its
100//! registry, asked before a machine exists to pull it and fail.
101//! - [`provisioner`] — where the provisioner comes from: the CI-built,
102//! version-pinned, checksum-verified release asset, cached locally,
103//! so an apply needs a network rather than a toolchain.
104
105#![warn(missing_docs)]
106
107pub use lm_provision_protocol::acquisition;
108pub use lm_provision_protocol::forward;
109pub mod balance;
110pub mod cost;
111pub mod credentials;
112pub mod driver;
113pub mod image;
114pub mod infra;
115pub mod inventory;
116pub use lm_provision_protocol::ledger;
117pub mod local_exec;
118pub mod prices;
119pub mod probe;
120pub mod provisioner;
121pub mod session;
122pub mod ssh;
123pub mod transport;
124
125/// The content digest of a local artifact this driver is about to push.
126///
127/// Both transports answer the same question before uploading — "is what
128/// is already over there the same bytes as this?" (08 §Session steps
129/// "ensure-binary") — and both now answer it through
130/// [`lm_provision::digest`], the workspace's single content-digest
131/// implementation. Before this they answered it two different ways: a
132/// local `format!("{:x}")` hash in [`ssh`], a whole-file `Vec<u8>`
133/// equality in [`local_exec`].
134///
135/// **An absent artifact is an error here, not a digest that fails to
136/// match.** The path names the binary the operator asked to push; if it
137/// is not there, nothing this function could return would be true, and
138/// the failure belongs at the input rather than downstream as a
139/// surprising re-upload.
140pub(crate) fn local_digest(path: &std::path::Path) -> Result<String, transport::TransportError> {
141 lm_provision::digest::of_file(path)?.ok_or_else(|| {
142 transport::TransportError::Io(std::io::Error::new(
143 std::io::ErrorKind::NotFound,
144 format!("no local artifact at {}", path.display()),
145 ))
146 })
147}