workers-rs Documentation

To test AbortSignal behavior, you can use a local slow Node.js server to simulate delayed responses and then invoke the Worker via wrangler dev.

1. Start a local slow server

Run the provided Node server to simulate delays. You can specify a port and a delay in milliseconds:

node slow-server.mjs 3000

2. Start the Worker

Navigate to the abort-signal example directory and start the development server:

npx wrangler dev

3. Verify behavior with curl

Test immediate abort:

curl "http://localhost:8787/abort?url=http://localhost:3000"
# Expected output: "Aborted: ..."

Test request timeout (e.g., 500ms timeout against a 5s delay):

curl "http://localhost:8787/timeout?url=http://localhost:3000&timeout=500"
# Expected output: "Request timed out after 500ms"

Test successful response within timeout (e.g., 2000ms timeout against a 100ms delay):

curl "http://localhost:8787/timeout?url=http://localhost:3000/delay/100&timeout=2000"
# Expected output: "Got response: {\"delayed_ms\":100,\"message\":\"slow response\"}"

By default, Rust panics terminate the WebAssembly instance. Using the --panic-unwind flag with worker-build converts panics into JavaScript PanicError exceptions, allowing the Worker to continue serving subsequent requests.

Requirements & Behavior:

• Requires the nightly Rust toolchain.
• Rebuilds std with -Zbuild-std=std,panic_unwind and -Cpanic=unwind.
• Enables wasm-bindgen panic catching.
• Automatically reinitializes the instance after a hard abort (e.g., OOM or stack overflow).

Unwind Safety: When using panic=unwind, exported function arguments and closure captures must satisfy the UnwindSafe trait. If you pass closures to JavaScript via Closure::new, you may need to wrap non-unwind-safe captures (like RefCell<T>) in std::panic::AssertUnwindSafe.

# Running worker-build directly
worker-build --panic-unwind

# In wrangler.toml
[build]
command = "cargo install worker-build && worker-build --release --panic-unwind"

use std::cell::Cell;
use std::panic::AssertUnwindSafe;
use wasm_bindgen::prelude::*;

let counter = Cell::new(0u32);
let counter_ref = AssertUnwindSafe(&counter);
let closure = Closure::new(move || {
    counter_ref.set(counter_ref.get() + 1);
});

Durable Objects can use SQLite for persistent relational storage.

1. Enable SQLite: In your wrangler.toml migration, use new_sqlite_classes instead of new_classes.
2. Access Storage: Use state.storage().sql() to get a SqlStorage instance.
3. Execute SQL: Use .exec(query, params) to run SQL commands.

#[durable_object]
pub struct SqlCounter {
    sql: SqlStorage,
}

impl DurableObject for SqlCounter {
    fn new(state: State, _env: Env) -> Self {
        let sql = state.storage().sql();
        sql.exec("CREATE TABLE IF NOT EXISTS counter(value INTEGER);", None)
            .expect("create table");
        Self { sql }
    }

    async fn fetch(&self, _req: Request) -> Result<Response> {
        // ... use self.sql.exec() to query and update
        Response::ok(format!("SQL counter is now {}", next))
    }
}

wrangler.toml configuration:

[durable_objects]
bindings = [
  { name = "SQL_COUNTER", class_name = "SqlCounter" }
]

[[migrations]]
tag = "v1"
new_sqlite_classes = ["SqlCounter"]

D1 databases are in alpha and require the d1 feature flag in your Cargo.toml.

To use D1, access the database via env.d1("binding_name")?. You can then prepare statements, bind parameters, and execute queries (e.g., .first::<T>(None).await?) to retrieve data mapped to Rust structs.

# Cargo.toml
worker = { version = "x.y.z", features = ["d1"] }

use worker::*;

#[derive(Deserialize)]
struct Thing {
	thing_id: String,
	desc: String,
	num: u32,
}

#[event(fetch, respond_with_errors)]
pub async fn main(request: Request, env: Env, _ctx: Context) -> Result<Response> {
	Router::new()
		.get_async("/:id", |_, ctx| async move {
			let id = ctx.param("id").unwrap()?;
			d1 = ctx.env.d1("things-db")?;
			let statement = d1.prepare("SELECT * FROM things WHERE thing_id = ?1");
			let query = statement.bind(&[id])?;
			let result = query.first::<Thing>(None).await?;
			match result {
				Some(thing) => Response::from_json(&thing),
				None => Response::error("Not found", 404),
			}
		})
		.run(request, env)
		.await
}