Skip to content

refactor(worker): rename microvm-worker to compute-worker - #922

Merged
ParidelPooya merged 3 commits into
mainfrom
refactor/compute-worker
Nov 10, 2026
Merged

ParidelPooya merged 3 commits into
mainfrom
refactor/compute-worker

Conversation

@ParidelPooya

@ParidelPooya ParidelPooya commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

What

This PR renames the worker package from aws-durable-execution-sdk-python-microvm-worker to aws-durable-execution-sdk-python-compute-worker. The MicroVM code moves to the microvm subpackage.

  • The old import was aws_durable_execution_sdk_python_microvm_worker.
  • The new import is aws_durable_execution_sdk_python_compute_worker.microvm.
  • compute_worker.microvm exports the same 23 names as the old top-level package. So a user changes only the import path.
  • The top-level aws_durable_execution_sdk_python_compute_worker exports only __version__.

The PR changes no behavior other than the names listed under "Visible name changes".

Twin PR: aws/aws-durable-execution-sdk-js#1204

Why

  1. The worker runs jobs from durable functions on compute that is defined outside the durable function.
  2. Today the only compute type is Lambda MicroVM. Later compute types, such as EC2 or ECS, need their own worker code.
  3. With a compute-neutral package name, each compute type can be a sibling subpackage of the same package.
  4. The extras package already uses this layout: aws_durable_execution_sdk_python_extras.compute.microvm. So the worker now matches extras.
  5. The worker is not published on PyPI yet. So no published import breaks, and the PR adds no alias package for the old name.

Design

We compared three options.

  1. Keep the name microvm-worker. A worker for another compute type would then need a second package. Code that every worker shares, such as callback reporting, would then live in a MicroVM-named package or be copied.
  2. Rename to compute-worker with a microvm subpackage. This is the chosen option. One package holds every compute type. A later compute type adds a subpackage. Shared code can move to the top level when a second compute type needs it.
  3. Publish one package per compute type, plus a shared package. This adds a package to publish and version for each compute type. No second compute type exists today. So this cost buys nothing yet.

Change

  • git mv moves the package directory, the source modules, and the tests. So history follows the files.
  • Source: src/aws_durable_execution_sdk_python_compute_worker/microvm/ holds every module. __about__.py and py.typed stay at the package top level.
  • Tests: tests/microvm/ holds the test modules. tests/conftest.py stays at the top, so every subdirectory uses it.

Shared modules

The brief named three candidates for the top level: callback_reporter, heartbeats, and logger. Each one stays under microvm. This PR does not split any module.

  1. logger defines the public type MicrovmWorkerLogger. A MicroVM-named type at the compute-neutral top level would need a rename. A rename changes the public API. So logger stays under microvm.
  2. callback_reporter takes a MicrovmWorkerLogger argument. Its docstrings describe MicroVM image snapshots and MicroVM credentials. If it moved to the top level, it would import from microvm. So it stays under microvm.
  3. heartbeats imports is_finite_number from the MicroVM payload module. Its jitter design exists because Lambda restores many MicroVMs from one snapshot. So it stays under microvm.

Visible name changes

  • Distribution: aws-durable-execution-sdk-python-microvm-worker becomes aws-durable-execution-sdk-python-compute-worker.
  • Default logger name: aws_durable_execution_sdk_python_microvm_worker becomes aws_durable_execution_sdk_python_compute_worker.microvm. The name follows the new module path.
  • HTTP Server header of the worker: aws-durable-execution-sdk-python-microvm-worker becomes aws-durable-execution-sdk-python-compute-worker. The extras composed test checks this header, and the PR updates that test.
  • Hatch env: dev-microvm-worker becomes dev-compute-worker.

References updated

  • Root pyproject.toml: pytest testpaths, the dev-extras workspace members, the dev-compute-worker env, and ruff known-first-party.
  • Worker pyproject.toml: the distribution name, wheel packages, legal-file targets, version path, coverage source, and ruff known-first-party.
  • .github/scripts/type-checks.sh: the mypy paths.
  • .github/scripts/js_examples/run.py: the JS build list now includes packages/aws-durable-execution-sdk-js-compute-worker. The list keeps packages/aws-durable-execution-sdk-js-microvm-worker. A JS ref has at most one of the two directories. The script already skips an optional directory that a ref does not have. So the harness builds JS refs from before and after the JS rename. .github/scripts/tests/test_js_examples.py uses the new directory.
  • AGENTS.md: the package list.
  • Worker README.md: the title, a paragraph about the subpackage layout, the install name, imports, the logger name, and links. docs/worker.md keeps its MicroVM text.
  • Extras: README.md, docs/microvm.md, docstrings in compute/microvm/config.py, job.py, and request.py, and the imports in three tests.
  • Examples: microvm-image/app.py, scripts/ensure_microvm_image.py, test/test_microvm_image_app.py, and test/README.md.
  • References to the JS worker now name @aws/durable-execution-sdk-js-compute-worker. The JS twin PR makes that rename. Until it merges, the JS GitHub link in extras/docs/microvm.md points to a directory that does not exist yet.
  • .github/workflows/pypi-publish.yml is unchanged. Publishing waits for a PyPI pending publisher for the new name.

The repository has no CHANGELOG files, lock files, release-please config, or changesets. So the PR changes none.

Checkpoint and error-type note

The worker reports a failed job with an ErrorType. The worker sets ErrorType to type(error).__name__. That value is the class name only. It holds no module path. So the move changes no ErrorType string. No code in the worker reads __module__ or __qualname__.

Follow-ups

  • Register a PyPI pending publisher for aws-durable-execution-sdk-python-compute-worker. Then add the package to .github/workflows/pypi-publish.yml in a separate PR.
  • After the JS twin PR is released, a maintainer runs this command: npm deprecate @aws/durable-execution-sdk-js-microvm-worker "Renamed to @aws/durable-execution-sdk-js-compute-worker".
  • Link the JS twin PR above.

Testing

All checks ran locally on Python 3.13 in a uv venv with editable installs of core, testing, extras, compute-worker, and examples.

  • Worker tests: 473 passed.
  • Extras tests: 436 passed.
  • Examples MicroVM tests, run from the examples package directory: 104 passed, 4 skipped. The 4 skipped tests run only in cloud mode.
  • .github/scripts/tests/test_js_examples.py: 65 passed.
  • hatch fmt --check passes in the worker, extras, and examples packages.
  • mypy: no issues in 17 worker files and 26 extras files.
  • import aws_durable_execution_sdk_python_microvm_worker raises ModuleNotFoundError.
  • The new microvm.__all__ equals the old top-level __all__, and every name resolves.
  • hatch build -t wheel builds aws_durable_execution_sdk_python_compute_worker-0.0.1-py3-none-any.whl. The wheel contains the microvm subpackage, LICENSE, and NOTICE.
  • git grep for the old names finds only the JS directory name in run.py, which the harness keeps for older JS refs.

The worker package is renamed from microvm-worker to compute-worker.
The MicroVM code moves to the microvm subpackage. The new import is
aws_durable_execution_sdk_python_compute_worker.microvm. It exports the
same names as the old top-level package.

A later worker for another compute type can then be a sibling
subpackage. The extras package uses the same compute.microvm layout.

The worker is not on PyPI yet. So no published import breaks. The
PyPI publish workflow is unchanged.

@hln33 hln33 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.

Looks good, just want some clarification on the changes within js_examples/run.py before approving

Comment thread .github/scripts/js_examples/run.py Resolved
The js_examples harness builds a checkout of any JS ref. A ref from
before the worker rename has only microvm-worker, and a ref from after
it has only compute-worker. The comments now say so, and say why
microvm-worker stays after the JS rename merges.
ParidelPooya added a commit to aws/aws-durable-execution-sdk-js that referenced this pull request Nov 10, 2026
)

## What

This PR renames the npm package
`@aws/durable-execution-sdk-js-microvm-worker` to
`@aws/durable-execution-sdk-js-compute-worker`.

- The package directory becomes
`packages/aws-durable-execution-sdk-js-compute-worker`.
- The MicroVM worker moves to the `./microvm` subpath:
`@aws/durable-execution-sdk-js-compute-worker/microvm`.
- The subpath exports the same names as the old root entry. So a user
changes only the import path.
- The package version stays `0.1.0-alpha.0`.

This PR does not change behavior. It adds no code for other compute
types.

Twin PR: aws/aws-durable-execution-sdk-python#922

## Why

1. The worker runs jobs from durable functions on compute that is
defined outside the function. Today the only compute type is the Lambda
MicroVM.
2. Later compute types, such as EC2 or ECS, need their own worker code.
A package named `microvm-worker` cannot hold that code without a
misleading name.
3. The extras package already groups the operations under a compute
namespace: `@aws/durable-execution-sdk-js-extras/compute/microvm`. So a
`compute-worker` package with a `microvm` subpath matches that layout.
4. The old package is published on npm as `0.1.0-alpha.0`. It is
experimental and alpha. So the rename is an allowed breaking change. The
old version stays on npm unchanged.

## Design

The PR compares three options.

1. Keep the name `microvm-worker`. A second compute type then needs a
second worker package. The shared code would have to live in one of them
or in a third package.
2. Rename to `compute-worker` with a `microvm` subpath. This is the
chosen option. One package holds every compute type. A later compute
type adds a sibling subpath. It can import the shared code from the
package root.
3. Publish one package per compute type, plus a shared package. This
adds a package to publish and version for each compute type. No second
compute type exists today. So this cost buys nothing yet.

## Change

- `git mv` moves the package directory, the sources, and the tests. So
history follows the files.
- `src/microvm/` holds `index.ts`, `worker.ts`, `payload.ts`, and the
tests.
- `src/callback-reporter.ts` stays at the top of `src/`. It imports only
`@aws-sdk/client-lambda`. It has no MicroVM logic. Its comments describe
MicroVM behavior, and those comments stay.
- The root entry `src/index.ts` exports only the callback reporter
names: `CallbackReporter`, `CallbackReporterOptions`,
`isTerminalCallbackError`, `MAX_CALLBACK_RESULT_BYTES`,
`ResultSerializationError`, and `ResultTooLargeError`. The `./microvm`
subpath re-exports them too.
- The Python twin keeps `callback_reporter` under `microvm`. The Python
module takes a MicroVM-named logger type. The JS module takes no such
type. So the JS module can move and the Python module cannot without an
API change.
- `package.json` adds the `./microvm` entry to `exports`. It uses the
same shape as the `./compute/microvm` entry in the extras package.
`rollup.config.mjs` adds the `microvm` input, as the extras package
does. Rollup puts the shared code in a `callback-reporter` chunk.

### References updated

- Root `package.json`: the `build` and `test` scripts.
- `package-lock.json`: regenerated with `npm install`.
- `.github/workflows/unit-tests.yml`: the `extras` shard and its
comment.
- `.github/workflows/lintcommit.js`: the scope `microvm-worker` becomes
`compute-worker`.
- `.github/workflows/iterate-publish-npm.sh` and `RELEASING.md`: the
comment about packages that wait for a first publication. The worker was
not in the publish list before. This PR does not add it.
-
`packages/aws-durable-execution-sdk-js-telemetry-mcp/src/packaging.test.ts`:
the list of packages whose first publication is deferred.
- Extras package: the dev dependency, the `pretest` script, the contract
and composed tests, the e2e app and script, the TSDoc in `request.ts`
and `types.ts`, the README, and the docs.
- Examples package: the dev dependency and `microvm-image/app.ts`.
- The root README, the worker README, and `docs/worker.md`.
- `CHANGELOG.md`: a new entry under Unreleased. Old entries keep the old
name.

## Checkpoint and error types

The worker sends `error.name` as the `ErrorType` of a failed callback.
No error class name changes in this PR. No error type string contains
the package name or a path. So the durable execution history and replay
see the same values as before.

## Follow-ups

- After the new package is released, a maintainer should deprecate the
old package:
`npm deprecate @aws/durable-execution-sdk-js-microvm-worker "Renamed to
@aws/durable-execution-sdk-js-compute-worker"`
- The new package needs the same first-publication setup that the old
package waited for. The publish script still defers it.

## Testing

Run on Node 24.22.2.

- `npm ci` and root `npm run build`: pass.
- Compute worker tests: 4 files, 305 tests pass.
- Extras tests: 26 files, 427 tests pass.
- Examples tests: 127 files pass, 4 skipped. 277 tests pass, 4 skipped.
- Telemetry MCP tests, which include the packaging test: 18 files, 553
tests pass.
- `npm run lint:ci` (biome): pass.
- `node .github/workflows/lintcommit.js test`: 30 tests pass.
- `verify-declared-files-shipped.mjs`: the compute worker pack includes
all 6 files that `package.json` points at.
- Resolution from the extras package, with `require` and `import`:
- `@aws/durable-execution-sdk-js-compute-worker` resolves with 5 runtime
exports.
- `@aws/durable-execution-sdk-js-compute-worker/microvm` resolves with
14 runtime exports. The old root entry had 14.
- `@aws/durable-execution-sdk-js-microvm-worker` fails with
`MODULE_NOT_FOUND`.
- `git grep` for `microvm-worker` finds only `CHANGELOG.md`: the new
entry and old entries.
@ParidelPooya
ParidelPooya marked this pull request as ready for review November 10, 2026 18:21
@ParidelPooya
ParidelPooya deployed to ai-pr-review-runtime November 10, 2026 18:21 — with GitHub Actions Active
@ParidelPooya
ParidelPooya merged commit 1d6461b into main Nov 10, 2026
25 of 26 checks passed
@ParidelPooya
ParidelPooya deleted the refactor/compute-worker branch November 10, 2026 18:21

This branch was successfully deployed

1 active deployment
ai-pr-review-runtime — 7fe6c475 Deployed Nov 10, 2026 by ParidelPooya via notify / Generate notification summary #403
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