Skip to content

Component: Smrt.Config

Canonical source: SmrtApps/src/Smrt.Config/README.md (mirrored below)

Smrt.Config

  • Configuration Subsystem (contracts and invariants): README.Files/Subsystems/Configuration/README.md
  • Configuration Capability (end-to-end flow): README.Files/Capabilities/Configuration/README.md

Overview & Responsibilities

  • Canonical library for resolving SmrtHub configuration and state file locations under the Operational Data Policy slugs.
  • Provides atomic JSON read/write helpers used by C# and Python runtimes to avoid corruption across concurrent processes.
  • Ships embedded logging defaults (Logging/appsettings.logging.json) so hosts can bootstrap Smrt.Logging without external files.

Dependencies & Integrations

  • Targets .NET 8; referenced by every SmrtHub app/library that needs configuration or logging defaults.
  • Integrates with SmrtHub.Logging to supply default sinks and retention settings via LoggingConfigurationExtensions.
  • Consumes Microsoft.Extensions.Configuration.Json for embedding the logging JSON stream.

Configuration & Log Paths

  • All helpers resolve into %APPDATA%/SmrtHub/Config/<component-slug>/ (roaming) or %LOCALAPPDATA%/SmrtHub/Config/<component-slug>/ (local) as defined in the Operational Data Policy.
  • JSON persistence methods generate .bak backups alongside the primary file and never write outside the canonical directories.
  • The logging defaults expect runtime log emission into %LOCALAPPDATA%/SmrtHub/Logs/<component-slug>/ with HTML export enabled via Smrt.Logging.

Runtime Flows

  • ConfigPathResolver normalizes component names into kebab-case slugs, creates directories if missing, then returns canonical file paths for config/state/custom artifacts.
  • ConfigJson exposes atomic read/modify/write utilities; callers wrap mutations with WithNamedMutex to guarantee single-writer semantics and will receive a timeout if the mutex cannot be acquired.
  • LoggingConfigurationExtensions.AddSmrtHubLoggingDefaults injects the embedded JSON into an IConfigurationBuilder before hosts construct their Serilog pipeline.

Public surface

The primary public surface is the set of APIs listed under Key APIs below.

Key APIs

  • ConfigPathResolver.GetComponentDirectory(component, scope) – returns %AppData%|%LocalAppData%/SmrtHub/Config/<slug> and ensures the directory exists.
  • ConfigPathResolver.GetFilePath(component, kind, scope, customFileName?, jsonExtOverride?) – produces canonical <slug>-config.json/<slug>-state.json paths without manual string manipulation.
  • ConfigPathResolver.GetConfigPath(component, fileName?) – returns the component directory when no file name is supplied, or combines the directory with caller-provided file names that still align with policy.
  • ConfigJson.LoadObject/SaveObject/Update – typed helpers for JsonObject persistence with deterministic serialization and retries on transient IO or parse errors.
  • ConfigJson.WithNamedMutex(name, action, timeoutMs?) – cross-process guard that throws TimeoutException when the mutex cannot be acquired within the allotted window.
  • LoggingConfigurationExtensions.AddSmrtHubLoggingDefaults(builder) – merges the embedded Logging:SmrtHub defaults into the host configuration.
  • Logging.SmrtLoggingOptions – strongly-typed options for binding logger settings prior to calling Smrt.Logging.Logger.ConfigureFrom.

Testing & Validation

  • Consumers cover this library through integration tests in their respective apps; when changing slug rules or atomic write semantics, run dotnet test for dependent solutions and perform config read/write smoke tests.
  • Exercise ConfigJson.WithNamedMutex in a multi-process harness when adjusting timeout behavior; the method now throws TimeoutException if the lock cannot be acquired.
  • Validate logging defaults by bootstrapping an app with the embedded configuration and confirming log rollovers and PII scrubbing behavior.

Support Bundle & Diagnostics

  • Support bundles collect configuration snapshots directly from the canonical directories produced by this library.
  • Logging defaults align with the HTML export pipeline; no additional diagnostics hooks are required beyond Smrt.Logging conventions.

Subdirectories

  • Logging/ – Houses the embedded logging JSON and typed binding model; see SmrtApps/src/Smrt.Config/Logging/README.md for details.
  • bin/, obj/ – Generated build output; excluded from documentation scope.