System Settings Management

Overview

The System Settings repository provides a centralized mechanism for managing and persisting system-wide configuration. It serves as the source of truth for operational parameters, feature flags, and tenant-specific customizations that need to be configurable without requiring a new deployment.

This component solves the problem of managing dynamic configuration by storing settings in a database table, s2r_system_setting. It provides services with a typed, tenant-aware API to read these settings. Key responsibilities include:

• Persistence: Storing settings in a SQL database.
• Mutability Control: A defined allow-list (MUTABLE_KEYS) dictates which settings can be modified at runtime.
• Tenancy: Supports a multi-tenant overlay model where tenant-specific settings can override platform-wide defaults.
• Secret Management: Encrypts sensitive values (like passwords and tokens) at rest and prevents them from being exposed in API responses.
• Configuration Resolution: Implements a fallback chain (DB setting → environment variable → hardcoded default) for critical settings like public URLs and localization.

Other services and components throughout the platform consume this repository to retrieve their configuration dynamically. API publishers with administrative privileges can modify these settings through the admin API.

How it Works

The SystemSettingRepository manages settings as key-value pairs stored in the s2r_system_setting database table. The system's behavior is governed by the interaction of several core mechanisms: data storage and tenancy, reading and writing settings, and specialized handling for secrets.

Settings Persistence and Tenancy

System settings are stored with tenant affinity. The platform supports a two-tiered configuration model:

1. Platform Defaults: A set of default values is associated with a shared, platform-level entity (__platform__).
2. Tenant Overrides: Each tenant can have its own specific value for a setting.

When a setting is read, the system first looks for a value specific to the current tenant. If one exists, it is used. If not, the system falls back to the platform-default value. This overlay allows for both global configuration and per-tenant customization. SQL queries are explicitly scoped to ensure a tenant's request can only access its own settings or the platform defaults, never the settings of another tenant.

Reading Settings

Settings are retrieved from the database using methods that respect the tenant-overlay model.

• The findEffectiveMap() method returns a map of all effective settings for the current tenant, with tenant-specific values shadowing platform defaults.
• Typed getters like getInt(), getString(), and getBoolean() retrieve a single setting value. They query for the tenant-specific value first, then the platform default, and finally return a caller-provided default if neither is found.

All read operations for secret values are handled specially to avoid exposing sensitive data (see Secret Management).

Updating Settings

Settings are modified via the patch() method, which accepts a map of key-value pairs to update. The process is as follows:

1. Validation: The request is first validated to ensure the payload is not empty.
2. Mutability Check: Each key in the payload is checked against the MUTABLE_KEYS allow-list. An attempt to modify a non-mutable key results in an IllegalArgumentException.
3. Value Validation: For certain keys, specific value validation is performed. For example, install_profile must be one of a few allowed strings. Invalid values are rejected.
4. Secret Handling: If a key is identified as a secret (i.e., it is in the SECRET_KEYS set), its value is encrypted using the CredentialsCipher service before being persisted. A blank or null value is ignored, preserving the existing secret.
5. Persistence: The validated and (if necessary) encrypted key-value pairs are written to the s2r_system_setting table using an UPSERT operation (INSERT ... ON CONFLICT ... DO UPDATE). This creates the setting if it's new for the tenant or updates the existing one. The user or process performing the update is recorded as the actor.

Secret Management

To protect sensitive data, certain settings are designated as secrets.

• Secret Keys: A predefined set of keys (SECRET_KEYS) like alert_smtp_password and f5_password are treated as secrets.
• Encryption at Rest: When a secret setting is updated via patch(), the value is encrypted before being stored in the database. The stored value is a JSON object containing the encrypted data and algorithm details.
• Egress Masking: When settings are read via findEffectiveMap(), any secret value is removed from the map. In its place, a boolean flag named <key>_set is added (e.g., f5_password_set). This confirms whether a value has been configured without exposing the value itself.
• Decryption: To use a secret, internal services must call the getSecret(String key) method, which retrieves the encrypted value from the database and decrypts it.
• Legacy Migration: The encryptLegacyPlaintextSecrets() method provides a way to find and encrypt any secrets that were stored in plain text before the encryption-at-rest feature was implemented. This is an idempotent operation designed to be run once per tenant.

Configuration Value Resolution

For a few critical, globally-used settings, the repository provides dedicated resolver methods that implement a multi-tiered fallback logic. This makes the system resilient to misconfiguration and provides flexible overrides. The standard resolution chain is:

1. Database: The value from the s2r_system_setting table for the current tenant.
2. Environment Variable: A system environment variable on the host machine.
3. Default Value: A hardcoded, generic default value in the code.

This pattern is used for the following settings:

• public_base_url
• openapi.primary_locale
• openapi.supported_locales
• local.timezone

The diagram below illustrates the resolution flow for the public_base_url setting.

flowchart TD
    subgraph resolvePublicBaseUrl()
        A[Read 'public_base_url' from DB] --> B{Value present?};
        B -- Yes --> C[Use DB value];
        B -- No / DB Error --> D[Read S2R_PUBLIC_BASE_URL env var];
        D --> E{Value present?};
        E -- Yes --> F[Use env var value];
        E -- No --> G[Use empty string];
        C --> H[Strip trailing slashes];
        F --> H;
        G --> I[Return final value];
        H --> I;
    end

API Reference

The SystemSettingRepository exposes the following public methods for use by other platform services.

System Settings Reference

The following table lists all system settings that are mutable at runtime via the Admin API.

General Settings

Update Channel Settings

These settings control the platform's automatic update behavior.

• update_channel | String | release | The update channel for the deployment. Valid values: internal, beta, early-access, release. The legacy aliases stable, early-release, and rc are also accepted on write. - |
• update_mode | String | operator_approved | The update mode. operator_approved requires manual approval for updates. auto allows automatic updates within the defined window. - |
• update_check_interval_hours | Integer | 24 | The interval in hours for checking for new updates. Must be between 1 and 168. - |
• update_window_utc_start_hour | Integer | 2 | The hour (in UTC, 0-23) when the automatic update window begins.

All SOAP-to-REST docs