veyron-sdk 0.1.1

Rust SDK for writing Veyron plugins — async IPC client, Plugin trait, and full Veyron wire protocol (framing, zstd compression, HMAC frame MACs, fragmentation, raw audio).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

//! # Veyron Rust SDK
//!
//! Write Veyron plugins in Rust. A plugin is a separate OS process that talks
//! to the Veyron kernel over a Unix domain socket using the Veyron wire
//! protocol (length-prefixed frames carrying Protobuf envelopes; see
//! `docs/FRAMING.md` in the Veyron repository).
//!
//! ## Quick start
//!
//! ```no_run
//! use veyron_sdk::{Plugin, VeyronClient};
//! use veyron_sdk::proto::{envelope, ActionResponse, ActionStatus, Envelope, PluginManifest};
//! use veyron_sdk::VeyronError;
//!
//! struct EchoPlugin;
//!
//! impl Plugin for EchoPlugin {
//!     fn id(&self) -> &str {
//!         "echo"
//!     }
//!
//!     fn manifest(&self) -> PluginManifest {
//!         PluginManifest::default()
//!     }
//!
//!     async fn on_message(&mut self, envelope: Envelope) -> Result<Option<Envelope>, VeyronError> {
//!         match envelope.payload {
//!             Some(envelope::Payload::ActionRequest(req)) => Ok(Some(Envelope {
//!                 payload: Some(envelope::Payload::ActionResponse(ActionResponse {
//!                     action_id: req.action_id,
//!                     status: ActionStatus::ActionOk as i32,
//!                     data_json: req.params_json,
//!                     error: String::new(),
//!                 })),
//!                 ..Default::default()
//!             })),
//!             _ => Ok(None),
//!         }
//!     }
//! }
//!
//! #[tokio::main]
//! async fn main() -> Result<(), VeyronError> {
//!     EchoPlugin.run().await
//! }
//! ```
//!
//! ## Environment
//!
//! | Variable             | Meaning                                                    |
//! |----------------------|------------------------------------------------------------|
//! | `VEYRON_SOCKET_PATH` | Kernel UDS path (default: per-user runtime dir)            |
//! | `VEYRON_JWT_TOKEN`   | JWT presented at registration (secured kernels)            |
//! | `VEYRON_JWT_SECRET`  | Shared secret; enables per-frame HMAC-SHA256 tags          |
//!
//! ## Protocol coverage
//!
//! Compression (`FLAG_COMPRESSED`), frame MACs (`FLAG_MAC_PRESENT`),
//! fragmentation (`FLAG_FRAGMENTED`) and raw audio (`FLAG_RAW_BINARY`) are all
//! handled — see [`VeyronClient`] for the transport API and [`framing`] for
//! the shared wire-format primitives.

pub mod client;
pub mod framing;
pub mod plugin;

pub use client::VeyronClient;
pub use plugin::Plugin;
pub use veyron_wire::WireError as VeyronError;

/// Frame-MAC primitives (HKDF session-key derivation, HMAC-SHA256 tags),
/// shared with the kernel.
pub use veyron_wire::mac as frame_mac;

/// Generated Protobuf types for the Veyron protocol
/// (`wire/proto/veyron_protocol.proto`).
pub mod proto {
    pub use veyron_wire::proto::veyron::*;
}