Skip to main content

Crate vynkor_sdk

Crate vynkor_sdk 

Source
Expand description

§Vynkor Rust SDK

Write Vynkor plugins in Rust. A plugin is a separate OS process that talks to the Vynkor kernel using the Vynkor wire protocol (length-prefixed frames carrying Protobuf envelopes; see docs/FRAMING.md in the Vynkor repository) over a Unix domain socket or — for remote devices — the kernel’s WebSocket gateway.

§Quick start

use vynkor_sdk::{Plugin, VynkorClient};
use vynkor_sdk::proto::{envelope, ActionResponse, ActionStatus, Envelope, PluginManifest};
use vynkor_sdk::VynkorError;

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>, VynkorError> {
        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<(), VynkorError> {
    EchoPlugin.run().await
}

§Environment

VariableMeaning
VYN_SOCKET_PATHKernel UDS path (default: per-user runtime dir)
VYN_JWT_TOKENJWT presented at registration (secured kernels)
VYN_JWT_SECRETShared secret; enables per-frame HMAC-SHA256 tags
VYN_DEVICE_IDPaired device id (WS only, E-01)
VYN_DEVICE_SECRETPaired device’s own MAC secret (WS only, E-01)

Plugin::run_ws connects over WebSocket. A paired remote device sets VYN_DEVICE_ID + VYN_DEVICE_SECRET (from vyn device connect) instead of VYN_JWT_SECRET — the host master secret never has to leave the host.

§Protocol coverage

Compression (FLAG_COMPRESSED), frame MACs (FLAG_MAC_PRESENT), fragmentation (FLAG_FRAGMENTED) and raw audio (FLAG_RAW_BINARY) are all handled — see VynkorClient for the transport API and framing for the shared wire-format primitives. Over WebSocket, compression and fragmentation are outbound-disabled to match the gateway’s limits (R5-03).

Re-exports§

pub use client::VynkorClient;
pub use concurrent::response_envelope;
pub use concurrent::run_concurrent_loop;
pub use concurrent::serve_concurrent;
pub use concurrent::ConcurrentHandler;
pub use concurrent::ResponseSink;
pub use confirmation_gate::send_confirmation;
pub use confirmation_gate::send_confirmation_request;
pub use confirmation_gate::ConfirmationGate;
pub use confirmation_gate::PendingAction;
pub use plugin::Plugin;

Modules§

client
Async client for the Vynkor kernel IPC socket.
concurrent
Concurrent message loop for hot-path plugins.
confirmation_gate
Confirmation gate (D-09): plugin-level permission separation for high-risk actions.
frame_mac
Frame-MAC primitives (HKDF session-key derivation, HMAC-SHA256 tags), shared with the kernel.
framing
Re-exports of the kernel framing layer — the single source of truth for the Vynkor wire format (docs/FRAMING.md). The SDK never redefines flag constants or frame parsing; it shares the kernel implementation so the two sides cannot drift.
plugin
The Plugin trait: implement it, call Plugin::run, and the SDK handles connection, registration, auth, the receive loop, Ping/Pong, event acknowledgement, and graceful shutdown.
proto
Generated Protobuf types for the Vynkor protocol (wire/proto/vynkor_protocol.proto).

Enums§

VynkorError