Skip to main content

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}