EyeAuras.Chiral.EntityFrameworkCore 0.1.0-alpha.5

EyeAuras.Chiral

Application-neutral .NET infrastructure for managed service nodes, discovery and PostgreSQL messaging, built on MassTransit. PackageId is EyeAuras.Chiral; namespace and assembly are Chiral.

Requirements and installation

The core targets netstandard2.0, with native Microsoft DI, settings lifecycle, discovery and PostgreSQL transport. It requires neither EF nor the ASP.NET shared framework. Source builds use SDK 10/C# 12; consumer runtimes are independent of that toolchain.

Optional packages, at the same version as the core:

The prior 0.1.0-alpha.1 package retains its original .NET 10 target. This package family requires an explicitly published new version. Add only the adapters your host needs; ASP.NET runtime is needed only by the HTTP adapter. PostgreSQL remains the sole production transport.

Migrating hosts must rebuild: direct INodeConfigurationModule implementations now supply EditorId, UiSchema and RestoreAsync explicitly (null/null/forward-to-ApplyAsync preserves the previous defaults). MappedNodeConfigurationModule retains its virtual defaults. FileStore/HTTP public types move assemblies; generic AddChiral<TContext> moves to ChiralEntityFrameworkServiceCollectionExtensions. Wire identities/settings documents remain unchanged.

Generic Host and default DI

using Chiral;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
// Deployment supplies Chiral:Mode=Connect and ConnectionStrings:Chiral.
builder.Services.AddNode(new NodeDescriptor("worker", "worker", "Worker"));
builder.Services.AddChiral(builder.Configuration);
using var host = builder.Build();
await host.RunAsync();

Configure Chiral:Mode=Off for an offline/stateless host. Connect requires an already provisioned transport database and runtime credentials; it performs no DDL. Use AddChiralProvisioning in a separate privileged provisioning process before starting clients. The runtime role must not have access to host business databases. Hosts own messages, consumers and business outbox persistence; call AddChiral once for the default MassTransit bus.

Managed node configuration

Hosts opt in through standard Microsoft.Extensions.DependencyInjection with AddNodeConfiguration() and singleton module-owned INodeConfigurationModule registrations. Register settings before workload hosted services, independently of AddChiral() call order. AddManagedNodeConfiguration(builder.Configuration) is optional for modules that publish configuration-key overlays; repeat calls on the same services/configuration share one overlay and gate registry. Use the host configuration consumed by modules. Register a custom INodeConfigurationStore or add EyeAuras.Chiral.FileStorage and call AddNodeFileStorage; the host container owns its lifetime. Call AddChiral() once for the default bus. A plain stateless host does not acquire a settings store/control endpoint. Register configuration hosting before workload hosted services. Each module supplies its JSON Schema, effective bootstrap configuration, semantic validation, workload gate and resource-application callback. Schemas use draft-07; format assertions are validated on the server. Secret fields use writeOnly and the masked GET value __configured__: omission/mask keeps the secret, a value replaces it, null/empty deletes it subject to validation. Nested objects/arrays, local JSON Pointer references and allOf/anyOf/oneOf are supported for secrets; composition conservatively masks every annotated branch. Removing an ordinary parent or array item removes its descendants. Array masks retain by index; send actual credentials when reordering/replacing items. Unsupported secret applicators/references fail closed. Never expose validator or provider exception text containing values.

The authenticated host API sends commands to the process-specific control address announced in heartbeat. NodeId selects a co-hosted module; InstanceId identifies a process run, not a persistent config key. Old nodes without configuration advertisements continue working. Heartbeats carry revision/status metadata only. Configuration and schemas are retrieved on demand. The Chiral bus remains trusted; the public API must derive the actor from its admin identity and enforce its existing CSRF protection.

The optional FileStorage backend is a private file directory specified by Nodes:ConfigurationDirectory (local default .node-config). Mount a persistent, private directory per deployment replica, outside any web/upload root. Every co-hosted node has its own document. Do not share a directory between live replicas: an OS-held ownership lock rejects a second owner. Linux creates directories/files with owner permissions; existing directories/documents must already be private. Unix staging is restricted before writing even when reused; on Windows provision suitable inherited ACLs and protect any existing staging file. Include the directory in protected backups; its documents contain secrets. Database/transport connection bootstrap stays in deployment configuration, never in managed module documents.

New settings audit timestamps use the host singleton TimeProvider (default System); the legacy coordinator constructor remains available. Historical saved/active/interrupted-start metadata is retained. Accepted save/retry IDs remain indefinitely retained across restart/time advancement.

Save validates and atomically replaces the document with config, enabled, revision and apply intent. Until the first save, modules use effective deployment values without inventing revision timestamps. After a save, the entire module document is authoritative; adapters must not silently mix fields from new environment values. Server-owned apply drains admitted work, replaces module resources and only then publishes active revision/time/actor and reopens admission. Other nodes and the control plane stay live. Failure leaves the last successful active metadata intact and the affected workload unavailable. Retry targets the current failed operation and creates no configuration revision. Request IDs are retained for deduplication, without retaining historical configuration values.

Startup reapplies saved state before admitting workload. Interrupted applying intents retain their initiator; restoration of already-active state preserves its metadata. A fresh system-initiated attempt after a previous failure is attributed to System. Browser cancellation never owns this lifecycle. Each module must actually route its workload through the gate and return from ApplyAsync only after its effective settings/resources have changed; registration alone does not implement reload/restart.

Options and readiness

Use standard Configure/PostConfigure with ChiralTransportOptions, NodeDiscoveryOptions and NodeConfigurationOptions. Transport timeout/retry policy is captured at startup. Discovery interval, region and heartbeat TTL follow monitored options. Defaults preserve a 15-second heartbeat, TTL multiplier 3, 30-second bus start/stop timeout and five retries at 100 milliseconds. The settings text limit defaults to 65,536 UTF-16 units.

Modules can implement INodeConfigurationReadiness to declare readiness independently of a custom runtime status. Existing modules retain the RuntimeStatus == "running" fallback. Discovery is an observation; actual work must respect the module's admission gate.

PostgreSQL maintenance

Provisioning runs MassTransit migrations, installs the Chiral maintenance coordination guards, and grants the runtime role access using the configuration supplied to the registration. Guards serialize maintenance callers and fence stale RepeatableRead snapshots without changing upstream message isolation/retry behavior. Reprovision before resuming clients after restoring a transport database into a different PostgreSQL cluster. Hosts own provisioning credentials and transport backups.

License and source availability

EyeAuras.Chiral is MIT licensed; LICENSE and THIRD-PARTY-NOTICES.md are included in the package. Dependencies retain their own licenses. Public/protected API documentation ships as lib/net10.0/Chiral.xml.

The package is public; its GitHub source repository currently remains private. Portable PDBs are distributed in the matching snupkg. Repository/commit metadata identifies the build, but source links require repository access; public source debugging is not promised. Full private source is not embedded in the package.