omnia-runtime-macro

Procedural macros for generating WebAssembly Component Runtime infrastructure.

Overview

This crate provides the runtime! macro that generates the necessary runtime infrastructure for executing WebAssembly components with WASI capabilities. Instead of manually managing feature flags and conditional compilation, you declaratively specify which WASI interfaces and backends your runtime needs.

Usage

Add omnia to your dependencies (the runtime! macro is re-exported from the omnia crate):

[dependencies]
omnia = { workspace = true }

Then use the runtime! macro to generate your runtime infrastructure:

use omnia::runtime;

// Import the backend types you want to use
use omnia_wasi_http::WasiHttpCtx;
use omnia_wasi_otel::DefaultOtel;
use be_mongodb::Client as MongoDb;
use be_nats::Client as Nats;
use be_azure::Client as Azure;

// Generate runtime infrastructure
runtime!({
    "http": WasiHttpCtx,
    "otel": DefaultOtel,
    "blobstore": MongoDb,
    "keyvalue": Nats,
    "messaging": Nats,
    "vault": Azure
});

// The macro generates:
// - RuntimeContext struct with backend connections
// - RuntimeStoreCtx struct with per-instance contexts
// - State trait implementation
// - WASI view trait implementations
// - runtime_run() function

Configuration Format

The macro accepts a map-like syntax:

runtime!({
    "interface_name": BackendType,
    // ...
});

Supported Interfaces

http: HTTP client and server
- Backend: WasiHttpCtx (marker type, no backend connection needed)
otel: OpenTelemetry observability
- Backend: DefaultOtel (connects to OTEL collector)
blobstore: Object/blob storage
- Backends: MongoDb or Nats
keyvalue: Key-value storage
- Backends: Nats or Redis
messaging: Pub/sub messaging
- Backends: Nats or Kafka
vault: Secrets management
- Backend: Azure (Azure Key Vault)
sql: SQL database
- Backend: Postgres
identity: Identity and authentication
- Backend: Azure (Azure Identity)
websocket: WebSocket connections
- Backend: WebSocketCtxImpl (default implementation for development use)

Generated Code

The macro generates the following:

RuntimeContext

A struct holding pre-instantiated components and backend connections:

#[derive(Clone)]
struct RuntimeContext {
    instance_pre: InstancePre<RuntimeStoreCtx>,
    // ... backend fields
}

RuntimeStoreCtx

Per-instance data shared between the WebAssembly runtime and host functions:

pub struct RuntimeStoreCtx {
    pub table: ResourceTable,
    pub wasi: WasiCtx,
    // ... interface context fields
}

State Trait Implementation

Implements the State trait from the runtime crate, providing methods to create new store contexts and access the pre-instantiated component.

WASI View Implementations

Implements view traits for each configured WASI interface, allowing the WebAssembly guest to call host functions.

`runtime_run()` Function

A public async function that:

Loads runtime configuration
Compiles the WebAssembly component
Links WASI interfaces
Connects to backends
Starts server interfaces (HTTP, messaging, WebSocket)

Example: Custom Initiator Configuration

You can create different runtime configurations for different use cases:

// Minimal HTTP server
mod http_runtime {
    use omnia_wasi_http::WasiHttpCtx;

    omnia::runtime!({
        "http": WasiHttpCtx
    });
}

// Full-featured runtime
mod full_runtime {
    use omnia_wasi_http::WasiHttpCtx;
    use omnia_wasi_otel::DefaultOtel;
    use be_nats::Client as Nats;

    omnia::runtime!({
        "http": WasiHttpCtx,
        "otel": DefaultOtel,
        "keyvalue": Nats,
        "messaging": Nats,
        "blobstore": Nats
    });
}

Now you can declaratively specify your configuration:

mod omnia_runtime {
    omnia::runtime!({
        "http": WasiHttpCtx,
        "otel": DefaultOtel,
        "blobstore": MongoDb,
        "keyvalue": Nats,
        "messaging": Nats,
        "vault": Azure
    });
}

This provides:

Better readability: The configuration is explicit and self-documenting
Less boilerplate: No need for complex feature flag combinations
Type safety: Backend types are checked at compile time
Flexibility: Easy to create multiple runtime configurations in the same binary

License

MIT OR Apache-2.0

omnia-runtime-macro 0.28.0