docs: callback

- Rewrites callback.md to be equally useful to TypeScript, Python,
  and Java developers
- Removes Table of Contents, back-links, Terminology, Key Features,
  Best Practices, and FAQ sections
- Adds createCallback and waitForCallback walkthrough examples for
  all three languages
- Documents method signatures, CallbackConfig, WaitForCallbackConfig,
   and the Callback handle type per language
- Adds Send callback results section covering the AWS CLI and SAM CLI
  (sam local and sam remote) with success and failure examples
- Adds new example files under examples/{typescript,python,java}/
  operations/callbacks/

closes #16, closes #10,  closes #70, closes #52

Author: yaythomas

docs/sdk-reference/operations/callback.md

@@ -0,0 +1,17 @@
+import software.amazon.lambda.durable.DurableCallbackFuture;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+
+public class BasicCallbackExample extends DurableHandler<Object, String> {
+    @Override
+    public String handleRequest(Object input, DurableContext context) {
+        DurableCallbackFuture<String> callback =
+                context.createCallback("wait-for-approval", String.class);
+
+        // Send callback.callbackId() to the external system that will resume this function.
+        sendApprovalRequest(callback.callbackId());
+
+        // Execution suspends here until the external system calls back.
+        return callback.get();
+    }
+}

examples/java/operations/callbacks/basic-example.java

@@ -0,0 +1,21 @@
+import java.time.Duration;
+import software.amazon.lambda.durable.DurableCallbackFuture;
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+import software.amazon.lambda.durable.config.CallbackConfig;
+
+public class CallbackConfigExample extends DurableHandler<Object, String> {
+    @Override
+    public String handleRequest(Object input, DurableContext context) {
+        CallbackConfig config = CallbackConfig.builder()
+                .timeout(Duration.ofHours(24))
+                .heartbeatTimeout(Duration.ofMinutes(30))
+                .build();
+
+        DurableCallbackFuture<String> callback =
+                context.createCallback("wait-for-payment", String.class, config);
+
+        submitPaymentRequest(callback.callbackId());
+        return callback.get();
+    }
+}

examples/java/operations/callbacks/callback-config.java

@@ -0,0 +1,7 @@
+// With Class<T>
+<T> DurableCallbackFuture<T> createCallback(String name, Class<T> resultType)
+<T> DurableCallbackFuture<T> createCallback(String name, Class<T> resultType, CallbackConfig config)
+
+// With TypeToken<T> for generic result types
+<T> DurableCallbackFuture<T> createCallback(String name, TypeToken<T> resultType)
+<T> DurableCallbackFuture<T> createCallback(String name, TypeToken<T> resultType, CallbackConfig config)

examples/java/operations/callbacks/create-callback-signature.java

@@ -0,0 +1,12 @@
+import software.amazon.lambda.durable.DurableContext;
+import software.amazon.lambda.durable.DurableHandler;
+
+public class WaitForCallbackExample extends DurableHandler<Object, String> {
+    @Override
+    public String handleRequest(Object input, DurableContext context) {
+        return context.waitForCallback(
+                "wait-for-approval",
+                String.class,
+                (callbackId, stepCtx) -> sendApprovalRequest(callbackId));
+    }
+}

examples/java/operations/callbacks/wait-for-callback-example.java

@@ -0,0 +1,7 @@
+// sync
+<T> T waitForCallback(String name, Class<T> resultType, BiConsumer<String, StepContext> func)
+<T> T waitForCallback(String name, Class<T> resultType, BiConsumer<String, StepContext> func, WaitForCallbackConfig config)
+
+// async
+<T> DurableFuture<T> waitForCallbackAsync(String name, Class<T> resultType, BiConsumer<String, StepContext> func)
+<T> DurableFuture<T> waitForCallbackAsync(String name, Class<T> resultType, BiConsumer<String, StepContext> func, WaitForCallbackConfig config)

examples/java/operations/callbacks/wait-for-callback-signature.java

@@ -0,0 +1,15 @@
+from typing import Any
+
+from aws_durable_execution_sdk_python import DurableContext, durable_execution
+
+
+@durable_execution
+def handler(event: Any, context: DurableContext) -> dict:
+    callback = context.create_callback(name="wait-for-approval")
+
+    # Send callback.callback_id to the external system that will resume this function.
+    send_approval_request(callback.callback_id, event["request_id"])
+
+    # Execution suspends here until the external system calls back.
+    result = callback.result()
+    return {"approved": True, "result": result}

examples/python/operations/callbacks/basic-example.py

@@ -0,0 +1,16 @@
+from typing import Any
+
+from aws_durable_execution_sdk_python import DurableContext, durable_execution
+from aws_durable_execution_sdk_python.config import CallbackConfig, Duration
+
+
+@durable_execution
+def handler(event: Any, context: DurableContext) -> dict:
+    config = CallbackConfig(
+        timeout=Duration.from_hours(24),
+        heartbeat_timeout=Duration.from_minutes(30),
+    )
+    callback = context.create_callback(name="wait-for-payment", config=config)
+
+    submit_payment_request(callback.callback_id, event["amount"])
+    return callback.result()

examples/python/operations/callbacks/callback-config.py

@@ -0,0 +1,5 @@
+def create_callback(
+    self,
+    name: str | None = None,
+    config: CallbackConfig | None = None,
+) -> Callback: ...

examples/python/operations/callbacks/create-callback-signature.py

@@ -0,0 +1,13 @@
+from typing import Any
+
+from aws_durable_execution_sdk_python import DurableContext, durable_execution
+from aws_durable_execution_sdk_python.types import WaitForCallbackContext
+
+
+@durable_execution
+def handler(event: Any, context: DurableContext) -> dict:
+    def submit(callback_id: str, ctx: WaitForCallbackContext) -> None:
+        send_approval_request(callback_id, event["request_id"])
+
+    result = context.wait_for_callback(submitter=submit, name="wait-for-approval")
+    return {"approved": True, "result": result}