Assets binding overview
The Assets binding provides APIs available in Cloudflare Workers to interact with a collection of static assets. Static assets can be uploaded as part of a Worker project.
Cloudflare Workers · Runtime APIs · all subjects
bindings
175 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
Assets binding documentation location
The Assets binding documentation is located at /workers/static-assets/binding/ in the Cloudflare Workers documentation.
Durable Objects is a globally distributed coordination API with strongly consistent storage
Durable Objects provide a globally distributed coordination API that offers strongly consistent storage for Workers.
Dispatcher documentation location
Dispatcher configuration for dynamic dispatch in Workers for Platforms is documented at /cloudflare-for-platforms/workers-for-platforms/configuration/dynamic-dispatch/.
Dispatcher binding for Workers for Platforms
The Dispatcher binding allows you to let your customers deploy their own code to your platform and dynamically dispatch requests from your Worker to their Worker. It is a runtime binding available in the Workers API.
Environment Variables documentation location
The full documentation for Environment Variables is located at /workers/configuration/environment-variables/.
Environment Variables binding
Environment Variables is a Workers runtime binding that allows you to add string and JSON values to your Worker.
Hyperdrive runtime binding overview
Hyperdrive is a Workers runtime binding that allows you to connect to your existing database from Workers, turning your existing regional database into a globally distributed database.
Secrets documentation location
Detailed secrets configuration documentation is located at /workers/configuration/secrets/ in the Cloudflare Workers documentation.
Secrets binding overview
Secrets are encrypted values that can be added to a Worker. Access to secrets is provided through the Worker bindings system.
Service binding requires fully-qualified URL for new requests
When constructing a new Request manually to send through a Service binding, provide a valid and fully-qualified URL with a hostname. Do not use relative URLs or URLs without a hostname.
Service binding with manually constructed request example
Example of constructing a new request and sending through a Service binding: export default { async fetch(request, env) { let newRequest = new Request("https://valid-url.com", { method: "GET" }); let response = await env.WORKER_B.fetch(newRequest); return response; }};
Service binding configuration in wrangler.json
To declare a Service binding in wrangler.json, add an entry to the 'services' array with 'binding' (the name to use in code) and 'service' (the target Worker name) properties. Example: {"binding": "WORKER_B", "service": "worker_b"}
Service binding fetch method for Worker-to-Worker communication
A Worker can declare a Service binding to another Worker and forward a Request object to it by calling the fetch() method exposed on the binding object. The binding is declared in wrangler.json under the 'services' array with a 'binding' name and 'service' referencing the target Worker.
Service binding forward existing request example
Example of forwarding an existing request through a Service binding: export default { async fetch(request, env) { return await env.WORKER_B.fetch(request); }};
Service binding fetch() method usage
Call the fetch() method on a Service binding object to forward a request to the bound Worker. Example: await env.WORKER_B.fetch(request). The method is async and returns a Response.
Monitoring rate-limited requests using Workers Observability
Rate limiting bindings are not currently visible in the Cloudflare dashboard. To monitor rate-limited requests, you can use Workers Observability through Workers Logs and Traces to observe HTTP 429 responses returned by your Worker when rate limits are exceeded.
Rate limit best practices for key selection
The key for rate limiting should represent a unique characteristic of a user or class of user to rate limit on. Recommended choices include API keys from Authorization headers, URL paths or routes, specific query parameters, user IDs, and tenant IDs. It is not recommended to use IP addresses or locations (regions or countries) as keys, since many users may share a single IP address, especially on mobile networks or when using privacy-enabling proxies.
Monitoring rate-limited requests using Analytics Engine
You can add an Analytics Engine binding to your Worker and emit custom data points (for example, a `rate_limited` event) when `limit()` returns `{ success: false }`. This allows you to build dashboards and query rate limiting metrics over time.
Wrangler CLI version requirement for Rate Limiting API
You must use version 4.36.0 or later of the Wrangler CLI to use the Rate Limiting API.
TypeScript example: using Rate Limiting API
interface Env { MY_RATE_LIMITER: RateLimit; } export default { async fetch(request, env): Promise<Response> { const { pathname } = new URL(request.url) const { success } = await env.MY_RATE_LIMITER.limit({ key: pathname }) if (!success) { return new Response(`429 Failure – rate limit exceeded for ${pathname}`, { status: 429 }) } return new Response(`Success!`) } } satisfies ExportedHandler<Env>; This example demonstrates how to use the Rate Limiting API in TypeScript with proper type annotations.
JavaScript example: using Rate Limiting API
export default { async fetch(request, env) { const { pathname } = new URL(request.url) const { success } = await env.MY_RATE_LIMITER.limit({ key: pathname }) if (!success) { return new Response(`429 Failure – rate limit exceeded for ${pathname}`, { status: 429 }) } return new Response(`Success!`) } } This example demonstrates how to call the `limit()` method on a rate limiting binding and return a 429 response when the rate limit is exceeded.
Rate Limiting API is eventually consistent and permissive
The Rate Limiting API is designed to be permissive, eventually consistent, and not intended to be used as an accurate accounting system. When many requests come in with the same rate limit key, each isolate serves requests against its locally cached rate limit value. Very quickly, but not immediately, all requests count towards the rate limit within that Cloudflare location.
Rate Limiting API performance and caching
The Rate Limiting API in Workers is designed to be fast. The underlying counters are cached on the same machine that the Worker runs in and updated asynchronously in the background. When awaiting a call to `limit()`, you are not waiting on a network request, so the Rate Limiting API does not introduce meaningful latency to the Worker.
Rate limits are local to Cloudflare locations
Rate limits defined and enforced in a Worker are local to the Cloudflare location that the Worker runs in. For each unique key passed to a rate limiting binding, there is a unique limit counter per Cloudflare location. A rate limit exceeded in one location does not affect requests served in other locations.
Multiple rate limiting configurations for different tiers
You can define and configure multiple rate limiting configurations per Worker to enforce different limits for different types of customers or users. For example, you can define separate rate limiting bindings with different `namespace_id` values and `limit`/`period` settings for free tier users and paid tier users.
Shared rate limit state with same namespace_id
Two rate limiting bindings that share the same `namespace_id`, even across different Workers on the same account, share the same rate limit counters for a given key. To avoid sharing rate limit state between bindings, use a unique `namespace_id` for each binding.
Key parameter for rate limit() method
The `key` parameter passed to the `limit()` method can be any string value of your choosing. Common patterns include combining a string that uniquely identifies the actor (such as a user ID or customer ID) with a string that identifies a specific resource (such as an API route).
RateLimit.limit() method returns {success: boolean}
The `limit()` method on a rate limiting binding accepts a configuration object with a `key` field (any string value) and returns a promise resolving to an object with a `success` boolean field. When `success` is true, the request is within the rate limit. When false, the rate limit has been exceeded.
Rate limit period must be 10 or 60 seconds
The `simple.period` field in a rate limiting binding must be either 10 or 60 seconds. No other values are supported.
namespace_id must be a string containing an integer
The `namespace_id` field in a rate limiting binding must be specified as a string (for example, `"1001"`), even though it contains a positive integer. This is intentional. The namespace_id uniquely defines the rate limiting namespace within a Cloudflare account.
Rate Limiting API binding configuration in wrangler.toml
The Rate Limiting API is configured in wrangler.toml under the `ratelimits` array. Each rate limiting binding requires a `name` field (the binding name), a `namespace_id` field (a string containing a positive integer unique to the account), and a `simple` object containing `limit` (number of allowed requests) and `period` (10 or 60 seconds) fields.
Rate Limiting API backed by WAF rate limiting rules infrastructure
The Rate Limiting API is backed by the same infrastructure that serves Cloudflare WAF rate limiting rules, ensuring consistency and reliability.
Service bindings limits
Service bindings have the following limits: Each request to a Worker via a Service binding counts toward the subrequest limit. A single request has a maximum of 32 Worker invocations, and each call to a Service binding counts towards this limit; subsequent calls will throw an exception. Calling a service binding does not count towards simultaneous open connection limits.
Service binding RPC example with WorkerEntrypoint
Service bindings using RPC require extending the WorkerEntrypoint class. Worker B that exposes a public add method: import { WorkerEntrypoint } from "cloudflare:workers"; export default class WorkerB extends WorkerEntrypoint { async fetch() { return new Response(null, { status: 404 }); } async add(a, b) { return a + b; } }. Worker A that calls it: export default { async fetch(request, env) { const result = await env.WORKER_B.add(1, 2); return new Response(result); } }.
Service bindings deployment order requirement
Workers using Service bindings are deployed separately. When getting started and deploying for the first time, the target Worker (Worker B) must be deployed before Worker A. Otherwise, deployment of Worker A will fail because it declares a binding to Worker B, which does not yet exist. When making changes to existing Workers, deploy changes to Worker B first in a way compatible with Worker A, then deploy changes to Worker A, then remove any unused code.
Service bindings local development with wrangler dev
Local development is supported for Service bindings. For each Worker, open a new terminal and run wrangler dev in the relevant directory. When running wrangler dev, service bindings show as connected or not connected depending on whether Wrangler can find a running wrangler dev session for that Worker. Wrangler also supports running multiple Workers at once with one command by passing multiple -c flags like wrangler dev -c wrangler.json -c ../other-worker/wrangler.json. The first config is treated as the primary worker exposed over HTTP at http://localhost:8787. The remaining configs are treated as secondary and only accessible via service binding from the primary worker. This feature is experimental and subject to change.
Service bindings are asynchronous and must be awaited
The Service bindings API is asynchronous. You must await any method you call. If Worker A invokes Worker B via a Service binding and Worker A does not await the completion of Worker B, Worker B will be terminated early.
Service bindings use cases
Service bindings are commonly used to: (1) Provide a shared internal service to multiple Workers, such as deploying an authentication service as its own Worker and having separate Workers communicate with it via Service bindings. (2) Isolate services from the public Internet by deploying a Worker that is not reachable via the public Internet and can only be reached via an explicit Service binding. (3) Allow teams to deploy code independently, with Team A deploying their Worker on their own release schedule separate from Team B.
Service bindings support two communication interfaces: RPC and HTTP
Worker A can call Worker B in two ways: (1) RPC lets you communicate between Workers using function calls that you define, such as await env.BINDING_NAME.myMethod(arg1). This is recommended for most use cases. (2) HTTP lets you communicate between Workers by calling the fetch() handler from other Workers, sending Request objects and receiving Response objects back, such as env.BINDING_NAME.fetch(request).
Service bindings configuration in wrangler.json
Service bindings are configured in the Wrangler configuration file of the caller Worker. The configuration format is: { "services": [{ "binding": "<BINDING_NAME>", "service": "<WORKER_NAME>" }] }. The binding property is the name of the key exposed on the env object. The service property is the name of the target Worker to communicate with, which must be on the same Cloudflare account.
Service bindings do not incur additional costs
You can split apart functionality into multiple Workers using Service bindings without incurring additional costs.
Service bindings have zero latency overhead
Service bindings are fast with zero overhead or added latency. By default, both Workers run on the same thread of the same Cloudflare server. When Smart Placement is enabled, each Worker runs in the optimal location for overall performance.
Service bindings enable Worker-to-Worker communication without public URLs
Service bindings allow one Worker to call into another Worker without going through a publicly-accessible URL. Worker A can call methods on Worker B or forward requests from Worker A to Worker B.
Queues binding documentation location
The Queues runtime API for Workers is documented in the navigation page at /queues/configuration/javascript-apis/. Queues are used to send and receive messages with guaranteed delivery.
Accessing bindings through env object in fetch handler
Bindings are located on the env object, which is an argument to entrypoint handlers such as fetch. The env object can be accessed as: export default { async fetch(request, env) { return new Response(`Hi, ${env.NAME}`); } }
Local development bindings behavior
During local development, bindings connect to locally simulated resources by default. They can also be configured to connect to real, production resources using remote bindings.
patch_env context manager in Python
Python Workers use the patch_env context manager to override env values. Example: with patch_env(NAME='Bob'): log_name() will temporarily override NAME to 'Bob' within the context.
Bindings definition and purpose
Bindings allow Workers to interact with resources on the Cloudflare Developer Platform. They provide better performance and fewer restrictions when accessing resources from Workers compared to REST APIs. Bindings grant specific capabilities such as reading and writing files to an R2 bucket.
Best practice: create binding-dependent objects per request
Create new instances of objects that depend on bindings for each incoming request, not in global scope. This ensures the instance is always up-to-date with the latest binding values. Example: export default { fetch(request, env) { let client = new Client(env.MY_SECRET); } }
Pitfall: global scope pollution with bindings
You must be careful when creating derivatives of bindings in global scope. Anything created there might continue to exist despite making changes to underlying bindings. For example, an external client instance using a secret API key from env will retain the original value if created at global scope, even after the env secret is changed.
Binding reuse during deployment without code changes
When you deploy a change to your Worker and only change its bindings without changing the Worker's code, Cloudflare may reuse existing isolates that are already running your Worker. This improves performance but requires careful handling to avoid stale state in global scope.
I/O restrictions for env from global scope
Workers do not allow I/O from outside a request context. Even though env is accessible from top-level scope, not every binding's methods can be called there. Environment variables and secrets are accessible, and you can call env.NAMESPACE.get to get a Durable Object stub in top-level context. However, calling methods on the Durable Object stub, making calls to a KV store, and calling to other Workers will not work from global scope.
withEnv function for overriding env values
The withEnv function provides a mechanism for overriding values of env. Example: withEnv({ NAME: 'Bob' }, () => { logName(); }) will temporarily override NAME to 'Bob' within the callback. This is useful for testing code that relies on an imported env object.
Importing env from cloudflare:workers module
The env object can be imported from the 'cloudflare:workers' module for use in top-level global scope. Example: import { env } from 'cloudflare:workers'; console.log(`Hi, ${env.Name}`);
Accessing env as class property on DurableObject
In a DurableObject class, env is accessible as a class property using this.env. Example: export class MyDurableObject extends DurableObject { async sayHello() { return `Hi, ${this.env.NAME}!`; } }
Binding as permission and API combined
A binding is both a permission and an API in one piece. With bindings, you never have to add secret keys or tokens to your Worker to access resources on your Cloudflare account — the permission is embedded within the API itself and the underlying secret is never exposed to the Worker's code.
Stream binding purpose
The Stream binding allows Workers to upload, manage, and deliver video content with Cloudflare Stream.
Stream binding documentation location
The Cloudflare Stream binding documentation is located at /stream/manage-video-library/bindings/ and provides information about uploading, managing, and delivering video with Cloudflare Stream.
Secrets Store runtime binding type
Secrets Store is a runtime binding type that provides account-level secrets that can be added to Workers applications. It is currently in Beta status.