Crate flaron_sdk 

flaron-sdk

Rust SDK for building flares - Wasm functions that run on the Flaron CDN edge. A flare receives an HTTP request (or WebSocket event) at the nearest edge, runs your Rust code in a sandboxed Wasm runtime, and returns a response with single-digit-millisecond latency.

Quick start

# Cargo.toml
[package]
name = "my-flare"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
flaron-sdk = "0.1"

// src/lib.rs
use flaron_sdk::{request, response, FlareAction};

flaron_sdk::handle_request!(my_flare);

fn my_flare() -> FlareAction {
    let body = format!("hello from {} {}", request::method(), request::url());
    response::set_status(200);
    response::set_header("content-type", "text/plain");
    response::set_body(body.as_bytes());
    FlareAction::Respond
}

Build with:

cargo build --release --target wasm32-unknown-unknown

Then deploy target/wasm32-unknown-unknown/release/my_flare.wasm to Flaron via the dashboard or flaronctl.

What’s in the SDK

Module	What it does
request	Read inbound request (method, URL, headers, body)
response	Write outbound response (status, headers, body)
beam	Outbound HTTP from the edge (beam::fetch)
spark	Per-site KV with TTL, persisted to disk on the edge
plasma	Cross-edge CRDT KV - counters, presence, leaderboards
secrets	Read domain-scoped secrets allowlisted for this flare
crypto	Hash, HMAC, AES-GCM encrypt/decrypt, JWT signing, RNG
encoding	Base64, hex, URL encode/decode helpers
id	UUID v4/v7, ULID, KSUID, Nanoid, Snowflake generators
time	Timestamps in unix / ms / ns / RFC3339 / HTTP / ISO8601
logging	Structured logs surfaced via the edge node’s slog stream
ws	WebSocket: send, close, read events from open/message/close

Memory model

Each flare invocation gets a fresh 256 KiB bump arena that the host writes into via the guest’s exported alloc function. The SDK resets the arena at the top of every invocation so memory is reclaimed automatically - you never need to free anything yourself.

The recommended entrypoint is the handle_request! macro for HTTP flares and ws_handlers! for WebSocket flares - both wire up the alloc export, reset the arena on every invocation, and call your handler. Use export_alloc! + reset_arena manually only when you need to define the host exports yourself.

Re-exports

pub use beam::BeamError;

pub use beam::FetchOptions;

pub use beam::FetchResponse;

pub use crypto::CryptoError;

pub use crypto::RandomBytesError;

pub use plasma::PlasmaError;

pub use spark::SparkEntry;

pub use spark::SparkError;

pub use spark::SparkPullError;

pub use ws::WsSendError;

Modules

beam

Outbound HTTP from inside a flare via the host’s beam_fetch.

crypto

Cryptographic primitives provided by the host.

encoding

Encoding helpers (base64, hex, URL) backed by the host runtime.

id

Unique-ID generators provided by the host.

logging

Structured logging from inside a flare.

plasma

Plasma - cross-edge CRDT key/value store.

request

Read the inbound HTTP request being handled by the flare.

response

Build the outbound HTTP response.

secrets

Read domain-scoped secrets allowlisted for this flare.

spark

Spark - per-site KV store with TTL, persisted to disk on the edge.

time

Edge-side timestamps in a variety of formats.

ws

WebSocket primitives for flares that handle WebSocket upgrades.

Macros

export_alloc

Export the guest alloc function the flaron host runtime requires.

handle_request

Wire up an HTTP flare entrypoint with a single line.

ws_handlers

Wire up a WebSocket flare entrypoint with a single line.

Enums

FlareAction

Action returned by an handle_request() export to tell the host how to proceed once the flare’s body has run.

Functions

guest_alloc

Guest memory allocator the host calls (via the alloc export generated by crate::export_alloc!) to write return values into the WASM linear memory. Hands out 8-byte aligned slices from the bump arena.

reset_arena

Reset the bump arena. Call this at the top of every guest export so the next host invocation starts with a fresh 256 KiB scratch space.