docs: warn that long-running compute() can take down an instance - #1226
Open
beaugunderson wants to merge 4 commits into
Open
docs: warn that long-running compute() can take down an instance#1226beaugunderson wants to merge 4 commits into
beaugunderson wants to merge 4 commits into
Conversation
Add a red callout and a 'Keep compute() fast' section to the Base Handler docs explaining that compute() runs synchronously on a bounded, instance-wide worker pool. A blocking external call (e.g. an LLM or third-party HTTP API) holds a worker for its full duration, so a slow or failing dependency can exhaust the pool and make the whole instance unresponsive. Points readers to set_async(), HttpRequestEffect, and the decompose-to-SimpleAPI pattern for moving slow work off the synchronous path.
|
This pull request is automatically being deployed by Amplify Hosting (learn more). |
Move the red callout into _includes/compute-availability-warning.html and reference it from both the Base Handler page and the Handlers index, so the warning stays consistent across pages. The 'see' link now points at the absolute Keep compute() fast anchor so it resolves from any page.
rmagier1
approved these changes
Jun 6, 2026
…ttons Reword the shared availability warning to apply to any handler entry point (compute(), handle()) rather than compute() specifically, and surface it on the Protocols and Action Buttons pages. Rename the Base Handler deep-dive section to 'Keep your handler fast' and update the anchor. Cron tasks are intentionally excluded since they run out-of-band of request serving.
Add inefficient queries (unbounded result sets, N+1, missing select_related/prefetch_related) to the 'Keep your handler fast' dangerous-work list, with guidance to filter, paginate, and follow foreign keys efficiently via the Data Module.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a prominent red warning that long-running handler code can take down a plugin author's entire Canvas instance. The warning lives in a shared include and appears on the Handlers index, Base Handler, Protocols, and Action Buttons pages, alongside a Keep your handler fast section explaining the mechanism and how to avoid it.
Why
Handlers run synchronously on a bounded, instance-wide worker pool. A handler that makes a synchronous, blocking external call (e.g. an LLM or third-party HTTP API) holds a worker for the full duration of that call. When the external dependency slows down or goes offline, every invocation hangs at once — and long timeouts plus retries multiply the damage — until the pool is exhausted and the whole instance stops responding to requests. Providers experience this as the entire application becoming inaccessible, not just the one plugin.
The SDK gives plugin authors that much reach by design, but the docs never warned them about it. With great power comes great responsibility — this PR makes the failure mode and the safe patterns explicit where authors first learn to write a handler.
Changes
_includes/compute-availability-warning.htmlwrapping adanger(red) callout, worded generically so it reads correctly for any handler entry point (compute(),handle())./sdk/handlers/), Base Handler (/sdk/handlers-basehandler/), Protocols (/sdk/protocols/), and Action Buttons (/sdk/handlers-action-buttons/)..set_async(),HttpRequestEffect, and the decompose-to-SimpleAPI callback pattern.set_async()defers effects, not the handler body itself — a raw blocking call inside the handler still pins a worker.Cron tasks are intentionally excluded: they run out-of-band of request serving, so a slow cron does not block the workers that serve providers the same way.
Testing
uv run ./test-code-blocks.py— all Python blocks on the edited pages pass. The change adds prose plus Liquid includes (a nested-include pattern already used throughout_includes/); no new code blocks.