Add warning about polluting global scope with bindings derivatives

[GregBrimble]

No description provided.

[cloudflare-pages]

Deploying cloudflare-docs with    Cloudflare Pages

Latest commit:	76432dc
Status:	✅  Deploy successful!
Preview URL:	https://e0b5bd7c.cloudflare-docs-7ou.pages.dev
Branch Preview URL:	https://add-warning-about-polluting.cloudflare-docs-7ou.pages.dev

View logs

[github-actions]

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/workers/runtime-apis/bindings/	https://add-warning-about-polluting.cloudflare-docs-7ou.pages.dev/workers/runtime-apis/bindings/

[irvinebroque]

@kodster28 this is good addition from @GregBrimble — is a fun tricky one to explain well. taking a crack but eyes helpful

[irvinebroque]

Suggested change

When creating a new Worker [version or deployment](/workers/configuration/versions-and-deployments/) and you only include changes to bindings (i.e. you don't change the code of the Worker), be aware that the any currently running Worker isolates may stay "hot" for a potentially long time if they continue to receive traffic. This is an optimization of our platform, allowing Workers to run with a dynamic set of bindings without needing to start a new isolate with every change to bindings. Broadly, this means you can expect better performance when rolling out non-code changes to your Worker.

When you deploy a change to your Worker, and only change its bindings (i.e. you don't change the Worker's code), Cloudflare will reuse existing isolates that are already running your Worker. This improves performance — you can change an environment variable or other binding without unnecessarily reloading your code.

[kodster28]

Suggested change

When creating a new Worker [version or deployment](/workers/configuration/versions-and-deployments/) and you only include changes to bindings (i.e. you don't change the code of the Worker), be aware that the any currently running Worker isolates may stay "hot" for a potentially long time if they continue to receive traffic. This is an optimization of our platform, allowing Workers to run with a dynamic set of bindings without needing to start a new isolate with every change to bindings. Broadly, this means you can expect better performance when rolling out non-code changes to your Worker.

When a new [version or deployment](/workers/configuration/versions-and-deployments/) only changes bindings - and not the code itself - your Worker generally has better performance. Isolates run with a dynamic set of bindings, meaning they do not need to restart with every change to bindings. So if an isolate is "hot" - or already responding to traffic - the isolate usually remains "hot" after non-code changes.

[irvinebroque]

Suggested change

	However, this does mean that you must be careful when "polluting" global scope with derivatives of your bindings. For example, if you create an external client instance which uses a secret API key on `env`, you must ensure that you don't place this client instance in a global scope. If you do, the client instance might continue to exist despite making changes to the secret which is likely undesirable. Instead of polluting global scope, you should create a new client instance for each request, or, if you have more advanced needs, you may want to explore the [AsyncLocalStorage API](/workers/runtime-apis/nodejs/asynclocalstorage/) which provides another mechanism for exposing values down to child execution handlers.
	This means you should not assign the values of bindings to variables in global scope. For example, you should not do this, because the client assigned to global scope can continue using the old value of `SECRET_KEY` even after you update it in your Worker:
	let client;
	export default {
	async fetch(request) {
	if (!client) { client = new ApiClient(env.SECRET_KEY) }
	// ...
	}
	}
	Instead, you should either create a new client instance for each request:
	export default {
	async fetch(request) {
	let client = new ApiClient(env.SECRET_KEY)
	// ...
	}
	}
	Or use the [AsyncLocalStorage API](/workers/runtime-apis/nodejs/asynclocalstorage/):
	...example

Think clearer with code?

[mhart]

Or even, store the client in a global Map where the key is the env value(s) or hash thereof 🧠

Just on the AsyncLocalStorage note, that's still only going to be per-request, so you'd still be creating "a new client instance for each request". Just would want to make that clear if we were providing code for that.

[kodster28]

Maybe lead with what you should do, then have the shouldn't do?

[kodster28]

Suggested change

When creating a new Worker [version or deployment](/workers/configuration/versions-and-deployments/) and you only include changes to bindings (i.e. you don't change the code of the Worker), be aware that the any currently running Worker isolates may stay "hot" for a potentially long time if they continue to receive traffic. This is an optimization of our platform, allowing Workers to run with a dynamic set of bindings without needing to start a new isolate with every change to bindings. Broadly, this means you can expect better performance when rolling out non-code changes to your Worker.

When a new [version or deployment](/workers/configuration/versions-and-deployments/) only changes bindings - and not the code itself - your Worker generally has better performance. Isolates run with a dynamic set of bindings, meaning they do not need to restart with every change to bindings. So if an isolate is "hot" - or already responding to traffic - the isolate usually remains "hot" after non-code changes.

[kodster28]

Maybe lead with what you should do, then have the shouldn't do?

[kodster28]

Suggested change

However, this does mean that you must be careful when "polluting" global scope with derivatives of your bindings. For example, if you create an external client instance which uses a secret API key on `env`, you must ensure that you don't place this client instance in a global scope. If you do, the client instance might continue to exist despite making changes to the secret which is likely undesirable. Instead of polluting global scope, you should create a new client instance for each request, or, if you have more advanced needs, you may want to explore the [AsyncLocalStorage API](/workers/runtime-apis/nodejs/asynclocalstorage/) which provides another mechanism for exposing values down to child execution handlers.

At the same time, be careful about which derivatives you add to the global scope. Anything you add might continue to exist despite making changes. For example, an external client instance uses a secret API key on `env`. If you put this client instance in a global scope and also make changes to the secret, the instance might continue to exist. The correct approach would be to create a new client instance for each request. Or - if you have more advanced needs - explore the [AsyncLocalStorage API](/workers/runtime-apis/nodejs/asynclocalstorage/), which provides another mechanism for exposing values down to child execution handlers.