Lyo.Config.Api 3.0.0

Lyo.Config.Api

HTTP host for central app configuration, backed by PostgreSQL and Lyo.Config. Microservices resolve merged config per deployment identity and poll using ETags or an optional version query mirror.

Resolution contracts (ConfigResolveConditionalResult) live in Lyo.Config.Api.Models. The HTTP typed client and AddConfigApiClientFromConfiguration live in Lyo.Config.Api.Client (readme). Route slug to EntityRef mapping uses AppConfigEntity from Lyo.Config. Polling plus IOptionsMonitor<T> is Lyo.Config.Api.Hosting.

Examples

Embed the host (DI + middleware pipeline)

using Lyo.Config.Api;
using Lyo.Config.Api.Security;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddConfigApi(builder.Configuration);

var app = builder.Build();
app.UseMiddleware<RequireConfigApiKeyMiddleware>(); // BEFORE MapConfigApiEndpoints
app.MapConfigApiEndpoints(); // default prefix /api/config
app.Run();

Samples (curl)

# Latest snapshot
curl -sS "http://localhost:5088/api/config/gateway/prod-west"

# Lightweight metadata only
curl -sSI "http://localhost:5088/api/config/gateway/prod-west"

# Poll with previous ETag (quoted)
ETAG='"A1B2C3..."'
curl -sSI -H "If-None-Match: $ETAG" "http://localhost:5088/api/config/gateway/prod-west"

# Same using version= (bare hex, no quotes)
curl -sSI "http://localhost:5088/api/config/gateway/prod-west?version=A1B2C3D4..."

Embed the host (DI + middleware pipeline)

Lyo.Config.Api can run as an example host (see Lyo.Config.Api.Example) or be embedded into another host that already owns the WebApplication pipeline. Two extensions plus one middleware, all in Lyo.Config.Api, are the registration surface:

How the standalone host is composed (and the pattern any embedding host should follow):

RequireConfigApiKeyMiddleware ordering and behavior

• Registered as a pipeline middleware (not an authorization filter). It checks HttpContext.Request.Path.StartsWithSegments("/api/config", …) and silently passes through any request outside that prefix. If you relocate the API by passing a non-default prefix to MapConfigApiEndpoints, the middleware will not match it. /api/config is the hard-coded path check.
• When ConfigApiSecurity.RequireApiKey == false, the middleware short-circuits to _next without inspecting headers. Toggling RequireApiKey to true requires the host to configure a non-empty ApiKey; otherwise matching requests get 500 Internal Server Error with { "detail": "API key enforcement is enabled but no server key has been configured." }.
• When enabled, the middleware accepts the secret via X-Api-Key: <value> or Authorization: Bearer <value> (other schemes are rejected). Comparison uses CryptographicOperations.FixedTimeEquals over UTF-8 bytes; missing / empty / mismatching credentials produce 401 Unauthorized with no body.
• Place this middleware after any TLS termination / proxy header middleware and before any logging that might leak request bodies, since it always returns before the endpoint runs on rejection.

Security options (ConfigApiSecurityOptions, section ConfigApiSecurity)

Note: this project has no authorization policy or scopes/role check, only the constant-time secret comparison above. If you need finer-grained access control, register your own auth middleware before RequireConfigApiKeyMiddleware, or replace it entirely.

Hosting options (ConfigApiHostingOptions, section ConfigApiHosting)

How routes map to Lyo.Config

A single store entity type App (AppConfigEntity.AppEntityType) is used for all API traffic for app config.

The persisted compound id:

EntityType = "App"
EntityId = "{appKind}:{appId}" // e.g. gateway:prod-west

Definitions you create with PUT /manage/definitions should use forEntityType: "App". Bindings must use the same App + that compound forEntityId, or use the manage routes below.

At runtime: resolve and poll

Base path (default): /api/config.

At runtime: resolve and poll. GET, HEAD, POST. /{appKind}/{appId}

• HEAD: same ETag / 304 behaviour, no body on 200.
• POST: same body as GET when you prefer not to put long ids in query strings.

Management (/api/config/manage)

The same auth as the rest of /api/config is required when ConfigApiSecurity.RequireApiKey is true (X-Api-Key or Authorization: Bearer).

Query routes and encryption

Lyo.Query get/query/export at Config/Definition and Config/Binding (no generic CRUD writes) are also mapped by MapConfigApiEndpoints. Those queries deny DefaultValueJson and EncryptedDefaultValue. Value encryption uses a keyed IEncryptionService named config-values on this host and TestApi only. Clients send plaintext plus IsEncrypted; the API encrypts at rest. TestGateway does not register encryption — its workbench uses ConfigApiStore over HTTP so encryption still happens in TestApi.

Configuration (appsettings)

• PostgresConfig: connection string and migrations for Lyo.Config.Postgres.
• ConfigApiHosting: optional PollIntervalAdvisoryMilliseconds (see Host embedding → Hosting options above).
• ConfigApiSecurity: RequireApiKey, ApiKey (see Host embedding → Security options above).

C# consumer (Lyo.Config.Api.Client)

Register the typed client:

using Lyo.Config.Api.Client;

services.AddConfigApiClientFromConfiguration(configuration);
// Alternate section binding:
// services.AddConfigApiClientFromConfiguration(configuration, configSectionName: "MyConfigApi");

var resolved = await configClient.ResolveForAppAsync(
    appKind: "gateway",
    appId: "prod-west",
    ifNoneMatch: lastEtag,
    version: null,
    headOnly: false,
    cancellationToken: ct);

// Background poll
var merged = await ConfigPolling.PollUntilChangedAsync(
    configClient,
    appKind: "api",
    appId: "checkout",
    ifNoneMatch: null,
    delayWhenNotModified: TimeSpan.FromSeconds(15),
    cancellationToken: ct);

Bind ConfigApi in configuration for BaseUrl, optional ApiKey, PollInterval, and similar ( ConfigApiClientOptions). More examples: Lyo.Config.Api.Client/README.md.

Run locally

dotnet run --project Lyo.Net/Apps/Config/Lyo.Config.Api/Lyo.Config.Api.csproj

/openapi/v1.json is the Development OpenAPI document (ASP.NET convention). Scalar UI is mapped only when the environment is Development.

See also

• Feature docs: Lyo.Config/README.md

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Api (direct, lyo)
• Lyo.Api.Export (direct, lyo)
• Lyo.Authentication (direct, lyo)
• Lyo.Authentication.AspNetCore (direct, lyo)
• Lyo.Authentication.Google (direct, lyo)
• Lyo.Authentication.Keycloak (direct, lyo)
• Lyo.Authentication.OpenIdConnect (direct, lyo)
• Lyo.Authentication.Postgres (direct, lyo)
• Lyo.Cache (direct, lyo)
• Lyo.Common.Core (direct, lyo)
• Lyo.Config (direct, lyo)
• Lyo.Config.Postgres (direct, lyo)
• Lyo.Encryption (direct, lyo)
• Lyo.EntityReference.Models (direct, lyo)
• Lyo.KeyStore (direct, lyo)
• Lyo.Api.Models (transitive, lyo)
• Lyo.Authentication.Models (transitive, lyo)
• Lyo.Common.Metadata (transitive, lyo)
• Lyo.Compression (transitive, lyo)
• Lyo.DateAndTime (transitive, lyo)
• Lyo.Diagnostic (transitive, lyo)
• Lyo.Diagnostic.AspNetCore (transitive, lyo)
• Lyo.Diff (transitive, lyo)
• Lyo.EntityReference.Postgres (transitive, lyo)
• Lyo.Exceptions (transitive, lyo)
• Lyo.Formatter (transitive, lyo)
• Lyo.Hashing (transitive, lyo)
• Lyo.Health (transitive, lyo)
• Lyo.Json (transitive, lyo)
• Lyo.Metrics (transitive, lyo)
• Lyo.PackageMetadata (transitive, lyo)
• Lyo.Parameters (transitive, lyo)
• Lyo.Postgres (transitive, lyo)
• Lyo.Query (transitive, lyo)
• Lyo.Query.Evaluation (transitive, lyo)
• Lyo.Query.Models (transitive, lyo)
• Lyo.Query.Sql (transitive, lyo)
• Lyo.Result (transitive, lyo)
• Lyo.Streams (transitive, lyo)
• Lyo.Validation (transitive, lyo)
• Lyo.Validation.Models (transitive, lyo)
• BouncyCastle.Cryptography 2.6.2 (transitive, third-party, netstandard2.0)
• DynamicExpresso.Core 2.19.3 (transitive, third-party)
• EasyCompressor 2.1.0 (transitive, third-party)
• Konscious.Security.Cryptography.Argon2 1.3.1 (transitive, third-party)
• Microsoft.AspNetCore.OpenApi 10.0.5 (transitive, microsoft)
• Microsoft.Bcl.AsyncInterfaces 10.0.5 (transitive, microsoft, netstandard2.0)
• Microsoft.EntityFrameworkCore 10.0.5 (transitive, microsoft)
• Microsoft.EntityFrameworkCore.Analyzers 10.0.5 (transitive, microsoft)
• Microsoft.EntityFrameworkCore.Design 10.0.5 (transitive, microsoft)
• Microsoft.EntityFrameworkCore.Relational 10.0.5 (transitive, microsoft)
• Microsoft.Extensions.Caching.Memory 10.0.5 (transitive, microsoft)
• Microsoft.Extensions.Configuration.Binder 10.0.5 (transitive, microsoft)
• Microsoft.Extensions.DependencyInjection 10.0.5 (transitive, microsoft)
• Microsoft.Extensions.DependencyInjection.Abstractions 10.0.5 (transitive, microsoft, net10.0, netstandard2.0)
• Microsoft.Extensions.Hosting.Abstractions 10.0.5 (transitive, microsoft)
• Microsoft.Extensions.Logging.Abstractions 10.0.5 (transitive, microsoft)
• Microsoft.Extensions.Options 10.0.5 (transitive, microsoft)
• Microsoft.Extensions.Options.ConfigurationExtensions 10.0.5 (transitive, microsoft)
• Npgsql.EntityFrameworkCore.PostgreSQL 10.0.3 (transitive, third-party)
• SmartFormat.NET 3.6.1 (transitive, third-party)
• System.Buffers 4.6.1 (transitive, microsoft, netstandard2.0)
• System.ComponentModel.Annotations 5.0.0 (transitive, microsoft)
• System.IO.Hashing 10.0.5 (transitive, microsoft, net10.0)
• System.Memory 4.6.3 (transitive, microsoft, netstandard2.0)
• System.Text.Encoding.CodePages 10.0.5 (transitive, microsoft)
• System.Text.Json 10.0.5 (transitive, microsoft, netstandard2.0)
• System.Threading.Tasks.Extensions 4.6.3 (transitive, microsoft, netstandard2.0)