Crate worker

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:

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

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
});

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));

[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))

§RPC Support

workers-rs has experimental support for Workers RPC. For now, this relies on JavaScript bindings and may require some manual usage of wasm-bindgen.

Not all features of RPC are supported yet (or have not been tested), including:

Function arguments and return values
Class instances
Stub forwarding

§RPC Server

Writing an RPC server with workers-rs is relatively simple. Simply export methods using wasm-bindgen. These will be automatically detected by worker-build and made available to other Workers. See example.

§RPC Client

Creating types and bindings for invoking another Worker’s RPC methods is a bit more involved. You will need to write more complex wasm-bindgen bindings and some boilerplate to make interacting with the RPC methods more idiomatic. See example.

With manually written bindings, it should be possible to support non-primitive argument and return types, using serde-wasm-bindgen.

§Generating Client Bindings

There are many routes that can be taken to describe RPC interfaces. Under the hood, Workers RPC uses Cap’N Proto. A possible future direction is for Wasm guests to include Cap’N Proto serde support and speak directly to the RPC protocol, bypassing JavaScript. This would likely involve defining the RPC interface in Cap’N Proto schema and generating Rust code from that.

Another popular interface schema in the WebAssembly community is WIT. This is a lightweight format designed for the WebAssembly Component model. workers-rs includes an experimental code generator which allows you to describe your RPC interface using WIT and generate JavaScript bindings as shown in the rpc-client example. The easiest way to use this code generator is using a build script as shown in the example. This code generator is pre-alpha, with no support guarantee, and implemented only for primitive types at this time.

Re-exports§

pub use worker_kv as kv;
pub use crate::d1::*;
pub use crate::durable::*;

Modules§

crypto
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§

AbortController: An interface that allows you to abort in-flight Fetch requests.
AbortSignal: An interface representing a signal that can be passed to cancellable operations, primarily a Fetch request.
Ai
BatchMessageBuilder
BatchSendMessage
Body: Requires http feature. A convenience Body type which wraps web_sys::ReadableStream and implements http_body::Body
Bucket: An instance of the R2 bucket binding.
ByteStream
Cache: Provides access to the Cache API. Because match is a reserved keyword in Rust, the match method has been renamed to get.
Cf: In addition to the methods on the Request struct, the Cf struct on an inbound Request contains information about the request provided by Cloudflare’s edge.
CfProperties: https://developers.cloudflare.com/workers/runtime-apis/request#requestinitcfproperties
CfResponseProperties
CloseEvent: Wrapper/Utility struct for the web_sys::CloseEvent
Conditional: You can pass an Conditional object to GetOptionsBuilder. If the condition check fails, the body will not be returned. This will make get have lower latency.
ConnectionBuilder
Context: A context bound to a fetch event.
Cors: Cors struct, holding cors configuration
CreateMultipartUploadOptionsBuilder: Options for configuring the create_multipart_upload operation.
Date: The equivalent to a JavaScript Date Object.
Delay: A Future for asynchronously waiting.
DynamicDispatcher: A binding for dispatching events to Workers inside of a dispatch namespace by their name. This allows for your worker to directly invoke many workers by name instead of having multiple service worker bindings.
Env: Env contains any bindings you have associated with the Worker when you uploaded it.
EventStream: A Stream that yields WebsocketEvents emitted by the inner WebSocket. The stream is guaranteed to always yield a WebsocketEvent::Close as the final non-none item.
Fetcher: A struct for invoking fetch events to other Workers.
File: A File representation used with FormData.
FixedLengthStream
FormData: A FormData representation of the request body, providing access to form encoded fields and files.
GetOptionsBuilder: Options for configuring the get operation.
Headers: A Headers representation used in Request and Response objects.
HttpMetadata: Metadata that’s automatically rendered into R2 HTTP API endpoints.
Hyperdrive
ListOptionsBuilder: Options for configuring the list operation.
Message: A message that is sent to a consumer Worker.
MessageBatch: A batch of messages that are sent to a consumer Worker.
MessageBuilder
MessageEvent: Wrapper/Utility struct for the web_sys::MessageEvent
MessageIter
MinifyConfig: Configuration options for Cloudflare’s minification features: https://www.cloudflare.com/website-optimization/
MultipartUpload
Object: Object is created when you put an object into a Bucket. Object represents the metadata of an object based on the information provided by the uploader. Every object that you put into a Bucket will have an Object created.
ObjectBody: The data contained within an Object.
Objects: A series of Objects returned by list.
PutOptionsBuilder: Options for configuring the put operation.
Queue
QueueRetryOptions: Optional configuration when marking a message or a batch of messages for retry.
QueueRetryOptionsBuilder
QueueSendBatchOptions
QueueSendOptions
RateLimiter
RawMessage: A message that is sent to a consumer Worker.
RawMessageBuilder
RawMessageIter
Request: A Request representation for handling incoming and creating outbound HTTP requests.
RequestInit: Optional options struct that contains settings to apply to the Request.
Response: A Response representation for working with or returning a response to a Request.
ResponseBuilder
RouteContext: Container for a route’s parsed parameters, data, and environment bindings from the Runtime (such as KV Stores, Durable Objects, Variables, and Secrets).
RouteParams: Represents the URL parameters parsed from the path, e.g. a route with “/user/:id” pattern would contain a single “id” key.
Router: A path-based HTTP router supporting exact-match or wildcard placeholders and shared data.
ScheduleContext
ScheduledEvent: Schedule
Secret: A string value representing a binding to a secret in a Worker.
SendMessage: A wrapper type used for sending message.
Socket: Represents an outbound TCP connection from your Worker.
SocketAddress: The host and port that you wish to connect to.
SocketInfo
SocketOptions: Used to configure outbound TCP connections.
TlsClientAuth: Only set when using Cloudflare Access or API Shield
UploadedPart: UploadedPart represents a part that has been uploaded. UploadedPart objects are returned from upload_part operations and must be passed to the complete operation.
Url: A parsed URL record.
WebSocket: Wrapper struct for underlying worker-sys WebSocket
WebSocketPair: Struct holding the values for a JavaScript WebSocketPair
WorkerVersionMetadata

Enums§

CacheDeletionOutcome: Successful outcomes when attempting to delete a Response from the cache
CacheKey: The String or Request object used as the lookup key. Strings are interpreted as the URL for a new Request object.
Data
DateInit: Initialize a Date by constructing this enum.
EncodeBody: Control how the body of the response will be encoded by the runtime before it is returned to the user.
Error: All possible Error variants that might be encountered while working with a Worker.
Fetch: Construct a Fetch call from a URL string or a Request object. Call its send method to execute the request.
FormEntry: Representing the options any FormData value can be, a field or a file.
Include
Method: A Method representation used on Request objects.
PolishConfig: Configuration options for Cloudflare’s image optimization feature: https://blog.cloudflare.com/introducing-polish-automatic-image-optimizati/
QueueContentType
Range
RequestRedirect
ResponseBody
SecureTransport: Secure transport options for outbound TCP connections.
WebsocketEvent: Events that can be yielded by a EventStream.

Traits§

EnvBinding
FromRequest: A trait used to represent any viable Request type that can be used in the Worker. The only requirement is that it be convertible from a web_sys::Request.
IntoResponse: A trait used to represent any viable Response type that can be used in the Worker. The only requirement is that it be convertible to a web_sys::Response.
MessageExt

Functions§

request_from_wasm: Requires http feature. Convert web_sys::Request to worker::HttpRequest
request_to_wasm: Requires http feature. Convert http::Request to web_sys::Request
response_from_wasm: Requires http feature. Convert web_sys::Response to worker::HttpResponse
response_to_wasm: Requires http feature. Convert generic http::Response<B> to web_sys::Response where B can be any http_body::Body

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§

durable_object
event: The event macro is used to denote a Worker handler, essentially binding from the JS runtime to a Rust function.
send: Convert an async function which is !Send to be Send.

Crate workerCopy item path