Crate wasm_runner_sdk

Expand description

§wasm-runner-sdk

High-level SDK for building WASM modules for wasm-runner.

Note: This crate is highly experimental and the APIs may change without notice.

This SDK provides an axum-like API for handling HTTP requests in WASM, with automatic extraction of request data and ergonomic response building.

§Quick Start

use wasm_runner_sdk::prelude::*;

#[derive(Deserialize)]
struct HelloQuery {
    name: Option<String>,
}

fn handler(Query(params): Query<HelloQuery>) -> impl IntoResponse {
    let name = params.name.as_deref().unwrap_or("World");
    Json(serde_json::json!({
        "message": format!("Hello, {}!", name)
    }))
}

#[no_mangle]
pub extern "C" fn _start() {
    run(handler);
}

§Extractors

Extractors allow you to extract data from requests in a type-safe way:

Query<T> - Extract query parameters as a struct
Path<T> - Extract path segments
Json<T> - Extract JSON body
Body - Extract raw body bytes
Headers - Extract all headers
Cookies - Extract cookies
BearerToken - Extract Bearer token from Authorization header

§Responses

Any type implementing IntoResponse can be returned from a handler:

String / &str - Plain text response
Json<T> - JSON response
Html<T> - HTML response
Response - Full control over the response
StatusCode - Empty response with status
(StatusCode, T) - Response with custom status
Result<T, E> - Ok returns T, Err returns E
Option<T> - Some returns T, None returns 404

§HTTP Client

Make outbound HTTP requests using the http module:

use wasm_runner_sdk::http::Client;

let client = Client::new();
let response = client.get("https://api.example.com/data").send()?;
let data: MyData = response.json()?;

§Capabilities

Query the enabled capabilities at runtime:

use wasm_runner_sdk::prelude::*;

if capabilities::has(Capability::Network) {
    let client = Client::new();
    let _ = client.get("https://example.com").send()?;
}

Re-exports§

pub use extract::Authorization;
pub use extract::BearerToken;
pub use extract::Body;
pub use extract::BodyString;
pub use extract::ContentType;
pub use extract::Cookies;
pub use extract::ExtractError;
pub use extract::FromRequest;
pub use extract::FullPath;
pub use extract::Headers;
pub use extract::Json as ExtractJson;
pub use extract::MethodExtractor;
pub use extract::Path;
pub use extract::PathSegments;
pub use extract::Query;
pub use extract::QueryMap;
pub use handler::Handler;
pub use request::Method;
pub use request::Request;
pub use response::Html;
pub use response::IntoResponse;
pub use response::Json;
pub use response::Redirect;
pub use response::Response;
pub use response::StatusCode;
pub use router::Param;
pub use router::Params;
pub use router::Router;
pub use capabilities as runtime_capabilities;
pub use capabilities::Capability;
pub use serde;
pub use serde_json;

Modules§

abi: Low-level ABI bindings to the wasm-runner host.
capabilities: Runtime capability queries for the current deployment.
extract: Request extractors for handler functions.
handler: Handler trait and implementations for request handlers.
http: HTTP client for making outbound requests.
log: Logging utilities for WASM modules.
prelude: Prelude module for convenient imports.
request: HTTP request types and accessors.
response: HTTP response types and the IntoResponse trait.
router: HTTP router for dispatching requests to handlers.

Macros§

log_error: Logs a formatted error message.
log_info: Logs a formatted info message.
log_warn: Logs a formatted warning message.

Functions§

run: Runs a handler function, extracting request data and sending the response.
run_with_request: Runs a handler function with direct access to the request.