docs: invoke

- Rewrites invoke.md to be equally useful to TypeScript, Python,
  and Java developers
- Removes Table of Contents, back-links, Terminology, Key Features,
  Best Practices, FAQ, and Testing sections
- Adds invoke walkthrough example for all three languages
- Documents method signatures, InvokeConfig, naming, configuration,
  and error handling per language
- Adds sequence diagram showing both checkpoints (start and result)
  and the suspend/resume lifecycle
- Adds note distinguishing context.invoke() from the Lambda Invoke API
- Adds new example files under examples/{typescript,python,java}/
  operations/invoke/

closes #36, closes #72, closes #54

Author: yaythomas

docs/sdk-reference/operations/invoke.md

@@ -0,0 +1,24 @@
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.exception.InvokeFailedException;
+import software.amazon.lambda.durable.exception.InvokeTimedOutException;
+
+public class HandleInvocationError extends DurableHandler<OrderEvent, OrderResult> {
+
+    @Override
+    public OrderResult handle(OrderEvent event, DurableContext context) {
+        try {
+            PaymentResult payment = context.invoke(
+                "process-payment",
+                "payment-processor-function:live",
+                event,
+                PaymentResult.class
+            );
+            return OrderResult.success(payment.getTransactionId());
+        } catch (InvokeTimedOutException e) {
+            return OrderResult.failed("payment timed out");
+        } catch (InvokeFailedException e) {
+            return OrderResult.failed(e.getMessage());
+        }
+    }
+}

examples/java/operations/invoke/handle-invocation-error.java

@@ -0,0 +1,11 @@
+// sync
+<T, U> T invoke(String name, String functionName, U payload, Class<T> resultType)
+<T, U> T invoke(String name, String functionName, U payload, Class<T> resultType, InvokeConfig config)
+<T, U> T invoke(String name, String functionName, U payload, TypeToken<T> resultType)
+<T, U> T invoke(String name, String functionName, U payload, TypeToken<T> resultType, InvokeConfig config)
+
+// async
+<T, U> DurableFuture<T> invokeAsync(String name, String functionName, U payload, Class<T> resultType)
+<T, U> DurableFuture<T> invokeAsync(String name, String functionName, U payload, Class<T> resultType, InvokeConfig config)
+<T, U> DurableFuture<T> invokeAsync(String name, String functionName, U payload, TypeToken<T> resultType)
+<T, U> DurableFuture<T> invokeAsync(String name, String functionName, U payload, TypeToken<T> resultType, InvokeConfig config)

examples/java/operations/invoke/invoke-method-signature.java

@@ -0,0 +1,21 @@
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.config.InvokeConfig;
+
+public class InvokeWithConfig extends DurableHandler<OrderEvent, OrderResult> {
+
+    @Override
+    public OrderResult handle(OrderEvent event, DurableContext context) {
+        InvokeConfig config = InvokeConfig.builder()
+            .tenantId(event.getTenantId())
+            .build();
+
+        return context.invoke(
+            "process-order",
+            "order-processor-function:live",
+            event,
+            OrderResult.class,
+            config
+        );
+    }
+}

examples/java/operations/invoke/invoke-with-config.java

@@ -0,0 +1,28 @@
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+
+public class ProcessOrder extends DurableHandler<OrderEvent, OrderResult> {
+
+    @Override
+    public OrderResult handle(OrderEvent event, DurableContext context) {
+        ValidationResult validation = context.invoke(
+            "validate-order",
+            "validate-order-function:live",
+            event,
+            ValidationResult.class
+        );
+
+        if (!validation.isValid()) {
+            return OrderResult.rejected(validation.getReason());
+        }
+
+        PaymentResult payment = context.invoke(
+            "process-payment",
+            "payment-processor-function:live",
+            event,
+            PaymentResult.class
+        );
+
+        return OrderResult.completed(payment.getTransactionId());
+    }
+}

examples/java/operations/invoke/process-order.java

@@ -0,0 +1,15 @@
+from aws_durable_execution_sdk_python import DurableContext, durable_execution
+from aws_durable_execution_sdk_python.exceptions import CallableRuntimeError
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    try:
+        result = context.invoke(
+            "payment-processor-function:live",
+            {"order_id": event["order_id"]},
+            name="process-payment",
+        )
+        return {"status": "success", "result": result}
+    except CallableRuntimeError as e:
+        return {"status": "failed", "reason": str(e)}

examples/python/operations/invoke/handle-invocation-error.py

@@ -0,0 +1,6 @@
+def invoke(
+    function_name: str,
+    payload: P,
+    name: str | None = None,
+    config: InvokeConfig[P, R] | None = None,
+) -> R: ...

examples/python/operations/invoke/invoke-method-signature.py

@@ -0,0 +1,16 @@
+from aws_durable_execution_sdk_python import DurableContext, durable_execution
+from aws_durable_execution_sdk_python.config import InvokeConfig
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    config = InvokeConfig(tenant_id=event.get("tenant_id"))
+
+    result = context.invoke(
+        "order-processor-function:live",
+        {"order_id": event["order_id"]},
+        name="process-order",
+        config=config,
+    )
+
+    return result

examples/python/operations/invoke/invoke-with-config.py

@@ -0,0 +1,21 @@
+from aws_durable_execution_sdk_python import DurableContext, durable_execution
+
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    validation = context.invoke(
+        "validate-order-function:live",
+        {"order_id": event["order_id"], "amount": event["amount"]},
+        name="validate-order",
+    )
+
+    if not validation["valid"]:
+        return {"status": "rejected", "reason": validation.get("reason")}
+
+    payment = context.invoke(
+        "payment-processor-function:live",
+        {"order_id": event["order_id"], "amount": event["amount"]},
+        name="process-payment",
+    )
+
+    return {"status": "completed", "transaction_id": payment["transaction_id"]}

examples/python/operations/invoke/process-order.py

@@ -0,0 +1,23 @@
+import {
+  DurableContext,
+  InvokeError,
+  durableExecution,
+} from "aws-durable-execution-sdk-js";
+
+export const handler = durableExecution(
+  async (event: { orderId: string }, context: DurableContext) => {
+    try {
+      const result = await context.invoke(
+        "process-payment",
+        "payment-processor-function:live",
+        { orderId: event.orderId },
+      );
+      return { status: "success", result };
+    } catch (err) {
+      if (err instanceof InvokeError) {
+        return { status: "failed", reason: err.message };
+      }
+      throw err;
+    }
+  },
+);