[Workers] Clarify passThroughOnException proxy usage#31304
[Workers] Clarify passThroughOnException proxy usage#31304irvinebroque wants to merge 3 commits into
Conversation
github-actions
Bot
assigned
GregBrimble,
korinne,
MattieTK,
mikenomitch,
vy-ton,
WalshyDev and
nevikashah
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
![ask-bonk[bot]](https://avatars.githubusercontent.com/in/2454580?s=60&v=4){kind=small}
|
I've reviewed PR #31304 and posted an approving review. Summary of ChangesThe PR clarifies
Validation
|
irvinebroque
requested review from
a team,
GregBrimble,
MattieTK,
WalshyDev,
korinne,
mikenomitch,
nevikashah and
vy-ton
as code owners
Review✅ No style-guide issues found in commit CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
| The Workers runtime uses streaming for request and response bodies. It does not buffer the body. If an exception occurs after the body has been consumed, `passThroughOnException()` cannot send the body again. | ||
|
|
||
| If this causes issues, we recommend cloning the request body and handling exceptions in code. This will protect against uncaught code exceptions. However some exception times such as exceed CPU or memory limits will not be mitigated. | ||
| For proxy Workers, avoid relying on the runtime fallback for failures from `fetch(request)`. If the origin fetch throws after consuming the request body, the fallback request may reach your origin without the original body and fail with an unrelated `4xx` error. Catch origin fetch errors and return a `5xx` response instead. |
There was a problem hiding this comment.
this shouldn't call them "proxy Workers" like it is capitalized thing, it should be like "for a Worker that is proxying requests to an origin" or something similar.
| }); | ||
|
|
||
| async function handleRequest(request) { | ||
| // An error here will return the origin response, as if the Worker wasn’t present. |
There was a problem hiding this comment.
Think we still need this comment?
| export default { | ||
| async fetch(request, env, ctx) { | ||
| ctx.passThroughOnException(); | ||
| // an error here will return the origin response, as if the Worker wasn't present |
There was a problem hiding this comment.
think we still need this comment?
| By using [`event.passThroughOnException`](/workers/runtime-apis/context/#passthroughonexception), a Workers application will forward requests to your origin if an exception is thrown during the Worker's execution. This allows you to add logging, tracking, or other features with Workers, without degrading your application's functionality. | ||
| By using [`passThroughOnException()`](/workers/runtime-apis/context/#passthroughonexception), a Workers application can forward requests to your origin if an exception is thrown during the Worker's execution. This allows you to add logging, tracking, or other features with Workers, without degrading your application's functionality. | ||
|
|
||
| If your Worker proxies to origin in the normal request path, catch errors from the origin fetch and return a `5xx` response. If `fetch(request)` throws after consuming the request body, `passThroughOnException()` cannot replay the body for the fallback request. |
There was a problem hiding this comment.
Think this should be more like — you should still wrap calls to fetch() in try/catch — if the fetch() request fails, it then the request will still fail. ctx.passThroughOnException() only "passes through" for unhandled exceptions that do not come from calling fetch() and making a request to the origin server. It will not reply the request to the origin
|
/bonk review my comments and improve the language to be most clear |
Co-authored-by: irvinebroque <irvinebroque@users.noreply.github.com>
|
Addressed all four review comments with clearer language and cleaner examples. Changes made:
|
|
|
||
| `passThroughOnException()` is a fail-open mechanism that sends requests to your origin when your Worker throws an unhandled exception. While it can be useful during migration from an origin server, it hides bugs and makes debugging difficult. Use explicit `try...catch` blocks with structured error responses instead. | ||
|
|
||
|
|
There was a problem hiding this comment.
| async fetch(request, env, ctx) { | ||
| // Proxy to origin on unhandled/uncaught exceptions | ||
| ctx.passThroughOnException(); | ||
| throw new Error("Oops"); |
There was a problem hiding this comment.
/bonk this example should still include try/catch and a fetch() request
actually you can remove it and just use the one below - and you don't need the sentence on line 266
8 participants
Summary
Updates Workers documentation for
passThroughOnException()to clarify proxy behavior when an originfetch(request)fails after consuming the request body. Adds safer examples that catch origin fetch failures and return a5xxresponse instead of relying on runtime fallback to replay the consumed body.Documentation checklist