hyprstream_workers/lib.rs
1//! hyprstream-workers: Isolated workload execution using Kata Containers
2//!
3//! This crate provides CRI-aligned (Kubernetes Container Runtime Interface) services
4//! for running isolated workloads in Kata Container VMs with GitHub Actions-compatible
5//! workflow orchestration.
6//!
7//! # Architecture
8//!
9//! Two main services:
10//!
11//! - **WorkerService**: AGPL implementation of the canonical worker contracts
12//! - PodSandbox = Kata VM (maps to CRI sandbox concept)
13//! - Container = OCI container within VM
14//! - Image operations backed by Nydus RAFS for chunk-level deduplication
15//!
16//! - **WorkflowService**: High-level workflow orchestration
17//! - Discovers `.github/workflows/*.yml` from RegistryService repos
18//! - Subscribes to event bus for automatic triggers
19//! - Spawns pods/containers via WorkerService
20//!
21//! # Event Bus
22//!
23//! Uses XPUB/XSUB proxy pattern with repo-scoped topics:
24//! - `git2db.{repo_id}.push` - Repository push events
25//! - `training.{model_id}.completed` - Training completion events
26//! - `metrics.{model_id}.breach` - Threshold breach events
27//!
28//! # Example
29//!
30//! ```ignore
31//! use hyprstream_workers::WorkerService;
32//!
33//! // Create worker service
34//! let worker = WorkerService::new(config).await?;
35//!
36//! // Pull an image
37//! let image_id = worker.pull_image(&ImageSpec::new("alpine:latest"), None).await?;
38//!
39//! // Create a pod sandbox (Kata VM)
40//! let sandbox_id = worker.run_pod_sandbox(&PodSandboxConfig::default()).await?;
41//!
42//! // Create and start a container
43//! let container_id = worker.create_container(&sandbox_id, &container_config, &sandbox_config).await?;
44//! worker.start_container(&container_id).await?;
45//! ```
46
47pub mod config;
48pub mod error;
49
50// Re-export paths from hyprstream-rpc
51pub use hyprstream_rpc::paths;
52
53pub mod runtime;
54// The `image` module is always compiled: the `ImageStore` trait +
55// `ImageBackendRegistration` inventory seam are feature-invariant, so
56// `WorkerService` can hold `Option<Arc<dyn ImageStore>>` without any cfg
57// mirror (#646). The concrete `RafsStore` impl + its `submit!` are
58// `oci-image`-gated (they pull the nydus deps); the trait surface is not.
59pub mod events;
60pub mod image;
61pub mod workflow;
62
63#[cfg(feature = "dbus")]
64pub mod dbus;
65
66// Re-export main types
67pub use config::{HypervisorType, ImageConfig, PoolConfig, WorkerConfig, WorkflowConfig};
68pub use error::WorkerError;
69
70// Re-export service types
71#[cfg(feature = "nspawn")]
72pub use runtime::{NspawnBackend, NspawnConfig};
73pub use runtime::{SandboxBackend, SandboxHandle, WorkerService};
74// Inventory-based backend registry + fail-closed selection spine (#507)
75pub use runtime::{resolve_backend, BackendCtx, BackendRegistration};
76// Scheduling-substrate explain (#628): the shared SelectionReport<C> trace.
77#[cfg(feature = "kata")]
78pub use runtime::KataBackend;
79pub use runtime::{explain_selection, BackendCandidate};
80// The image-store trait seam is always available; only the concrete RAFS impl
81// (`RafsStore`) requires `oci-image`.
82#[cfg(feature = "oci-image")]
83pub use image::RafsStore;
84pub use image::{ImageBackendRegistration, ImageStore};
85
86pub use events::{
87 serialize_container_started,
88 serialize_container_stopped,
89 serialize_sandbox_started,
90 serialize_sandbox_stopped,
91 ContainerStarted,
92 ContainerStopped,
93 ReceivedEvent,
94 SandboxStarted,
95 SandboxStopped,
96 // Event types
97 WorkerEvent,
98};
99pub use workflow::WorkflowService;
100// Re-export the moq event origin init function for the factory
101pub use hyprstream_rpc::moq_event::{init_global_moq_event_origin, MoqEventOrigin};
102
103// Re-export capnp modules from hyprstream-rpc (compiled once, shared by all crates)
104pub use hyprstream_rpc::annotations_capnp;
105pub use hyprstream_rpc::common_capnp;
106pub use hyprstream_rpc::streaming_capnp;
107
108/// Generated RPC dispatch code from `generate_rpc_service!` proc macro.
109///
110/// Provides `WorkerHandler`/`dispatch_worker` and `WorkflowHandler`/`dispatch_workflow`.
111pub mod generated;