feat: add web runner & cli

Implement complete HTTP service that mimics AWS APIs for local
durable function testing. Add cli to start web-runner and invoke
methods on it.

It has a multi-threaded server, strongly-typed routing, and
AWS CLI compatibility.

Note this PR does not fully implement all features. This is a stub
to get the end-to-end flow hooked up. Specifically the various
list and history apis are not implement yet.

Temporarily lower cov minimum to 96% while placeholder functionality
still in place.

- Add ThreadingHTTPServer-based WebServer with graceful shutdown
- Implement strongly-typed Route system with Router class for efficient
  path matching and parameter extraction
- Create comprehensive HTTP models with AWS serialization integration
- Add boto3-compatible serialization using rest-json protocol

- Implement Router class with pattern matching for all AWS API endpoints
- Add EndpointHandler base class with common HTTP utilities and error handling
- Create complete handler implementations for all durable execution operations
- Integrate shared router and handler registry for thread-safe request processing

- Add comprehensive serialization dataclasses with from_dict/to_dict methods
- Implement AWS rest-json serialization using botocore components
- Support all AWS Lambda durable execution endpoints (/2025-12-01/*)
- Add automatic fallback from AWS to JSON serialization

- Create dex-local-runner CLI with start-server, invoke, get-durable-execution,
  and get-durable-execution-history commands
- Add comprehensive configuration via CLI args and AWS_DEX_* env variables
- Integrate LambdaInvoker for better Lambda service compatibility
- Support boto3 client integration with lambdainternal-local service

- Add comprehensive AWS-compatible exception mapping (400/404/409/500)
- Implement consistent error response formatting across all endpoints
- Add request validation with proper field checking and type safety
- Support operation-specific error codes and messages

Author: yaythomas

README.md

@@ -10,6 +10,7 @@
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Architecture](#architecture)
+- [Documentation](#documentation)
 - [Developer Guide](#developers)
 - [License](#license)
 
@@ -168,6 +169,20 @@ The observer pattern enables loose coupling between checkpoint processing and ex
 5. **Execution** complete_* methods finalize the execution state
 
 
+## Documentation
+
+### Error Handling
+
+The testing framework implements AWS-compliant error responses that match the exact format expected by boto3 and AWS services. For detailed information about error response formats, exception types, and troubleshooting, see:
+
+- [Error Response Documentation](docs/error-responses.md)
+
+Key features:
+- **AWS-compliant JSON format**: Matches boto3 expectations exactly
+- **Smithy model compliance**: Field names follow AWS Smithy definitions  
+- **HTTP status code mapping**: Standard AWS service status codes
+- **Boto3 compatibility**: Seamless integration with boto3 error handling
+
 ## Developers
 Please see [CONTRIBUTING.md](CONTRIBUTING.md). It contains the testing guide, sample commands and instructions
 for how to contribute to this package.

docs/error-responses.md

@@ -0,0 +1,311 @@
+# AWS-Compliant Error Response Documentation
+
+This document describes the AWS-compliant error response format used by the Durable Executions Testing Library.
+
+## Overview
+
+The testing library implements AWS-compliant error responses that match the exact format expected by boto3 and AWS services. All error responses follow Smithy model definitions for structure and field naming.
+
+## Error Response Format
+
+### HTTP Response Structure
+
+All error responses use the following HTTP structure:
+
+```
+HTTP/1.1 <status_code>
+Content-Type: application/json
+
+<JSON_BODY>
+```
+
+### JSON Body Format
+
+The JSON body format varies by exception type based on Smithy model definitions:
+
+#### Standard Format (Most Exceptions)
+
+```json
+{
+  "Type": "ExceptionName",
+  "message": "Detailed error message"
+}
+```
+
+**Used by:**
+- `InvalidParameterValueException`
+- `CallbackTimeoutException`
+
+#### Capital Message Format
+
+```json
+{
+  "Type": "ExceptionName", 
+  "Message": "Detailed error message"
+}
+```
+
+**Used by:**
+- `ResourceNotFoundException`
+- `ServiceException`
+
+#### Special Format (ExecutionAlreadyStartedException)
+
+```json
+{
+  "message": "Detailed error message",
+  "DurableExecutionArn": "arn:aws:states:region:account:execution:name"
+}
+```
+
+**Note:** This exception has no "Type" field per AWS Smithy definition.
+
+## Exception Types and Examples
+
+### InvalidParameterValueException (HTTP 400)
+
+**When:** Invalid parameter values are provided to API operations.
+
+**Example Response:**
+```json
+{
+  "Type": "InvalidParameterValueException",
+  "message": "The parameter 'executionName' cannot be empty"
+}
+```
+
+**Common Causes:**
+- Empty or null required parameters
+- Invalid parameter formats
+- Parameter values outside allowed ranges
+
+### ResourceNotFoundException (HTTP 404)
+
+**When:** Requested resource does not exist.
+
+**Example Response:**
+```json
+{
+  "Type": "ResourceNotFoundException",
+  "Message": "Execution with ID 'exec-123' not found"
+}
+```
+
+**Common Causes:**
+- Non-existent execution IDs
+- Deleted or expired resources
+- Incorrect resource identifiers
+
+### ServiceException (HTTP 500)
+
+**When:** Internal service errors occur.
+
+**Example Response:**
+```json
+{
+  "Type": "ServiceException", 
+  "Message": "An internal error occurred while processing the request"
+}
+```
+
+**Common Causes:**
+- Unexpected internal errors
+- System unavailability
+- Configuration issues
+
+### CallbackTimeoutException (HTTP 408)
+
+**When:** Callback operations timeout.
+
+**Example Response:**
+```json
+{
+  "Type": "CallbackTimeoutException",
+  "message": "Callback operation timed out after 30 seconds"
+}
+```
+
+**Common Causes:**
+- Callback not received within timeout period
+- Network connectivity issues
+- Client-side delays
+
+### ExecutionAlreadyStartedException (HTTP 409)
+
+**When:** Attempting to start an execution that is already running.
+
+**Example Response:**
+```json
+{
+  "message": "Execution is already started",
+  "DurableExecutionArn": "arn:aws:states:us-east-1:123456789012:execution:MyExecution:abc123"
+}
+```
+
+**Common Causes:**
+- Duplicate start execution requests
+- Race conditions in execution management
+- Client retry logic issues
+
+## HTTP Status Code Mapping
+
+| Exception | HTTP Status | Description |
+|-----------|-------------|-------------|
+| InvalidParameterValueException | 400 | Bad Request - Invalid input parameters |
+| ResourceNotFoundException | 404 | Not Found - Resource does not exist |
+| CallbackTimeoutException | 408 | Request Timeout - Operation timed out |
+| ExecutionAlreadyStartedException | 409 | Conflict - Resource already exists |
+| ServiceException | 500 | Internal Server Error - System error |
+
+## Field Name Conventions
+
+Field names strictly follow Smithy model definitions:
+
+- **lowercase "message"**: InvalidParameterValueException, CallbackTimeoutException, ExecutionAlreadyStartedException
+- **capital "Message"**: ResourceNotFoundException, ServiceException
+- **"Type"**: Present in all exceptions except ExecutionAlreadyStartedException
+- **"DurableExecutionArn"**: Only in ExecutionAlreadyStartedException
+
+## Boto3 Compatibility
+
+All error responses are designed for boto3 compatibility:
+
+### Client Error Handling
+
+```python
+import boto3
+from botocore.exceptions import ClientError
+
+try:
+    # API call that might fail
+    response = client.some_operation()
+except ClientError as e:
+    error_code = e.response['Error']['Code']
+    error_message = e.response['Error']['Message']
+    
+    if error_code == 'InvalidParameterValueException':
+        # Handle invalid parameter
+        pass
+    elif error_code == 'ResourceNotFoundException':
+        # Handle not found
+        pass
+```
+
+### Error Response Structure
+
+The testing library's error responses match the structure boto3 expects:
+
+```python
+# What boto3 receives
+{
+    'Error': {
+        'Code': 'InvalidParameterValueException',
+        'Message': 'The parameter cannot be empty'
+    },
+    'ResponseMetadata': {
+        'HTTPStatusCode': 400,
+        'HTTPHeaders': {...}
+    }
+}
+```
+
+## Migration from Legacy Format
+
+### Old Format (Deprecated)
+```json
+{
+  "error": {
+    "type": "InvalidParameterError",
+    "message": "Error message",
+    "code": "INVALID_PARAMETER",
+    "requestId": "req-123"
+  }
+}
+```
+
+### New AWS-Compliant Format
+```json
+{
+  "Type": "InvalidParameterValueException",
+  "message": "Error message"
+}
+```
+
+### Key Changes
+1. **No wrapper object**: Direct JSON structure, no "error" wrapper
+2. **AWS exception names**: Use official AWS exception names
+3. **Smithy field names**: Follow exact Smithy model field naming
+4. **Simplified structure**: Only essential fields per AWS standards
+5. **Consistent HTTP codes**: Match AWS service status codes
+
+## Testing Error Responses
+
+### Unit Testing
+
+```python
+from aws_durable_execution_sdk_python_testing.exceptions import InvalidParameterValueException
+from aws_durable_execution_sdk_python_testing.web.models import HTTPResponse
+
+def test_error_response():
+    exception = InvalidParameterValueException("Test error")
+    response = HTTPResponse.create_error_from_exception(exception)
+    
+    assert response.status_code == 400
+    assert response.body == {
+        "Type": "InvalidParameterValueException",
+        "message": "Test error"
+    }
+```
+
+### Integration Testing
+
+```python
+import requests
+
+def test_api_error_response():
+    response = requests.post('http://localhost:8080/invalid-endpoint')
+    
+    assert response.status_code == 404
+    error_data = response.json()
+    assert error_data['Type'] == 'ResourceNotFoundException'
+    assert 'Message' in error_data
+```
+
+## Best Practices
+
+### Error Message Guidelines
+
+1. **Be specific**: Include relevant details about what went wrong
+2. **Be actionable**: Suggest how to fix the issue when possible
+3. **Be consistent**: Use consistent terminology across similar errors
+4. **Avoid sensitive data**: Don't include passwords, tokens, or PII
+
+### Exception Selection
+
+1. **InvalidParameterValueException**: For all input validation errors
+2. **ResourceNotFoundException**: When requested resources don't exist
+3. **ServiceException**: For unexpected internal errors only
+4. **CallbackTimeoutException**: Specifically for callback timeouts
+5. **ExecutionAlreadyStartedException**: Only for duplicate execution starts
+
+### HTTP Status Codes
+
+1. **Use standard codes**: Follow HTTP and AWS conventions
+2. **Be consistent**: Same error types should use same status codes
+3. **Client vs Server**: 4xx for client errors, 5xx for server errors
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Wrong field names**: Ensure "message" vs "Message" matches exception type
+2. **Missing Type field**: All exceptions except ExecutionAlreadyStartedException need "Type"
+3. **Wrong status codes**: Verify HTTP status matches exception type
+4. **JSON serialization**: Ensure all fields are JSON-serializable
+
+### Debugging Tips
+
+1. **Check exception type**: Verify you're using the correct AWS exception
+2. **Validate JSON structure**: Use `to_dict()` to see exact output
+3. **Test with boto3**: Verify compatibility with actual boto3 client
+4. **Compare with AWS**: Match format with real AWS service responses

examples/test/test_hello_world.py

@@ -14,5 +14,5 @@ def test_hello_world():
     with DurableFunctionTestRunner(handler=hello_world.handler) as runner:
         result: DurableFunctionTestResult = runner.run(input="test", timeout=10)
 
-    assert result.status is InvocationStatus.SUCCEEDED  # noqa: S101
-    assert result.result == "Hello World!"  # noqa: S101
+    assert result.status is InvocationStatus.SUCCEEDED
+    assert result.result == "Hello World!"