Repository navigation
docs(extras): add MicroVM best practices - #825
Merged
Merged
Conversation
The extras README now lists what code and deploys must do for the MicroVM operations, and what happens if they do not. The worker README gets the job handler rules. The examples test README gets the rules for deploying and testing the MicroVM examples.
yaythomas
approved these changes
Oct 24, 2026
yaythomas
left a comment
Contributor
There was a problem hiding this comment.
![]()
The new guidance makes the operational requirements easier to find. I checked it against the Python implementation, its tests, and the corresponding JavaScript behavior. The inline suggestions correct minor edge-case wording. None blocks this PR. They can be addressed here or in a follow-up.
ParidelPooya
added a commit
to aws/aws-durable-execution-sdk-js
that referenced
this pull request
Oct 24, 2026
## Summary This PR adds best practices for the MicroVM operations. It changes only documentation. - The extras README gets the section "Best practices for MicroVM operations". It covers deploys and versions, the function timeout, job inputs, the HTTP job route, sessions, retry strategies, custom clients and test fakes, and permissions and monitoring. - The worker README gets the section "Best practices for job handlers". It covers the result size, thrown values, the logger, and side effects that are safe to repeat. - Each rule states what happens if it is broken. Each rule appears in one README only, and the two sections link to each other. ## Why 1. The MicroVM operations guard many edge cases in code. 2. Some of those cases come from a developer's own choices, such as invoking through `$LATEST`, a custom client, or a route that redirects. 3. A written rule handles such a case with no code to keep in sync across the SDKs. 4. So this PR writes down the rules first. Later PRs can then remove or simplify the safeguards that a rule now covers. The version rule follows the AWS documentation: an execution started through a version or an alias is pinned to that version, and one started through `$LATEST` is not. See [Invoking durable Lambda functions](https://docs.aws.amazon.com/lambda/latest/dg/durable-invoking.html). The Python SDK gets the same rules in aws/aws-durable-execution-sdk-python#825, with Python names. ## Testing - Every claim was checked against the code on `main`: the 10-second reserve and the 11-second minimum, the 6 MiB job body, the 4,096-code-point `run` hook payload, the 256 KB result, the 10-second minimum idle time, the path rules, the 3xx rejection, the 1,000-job duplicate check, and the terminate failure log text. - Every relative link and anchor resolves to a heading. - `npm run format:check` passes.
ParidelPooya
marked this pull request as ready for review
October 24, 2026 00:52
ParidelPooya
temporarily deployed
to
ai-pr-review-runtime
October 24, 2026 00:52 — with
GitHub Actions
Inactive
ParidelPooya
added a commit
that referenced
this pull request
Oct 24, 2026
The launch error docs now cover a retry that RunMicrovm rejects, and limit the repeated job to run hook delivery. The worker forgets a callback ID after at least 1,000 other jobs end, not more than 1,000. Addresses review comments on #825.
ParidelPooya
added a commit
that referenced
this pull request
Oct 24, 2026
* docs(extras): correct MicroVM best practices Address review comments on #825. A launch retry with changed settings now fails with MicrovmLaunchError, as RunMicrovm rejects the reused client token. The HTTP delivery, launch error, and idle time rules now state their exact conditions. * docs(extras): align launch error and dedupe docs The launch error docs now cover a retry that RunMicrovm rejects, and limit the repeated job to run hook delivery. The worker forgets a callback ID after at least 1,000 other jobs end, not more than 1,000. Addresses review comments on #825. * docs(extras): scope MicroVM launch error docs This addresses the review of #826. List every case that selects HTTP delivery, and scope the HTTP launch guarantee to versions and aliases. Cut the unverified reused-token detail from the launch error docs. * docs(extras): restore ValidationException retry note The default strategy does not retry ValidationException. The previous commit removed it from the tier 2 list by mistake. * docs(extras): drop a repeated session sentence The ingress_network_connectors docstring stated twice that every session job goes over HTTP. Addresses the second review of #826.
This branch was previously deployed
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
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.
Summary
This PR adds best practices for the MicroVM operations. It changes only documentation.
asyncio.run, the result size, and the logger.test/README.mdgets the subsection "MicroVM Examples and Tests". It covers the SAM deploy, cloud-test inputs as objects, andrun_asyncwithwait_for_result.Why
$LATEST, a custom client, or a route that redirects.The version rule follows the AWS documentation: an execution started through a version or an alias is pinned to that version, and one started through
$LATESTis not. See Invoking durable Lambda functions.The JS SDK gets the same rules in aws/aws-durable-execution-sdk-js#1076, with JS names.
Testing
main: the 10-second reserve and the 11-second minimum, the 10-second request timeout, the 6 MiB job body, the 4,096-code-pointrunhook payload, the 256 KB result, the 10-second minimum idle time, the path rules, the 3xx rejection, the 1,000-job duplicate check, and the terminate failure log text.Stubberonly. moto 5.2.4 has nolambda-microvmsbackend.lintcommit.pypasses. The repository has no Markdown check.By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.