Skip to content

docs(extras): add MicroVM best practices - #825

Merged
ParidelPooya merged 3 commits into
mainfrom
docs/microvm-best-practices
Oct 24, 2026
Merged

ParidelPooya merged 3 commits into
mainfrom
docs/microvm-best-practices

Conversation

@ParidelPooya

Copy link
Copy Markdown
Contributor

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, job handlers, the HTTP job route, sessions, retry strategies, custom clients and tests, and permissions and monitoring.
  • The worker README gets the section "Best practices for job handlers". It covers plain functions and asyncio.run, the result size, and the logger.
  • The examples test/README.md gets the subsection "MicroVM Examples and Tests". It covers the SAM deploy, cloud-test inputs as objects, and run_async with wait_for_result.
  • Each rule states what happens if it is broken. Each rule appears in one README only, and the 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.

The JS SDK gets the same rules in aws/aws-durable-execution-sdk-js#1076, with JS names.

Testing

  • Every claim was checked against the code on main: the 10-second reserve and the 11-second minimum, the 10-second request timeout, 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.
  • The test advice names botocore Stubber only. moto 5.2.4 has no lambda-microvms backend.
  • Every relative link and anchor resolves to a heading.
  • lintcommit.py passes. 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.

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 yaythomas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:shipit:

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.

Comment thread packages/aws-durable-execution-sdk-python-extras/README.md
Comment thread packages/aws-durable-execution-sdk-python-extras/README.md
Comment thread packages/aws-durable-execution-sdk-python-extras/README.md
Comment thread packages/aws-durable-execution-sdk-python-extras/README.md
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
ParidelPooya marked this pull request as ready for review October 24, 2026 00:52
@ParidelPooya
ParidelPooya temporarily deployed to ai-pr-review-runtime October 24, 2026 00:52 — with GitHub Actions Inactive
@ParidelPooya
ParidelPooya merged commit e6d60c9 into main Oct 24, 2026
70 of 72 checks passed
@ParidelPooya
ParidelPooya deleted the docs/microvm-best-practices branch October 24, 2026 00:52
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

1 inactive deployment
ai-pr-review-runtime — ba47bb98 Deployed Oct 24, 2026 by ParidelPooya via notify / Generate notification summary #272
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants