JDBC-backed Last-Known-Good Platform Settings Cache

Overview

The JdbcPlatformSettingsStore is a persistent, database-backed cache for platform-wide settings. It provides a "last-known-good" (LKG) store, ensuring that the system can operate with a valid configuration even if the primary settings source is temporarily unavailable.

This component solves two main problems:

1. Resilience: It caches the latest successfully fetched platform settings in a database table. If the upstream settings provider cannot be reached, the system can load the last-known configuration from this store.
2. Efficiency: It stores the raw settings JWT and its ETag, allowing the settings poller to use conditional If-None-Match requests, reducing data transfer. It also stores a pre-parsed JSON representation of the settings, avoiding the need to re-parse the JWT on every load.

It is designed to be called by the central platform settings management service. When new settings are fetched, they are passed to the save method for persistence. When the application starts or needs to reload settings, it calls the loadLatest method.

A key feature of this component is its ability to audit changes to the "support break-glass" setting (support_consent_override), creating a clear record of when this override is enabled or disabled.

How it Works

The JdbcPlatformSettingsStore uses a single database table, s2r_specaria_settings_cache, to store the platform settings. It operates on a single row in this table, identified by the fixed primary key id=1.

Persistence Mechanism

When settings are saved, the component performs an UPSERT operation (specifically, INSERT ... ON CONFLICT DO UPDATE) on the s2r_specaria_settings_cache table. This ensures that the single row is created if it doesn't exist or updated if it does.

The data is stored across several columns:

• payload: A JSONB column containing the parsed configuration settings. The raw JWT is explicitly excluded from this payload.
• raw_jwt: The original, unmodified JWT string received from the settings provider. This is never logged.
• etag: The ETag header from the settings provider response, used for conditional polling.
• settings_version: The version number of the settings.
• fetched_at: The timestamp when the settings were originally fetched.

Saving Settings

The process of saving settings via the save method involves several steps to ensure data integrity and proper auditing.

sequenceDiagram
    participant Caller
    participant JdbcPlatformSettingsStore
    participant Database
    participant Audit Log Service

    Caller->>+JdbcPlatformSettingsStore: save(settings, rawJwt, etag)
    JdbcPlatformSettingsStore->>+Database: SELECT override FROM s2r_specaria_settings_cache
    Database-->>-JdbcPlatformSettingsStore: Previous override value
    JdbcPlatformSettingsStore->>+Database: UPSERT into s2r_specaria_settings_cache
    Database-->>-JdbcPlatformSettingsStore: upsert result
    Note over JdbcPlatformSettingsStore: Compares previous and new<br/>support_consent_override values
    alt support_consent_override changed
        JdbcPlatformSettingsStore->>+Audit Log Service: Write audit record
        Audit Log Service-->>-JdbcPlatformSettingsStore: audit result
    end
    JdbcPlatformSettingsStore-->>-Caller: void

1. Read Previous State: Before writing, the store queries the database to get the current persisted value of the support_consent_override flag. This read is wrapped in an exception handler; if it fails, the operation continues, assuming the previous state was false.
2. Upsert Data: The PlatformSettings object is serialized to a JSON string, and the upsert method is called to write the new settings, raw JWT, and ETag to the database.
3. Compare and Audit: The store compares the previous support_consent_override value with the new one.
4. Audit Transition: If the value has changed, the auditBreakGlassTransition method is invoked to log a WARN message and write a detailed audit event.

Loading Settings

The loadLatest method retrieves the cached settings from the database.

1. It executes a SELECT query on s2r_specaria_settings_cache for the row where id = 1.
2. If no row is found (e.g., on a fresh installation), it returns an empty result.
3. If a row is found, it reads all relevant columns.
4. The payload_json content is deserialized into a PlatformSettings object. If this parsing fails, a WARN is logged, and a minimal, empty PlatformSettings object is returned to prevent system failure.
5. Finally, it returns a Stored object containing the PlatformSettings, the raw_jwt, and the etag.

Support Break-Glass Auditing

A critical function of this store is to create an audit trail for the support_consent_override flag, also known as the "support break-glass" mechanism.

When the save method detects a change in this boolean flag, it generates an audit event with the following characteristics:

• Actor: system@platform
• Action: support-consent.break-glass.on or support-consent.break-glass.off.
• Entity Type: support_consent. This specific type ensures the audit record is visible to deployment administrators, unlike other platform-level events.
• Details: The event includes the "before" and "after" values of the supportConsentOverride flag and the settingsVersion that introduced the change.

This comparison is made against the value durably persisted in the database, not an in-memory value, which prevents false audit events after an application restart. If two instances save the same transition concurrently, both may write an audit record, following a principle of "over-audit, never under-audit".

API Reference

The JdbcPlatformSettingsStore class implements the PlatformSettingsStore interface.

loadLatest()

Loads the most recently saved platform settings from the database.

• Returns: An Optional<Stored> object.
  • If settings are found, the Optional contains a Stored object wrapping the PlatformSettings, the raw JWT string, and the ETag string.
  • If no settings are cached, the Optional is empty.

save(PlatformSettings settings, String rawJwt, String etag)

Persists a new version of platform settings to the database and audits relevant changes.

• Parameters:
  • settings (PlatformSettings): The parsed platform settings object to save.
  • rawJwt (String): The raw, signed JWT from which the settings were derived.
  • etag (String): The ETag associated with this version of the settings, for cache-invalidation.
• Returns: void.
• Side Effects:
  • Writes to the s2r_specaria_settings_cache database table.
  • May write an audit event if the support_consent_override flag changes.
  • Logs a WARN message upon a support_consent_override transition.

Persisted Data Schema

The component relies on a specific database table and a JSON structure within it.

s2r_specaria_settings_cache Table

payload JSON Schema

The payload column contains a JSON object with the following top-level fields.

An example of the payload JSON structure:

{
  "customer_id": "cust-12345",
  "customer_display_name": "Example Corp",
  "deployment_mode": "standard",
  "public_base_url": "https://api.example.com",
  "support_consent_override": false,
  "region": {
    "allowed": [
      "us-east-1",
      "eu-west-2"
    ],
    "selected": "us-east-1",
    "state": "ACTIVE"
  },
  "branding": {
    "logo_url": "https://cdn.example.com/logo.png",
    "primary_locale": "en-US"
  }
}

Troubleshooting

The component logs specific messages to indicate its status or error conditions.

See Also

• Platform Settings Overview
• Audit Log Service
• Support Consent and Break-Glass Procedures

All SOAP-to-REST docs