zhmdff.uc.Client 1.0.6

zhmdff.uc.Client

A fail-open .NET 8 client SDK for the zhmdffUC control-plane. Provides ASP.NET Core middleware, background polling, Serilog sink, and log transport with zero impact on your application's reliability during control-plane downtime.

Features

• Middleware: automatically short-circuits requests when your project status is Paused or Disabled
• Heartbeat Endpoint: Built-in /_uc/status endpoint to allow the control-plane to ping, wake up, and sync with your container.
• Fail-Open: if the control-plane is unreachable and FailOpen = true, all requests pass through
• Background polling: dual IHostedService loop — status poll + log flush. Supports ETag optimization to reduce bandwidth.
• Log Transport: ships logs to the control-plane respecting per-project enabled log levels. Supports optional GZIP compression.
• Metadata & Profile Sync: Read and write project-specific private metadata (UpdateMetadataAsync) and fetch centralized app profiles.
• SDK registration: announces itself to the control-plane on startup (version, hostname, runtime)
• Dual-Key Auth Support: Supports both project-specific API keys and the global Master API Key for authentication.

Package Structure

zhmdff.uc.Client/
  MasterControlExtensions.cs   — AddMasterControl() + UseMasterControl()
  MasterControlMiddleware.cs   — ASP.NET Core middleware (with /_uc/status heartbeat + ETags)
  MasterControlService.cs      — IHostedService (status poll + log flush + ping loops)
  ZhmdffUcClient.cs            — On-demand polling client (Metadata, Status, Profile)
  ZhmdffUcOptions.cs           — Options class
  IZhmdffUcClient.cs           — Interface for mocking
  Http/
    MasterControlHttpClient.cs — Centralized HttpClient with ETags and GZIP support

Logging/ MasterControlSink.cs — Serilog ILogEventSink LogBuffer.cs — ConcurrentQueue<LogEntry> (max 1000, drop-oldest) Models/ ProjectStatus.cs LogBatch.cs SdkRegistration.cs DependencyInjection/ — Internal DI helpers Cache/ — IMemoryCache slot management

---

## Quick Start

### 1. Configure `appsettings.json`
```json
{
  "MasterControl": {
    "BaseUrl": "https://uc.zhmdff.dev",
    "ProjectId": "your-project-guid",
    "ApiKey": "your-project-api-key",
    "PollIntervalSeconds": 30,
    "LogFlushIntervalSeconds": 45,
    "FailOpen": true,
    "GzipLogs": false,
    "GzipThreshold": 1024
  }
}

2. Register in Program.cs

using zhmdff.uc.Client;

// Registers typed HttpClient, IHostedService, and Serilog sink
builder.Services.AddMasterControl(builder.Configuration);

// Optional: Serilog integration
builder.Host.UseSerilog((ctx, cfg) =>
    cfg.WriteTo.Console()
       .WriteTo.MasterControl());

var app = builder.Build();

// Must be first middleware in the pipeline
app.UseMasterControl();

3. Middleware Behaviour

On each request MasterControlMiddleware reads the cached ProjectStatus from IMemoryCache:

Response body for /_uc/status:

{
  "projectId": "guid",
  "status": "Active",
  "statusCode": 200,
  "isFromCache": true
}

Options Reference

Serilog Sink

MasterControlSink checks the EnabledLogLevels returned by the last status poll before enqueuing. Only matching log levels are buffered.

// Wired automatically by AddMasterControl() — or manually:
.WriteTo.MasterControl()

LogBuffer is a ConcurrentQueue<LogEntry> capped at 1,000 entries. Oldest entries are dropped on overflow.

Resilience Guarantees

Running Tests

cd Packages/nuget
dotnet test zhmdff.uc.Client.Tests\zhmdff.uc.Client.Tests.csproj --logger "console;verbosity=normal"

Current version: 1.0.6.

Part of the zhmdffUC ecosystem. See usage.md for full integration guide.