Crate worker

source ·
Expand description

§Features

§d1

Allows the use of D1 bindings and query! macro.

§queue

Enables queue event type in [event] macro.

// Consume messages from a queue
#[event(queue)]
pub async fn main(message_batch: MessageBatch<MyType>, env: Env, _ctx: Context) -> Result<()> {
    Ok(())
}

§http

worker 0.0.21 introduced an http feature flag which starts to replace custom types with widely used types from the http crate.

This makes it much easier to use crates which use these standard types such as axum.

This currently does a few things:

  1. Introduce Body, which implements http_body::Body and is a simple wrapper around web_sys::ReadableStream.
  2. The req argument when using the [event(fetch)] macro becomes http::Request<worker::Body>.
  3. The expected return type for the fetch handler is http::Response<B> where B can be any http_body::Body<Data=Bytes>.
  4. The argument for Fetcher::fetch_request is http::Request<worker::Body>.
  5. The return type of Fetcher::fetch_request is http::Response<worker::Body>.

The end result is being able to use frameworks like axum directly (see example):

pub async fn root() -> &'static str {
    "Hello Axum!"
}

fn router() -> Router {
    Router::new().route("/", get(root))
}

#[event(fetch)]
async fn fetch(
    req: HttpRequest,
    _env: Env,
    _ctx: Context,
) -> Result<http::Response<axum::body::Body>> {
    Ok(router().call(req).await?)
}

We also implement try_from between worker::Request and http::Request<worker::Body>, and between worker::Response and http::Response<worker::Body>. This allows you to convert your code incrementally if it is tightly coupled to the original types.

§Send Helpers

A number of frameworks (including axum) require that objects that they are given (including route handlers) can be sent between threads (i.e are marked as Send). Unfortuntately, objects which interact with JavaScript are frequently not marked as Send. In the Workers environment, this is not an issue, because Workers are single threaded. There are still some ergonomic difficulties which we address with some wrapper types:

  1. send::SendFuture - wraps any Future and marks it as Send:
// `fut` is `Send`
let fut = send::SendFuture::new(async move {
    // `JsFuture` is not `Send`
    JsFuture::from(promise).await
});
  1. send::SendWrapper - Marks an arbitrary object as Send and implements Deref and DerefMut, as well as Clone, Debug, and Display if the inner type does. This is useful for attaching types as state to an axum Router:
// `KvStore` is not `Send`
let store = env.kv("FOO")?;
// `state` is `Send`
let state = send::SendWrapper::new(store);
let router = axum::Router::new()
    .layer(Extension(state));
  1. [worker::send] - Macro to make any async function Send. This can be a little tricky to identify as the problem, but axum’s [debug_handler] macro can help, and looking for warnings that a function or object cannot safely be sent between threads.
// This macro makes the whole function (i.e. the `Future` it returns) `Send`.
#[worker::send]
async fn handler(Extension(env): Extension<Env>) -> Response<String> {
    let kv = env.kv("FOO").unwrap()?;
    // Holding `kv`, which is not `Send` across `await` boundary would mark this function as `!Send`
    let value = kv.get("foo").text().await?;
    Ok(format!("Got value: {:?}", value));
}

let router = axum::Router::new()
    .route("/", get(handler))

Re-exports§

Modules§

  • d1
    Requires d1 feature.
  • durable
    Durable Objects provide low-latency coordination and consistent storage for the Workers platform. A given namespace can support essentially unlimited Durable Objects, with each Object having access to a transactional, key-value storage API.
  • postgres_tls
    Implements TlsConnect for Socket to enable tokio_postgres connections to databases using TLS.
  • send
    This module provides utilities for working with JavaScript types which do not implement Send, in contexts where Send is required. Workers is guaranteed to be single-threaded, so it is safe to wrap any type with Send and Sync traits.
  • ws_events

Macros§

  • console_debug
    When debugging your Worker via wrangler dev, wrangler tail, or from the Workers Dashboard, anything passed to this macro will be printed to the terminal or written to the console.
  • console_error
    When debugging your Worker via wrangler dev, wrangler tail, or from the Workers Dashboard, anything passed to this macro will be printed to the terminal or written to the console.
  • console_log
    When debugging your Worker via wrangler dev, wrangler tail, or from the Workers Dashboard, anything passed to this macro will be printed to the terminal or written to the console.
  • console_warn
    When debugging your Worker via wrangler dev, wrangler tail, or from the Workers Dashboard, anything passed to this macro will be printed to the terminal or written to the console.
  • query
    Requires d1 feature. Prepare a D1 query from the provided D1Database, query string, and optional query parameters.

Structs§

Enums§

Traits§

Functions§

Type Aliases§

  • HttpRequest
    Requires http feature. Type alias for http::Request<worker::Body>.
  • HttpResponse
    Requires http feature. Type alias for http::Response<worker::Body>.
  • Result
  • Var
    A string value representing a binding to an environment variable in a Worker.

Attribute Macros§