feat(floci): model Cosmos API as a child resource

[thomhurst]

Closes #1545

Overview

Models the Cosmos DB API exposed by the Floci Azure emulator as a dedicated Aspire child resource. Dependents now use Aspire's standard WithReference flow, so Cosmos appears in the resource graph and can be swapped with another IResourceWithConnectionString for deployment.

Usage

var azure = builder.AddFlociAzure("floci-az");
var cosmos = azure.WithCosmos();

builder.AddProject<Projects.Api>("api")
    .WithReference(azure)    // storage variables (optional)
    .WithReference(cosmos)   // ConnectionStrings__cosmos
    .WaitFor(azure);

const azure = await builder.addFlociAzure('floci-az');
const cosmos = await azure.withCosmos();

await builder.addProject('api', '../MyApi/MyApi.csproj')
    .withFlociAzureReference(azure)
    .withReference(cosmos)
    .waitFor(azure);

App side remains the normal flow:

builder.AddAzureCosmosClient("cosmos");

What's included

• WithCosmos(name = "cosmos", accountName = null) returning IResourceBuilder<FlociAzureCosmosResource>.
• FlociAzureCosmosResource implements IResourceWithConnectionString and IResourceWithParent<FlociAzureContainerResource>.
• Standard WithReference(cosmos) injects ConnectionStrings__{resourceName}.
• Cosmos endpoint follows Aspire endpoint resolution and TLS scheme changes.
• Custom resource and account names remain supported.
• README and unit tests updated.
• Generated public API file left for CI regeneration.

Testing

• WithReferenceTests: 11/11 passed.
• Floci project build: net8.0, net9.0, and net10.0; 0 warnings, 0 errors.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[aaronpowell]

Doing the review and I feel like this kind of has to work around some of the design of how Aspire works since we're not really treating the floci resource as something that can provide a Cosmos-formatted connection string, and bypassing the WithReference design for that.

I wonder if this as an API wouldn't be better:

var azure = builder.AddFlociAzure("floci-az");

var cosmos = azure.WithCosmos();

builder.AddProject<Projects.Api>("api")
  .WithReference(azure)
  .WithReference(cosmos)
  .WaitFor(azure);

In this case the WithCosmos() method would return a IResourceBuilder<FlociAzureCosmosResource>, and then we treat it as a dedicated resource on its own which overrides the connection string creation to return a Cosmos formatted one.

This then models the CosmosDB part of Floci as a resource in its own right, making it visualise what the resource graph looks like, unlike your current proposal which would show the resource graph as not containing a CosmosDB resource since the resource doesn't exist it's just something teased out of another resource. Then, since it's modelled as a resource, you can handle deployments easier by doing something like:

IResourceBuilder<IResourceWithConnectionString> cosmos = builder.IsDeployment ?
  builder.AddAzureCosmos(...) :
  flociAzure.WithCosmos();

(yes, that code isn't 100% right, I'm doing it from memory 😅).

Does that make sense?

[thomhurst]

Addressed review feedback in 088933e:

• Replaced WithCosmosReference with azure.WithCosmos().
• Added FlociAzureCosmosResource implementing IResourceWithConnectionString and IResourceWithParent<FlociAzureContainerResource>.
• Dependents now use standard .WithReference(cosmos).
• Added parent relationship so Cosmos appears in resource graph.
• Reverted generated API surface file.
• Updated C#/TypeScript docs and tests.

Validation: WithReferenceTests 11/11 passed; Floci project builds cleanly on net8.0/net9.0/net10.0.

[aaronpowell]

Thanks @thomhurst - looks right to go.