MODULE 13 · LESSON 13.6
Build your own cloud configuration server
Implement your own cloud configuration server with the open reference sample.
Lesson 81 of 88 · FabrCore 2.0
Overview
The open reference cloud demonstrates the host-facing contract without requiring Insights source. Your server owns authentication, effective configuration/versioning and durable administration state. Reusing the contract lets existing FabrCore Hosts connect without a private agent protocol.
The reference sample makes the wire contract concrete
A conforming server authenticates the cluster key, selects the effective environment resource, and returns the versioned envelope. It also accepts heartbeats and can request a refresh according to the protocol. The sample is a starting implementation of that Host-facing contract, not a complete product with durable operator accounts, publishing policy or fleet storage.
Stable versions make caching correct
Hash or otherwise version the effective document deterministically. Whitespace/order quirks in a serializer should not cause an endless stream of meaningless versions, while an environment-only change must not be hidden under an old ETag. Define offline, unknown-environment, credential-rotation and schema-version behavior in tests rather than letting an HTTP framework's defaults decide them.
Retain reports independently from desired settings
Accept the optional ConfigurationState heartbeat contract and advertise configuration-state: 1 on compatible hosts. Store observations per host process using BootId, Sequence and ObservedAt. Reject stale sequences, retain the prior report when legacy heartbeats omit it, and show dated/offline or truncated observations explicitly.
The reference server provides GET /operator/configuration/reports and POST /operator/configuration/draft. A draft body contains hostInstanceId and keys; eligible applied values are copied into a separate settings draft. Desired configuration is not rewritten. State and preview requests use the existing outbound administration command channel.
Validate and redact at ingestion. Cap reports at 256 rows and 196,608 serialized bytes. The fixture serves one cluster in one process with bounded in-memory reports and commands. Durable storage, tenant scoping, operator permissions and publish concurrency remain production responsibilities.
Implement the configuration endpoint
- Start from samples/FabrCore.ReferenceCloud. Program.cs is the entry point; ReferenceCloudApplication.cs implements routes and authentication, and ConfigurationReportStore.cs validates and retains bounded reports. Its operator API is an example, not a required publishing API.
- Implement the effective configuration, ETag/304 and heartbeat contracts with protected credentials. If offering base/environment overlays, document and test that server-owned merge policy.
- Run the compatibility checks below before connecting a production Host. Add durable publishing/operation storage and operator authorization for your deployment.
using System.Collections.Concurrent;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Channels;
using FabrCore.Core.CloudServer;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Hosting;
namespace FabrCore.ReferenceCloud;
internal static class ReferenceCloudApplication
{
internal static WebApplication Build(string[] args, Action<WebApplicationBuilder>? configure = null,
Func<string, string?>? readEnvironment = null)
{
// Single-cluster, single-process conformance fixture. Pending commands are intentionally
// not replayed after a process restart. Production servers need durable leases/receipts.
var builder = WebApplication.CreateBuilder(args);
configure?.Invoke(builder);
builder.WebHost.ConfigureKestrel(o => o.Limits.MaxRequestBodySize = 1024 * 1024);
var clusterKey = Required("REFERENCE_CLUSTER_KEY");
var operatorKey = Required("REFERENCE_OPERATOR_KEY");
var clusterId = Required("REFERENCE_CLUSTER_ID");
var environment = Required("REFERENCE_ENVIRONMENT");
var configurationFile = Path.GetFullPath(Required("REFERENCE_CONFIGURATION_FILE"));
var queue = Channel.CreateBounded<CloudAdminCommand>(100);
var commands = new ConcurrentDictionary<string, (CloudAdminCommand Command, CloudAdminCommandResponse? Response)>();
var reports = new ConfigurationReportStore(clusterId, environment);
var app = builder.Build();
app.Use(async (context, next) =>
{
var admin = context.Request.Path.StartsWithSegments("/operator");
var expected = admin ? operatorKey : clusterKey;
var supplied = context.Request.Headers.Authorization.ToString();
if (!Equal(supplied, "Bearer " + expected) || (!admin &&
(context.Request.Headers[CloudServerProtocol.ClusterIdHeader] != clusterId ||
context.Request.Headers[CloudServerProtocol.EnvironmentHeader] != environment)))
{ context.Response.StatusCode = 401; return; }
await next(context);
});
app.MapGet(CloudServerProtocol.ConfigurationPath, async (HttpContext context) =>
{
var contents = await File.ReadAllBytesAsync(configurationFile, context.RequestAborted);
var etag = "\"" + Convert.ToHexString(SHA256.HashData(contents)) + "\"";
context.Response.Headers.ETag = etag;
return context.Request.Headers.IfNoneMatch.Contains(etag) ? Results.StatusCode(304) : Results.Bytes(contents, "application/json");
});
app.MapPost(CloudServerProtocol.HeartbeatPath, (CloudHeartbeatRequest heartbeat) =>
{
try { reports.Accept(heartbeat); }
catch (ArgumentException) { return Results.BadRequest(new { error = "Invalid heartbeat or configuration report." }); }
return Results.Ok(new CloudHeartbeatResponse());
});
app.MapGet("/operator/configuration/reports", () => Results.Ok(reports.Snapshot()));
app.MapPost("/operator/configuration/draft", async (ConfigurationDraftRequest request, HttpContext context) =>
{
var contents = await File.ReadAllTextAsync(configurationFile, context.RequestAborted);
var desired = System.Text.Json.JsonSerializer.Deserialize<CloudConfigurationEnvelope>(contents, System.Text.Json.JsonSerializerOptions.Web)!;
try
{
var settings = reports.CreateDraft(request.HostInstanceId, request.Keys, desired.Settings ?? []);
// Return a reviewable draft only. Publishing must use the server's revision/concurrency policy.
return Results.Ok(new { baseRevision = desired.ConfigurationVersion, settings });
}
catch (ArgumentException) { return Results.BadRequest(new { error = "The selected observations cannot be adopted." }); }
});
app.MapPost("/operator/commands", (CloudAdminCommand input) =>
{
if (!input.PathAndQuery.StartsWith("/fabrcoreapi/admin/v1/", StringComparison.Ordinal) ||
input.Method is not ("GET" or "POST" or "PUT" or "DELETE")) return Results.BadRequest();
if (commands.Count >= 1000) return Results.StatusCode(429);
var command = new CloudAdminCommand { CommandId = Guid.NewGuid().ToString("N"),
LeaseToken = Convert.ToHexString(RandomNumberGenerator.GetBytes(32)),
Method = input.Method, PathAndQuery = input.PathAndQuery, Body = input.Body,
ExpiresAt = DateTimeOffset.UtcNow.AddSeconds(60), Headers = new(StringComparer.OrdinalIgnoreCase)
{ ["X-FabrCore-Admin-Actor"] = ["reference-operator"] } };
if (input.Headers.TryGetValue("If-Match", out var revision)) command.Headers["If-Match"] = revision;
if (input.Body is not null) command.Headers["Content-Type"] = ["application/json"];
commands[command.CommandId] = (command, null);
if (!queue.Writer.TryWrite(command)) { commands.TryRemove(command.CommandId, out _); return Results.StatusCode(429); }
return Results.Accepted("/operator/commands/" + command.CommandId, new { command.CommandId });
});
app.MapGet(CloudServerProtocol.ConnectPath, async (HttpContext context) =>
{
using var timeout = CancellationTokenSource.CreateLinkedTokenSource(context.RequestAborted);
timeout.CancelAfter(TimeSpan.FromSeconds(20));
try
{
while (await queue.Reader.WaitToReadAsync(timeout.Token))
if (queue.Reader.TryRead(out var command) && command.ExpiresAt > DateTimeOffset.UtcNow)
return Results.Ok(command);
}
catch (OperationCanceledException) when (!context.RequestAborted.IsCancellationRequested) { }
return Results.NoContent();
});
app.MapPost("/fabrcore-cloud/v2/connect/{id}/response", (string id, CloudAdminCommandResponse response) =>
{
if (!commands.TryGetValue(id, out var prior) || response.CommandId != id ||
!Equal(response.LeaseToken, prior.Command.LeaseToken)) return Results.NotFound();
if (prior.Response is not null) return Results.Conflict();
if (prior.Command.ExpiresAt <= DateTimeOffset.UtcNow) return Results.StatusCode(410);
return commands.TryUpdate(id, (prior.Command, response), prior) ? Results.NoContent() : Results.Conflict();
});
app.MapGet("/operator/commands/{id}", (string id) =>
{
if (!commands.TryGetValue(id, out var entry)) return Results.NotFound();
if (entry.Response is not null) return Results.Ok(entry.Response);
return Results.Json(new { status = entry.Command.ExpiresAt <= DateTimeOffset.UtcNow ? "incomplete" : "pending" }, statusCode: 202);
});
app.MapDelete("/operator/commands/{id}", (string id) => commands.TryRemove(id, out _) ? Results.NoContent() : Results.NotFound());
return app;
string Required(string name) => (readEnvironment ?? Environment.GetEnvironmentVariable)(name) is { Length: > 0 } value ? value : throw new InvalidOperationException(name + " is required.");
static bool Equal(string left, string right) => CryptographicOperations.FixedTimeEquals(SHA256.HashData(Encoding.UTF8.GetBytes(left)), SHA256.HashData(Encoding.UTF8.GetBytes(right)));
}
}
POST /operator/configuration/draft
Authorization: Bearer <operator-key>
Content-Type: application/json
{
"hostInstanceId": "<reported-host-instance>",
"keys": ["FabrCore:Host:WebSocketPath"]
}
Connect the same Host to your implementation
- Run the reference Cloud Server and point the development Host at it with matching authentication and environment identifiers. Observe configuration and heartbeat traffic.
- Request the same effective configuration twice with If-None-Match on the second request. Expect 304 until the effective body changes, then 200/new version.
- Test invalid keys, an unsupported envelope schema and first connection with no usable configuration. Confirm the Host follows the documented failure/last-known-good behavior.
- Send a newer report, an older sequence and a legacy heartbeat. Verify the newest report is retained, secret values remain redacted and draft adoption changes no desired settings.
This establishes protocol compatibility for the exercised cases. Production operator authentication, secret storage and durable publishing/operation state still belong to your Cloud Server implementation.
If the result is different
A valid JSON response is insufficient if its ETag changes nondeterministically or environment layering differs. Use the normative protocol and reference validation cases.
Go deeper
Explore the related documentation.