wasm_runner_sdk/

lib.rs

//! # 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
//!
//! ```ignore
//! 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:
//!
//! ```ignore
//! 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:
//!
//! ```ignore
//! use wasm_runner_sdk::prelude::*;
//!
//! if capabilities::has(Capability::Network) {
//!     let client = Client::new();
//!     let _ = client.get("https://example.com").send()?;
//! }
//! ```

#![allow(clippy::module_name_repetitions)]

pub mod abi;
pub mod capabilities;
pub mod extract;
pub mod handler;
pub mod http;
pub mod log;
pub mod request;
pub mod response;
pub mod router;

// Re-export commonly used types at the crate root
pub use extract::{
    Authorization, BearerToken, Body, BodyString, ContentType, Cookies, ExtractError, FromRequest,
    FullPath, Headers, Json as ExtractJson, MethodExtractor, Path, PathSegments, Query, QueryMap,
};
pub use handler::Handler;
pub use request::{Method, Request};
pub use response::{Html, IntoResponse, Json, Redirect, Response, StatusCode};
pub use router::{Param, Params, Router};
pub use capabilities as runtime_capabilities;
pub use capabilities::Capability;

// Re-export serde for user convenience
pub use serde;
pub use serde_json;

/// Prelude module for convenient imports.
///
/// Import everything you need with:
/// ```ignore
/// use wasm_runner_sdk::prelude::*;
/// ```
pub mod prelude {
    pub use crate::extract::{
        Authorization, BearerToken, Body, BodyString, ContentType, Cookies, ExtractError,
        FromRequest, FullPath, Headers, Json as ExtractJson, MethodExtractor, Path, PathSegments,
        Query, QueryMap,
    };
    pub use crate::handler::Handler;
    pub use crate::http::{Client, HttpError, HttpResponse};
    pub use crate::log::{error, info, warn, Level};
    pub use crate::request::{Method, Request};
    pub use crate::response::{Html, IntoResponse, Json, Redirect, Response, StatusCode};
    pub use crate::router::{Param, Params, Router};
    pub use crate::runtime_capabilities as capabilities;
    pub use crate::Capability;
    pub use crate::{log_error, log_info, log_warn, run, run_with_request};
    pub use serde::{Deserialize, Serialize};
    pub use serde_json;
}

/// Runs a handler function, extracting request data and sending the response.
///
/// This is the main entry point for handling requests. It:
/// 1. Creates a new Request from the host
/// 2. Calls the handler function with extracted data
/// 3. Converts the result to a Response
/// 4. Sends the response to the host
///
/// # Example
///
/// ```ignore
/// use wasm_runner_sdk::prelude::*;
///
/// fn my_handler() -> impl IntoResponse {
///     "Hello, World!"
/// }
///
/// #[no_mangle]
/// pub extern "C" fn _start() {
///     run(my_handler);
/// }
/// ```
pub fn run<H, Args>(handler: H)
where
    H: Handler<Args>,
    H::Output: IntoResponse,
{
    let mut request = Request::new();
    let method = request.method();
    let path = request.path().to_string();
    log_info!("Handling request {} {}", method, path);
    let response = handler.call(&mut request);
    response.into_response().send();
}

/// Runs a handler function with direct access to the request.
///
/// Use this when you need mutable access to the request within your handler.
///
/// # Example
///
/// ```ignore
/// use wasm_runner_sdk::prelude::*;
///
/// fn my_handler(req: &mut Request) -> impl IntoResponse {
///     let method = req.method();
///     let path = req.path();
///     format!("{} {}", method, path)
/// }
///
/// #[no_mangle]
/// pub extern "C" fn _start() {
///     run_with_request(my_handler);
/// }
/// ```
pub fn run_with_request<F, R>(handler: F)
where
    F: FnOnce(&mut Request) -> R,
    R: IntoResponse,
{
    let mut request = Request::new();
    let method = request.method();
    let path = request.path().to_string();
    log_info!("Handling request {} {}", method, path);
    let response = handler(&mut request);
    response.into_response().send();
}