diff --git a/docs/sdk-reference/languages/index.md b/docs/sdk-reference/languages/index.md index 356bba91..673b4601 100644 --- a/docs/sdk-reference/languages/index.md +++ b/docs/sdk-reference/languages/index.md @@ -7,3 +7,12 @@ Language-specific installation and setup for the AWS Durable Execution SDK. - [Java](java/index.md) - [Go](go/index.md) - [C#](csharp/index.md) + +## Upgrade an existing application + +For the 3.0 major release, follow the upgrade summary for +[TypeScript](typescript/index.md#upgrade-from-2x-to-30), +[Python](python/index.md#upgrade-from-2x-to-30), or +[Java](java/index.md#upgrade-from-2x-to-30). Each summary covers package versions, plugin +registration changes, and validation, and links to the SDK repository's full migration +guide. diff --git a/docs/sdk-reference/languages/java/index.md b/docs/sdk-reference/languages/java/index.md index dfdbc4e8..a0af36d6 100644 --- a/docs/sdk-reference/languages/java/index.md +++ b/docs/sdk-reference/languages/java/index.md @@ -208,18 +208,21 @@ return DurableConfig.builder() ### Load plugins dynamically -`withPlugins(...)` registers plugin instances in application code. Java can also load -plugin providers from the application class path. Set `DURABLE_EXECUTION_PLUGINS` to an -ordered, comma-separated list of provider names: +In 2.x, `withPlugins(...)` registers plugin instances in application code. In 3.x, it +registers factories that create one plugin per invocation. See +[Upgrade from 2.x to 3.0](#upgrade-from-2x-to-30) for the new contract. + +Java can also load plugin providers from the application class path. Set +`DURABLE_EXECUTION_PLUGINS` to an ordered, comma-separated list of provider names: ```text DURABLE_EXECUTION_PLUGINS=otel-invocation,com.example.audit ``` -The SDK discovers `DurableExecutionPluginProvider` implementations with -`ServiceLoader`, but creates only the providers named in the environment variable. -Dynamically loaded plugins run first in the listed order, followed by plugins supplied -through `withPlugins(...)`. +The SDK discovers `DurableExecutionPluginProvider` implementations with `ServiceLoader` +and selects the providers named in the environment variable. Selected dynamically loaded +plugins run first in the listed order, followed by plugins supplied through +`withPlugins(...)`. For a Lambda layer, place the provider JAR under `java/lib`. The JAR must contain this service-provider configuration file: @@ -230,9 +233,60 @@ META-INF/services/software.amazon.lambda.durable.plugin.DurableExecutionPluginPr The file contains the provider implementation class name. If you shade multiple providers into one JAR, configure the build to merge `META-INF/services` entries. -Invalid or missing providers, duplicate configured or discovered provider names, and -incompatible provider API versions cause `DurableConfig` construction to throw -`IllegalStateException`. +Invalid or missing providers and duplicate configured or discovered provider names cause +`DurableConfig` construction to throw `IllegalStateException`. In 2.x, this includes +incompatible provider API versions. In 3.x, selected providers must implement +`createPlugin(InvocationInfo)`; rebuild providers compiled against the old interface. + +## Upgrade from 2.x to 3.0 + +Core 3.0 creates a fresh instrumentation plugin for each Lambda invocation. This isolates +plugin state when invocations run concurrently. Applications that register no plugins, +select none through `DURABLE_EXECUTION_PLUGINS`, and ship no plugin providers or plugin +JARs can update their dependencies without changing handler or durable operation calls. + +### Upgrade dependencies together + +Use these coordinated versions after publication. All three artifacts use group ID +`software.amazon.lambda.durable`: + +| Artifact | Version | +| -------------------------------------------- | ------- | +| `aws-durable-execution-sdk-java` | `3.0.0` | +| `aws-durable-execution-sdk-java-plugin-otel` | `3.0.0` | +| `aws-durable-execution-sdk-java-testing` | `3.0.0` | + +Update the artifacts your application uses together, including test dependencies and +Lambda layers. OTel remains optional. Java's durable OTel plugin follows the SDK version +and uses `3.0.0`. Check `mvn dependency:tree` for older transitive SDK or plugin artifacts. + +### Update plugin registrations + +Replace `withPlugins(pluginInstance)` with a `DurableExecutionPluginFactory`, such as +`withPlugins(info -> new MyPlugin())`. Keep shared exporters and connection pools outside +the factory lambda, and keep invocation state on the new plugin. + +Replace OTel plugin constructors with `InvocationOtelPlugin.factory(...)` or +`ExecutionOtelPlugin.factory(...)`. Choose one OTel view across code and environment +configuration. + +Rebuild plugin registration code and all provider JARs against 3.x. Providers now +implement `createPlugin(InvocationInfo)`; remove `API_VERSION`, `getApiVersion()`, and +`getPluginType()`. Update provider layers as well as the function package. Replace +`DurableConfig.getPluginRunner()` with `getPluginFactories()` when inspecting configured +plugins. + +### Validate the upgrade + +Compile and test the application with the coordinated artifacts. Exercise suspension, +resume, and concurrent invocations, then verify plugin output. A stale discovered +provider fails startup, while a stale directly registered provider can log a warning and +produce no telemetry. Hooks within one invocation can still run on multiple threads. +Preserve operation names, order, nesting, and serialization while executions remain +in flight. + +For all API changes and before/after examples, see the +[Java 2.x to 3.0 migration guide](https://github.com/aws/aws-durable-execution-sdk-java/blob/51222863a604910b8d6da97b00e7dde581803a87/docs/migration-2.x-to-3.x.md). ## 2.x Upgrade diff --git a/docs/sdk-reference/languages/python/index.md b/docs/sdk-reference/languages/python/index.md index 0605fa57..1d632da0 100644 --- a/docs/sdk-reference/languages/python/index.md +++ b/docs/sdk-reference/languages/python/index.md @@ -38,6 +38,56 @@ The SDK provides decorators to mark functions as durable: The Python SDK uses synchronous methods and does not support `await`. +## Upgrade from 2.x to 3.0 + +Core 3.0 creates a fresh instrumentation plugin for each Lambda invocation. This isolates +plugin state when invocations run concurrently. Applications that register no plugins, +select none through `DURABLE_EXECUTION_PLUGINS`, and ship no plugin providers can update +their dependencies without changing handler or durable operation calls. + +### Upgrade dependencies together + +Use these coordinated versions after publication: + +| Package | Version | +| ------------------------------------------ | ------- | +| `aws-durable-execution-sdk-python` | `3.0.0` | +| `aws-durable-execution-sdk-python-otel` | `2.0.0` | +| `aws-durable-execution-sdk-python-testing` | `1.3.0` | + +Upgrade Core and OTel together in your requirements, lock file, deployment bundle, and +Lambda layers. OTel remains optional, but OTel 2 requires Core 3. Testing SDK 1.3.0 already +declares a compatible Core range and does not need a major version bump. Run +`python -m pip check` in the built application environment. + +### Update plugin registrations + +Replace plugin instances in `plugins` with factory objects. Each factory's synchronous +`create_plugin(info)` method must return a fresh `DurableInstrumentationPlugin` subclass +instance. Pass a factory instance, not a bare lambda or an uninstantiated factory class +with an ordinary instance method. Keep shared resources on the factory and invocation +state on the plugin. + +Replace `InvocationOtelPlugin(...)` with `InvocationOtelPluginFactory(...)`, or +`ExecutionOtelPlugin(...)` with `ExecutionOtelPluginFactory(...)`. Choose one OTel view +across the decorator and `DURABLE_EXECUTION_PLUGINS`. + +Replace the removed `DurableInstrumentationPluginProvider` wrapper with a factory +object. Update the distribution's `aws_durable_execution.plugins` entry point to name +that object, then rebuild and reinstall the provider package or layer. + +### Validate the upgrade + +Check the package versions imported by the deployed function and its layers. Test a +workflow that suspends and resumes, then test concurrent invocations and parallel +branches. Confirm fresh plugin instances and telemetry for each invocation. Plugin +fields do not survive suspension, and shared resources still need synchronization. +Preserve operation names, order, nesting, and serialization while executions remain +in flight. + +For all API changes and before/after examples, see the +[Python 2.x to 3.0 migration guide](https://github.com/aws/aws-durable-execution-sdk-python/blob/df8951032df6e4fbbb0468bafd2ac09e9a2fdbd4/docs/migration-2.x-to-3.0.md). + ## 2.x Upgrade When upgrading from `1.x` to `2.x`, review the Python SDK migration guide in the diff --git a/docs/sdk-reference/languages/typescript/index.md b/docs/sdk-reference/languages/typescript/index.md index 03ed5876..bd6487c1 100644 --- a/docs/sdk-reference/languages/typescript/index.md +++ b/docs/sdk-reference/languages/typescript/index.md @@ -27,3 +27,50 @@ export const handler = withDurableExecution( ``` The TypeScript SDK uses `async/await` throughout. + +## Upgrade from 2.x to 3.0 + +Core 3.0 creates a fresh instrumentation plugin for each Lambda invocation. This isolates +plugin state when invocations run concurrently. Applications that register no plugins, +select none through `DURABLE_EXECUTION_PLUGINS`, and ship no plugin providers can update +their dependencies without changing handler or durable operation calls. + +### Upgrade dependencies together + +Use these coordinated versions after publication: + +| Package | Version | +| --------------------------------------- | ------- | +| `@aws/durable-execution-sdk-js` | `3.0.0` | +| `@aws/durable-execution-sdk-js-otel` | `2.0.0` | +| `@aws/durable-execution-sdk-js-testing` | `1.3.2` | + +If you use the Testing SDK, upgrade it first. Version `1.3.1` excludes Core 3 from its +peer range; `1.3.2` supports both Core 2 and Core 3. Then upgrade Core and OTel together. +OTel remains optional, but OTel 2 requires Core 3. Rebuild application bundles and update +any Lambda layers containing these packages. + +### Update plugin registrations + +Replace plugin instances in `plugins` with factory objects. Each factory's synchronous +`createPlugin(info)` method must return a fresh plugin. Keep providers and exporters +shared where appropriate, and keep invocation state on the new plugin. + +Replace `new InvocationOtelPlugin(...)` with `createInvocationOtelPluginFactory(...)`, +or `new ExecutionOtelPlugin(...)` with `createExecutionOtelPluginFactory(...)`. Choose +one OTel view across code and environment configuration. + +Environment-loaded modules still export `durableExecutionPluginProvider`. Change that +export to the factory contract and remove the legacy `pluginApiVersion` and `pluginType` +fields. Rebuild custom provider packages and their layers. + +### Validate the upgrade + +Check the package versions resolved by the deployed function and its layers. Test a +workflow that suspends and resumes, then test concurrent invocations. Confirm that each +invocation gets separate plugin state, completed steps do not repeat their side effects, +and telemetry appears for both successful and failed executions. Preserve operation +names, order, nesting, and serialization while executions remain in flight. + +For all API changes and before/after examples, see the +[TypeScript 2.x to 3.0 migration guide](https://github.com/aws/aws-durable-execution-sdk-js/blob/8740dffd3080e481a4e6cbd82106cd3f2e8d1ae5/docs/migration-2.x-to-3.0.md).