vaiexia-core

The interaction contract and transport toolkit for the VAIEXIA ecosystem.

---

What it is

vaiexia-core defines the shared contract that every VAIEXIA component speaks: versioned message envelopes, severity-tagged diagnostics, machine-auth types, and the transport abstraction. It ships a fault-injecting in-memory mock so that higher-level crates and applications can be fully tested without a real network.

It does not contain any business logic, server implementations, or real network transports — those live in separate crates above this one.

---

Layer model

L2  client / server        (vaiexia-core::client, vaiexia-core::server)
        │ depend on transport traits (DIP)
L1  transport abstraction  (vaiexia-core::transport)
        │ + MockTransport for tests (feature = "mock")
L0  foundation             (version, diagnostic, error, auth, protocol)
        │ pure, wasm-safe, no I/O

Each layer depends only on the layers below it. Real HttpTransport / WsTransport implementations arrive in a later release as an optional L1 backend.

---

Module map

Module	Contents
version	ProtoVersion, compatibility(), Compatibility
diagnostic	Diagnostic, Severity, codes constants
error	CoreError, Result
auth	Capability, Scope, ScopeSet, Subject, Credentials, Verifier
protocol	Request, Response, Outcome, Method, Topic, Event, RequestId
transport	Requester, Subscriber, Connection, Transport traits; BackoffPolicy
transport::mock	MockTransport (feature = "mock" or #[cfg(test)])
server	Service, ServiceBuilder
client	Client, ClientBuilder
prelude	Re-exports of the most commonly used items

---

Quick example

use vaiexia_core::prelude::*;
use vaiexia_core::transport::mock::MockTransport;
use std::sync::Arc;

// --- server side ---
struct OpenVerifier;
impl Verifier for OpenVerifier {
    fn verify(
        &self,
        _cap: Option<&Capability>,
        _method: &Method,
    ) -> vaiexia_core::error::Result<Subject> {
        Ok(Subject {
            id: SubjectId::new("anonymous"),
            scopes: ScopeSet::from_iter(["server.read"]),
        })
    }
}

let svc = Arc::new(
    Service::builder()
        .verifier(OpenVerifier)
        .method(
            Method::new("server.ping").unwrap(),
            |_params, _subject| async { Ok(serde_json::json!("pong")) },
        )
        .build(),
);

// --- wire mock transport ---
let mock = MockTransport::new();
let svc2 = svc.clone();
mock.on_request(move |req| {
    let s = svc2.clone();
    let r = req.clone();
    Ok(futures::executor::block_on(async move { s.handle(r).await }))
});

// --- client side ---
use vaiexia_core::auth::StaticCredentials;
let client = Client::builder()
    .credentials(StaticCredentials(Capability::new("my-token")))
    .connect(mock);

// async context:
// let resp = client.call(Method::new("server.ping").unwrap(), serde_json::Value::Null).await?;
// assert!(matches!(resp.outcome, Outcome::Ok(_)));

---

Feature flags

Flag	Effect
mock	Exposes vaiexia_core::transport::mock::MockTransport to external crates.
http	HttpTransport — unary request/response over HTTP POST /rpc.
ws	WsTransport — event subscriptions over WebSocket (reconnect + heartbeat).
server-http	serve() — run a Service over HTTP + WebSocket via an axum listener.

MockTransport is also available to code inside this crate via #[cfg(test)] without enabling the feature.

Run unit tests only:

cargo test

Run unit tests and integration tests (requires the mock transport):

cargo test --features mock

---

Transports

Concrete network transports are provided behind cargo features:

• HttpTransport (http) — unary request/response over HTTP POST /rpc (JSON, HTTP/1.1→2). Implements Requester.
• WsTransport (ws) — event subscriptions over a WebSocket with automatic reconnect (exponential backoff), heartbeat liveness, transparent re-subscribe after a drop, and seq-based dedup. Implements Subscriber + Connection.
• serve() (server-http) — run a Service over HTTP + WebSocket from one axum listener; ServeHandle::shutdown() force-closes connections so clients reconnect.

// server
let handle = vaiexia_core::server::serve(service, "127.0.0.1:8080").await?;
// client — unary over HTTP
let resp = HttpTransport::new(format!("http://{}", handle.addr())).request(req).await?;
// client — event stream over WebSocket
let mut logs = WsTransport::connect(format!("ws://{}/ws", handle.addr())).await?
    .subscribe(&Topic::new("server.logs")).await?;

Wasm

HttpTransport and WsTransport also build for wasm32-unknown-unknown under --features wasm, backed by the browser fetch and WebSocket APIs (via gloo-net) with the same public API — so the panel links core in the browser and writes target-agnostic code. Build it with:

cargo build --target wasm32-unknown-unknown --features wasm

The L1 trait surface (Requester, Subscriber, Connection) is stable, so a future custom TCP/QUIC transport slots in without touching consumers.

---

License

Licensed under either of:

• MIT license (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.