AWS durable-execution documentation change
Summary
Major restructuring of the Best Practices documentation from a single comprehensive page to an index page that links to separate topic pages (Determinism and Replay, Idempotency and Retries, Manage State, Step Design, Pause and Resume, Code Organization). Removed all detailed content and code examples, replacing them with brief descriptions and links.
Security assessment
This is a documentation reorganization and refactoring change. There is no evidence in the diff of addressing a specific security vulnerability, weakness, or incident. The changes are structural, moving content into separate files for better organization. The removed content includes general best practices like error handling, timeout configuration, and serialization, but none of the changes indicate a security fix. The new structure mentions topics like idempotency and state management, which have security implications, but the change itself is not adding new security documentation; it's reorganizing existing content.
Diff
diff --git a/durable-execution/patterns/best-practices.md b/durable-execution/patterns/best-practices.md index 988b86058..eb66a7e61 100644 --- a//durable-execution/patterns/best-practices.md +++ b//durable-execution/patterns/best-practices.md @@ -7 +7 @@ AWS Durable Execution SDK Developer Guide -Best Practices +Best practices @@ -66,4 +66,7 @@ Testing - * [ Basic Tests ](../../testing/basic-tests/) - * [ Complex Workflows ](../../testing/complex-workflows/) - * [ Stores ](../../testing/stores/) - * [ Testing Modes ](../../testing/testing-modes/) + * [ Runner ](../../testing/runner/) + * [ Authoring ](../../testing/authoring/) + * [ Assertions ](../../testing/assertions/) + * [ API Reference ](../../testing/api-reference/) + * [ Workflow Patterns ](../../testing/workflow-patterns/) + * [ Cloud Runner ](../../testing/cloud-runner/) + * [ SAM CLI ](../../testing/sam-cli/) @@ -73,43 +76 @@ Patterns - * Best Practices [ Best Practices ](././) On this page - * Table of Contents - * Overview - * Function design - * Keep functions focused - * Wrap non-deterministic code in steps - * Use @durable_step for reusable functions - * Don't share state between steps - * Choose the right execution semantics - * Handle errors explicitly - * Timeout configuration - * Set realistic timeouts - * Use heartbeat timeouts for long operations - * Configure retry delays appropriately - * Naming conventions - * Use descriptive operation names - * Use consistent naming patterns - * Name dynamic operations with context - * Performance optimization - * Minimize checkpoint size - * Batch operations when possible - * Use parallel operations for independent work - * Avoid unnecessary waits - * Serialization - * Use JSON-serializable types - * Convert non-serializable types - * Use custom serialization for complex types - * Common mistakes - * ⚠️ Modifying mutable objects between steps - * ⚠️ Using context inside its own operations - * ⚠️ Forgetting to handle callback timeouts - * ⚠️ Creating too many small steps - * ⚠️ Not using retry for transient failures - * Code organization - * Separate business logic from orchestration - * Use child contexts for complex workflows - * Group related configuration - * FAQ - * See also - - - -On this page + * [ Best Practices ](././) @@ -117,38 +78,7 @@ On this page - * Table of Contents - * Overview - * Function design - * Keep functions focused - * Wrap non-deterministic code in steps - * Use @durable_step for reusable functions - * Don't share state between steps - * Choose the right execution semantics - * Handle errors explicitly - * Timeout configuration - * Set realistic timeouts - * Use heartbeat timeouts for long operations - * Configure retry delays appropriately - * Naming conventions - * Use descriptive operation names - * Use consistent naming patterns - * Name dynamic operations with context - * Performance optimization - * Minimize checkpoint size - * Batch operations when possible - * Use parallel operations for independent work - * Avoid unnecessary waits - * Serialization - * Use JSON-serializable types - * Convert non-serializable types - * Use custom serialization for complex types - * Common mistakes - * ⚠️ Modifying mutable objects between steps - * ⚠️ Using context inside its own operations - * ⚠️ Forgetting to handle callback timeouts - * ⚠️ Creating too many small steps - * ⚠️ Not using retry for transient failures - * Code organization - * Separate business logic from orchestration - * Use child contexts for complex workflows - * Group related configuration - * FAQ - * See also +Best Practices + * [ Determinism and Replay ](./determinism/) + * [ Idempotency and Retries ](./idempotency/) + * [ Manage State ](./state/) + * [ Step Design ](./step-design/) + * [ Pause and Resume ](./pause-resume/) + * [ Code Organization ](./code-organization/) @@ -159,0 +90 @@ On this page + 3. [ Best Practices ](././) @@ -161,1230 +92 @@ On this page -[ ](https://github.com/aws/aws-durable-execution-docs/edit/main/docs/patterns/best-practices.md "Edit this page") [ ](https://github.com/aws/aws-durable-execution-docs/raw/main/docs/patterns/best-practices.md "View source of this page") - -# Best Practices¶ - -## Table of Contents¶ - - * Overview - * Function design - * Timeout configuration - * Naming conventions - * Performance optimization - * Serialization - * Common mistakes - * Code organization - * FAQ - * See also - - - -[← Back to main index](../) - -## Overview¶ - -This guide covers best practices for building reliable, maintainable durable functions. You'll learn how to design functions that are easy to test, debug, and maintain in production. - -↑ Back to top - -## Function design¶ - -### Keep functions focused¶ - -Each durable function should have a single, clear purpose. Focused functions are easier to test, debug, and maintain. They also make it simpler to understand execution flow and identify failures. - -**Good:** - -TypeScriptPythonJava - - - // Coming soon... - - - - @durable_execution - def process_order(event: dict, context: DurableContext) -> dict: - """Process a single order through validation, payment, and fulfillment.""" - order_id = event["order_id"] - - validation = context.step(validate_order(order_id)) - payment = context.step(process_payment(order_id, event["amount"])) - fulfillment = context.step(fulfill_order(order_id)) - - return {"order_id": order_id, "status": "completed"} - - - - // Coming soon... - - -**Avoid:** - -TypeScriptPythonJava - - - // Coming soon... - - - - @durable_execution - def process_everything(event: dict, context: DurableContext) -> dict: - """Process orders, update inventory, send emails, generate reports...""" - # Too many responsibilities - hard to test and maintain - # If one part fails, the entire function needs to retry - pass - - - - // Coming soon... - - -### Wrap non-deterministic code in steps¶ - -All non-deterministic operations must be wrapped in steps: - -TypeScriptPythonJava - - - // Coming soon...