microsandbox_protocol/
core.rs

1//! Core protocol message payloads.
2
3use serde::{Deserialize, Serialize};
4
5//--------------------------------------------------------------------------------------------------
6// Types
7//--------------------------------------------------------------------------------------------------
8
9/// Payload for `core.ready` messages.
10///
11/// Sent by the guest agent to signal that it has finished initialization
12/// and is ready to receive commands. Includes timing data for boot
13/// performance measurement.
14#[derive(Debug, Clone, Default, Serialize, Deserialize)]
15pub struct Ready {
16    /// `CLOCK_BOOTTIME` nanoseconds captured at the start of `main()`.
17    ///
18    /// Represents how long the kernel took to boot before userspace started.
19    pub boot_time_ns: u64,
20
21    /// Nanoseconds spent in `init::init()` (mounting filesystems).
22    pub init_time_ns: u64,
23
24    /// `CLOCK_BOOTTIME` nanoseconds captured just before sending this message.
25    ///
26    /// Represents total time from kernel boot to agent readiness.
27    pub ready_time_ns: u64,
28
29    /// The agent's package version (`CARGO_PKG_VERSION`), for diagnostics.
30    ///
31    /// Additive and optional: an older agent that predates this field decodes to
32    /// an empty string, and an older host ignores it. Empty means unknown. This
33    /// is the runtime's self-reported product version; the protocol generation is
34    /// carried separately in the message envelope's `v`.
35    #[serde(default, skip_serializing_if = "String::is_empty")]
36    pub agent_version: String,
37}
38
39/// Payload for `core.clock.sync` messages.
40///
41/// Sent by the host to ask the guest agent to step `CLOCK_REALTIME` to the
42/// host's current wall-clock time.
43#[derive(Debug, Clone, Serialize, Deserialize)]
44pub struct ClockSync {
45    /// Host Unix timestamp in nanoseconds.
46    pub unix_time_nanos: u64,
47}
48
49/// Payload for `core.init.resolved` messages.
50///
51/// Sent by agentd after the guest rootfs is ready to resolve init-time facts,
52/// but before user volume mounts are attached. The host uses this to install
53/// early runtime state that depends on guest-resolved values.
54#[derive(Debug, Clone, Serialize, Deserialize)]
55pub struct InitResolved {
56    /// Default guest user for sandbox commands.
57    pub default_user: ResolvedUser,
58}
59
60/// A guest user and group resolved by agentd.
61#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
62pub struct ResolvedUser {
63    /// Effective default guest user id for sandbox commands.
64    pub uid: u32,
65
66    /// Effective default guest group id for sandbox commands.
67    pub gid: u32,
68}
69
70/// Payload for `core.init.ack` messages.
71///
72/// Sent by the host after it has consumed the init context and completed any
73/// dependent setup.
74#[derive(Debug, Clone, Serialize, Deserialize)]
75pub struct InitAck {}
76
77/// Payload for `core.relay.client.disconnected` messages.
78///
79/// Sent by the host relay when one SDK client socket disconnects. The
80/// guest agent uses the assigned correlation ID range to clean up resources
81/// owned by that client, such as open filesystem handles.
82#[derive(Debug, Clone, Serialize, Deserialize)]
83pub struct RelayClientDisconnected {
84    /// First correlation ID assigned to the disconnected client.
85    pub id_start: u32,
86
87    /// Exclusive upper bound of the disconnected client's ID range.
88    pub id_end_exclusive: u32,
89}
microsandbox_protocol/core.rs

microsandbox_protocol/
core.rs
