Skip to main content

vynkor_sdk/
lib.rs

1//! # Vynkor Rust SDK
2//!
3//! Write Vynkor plugins in Rust. A plugin is a separate OS process that talks
4//! to the Vynkor kernel using the Vynkor wire protocol (length-prefixed frames
5//! carrying Protobuf envelopes; see `docs/FRAMING.md` in the Vynkor
6//! repository) over a Unix domain socket or — for remote devices — the
7//! kernel's WebSocket gateway.
8//!
9//! ## Quick start
10//!
11//! ```no_run
12//! use vynkor_sdk::{Plugin, VynkorClient};
13//! use vynkor_sdk::proto::{envelope, ActionResponse, ActionStatus, Envelope, PluginManifest};
14//! use vynkor_sdk::VynkorError;
15//!
16//! struct EchoPlugin;
17//!
18//! impl Plugin for EchoPlugin {
19//!     fn id(&self) -> &str {
20//!         "echo"
21//!     }
22//!
23//!     fn manifest(&self) -> PluginManifest {
24//!         PluginManifest::default()
25//!     }
26//!
27//!     async fn on_message(&mut self, envelope: Envelope) -> Result<Option<Envelope>, VynkorError> {
28//!         match envelope.payload {
29//!             Some(envelope::Payload::ActionRequest(req)) => Ok(Some(Envelope {
30//!                 payload: Some(envelope::Payload::ActionResponse(ActionResponse {
31//!                     action_id: req.action_id,
32//!                     status: ActionStatus::ActionOk as i32,
33//!                     data_json: req.params_json,
34//!                     error: String::new(),
35//!                 })),
36//!                 ..Default::default()
37//!             })),
38//!             _ => Ok(None),
39//!         }
40//!     }
41//! }
42//!
43//! #[tokio::main]
44//! async fn main() -> Result<(), VynkorError> {
45//!     EchoPlugin.run().await
46//! }
47//! ```
48//!
49//! ## Environment
50//!
51//! | Variable             | Meaning                                                    |
52//! |----------------------|------------------------------------------------------------|
53//! | `VYN_SOCKET_PATH` | Kernel UDS path (default: per-user runtime dir)            |
54//! | `VYN_JWT_TOKEN`   | JWT presented at registration (secured kernels)            |
55//! | `VYN_JWT_SECRET`  | Shared secret; enables per-frame HMAC-SHA256 tags          |
56//! | `VYN_DEVICE_ID`   | Paired device id (WS only, E-01)                           |
57//! | `VYN_DEVICE_SECRET` | Paired device's own MAC secret (WS only, E-01)           |
58//!
59//! [`Plugin::run_ws`](crate::Plugin::run_ws) connects over WebSocket. A
60//! paired remote device sets `VYN_DEVICE_ID` + `VYN_DEVICE_SECRET` (from
61//! `vyn device connect`) instead of `VYN_JWT_SECRET` — the host master
62//! secret never has to leave the host.
63//!
64//! ## Protocol coverage
65//!
66//! Compression (`FLAG_COMPRESSED`), frame MACs (`FLAG_MAC_PRESENT`),
67//! fragmentation (`FLAG_FRAGMENTED`) and raw audio (`FLAG_RAW_BINARY`) are all
68//! handled — see [`VynkorClient`] for the transport API and [`framing`] for
69//! the shared wire-format primitives. Over WebSocket, compression and
70//! fragmentation are outbound-disabled to match the gateway's limits (R5-03).
71
72pub mod client;
73pub mod concurrent;
74pub mod confirmation_gate;
75pub mod framing;
76pub mod plugin;
77
78pub use client::VynkorClient;
79pub use concurrent::{
80    response_envelope, run_concurrent_loop, serve_concurrent, ConcurrentHandler, ResponseSink,
81};
82pub use confirmation_gate::{
83    send_confirmation, send_confirmation_request, ConfirmationGate, PendingAction,
84};
85pub use plugin::Plugin;
86pub use vynkor_wire::WireError as VynkorError;
87
88/// Frame-MAC primitives (HKDF session-key derivation, HMAC-SHA256 tags),
89/// shared with the kernel.
90pub use vynkor_wire::mac as frame_mac;
91
92/// Generated Protobuf types for the Vynkor protocol
93/// (`wire/proto/vynkor_protocol.proto`).
94pub mod proto {
95    pub use vynkor_wire::proto::vynkor::*;
96}