somatize_fabric_wire/
lib.rs

1//! Carrying a slice of plan to another process, and bringing back what it
2//! produced.
3//!
4//! The first implementation of [`Transport`](somatize_core::Transport), and it
5//! lives **outside** the core for the same reason `python/` does: here there
6//! are pipes, child processes and a byte format, which are three things a core
7//! has no business knowing.
8//!
9//! | piece | role |
10//! |---|---|
11//! | [`Worker`] | this side: starts the process and sends it work |
12//! | [`Serving`] | the far side: over standard input, or standing on a port |
13//! | [`Provision`] | the hole: turns an artifact into a [`Provisioned`] |
14//! | [`Artifact`] | what an empty worker is provisioned with |
15//! | [`Request`] / [`Answer`] | what they say, in what order, and in bytes |
16//!
17//! Two kinds of worker:
18//!
19//! ```ignore
20//! // A. the worker brings its own catalog — same code on both sides
21//! let w = Worker::spawn(Command::new("./my-worker"))?;   // there: Serving::own(&c).over_stdin()
22//!
23//! // B. the worker starts empty and the client provisions it
24//! let w = Worker::connect("node3:7000")?                 // there: Serving::provisioned(&p).listen(addr)
25//!     .carrying(Artifact::new("pickle", "sha256:abc…", bytes),
26//!               "cpython-3.13/cloudpickle-3.1");
27//! ```
28//!
29//! A is right when you control the infrastructure. B is what removes friction
30//! when you do **not**: `pip install` on a bare node, stand up a generic worker,
31//! and send it everything from your machine.
32//!
33//! What travels: the **plan**, the **values** read there and not produced
34//! there, the **placement**, and — for an empty worker — an **artifact** this
35//! crate never looks inside, which is where the nodes ride.
36//!
37//! What does not: the **catalog as such**, since an `Arc<dyn Node>` has no way
38//! of crossing a wire; the **environment**, which belongs to whoever stands the
39//! worker up and cost the original soma 420 lines and a hot `pip install`; and
40//! a [`Value::Opaque`](somatize_core::Value::Opaque), which carries something
41//! that only exists in its own process and fails at encoding time, with the
42//! host in front of you.
43
44#![forbid(unsafe_code)]
45#![warn(missing_docs)]
46
47mod artifact;
48mod frame;
49mod machine;
50mod protocol;
51mod provision;
52mod serve;
53mod worker;
54
55pub use artifact::{Artifact, Label};
56pub use machine::{Machine, filed};
57pub use protocol::{Answer, MessageError, Request};
58pub use provision::{Provision, ProvisionError, Provisioned};
59pub use serve::Serving;
60pub use worker::Worker;
61
62// Re-exported because it is part of the protocol's vocabulary: whoever
63// implements a `Provision` or reads an `Answer::Done` needs it.
64pub use somatize_core::Outcome;
somatize_fabric_wire/lib.rs

somatize_fabric_wire/
lib.rs
