feat: CommunityToolkit.Aspire.Hosting.Floc — Floci AWS emulator hosing integration

[edmondshtogu]

Closes floci-io/floci#1242

Adds CommunityToolkit.Aspire.Hosting.Floci — a hosting integration for Floci, a high-performance AWS emulator (65+ services, LocalStack-compatible) that runs as a container inside the Aspire AppHost.

What's included

Core integration (src/CommunityToolkit.Aspire.Hosting.Floci/)

• AddFloci(name, port?, defaultRegion?, defaultAccountId?) — adds the Floci container with health check at /_floci/info
• WithReference(floci) automatically injects AWS_ENDPOINT_URL, AWS_DEFAULT_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY into dependent resources via a BeforeStartEvent subscriber. Host processes get localhost:{port}; containers get host.docker.internal:{port}
• WithDataVolume / WithDataBindMount — switches Floci to persistent storage mode
• WithDockerSocket — mounts the Docker socket and sets FLOCI_DOCKER_DOCKER_HOST so Lambda and other container-backed services can launch sibling containers
• WithConfigFile(hostPath) — bind-mounts a Quarkus application.yml override at /deployments/config/application.yml for advanced Floci configuration not covered by extension methods
• TLS — WithHttpsCertificateConfiguration is registered inside AddFloci and fires automatically when the Aspire developer certificate service is active (or when WithHttpsDeveloperCertificate() is chained). Sets FLOCI_TLS_ENABLED, FLOCI_TLS_CERT_PATH, FLOCI_TLS_KEY_PATH and switches connection strings to https:// — no integration-specific TLS wrapper needed. WithDeveloperCertificateTrust(true) is also registered so Floci trusts the dev cert for its own outbound calls

Example app (examples/floci/)

• AppHost — orchestrates Floci + ApiService, demonstrating WithReference, WaitFor, and health checks
• ApiService — minimal ASP.NET Core app showing S3 bucket listing via AWSSDK.S3
• AppHost.TypeScript — TypeScript AppHost covering the full exported API surface for compile-time validation

Tests (tests/CommunityToolkit.Aspire.Hosting.Floci.Tests/)

• Container lifecycle, health check, connection string, data volume/bind-mount, Docker socket, config file, and TLS env-var tests

PR Checklist

• Created a feature/dev branch in your fork (vs. submitting directly from a commit on main)
• Based off latest main branch of toolkit
• PR doesn't include merge commits (always rebase on top of our main, if needed)
• New integration
  • Docs are written
  • Added description of major feature to project description for NuGet package (4000 total character limit, so don't push entire description over that)
• Tests for the changes have been added (for bug fixes / features) (if applicable)
• Contains NO breaking changes
• Every new API (including internal ones) has full XML docs
• Code follows all style conventions

Other information

• Floci serves both HTTP and HTTPS on the same port (4566), so no endpoint annotation switching is needed when TLS is enabled
• AWS_ENDPOINT_URL is the standard SDK v4 env var; no AmazonS3Config.RegionEndpoint should be set alongside ServiceURL (triggers a NullReferenceException in the v4 endpoint rule engine — documented in the example)
• The ASPIRECERTIFICATES001 experimental diagnostic is suppressed at file level in the hosting extension
• TypeScript AppHost uses @ts-expect-error guards for experimental certificate APIs that have no polyglot binding yet

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/CommunityToolkit/Aspire/main/eng/scripts/dogfood-pr.sh | bash -s -- 1448

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/CommunityToolkit/Aspire/main/eng/scripts/dogfood-pr.ps1) } 1448"

[Copilot]

Pull request overview

This PR introduces a new CommunityToolkit.Aspire.Hosting.Floci hosting integration that models the Floci AWS emulator as an Aspire container resource, plus accompanying examples (C# + TypeScript AppHost) and automated tests to validate resource wiring and startup.

Changes:

• Added AddFloci + related fluent configuration APIs (data persistence, Docker socket, config file, TLS wiring) and the FlociContainerResource model.
• Added an end-to-end example (examples/floci) including a minimal API service using AWSSDK.S3, plus a TypeScript AppHost for polyglot surface validation.
• Added integration and model-level tests and registered the new projects in the solution and root README integration list.

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/CommunityToolkit.Aspire.Hosting.Floci.Tests/TypeScriptAppHostTests.cs	Adds an integration test ensuring the TypeScript AppHost compiles and starts required resources.
tests/CommunityToolkit.Aspire.Hosting.Floci.Tests/ContainerResourceCreationTests.cs	Adds unit tests validating resource construction, image metadata, env var wiring, and mount annotations.
tests/CommunityToolkit.Aspire.Hosting.Floci.Tests/CommunityToolkit.Aspire.Hosting.Floci.Tests.csproj	Introduces the Floci test project and references to the integration and examples.
tests/CommunityToolkit.Aspire.Hosting.Floci.Tests/AppHostTests.cs	Adds a Docker-required integration test asserting the Floci resource becomes healthy.
src/CommunityToolkit.Aspire.Hosting.Floci/README.md	Provides usage documentation and examples for the new Floci hosting integration.
src/CommunityToolkit.Aspire.Hosting.Floci/FlociHostingExtension.cs	Implements the hosting integration extension methods (AddFloci and configuration helpers).
src/CommunityToolkit.Aspire.Hosting.Floci/FlociContainerResource.cs	Adds the Floci container resource model and connection string/connection properties.
src/CommunityToolkit.Aspire.Hosting.Floci/FlociContainerImageTags.cs	Defines the default container image coordinates for Floci.
src/CommunityToolkit.Aspire.Hosting.Floci/CommunityToolkit.Aspire.Hosting.Floci.csproj	Adds the new integration package project and dependencies.
README.md	Adds Floci to the repository’s integrations table and link references.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost/Program.cs	Adds a sample AppHost wiring Floci + ApiService with health checks and references.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost/CommunityToolkit.Aspire.Hosting.Floci.AppHost.csproj	Adds the example C# AppHost project for Floci.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost.TypeScript/tsconfig.json	TypeScript compiler configuration for the polyglot AppHost example.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost.TypeScript/package.json	Defines the TypeScript AppHost example’s scripts, dependencies, and Node engine constraints.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost.TypeScript/package-lock.json	Locks dependencies for the TypeScript AppHost example.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost.TypeScript/eslint.config.mjs	Adds ESLint configuration for the TypeScript AppHost example.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost.TypeScript/aspire.config.json	Adds Aspire config for the TypeScript AppHost example and local package wiring.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost.TypeScript/apphost.mts	Implements the TypeScript AppHost example covering runtime and compile-only scenarios.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.ApiService/Properties/launchSettings.json	Adds launch settings for the example API service.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.ApiService/Program.cs	Adds a minimal API demonstrating S3 access against the emulator using injected env vars.
examples/floci/CommunityToolkit.Aspire.Hosting.Floci.ApiService/CommunityToolkit.Aspire.Hosting.Floci.ApiService.csproj	Adds the example API service project and AWSSDK.S3 dependency.
CommunityToolkit.Aspire.slnx	Registers the new integration, tests, and example projects in the solution.

Files not reviewed (1)

• examples/floci/CommunityToolkit.Aspire.Hosting.Floci.AppHost.TypeScript/package-lock.json: Generated file

[edmondshtogu]

@aaronpowell can you please take a look here?