feat(eager-loading): implement eager service loading with health check improvements

Complete implementation of eager loading feature with critical bug fixes:

**Feature Implementation:**
- Add EagerLoadedServices property to LocalStackContainerOptions
- Automatically set EAGER_SERVICE_LOADING and SERVICES environment variables
- Update health check to verify eagerly loaded services are running
- Add environment variable collision detection for SERVICES/EAGER_SERVICE_LOADING

**Critical Bug Fixes:**
- Fix missing resourceBuilder assignment on line 200 (fluent API pattern)
- Fix case-insensitive service name lookup in health check
- Fix URL construction to handle trailing slashes

**Health Check Improvements:**
- Use IHttpClientFactory with proper timeout configuration
- Add case-insensitive JsonObject key matching (StringComparison.OrdinalIgnoreCase)
- Implement IDisposable pattern for proper resource cleanup
- Add specific error handling for HttpRequestException and timeouts

**Testing:**
- Add comprehensive LocalStackHealthCheck unit tests (9 test cases)
- Add integration tests for eager loading scenarios
- Add tests for environment variable collision detection
- Add tests for multiple services, empty lists, and edge cases

**Documentation:**
- Add Container Configuration section to README
- Create comprehensive CONFIGURATION.md guide
- Document lazy vs eager loading patterns
- Add configuration patterns for Dev/CI/CD/Testing
- Cross-reference official LocalStack documentation
- Add troubleshooting guide

Co-authored-by: slang25 <[email protected]>

Closes #7
Refs #8

Author: Blind-Striker

CHANGELOG.md

@@ -25,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **LocalStack Container**: Updated from `4.6.0` → `4.9.1`
+- **LocalStack Container**: Updated from `4.6.0` → `4.9.2`
 - **Aspire.Hosting**: Updated to `9.5.0` (aligns with release version)
 - **Aspire.Hosting.AWS**: Updated to `9.2.6` (latest stable AWS integration)
 - **Aspire.Hosting.Testing**: Updated to `9.5.0`

README.md

@@ -33,6 +33,8 @@ dotnet add package LocalStack.Aspire.Hosting --prerelease --source github-locals
 
 ## Usage
 
+> 💡 **Prefer learning by example?** Check out our [complete working examples](#examples) in the playground (CloudFormation, CDK, Lambda). Clone, run, explore - then come back here for configuration details.
+
 When LocalStack is disabled in configuration, both host and client configurations automatically fall back to real AWS services without requiring code changes. The [LocalStack.NET Client](https://github.com/localstack-dotnet/localstack-dotnet-client) automatically switches to AWS's official client factory when LocalStack is not enabled.
 
 ### Host Configuration (AppHost)
@@ -76,6 +78,35 @@ The `UseLocalStack()` method automatically:
 - Sets up proper dependency ordering and CDK bootstrap if needed
 - Transfers LocalStack configuration to service projects via environment variables
 
+#### Container Configuration
+
+The `configureContainer` parameter allows you to customize LocalStack container behavior. By default, LocalStack uses lazy loading - services start only when first accessed. For faster startup in CI or when you know which services you need, configure eager loading:
+
+```csharp
+builder.AddLocalStack(configureContainer: container =>
+{
+    // Eagerly load specific services for faster startup
+    container.EagerLoadedServices = [AwsService.Sqs, AwsService.DynamoDB, AwsService.S3];
+
+    // Recommended: Clean up container when application stops
+    container.Lifetime = ContainerLifetime.Session;
+
+    // Optional: Enable verbose logging for troubleshooting
+    container.DebugLevel = 1;
+    container.LogLevel = LocalStackLogLevel.Debug;
+});
+```
+
+**Available Options:**
+
+- **`EagerLoadedServices`** - Pre-load specific AWS services at startup (reduces cold start latency)
+- **`Lifetime`** - Container lifecycle: `Persistent` (survives restarts) or `Session` (cleaned up on stop)
+- **`DebugLevel`** - LocalStack debug verbosity (0 = default, 1 = verbose)
+- **`LogLevel`** - Log level control (Error, Warn, Info, Debug, Trace, etc.)
+- **`AdditionalEnvironmentVariables`** - Custom environment variables for advanced scenarios
+
+For detailed configuration guide and best practices, see [Configuration Documentation](docs/CONFIGURATION.md).
+
 #### Manual Configuration
 
 For fine-grained control, you can manually configure each resource:
@@ -126,7 +157,8 @@ The `LocalStack.Aspire.Hosting` host automatically transfers LocalStack configur
 - **Manual Configuration**: Fine-grained control with explicit `WithReference()` calls for each resource
 - **AWS Service Integration**: Works with CloudFormation templates, CDK stacks, and AWS service clients
 - **Automatic Fallback**: Falls back to real AWS services when LocalStack is disabled
-- **Container Lifecycle Management**: Configurable container with session/project lifetime options
+- **Container Lifecycle Management**: Configurable container with session/persistent lifetime options
+- **Eager Service Loading**: Pre-load specific AWS services for faster startup in CI/CD environments
 - **Extension-Based**: Works alongside official AWS integrations for .NET Aspire without code changes
 
 ## Examples

docs/CONFIGURATION.md

@@ -0,0 +1,280 @@
+# LocalStack Configuration Guide
+
+This guide covers configuration options for customizing LocalStack container behavior in .NET Aspire applications.
+
+## Quick Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `EagerLoadedServices` | `IReadOnlyCollection<AwsService>` | `[]` (empty) | AWS services to pre-load at container startup |
+| `Lifetime` | `ContainerLifetime` | `Persistent` | Container lifecycle behavior |
+| `DebugLevel` | `int` | `0` | LocalStack DEBUG flag (0 or 1) |
+| `LogLevel` | `LocalStackLogLevel` | `Error` | LocalStack LS_LOG level |
+| `AdditionalEnvironmentVariables` | `IDictionary<string, string>` | `{}` (empty) | Custom environment variables |
+
+## Service Loading Strategy
+
+LocalStack supports two service loading strategies via the [`EAGER_SERVICE_LOADING`](https://docs.localstack.cloud/aws/capabilities/config/configuration/#core) configuration.
+
+### Lazy Loading (Default)
+
+Services start only when first accessed. This provides faster initial container startup but adds latency to the first request that uses each service.
+
+```csharp
+var localstack = builder.AddLocalStack(); // No eager loading - uses lazy loading
+```
+
+**When to use:**
+
+- Local development (faster container startup)
+- Exploratory development where service usage isn't predictable
+- When working with many services but only using a few
+
+### Eager Loading
+
+Pre-loads specific AWS services during container startup. The container takes longer to start but subsequent requests have no cold-start latency.
+
+```csharp
+builder.AddLocalStack(configureContainer: container =>
+{
+    container.EagerLoadedServices = [AwsService.Sqs, AwsService.DynamoDB, AwsService.S3];
+});
+```
+
+This sets the [`EAGER_SERVICE_LOADING=1`](https://docs.localstack.cloud/aws/capabilities/config/configuration/#core) and [`SERVICES`](https://docs.localstack.cloud/aws/capabilities/config/configuration/#core) environment variables automatically.
+
+**When to use:**
+
+- CI/CD pipelines (consistent startup, no cold-start flakiness)
+- Integration tests (eliminate service initialization variance)
+- When you know exactly which services you'll use
+
+**Available Services:**
+
+You can eagerly load any AWS service supported by LocalStack. Common examples:
+
+```csharp
+container.EagerLoadedServices =
+[
+    AwsService.Sqs,           // Simple Queue Service
+    AwsService.DynamoDB,      // DynamoDB
+    AwsService.S3,            // S3 Storage
+    AwsService.Sns,           // Simple Notification Service
+    AwsService.Lambda,        // Lambda Functions
+    AwsService.CloudFormation,// CloudFormation
+    AwsService.SecretsManager,// Secrets Manager
+    AwsService.Ssm,           // Systems Manager (Parameter Store)
+    // ... see LocalStack docs for full list
+];
+```
+
+For a complete list of supported services, check the [LocalStack health endpoint](https://docs.localstack.cloud/aws/capabilities/networking/internal-endpoints/#localstack-endpoints) at `/_localstack/health`.
+
+## Container Lifetime
+
+Controls when the LocalStack container is created and destroyed.
+
+### Persistent (Default)
+
+Container survives application restarts. Data may persist between debugging sessions depending on your configuration.
+
+```csharp
+container.Lifetime = ContainerLifetime.Persistent;
+```
+
+**When to use:**
+
+- Local development (container reuse between runs)
+- When combined with [LocalStack persistence](https://docs.localstack.cloud/aws/capabilities/state-management/persistence/)
+
+### Session
+
+Container is created when the application starts and destroyed when it stops.
+
+```csharp
+container.Lifetime = ContainerLifetime.Session;
+```
+
+**When to use:**
+
+- CI/CD pipelines (clean slate for each run)
+- Integration tests (isolated test runs)
+- When you want guaranteed clean state
+
+**Recommendation:** Use `Session` for CI/CD and integration tests, `Persistent` for local development.
+
+## Logging and Debugging
+
+### Debug Level
+
+Controls LocalStack's [`DEBUG`](https://docs.localstack.cloud/aws/capabilities/config/configuration/#core) flag for increased log verbosity.
+
+```csharp
+container.DebugLevel = 1; // Enable verbose logging
+```
+
+**Values:**
+
+- `0` (default): Standard log level
+- `1`: Increased log level with more verbose logs (useful for troubleshooting)
+
+### Log Level
+
+Controls LocalStack's [`LS_LOG`](https://docs.localstack.cloud/aws/capabilities/config/configuration/#core) environment variable.
+
+```csharp
+container.LogLevel = LocalStackLogLevel.Debug;
+```
+
+**Available Levels:**
+
+- `Trace`: Detailed request/response logging
+- `TraceInternal`: Internal calls logging
+- `Debug`: Debug level logging
+- `Info`: Info level logging
+- `Warn`: Warning level logging
+- `Error` (default): Error level logging
+- `Warning`: Alias for `Warn`
+
+**Note:** `LS_LOG` currently overrides the `DEBUG` configuration in LocalStack.
+
+For more details on LocalStack logging, see the [official logging documentation](https://docs.localstack.cloud/aws/capabilities/config/logging/).
+
+## Advanced Environment Variables
+
+For advanced scenarios, you can pass custom environment variables to the LocalStack container:
+
+```csharp
+container.AdditionalEnvironmentVariables["LOCALSTACK_API_KEY"] = "your-pro-key";
+container.AdditionalEnvironmentVariables["PERSISTENCE"] = "1";
+```
+
+**Important:** Do not manually set `SERVICES` or `EAGER_SERVICE_LOADING` - these are managed automatically when using `EagerLoadedServices`. An exception will be thrown if conflicts are detected.
+
+**Common Use Cases:**
+
+- LocalStack Pro features ([`LOCALSTACK_API_KEY`](https://docs.localstack.cloud/aws/capabilities/config/configuration/#localstack-pro))
+- [Persistence configuration](https://docs.localstack.cloud/aws/capabilities/state-management/persistence/) (`PERSISTENCE`)
+- Custom [configuration options](https://docs.localstack.cloud/aws/capabilities/config/configuration/)
+
+## Configuration Patterns
+
+### Development
+
+```csharp
+builder.AddLocalStack(configureContainer: container =>
+{
+    container.Lifetime = ContainerLifetime.Persistent;
+    container.LogLevel = LocalStackLogLevel.Warn;
+    // Use lazy loading for faster startup
+});
+```
+
+### CI/CD
+
+```csharp
+builder.AddLocalStack(configureContainer: container =>
+{
+    container.Lifetime = ContainerLifetime.Session;
+    container.LogLevel = LocalStackLogLevel.Error;
+
+    // Eagerly load all services used in tests
+    container.EagerLoadedServices = [AwsService.Sqs, AwsService.DynamoDB, AwsService.S3];
+});
+```
+
+### Debugging
+
+```csharp
+builder.AddLocalStack(configureContainer: container =>
+{
+    container.Lifetime = ContainerLifetime.Session;
+    container.LogLevel = LocalStackLogLevel.Debug;
+    container.DebugLevel = 1;
+
+    // Eagerly load to see startup issues
+    container.EagerLoadedServices = [AwsService.Sqs];
+});
+```
+
+### Integration Testing
+
+```csharp
+builder.AddLocalStack(configureContainer: container =>
+{
+    container.Lifetime = ContainerLifetime.Session;
+    container.LogLevel = LocalStackLogLevel.Error;
+
+    // Eagerly load services to avoid cold-start variance
+    container.EagerLoadedServices = [AwsService.Sqs, AwsService.DynamoDB];
+});
+```
+
+## Troubleshooting
+
+### Environment Variable Conflicts
+
+If you get an error about environment variable conflicts:
+
+```text
+InvalidOperationException: Cannot set 'SERVICES' or 'EAGER_SERVICE_LOADING'
+in AdditionalEnvironmentVariables when using EagerLoadedServices.
+```
+
+**Solution:** Remove manual `SERVICES` or `EAGER_SERVICE_LOADING` from `AdditionalEnvironmentVariables`:
+
+```csharp
+// ❌ DON'T DO THIS
+container.AdditionalEnvironmentVariables["SERVICES"] = "sqs,dynamodb";
+container.EagerLoadedServices = [AwsService.S3]; // Conflict!
+
+// ✅ DO THIS
+container.EagerLoadedServices = [AwsService.Sqs, AwsService.DynamoDB, AwsService.S3];
+```
+
+### Container Health Checks Fail
+
+If health checks fail after container starts:
+
+1. **Enable verbose logging:**
+
+   ```csharp
+   container.DebugLevel = 1;
+   container.LogLevel = LocalStackLogLevel.Debug;
+   ```
+
+2. **Check Aspire Dashboard:** Look at health check details for specific failing services
+
+3. **Try eager loading:** Some services may benefit from eager loading:
+
+   ```csharp
+   container.EagerLoadedServices = [AwsService.Sqs];
+   ```
+
+### Data Not Persisting
+
+If you expect data to persist between runs:
+
+1. **Check container lifetime:** Ensure `ContainerLifetime.Persistent` is set
+2. **Enable persistence:** See [LocalStack Persistence documentation](https://docs.localstack.cloud/aws/capabilities/state-management/persistence/)
+
+   ```csharp
+   container.AdditionalEnvironmentVariables["PERSISTENCE"] = "1";
+   ```
+
+## Best Practices
+
+1. **Use Session lifetime in CI/CD** - Ensures clean state for each test run
+2. **Eagerly load services in CI** - Eliminates cold-start variability in automated tests
+3. **Keep logging minimal in CI** - Use `LogLevel.Error` for cleaner output
+4. **Use Persistent lifetime for development** - Faster iteration with container reuse
+5. **Start with lazy loading** - Only use eager loading when you have a specific need
+6. **Limit eager loaded services** - Only pre-load services you actually use
+7. **Document your configuration** - Add comments explaining configuration choices
+
+## Related Documentation
+
+- [README](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack/blob/master/README.md) - Getting started guide
+- [LocalStack Configuration](https://docs.localstack.cloud/aws/capabilities/config/configuration/) - Official LocalStack configuration reference
+- [LocalStack Persistence](https://docs.localstack.cloud/aws/capabilities/state-management/persistence/) - Data persistence options
+- [LocalStack.NET Client](https://github.com/localstack-dotnet/localstack-dotnet-client) - Client-side configuration

src/Aspire.Hosting.LocalStack/Container/LocalStackContainerImageTags.cs

@@ -18,5 +18,5 @@ internal static class LocalStackContainerImageTags
     /// <summary>
     /// The default LocalStack container image tag.
     /// </summary>
-    internal const string Tag = "4.9.1";
+    internal const string Tag = "4.9.2";
 }

src/Aspire.Hosting.LocalStack/Internal/Constants.cs

@@ -6,4 +6,7 @@ internal static class Constants
     internal const int DefaultContainerPort = 4566;
     internal const string CloudFormationReferenceAnnotation = "Aspire.Hosting.AWS.CloudFormation.CloudFormationReferenceAnnotation";
     internal const string SQSEventSourceResource = "Aspire.Hosting.AWS.Lambda.SQSEventSourceResource";
+
+    internal const string LocalStackHealthClientName = "localstack_health_client";
+    internal const string LocalStackHealthCheckName = "localstack_health";
 }