Runtime configuration
FabrCore 2.0 · Release and package availability
These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes
See which settings the cloud requested, which values the host resolved, and which values its running components actually use. Preview a candidate before publishing it, and explain overrides and pending restarts with observations from each host process.
Follow tour lesson 13.3 for a configuration exercise, or lesson 13.6 to implement the same contract in your own cloud server. Vulcan365 Insights is one implementation; these contracts require no Insights packages or identities.
Desired, resolved and applied
| State | What it establishes |
|---|---|
| Desired | The supported settings supplied by the Cloud Server, identified by a revision. |
| Resolved | The value after configuration providers, named code rules and supported host defaults. |
| Applied | A value observed in an actual supported consumer or provider after startup. Unobserved components remain unverified. |
A settings catalog describes configuration and apply modes; it is not proof of runtime application. A stored SQL mode can be masked by an operator override. Conversely, SQL membership selected through database defaults is reported from the running Orleans membership provider even when no explicit clustering mode exists in JSON.
Supported scalar options are observed when consumers access them. Snapshot consumers retain their consumed value across refresh. Monitored options record successful access/change callbacks; failed callbacks remain unverified. Named options are separate runtime facts. Arbitrary post-configuration is marked code-or-consumer when observed values differ from input; preview never replays those startup callbacks.
Name the rules your application owns
Register pure rules on FabrCoreServerOptions before host registration. Read dependencies through the context. Do not register services, initialize databases or perform external writes in a rule.
using FabrCore.Host;
var options = new FabrCoreServerOptions()
.ConfigureRuntime("OperationsDesk.Hosting", context =>
{
if (context.EnvironmentName == "Production")
{
const string key = "FabrCore:Orleans:ClusteringMode";
context.Override(key, "SqlServer", "Production uses shared durable state.");
context.Require(key,
value => string.Equals(value, "SqlServer", StringComparison.OrdinalIgnoreCase),
"Production requires SQL Server clustering.");
}
});
builder.AddFabrCoreServer(options);Default fills an absent key; explicit null is not absent. Override declares code ownership even when its value equals the cloud value. Standard environment and command-line providers retain final precedence. Require validates the final value, including operator inputs. Competing named owners are rejected. Keep names and reasons free of secrets.
Rules run at registration, cloud refresh and explicit preview. Ordinary file reloads and late provider registrations do not rerun them: use cloud refresh or restart when those inputs change. Enrollment settings in fabrcore.cloud.json remain separate. The legacy fabrcore.json A2A fallback has lower priority than cloud and operator configuration.
Inspect and preview without applying
Use the normal authenticated administration channel. The heartbeat advertises configuration-state: 1; older hosts need a configuration-only fallback.
GET /fabrcoreapi/admin/v1/settings/state
Authorization: Bearer <administration-credential>
POST /fabrcoreapi/admin/v1/settings/preview
Authorization: Bearer <administration-credential>
Content-Type: application/json
{
"FabrCore:Host:WebSocketPath": "/ws"
}The POST body is the complete candidate cloud settings map, with string or null values. Merge your draft first; it is not a one-key patch. Preview requires cloud runtime settings to be enabled and rejects unsupported keys and failed constraints. It runs pure rules and infrastructure resolution without changing installed settings, firing reload notifications or constructing another host.
Compare candidate resolved values with the current applied observations. A changed draft invalidates its previous preview. Publish through your server's revision/concurrency policy and inspect each process again. Rule rejection retains the installed cloud layer and rule outputs and records the rejected revision. A consumer may fail after a valid candidate is installed; reports do not promise rollback.
PendingRestart compares known applied values against resolvable current inputs for restart-required settings. A cloud value masked by code does not itself imply restart. An unknown consumer or an unreplayable callback cannot prove a prospective value.
Reports for independent cloud servers
CloudHeartbeatRequest.ConfigurationState carries the optional CloudConfigurationState contract from Core. Reports begin after application startup and include BootId, increasing Sequence, ObservedAt, application build, received/rejected revisions, errors and setting rows. Keep reports per process, reject stale sequences, and retain the last report when a legacy heartbeat omits it. Show stored timestamps and incomplete or truncated observations explicitly.
Reports redact secret values and cap rows at 256 and serialized payloads at 196,608 bytes. They exclude enrollment and remote-administration settings. Do not infer secrets from redacted nulls or infer application from schema example values.
The reference server demonstrates GET /operator/configuration/reports and POST /operator/configuration/draft. Draft requests specify a hostInstanceId and keys. Adoption copies eligible applied values into a separate draft and leaves desired settings and code ownership unchanged. Secrets, unverified values, derived/runtime facts and cluster/service identities cannot be adopted.
The reference implementation uses bounded in-memory state for one cluster and one process. Production servers supply tenant scoping, durable observation and command storage, authentication and revision handling. Confirmed commits, automatic rollback and storage migration are not implemented by this reporting protocol.
Observe custom consumers
Register IFabrCoreRuntimeSettingsContributor to return RuntimeSettingObservation values from real consumer instances. Do not construct replacement services or write state during inspection. Configurable keys need a settings descriptor; Runtime: facts are read-only observations. Mark sensitive values Secret: true. Nested or unsupported options remain unverified unless explicitly observed.
Source references: reconciliation behavior and open configuration-state protocol.