refactor(plugin): make the factory an object with create_plugin

A reviewer asked for the registration type to be an object with a method
rather than a bare callable, and the reason is future extensibility
rather than taste. A callable type alias has no member to add anything
to. So adding a process-level hook later -- a flush when the execution
environment shuts down, for example -- would have to change the
registration type from callable to object, which is a second breaking
change on the same public surface. An object with one method can gain an
optional second member additively, so doing this now costs one break
instead of two.

`DurableInstrumentationPluginFactory` is therefore a Protocol declaring
`create_plugin(info)`, not `Callable[[InvocationStartInfo], ...]`. The
type's name and the returned type's name are both unchanged, so no
identifier changes meaning. The method is `create_plugin` rather than
`new_invocation` because what it returns is still called a plugin, so
the verb and the noun agree. This is the shape the Java SDK already had,
as `DurableExecutionPluginFactory.createPlugin(InvocationInfo)`, so the
three SDKs now describe one contract.

The protocol is deliberately not `@runtime_checkable`, for three
reasons. An `isinstance` check against a runtime-checkable protocol
tests only that the member name exists, so it accepts an object whose
`create_plugin` is a string. The SDK also has to name what an invalid
entry actually was, which a boolean cannot supply. And such a check
requires every declared member, which would make the optional second
member above non-additive for any caller who wrote one.
`_is_plugin_factory` tests for a callable `create_plugin` instead,
structurally, so a factory need not import the protocol.

`info` is positional-only on the protocol method. A protocol parameter
that is positional-or-keyword is part of the structural contract, so a
factory naming it `invocation` would otherwise be a type error.

One consequence reverses guidance added earlier in this branch. A plugin
class used to be a valid factory, because calling a class constructs an
instance, and the docs said so. A class carries no `create_plugin`, so
`plugins=[MyPlugin]` now fails at handler initialization, and the test
that pinned the old behaviour is replaced by one pinning the new. A
class that declares `create_plugin` itself, as a classmethod, is still
valid, because the requirement is the member and not the kind of object.

The reversal is an improvement for a reason the earlier round raised
separately: `CONTRIBUTING.md:246` asks for light constructors, and
class-as-factory encouraged `__init__(self, info)` to do setup work. A
factory object puts that work in the factory's own constructor, where it
can fail before any invocation depends on it.

Migrated with it: both bundled plugins' factory classes, whose
`__call__` becomes `create_plugin`; 23 conformance plugin handlers, each
gaining a small factory class beside its plugin; two examples; one
testing-package e2e test that previously aborted collection of that
whole suite; and the prose in four READMEs.

No handler's observable behaviour changed, and that was measured rather
than assumed. The pre-migration handlers were extracted against the pre-
migration SDK, every handler was driven through the local runner in both
trees, and the emitted records were compared after dropping the
execution ARN and wall-clock fields: 23 handlers, 89 records, 23
identical streams, 0 differing. Registration order is preserved in both
handlers that register two plugins.

Author: ParidelPooya

packages/aws-durable-execution-sdk-python-conformance-tests-otel/README.md

@@ -182,8 +182,8 @@ write access; the runner identity needs list, read, and cleanup access.
 1. Find or add the requirement in the conformance repository under
    `test-requirements/<suite>/<id>.yaml`. New requirement IDs must be registered
    there first.
-2. Add `src/otel_<n>_<name>.py` exporting `handler`. Select the plugin with
-   `common.otel_plugin_factory()` and guard the input with
+2. Add `src/otel_<n>_<name>.py` exporting `handler`. Select the plugin factory
+   with `common.otel_plugin_factory()` and guard the input with
    `common.require_scenario()`.
    Use the SDK's real API; never hand-roll behavior to force an expected result.
 3. Register the function in `template.yaml` (or `template-long-running.yaml`)

packages/aws-durable-execution-sdk-python-conformance-tests-otel/src/common.py

@@ -23,8 +23,9 @@ def otel_plugin_factory() -> DurableInstrumentationPluginFactory:
     """Select the telemetry view configured for this deployed function.
 
     Returns a factory, which is what ``durable_execution(plugins=[...])`` takes:
-    the SDK calls it once per invocation to build that invocation's plugin. The
-    view is still resolved once, when the handler module is imported.
+    the SDK calls its ``create_plugin`` once per invocation to build that
+    invocation's plugin. The view is still resolved once, when the handler module
+    is imported.
     """
 
     if os.environ.get("OTEL_PLUGIN_MODE") == "execution":

packages/aws-durable-execution-sdk-python-conformance-tests/handlers/plugin/plugin_attempt_hooks_retry.py

@@ -79,6 +79,21 @@ def on_user_function_end(self, info: UserFunctionEndInfo) -> None:
         )
 
 
+class AttemptPluginFactory:
+    """Builds one :class:`AttemptPlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> AttemptPlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return AttemptPlugin()
+
+
 @durable_step
 def unreliable_operation(step_context: StepContext) -> str:
     # Fail on the first attempt, succeed on the second, using the SDK's built-in
@@ -89,7 +104,7 @@ def unreliable_operation(step_context: StepContext) -> str:
     return "Operation succeeded"
 
 
-@durable_execution(plugins=[lambda _info: AttemptPlugin()])
+@durable_execution(plugins=[AttemptPluginFactory()])
 def handler(_event: Any, context: DurableContext) -> str:
     retry_config = RetryStrategyConfig(
         max_attempts=3,

packages/aws-durable-execution-sdk-python-conformance-tests/handlers/plugin/plugin_attempt_info_shape.py

@@ -79,14 +79,29 @@ def on_user_function_end(self, info: UserFunctionEndInfo) -> None:
         _emit(record, self._execution_arn)
 
 
+class AttemptInfoShapePluginFactory:
+    """Builds one :class:`AttemptInfoShapePlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> AttemptInfoShapePlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return AttemptInfoShapePlugin()
+
+
 @durable_step
 def flaky(step_context: StepContext) -> str:
     if step_context.attempt < 2:
         raise RuntimeError(f"Attempt {step_context.attempt} failed")
     return "ok"
 
 
-@durable_execution(plugins=[lambda _info: AttemptInfoShapePlugin()])
+@durable_execution(plugins=[AttemptInfoShapePluginFactory()])
 def handler(_event: Any, context: DurableContext) -> str:
     retry_config = RetryStrategyConfig(
         max_attempts=3,

packages/aws-durable-execution-sdk-python-conformance-tests/handlers/plugin/plugin_context_info_shape.py

@@ -79,6 +79,21 @@ def on_user_function_start(self, info: UserFunctionStartInfo) -> None:
         _emit(record, self._execution_arn)
 
 
+class ContextInfoShapePluginFactory:
+    """Builds one :class:`ContextInfoShapePlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> ContextInfoShapePlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return ContextInfoShapePlugin()
+
+
 @durable_step
 def inner(_step_context: StepContext) -> str:
     return "x"
@@ -94,7 +109,7 @@ def branch_b(_context: DurableContext) -> str:
     return "b-done"
 
 
-@durable_execution(plugins=[lambda _info: ContextInfoShapePlugin()])
+@durable_execution(plugins=[ContextInfoShapePluginFactory()])
 def handler(_event: Any, context: DurableContext) -> list[str]:
     result: BatchResult[str] = context.parallel(
         [

packages/aws-durable-execution-sdk-python-conformance-tests/handlers/plugin/plugin_error_isolation.py

@@ -82,12 +82,27 @@ def on_user_function_end(self, info: UserFunctionEndInfo) -> None:
         raise RuntimeError("faulty attempt-end")
 
 
+class FaultyPluginFactory:
+    """Builds one :class:`FaultyPlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> FaultyPlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return FaultyPlugin()
+
+
 @durable_step
 def greet(_step_context: StepContext, name: str) -> str:
     return f"Hello, {name}!"
 
 
-@durable_execution(plugins=[lambda _info: FaultyPlugin()])
+@durable_execution(plugins=[FaultyPluginFactory()])
 def handler(event: Any, context: DurableContext) -> str:
     result: str = context.step(greet(event))
     return result

packages/aws-durable-execution-sdk-python-conformance-tests/handlers/plugin/plugin_external_update_on_invoke.py

@@ -65,7 +65,22 @@ def on_operation_end(self, info: OperationEndInfo) -> None:
         )
 
 
-@durable_execution(plugins=[lambda _info: ExternalUpdatePlugin()])
+class ExternalUpdatePluginFactory:
+    """Builds one :class:`ExternalUpdatePlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> ExternalUpdatePlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return ExternalUpdatePlugin()
+
+
+@durable_execution(plugins=[ExternalUpdatePluginFactory()])
 def handler(_event: Any, context: DurableContext) -> str:
     context.wait(Duration.from_seconds(2))
     return "Wait completed"

packages/aws-durable-execution-sdk-python-conformance-tests/handlers/plugin/plugin_faulty_and_healthy.py

@@ -1,9 +1,10 @@
 """10-17: Faulty plugin does not affect a healthy plugin.
 
-Two plugins are registered together, in order: a faulty plugin whose every
-exercised hook logs a line and then raises, and a healthy plugin that logs
-normally. The exercised hooks span the full lifecycle: invocation-start,
-operation-start, attempt-start, attempt-end, operation-end, and invocation-end.
+Two plugins are registered together, through their factories, in order: a faulty
+plugin whose every exercised hook logs a line and then raises, and a healthy
+plugin that logs normally. The exercised hooks span the full lifecycle:
+invocation-start, operation-start, attempt-start, attempt-end, operation-end, and
+invocation-end.
 In the Python SDK the per-attempt hooks are the real ``on_user_function_start`` /
 ``on_user_function_end`` callbacks (the latter carries the attempt ``outcome``),
 and the operation hooks are ``on_operation_start`` / ``on_operation_end``.
@@ -103,6 +104,21 @@ def on_invocation_end(self, info: InvocationEndInfo) -> None:
         raise RuntimeError("faulty invocation-end")
 
 
+class FaultyPluginFactory:
+    """Builds one :class:`FaultyPlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> FaultyPlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return FaultyPlugin()
+
+
 class HealthyPlugin(DurableInstrumentationPlugin):
     def __init__(self) -> None:
         # Operation/attempt hooks do not carry the execution ARN, so capture it
@@ -182,14 +198,27 @@ def on_invocation_end(self, info: InvocationEndInfo) -> None:
         )
 
 
+class HealthyPluginFactory:
+    """Builds one :class:`HealthyPlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> HealthyPlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return HealthyPlugin()
+
+
 @durable_step
 def greet(_step_context: StepContext, name: str) -> str:
     return f"Hello, {name}!"
 
 
-@durable_execution(
-    plugins=[lambda _info: FaultyPlugin(), lambda _info: HealthyPlugin()]
-)
+@durable_execution(plugins=[FaultyPluginFactory(), HealthyPluginFactory()])
 def handler(event: Any, context: DurableContext) -> str:
     result: str = context.step(greet(event))
     return result

packages/aws-durable-execution-sdk-python-conformance-tests/handlers/plugin/plugin_first_invocation_flag.py

@@ -47,7 +47,22 @@ def on_invocation_end(self, info: InvocationEndInfo) -> None:
         )
 
 
-@durable_execution(plugins=[lambda _info: FirstInvocationPlugin()])
+class FirstInvocationPluginFactory:
+    """Builds one :class:`FirstInvocationPlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> FirstInvocationPlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return FirstInvocationPlugin()
+
+
+@durable_execution(plugins=[FirstInvocationPluginFactory()])
 def handler(_event: Any, context: DurableContext) -> str:
     context.wait(Duration.from_seconds(2))
     return "Wait completed"

packages/aws-durable-execution-sdk-python-conformance-tests/handlers/plugin/plugin_invocation_info_shape.py

@@ -58,7 +58,22 @@ def on_invocation_end(self, info: InvocationEndInfo) -> None:
         _emit(record, info.execution_arn)
 
 
-@durable_execution(plugins=[lambda _info: InvocationInfoShapePlugin()])
+class InvocationInfoShapePluginFactory:
+    """Builds one :class:`InvocationInfoShapePlugin` for each invocation.
+
+    ``durable_execution(plugins=[...])`` takes factory objects whose
+    ``create_plugin`` the SDK calls once per invocation. A bare callable is
+    rejected while the handler is being initialized, so registering one would
+    stop this handler from importing. This factory exists only to construct the
+    plugin.
+    """
+
+    def create_plugin(self, info: InvocationStartInfo) -> InvocationInfoShapePlugin:
+        """Return this invocation's plugin. ``info`` is unused."""
+        return InvocationInfoShapePlugin()
+
+
+@durable_execution(plugins=[InvocationInfoShapePluginFactory()])
 def handler(event: Any, context: DurableContext) -> str:
     context.wait(Duration.from_seconds(2))
     return f"done-{event}"