Runtime SaaS Capability Check

Overview

The SettingBackedSaasCapability is a runtime component that determines whether the platform's Software-as-a-Service (SaaS) features are enabled.

The runtime component itself does not have the capability to verify license grants directly. To solve this, it relies on a different component, the admin-api, which owns the license verification logic. The admin-api evaluates the license and publishes a simple boolean flag to a shared database setting. The SettingBackedSaasCapability component provides other runtime services with a cached, read-only view of this flag.

This mechanism allows runtime services, such as the SaasTenantResolver for multi-tenancy, to gate functionality based on the active license without performing complex verification on every request. The component's output is a boolean value indicating if SaaS is enabled.

How it works

The SettingBackedSaasCapability uses a combination of scheduled database reads and an in-memory cache to provide an efficient and resilient capability check. The entire process is designed to be fail-safe, prioritizing system stability and security.

flowchart TD
    subgraph admin-api [Admin API Component]
        A[Verify License] --> B{SaaS Enabled?}
        B -- Yes --> C[Write 'true' to DB Setting]
        B -- No --> D[Write 'false' to DB Setting]
    end

    subgraph runtime [Runtime Component]
        E(Scheduled Refresh / Startup) --> F[Read DB Setting]
        F --> G{Row Found & Valid?}
        G -- Yes --> H[Parse Boolean Value]
        G -- No / DB Error --> I[Retain Last Known Value]
        H --> J[Update In-Memory Cache]
        I --> K[Use Cached Value]
        J --> K
    end

    subgraph db[Shared Database]
        C --> db_setting(s2r_system_setting)
        D --> db_setting
        F --> db_setting
    end

    L(Runtime Services) --> M{SaaS Feature Gate}
    M -- Check --> K

Caching and Refresh Cycle

The component maintains the SaaS enabled status in an AtomicBoolean cache.

1. Initialization: The cache is initialized to false. This "fail-closed" approach ensures that SaaS features are disabled by default until an explicit true value is read from the database.
2. Startup Priming: Upon application startup (ApplicationStartedEvent), the component immediately runs a refresh cycle to prime the cache with the current value from the database. This avoids a delay where the system might operate with the default false value after a restart.
3. Scheduled Refresh: The component periodically calls the refresh() method on a schedule. This keeps the cache synchronized with the database flag, which the admin-api component updates hourly based on license re-verification. The refresh interval is configurable.

Database Interaction

The refresh logic reads a specific row from the s2r_system_setting table, identified by the key specaria.saas_enabled. This read operation is performed in the platform's tenant context to access the shared setting.

• If the database row exists and contains a valid boolean string ("true" or "false"), the in-memory cache is updated.
• If the value in the cache changes (e.g., from false to true), a log message is generated: S2R-SAAS-CAP runtime capability transition {} -> {}.

Failure Handling

The component is designed to be resilient to database connectivity issues and missing data.

Configuration

The refresh schedule can be configured via the following application properties. The values must be specified in ISO-8601 duration format.

API Reference

The component exposes public methods that can be used by other services within the runtime application.

isEnabled()

Returns the current cached state of the SaaS capability flag. This is the primary method used by other components to gate SaaS-only features.

• Returns: boolean — true if the cache indicates SaaS is enabled; false otherwise.

refresh()

Manually triggers a refresh of the SaaS capability flag from the database and updates the in-memory cache. This method is primarily intended for testing or targeted administrative actions.

• Returns: boolean — The state of the capability flag after the refresh attempt.

Troubleshooting

SaaS features are not enabled after applying a valid license.

• Cause: The component is fail-closed. This can happen if the admin-api component has not yet written the specaria.saas_enabled flag to the database, or if the runtime component has not yet completed its first refresh cycle.
• Action: Verify that the admin-api is running and has successfully processed the license. Check the logs for refresh activity on the runtime component.

Log message: S2R-SAAS-CAP saas_enabled read failed

• Cause: The runtime component failed to connect to the database or execute the query to read the SaaS capability flag.
• Meaning: This indicates a transient database issue. The component will continue to use its last known value for the SaaS flag and will retry the read on the next scheduled interval. The system remains operational but is not receiving updates on its license status.

Log message: S2R-SAAS-CAP runtime capability transition

• Cause: The value of the SaaS capability flag has changed in the database, and the cache has been updated.
• Meaning: This is a normal operational log. It indicates a change in the licensed state, such as when a new license is applied or an existing one expires.

See Also

• Admin API: The component responsible for all license verification. It writes the database flag that SettingBackedSaasCapability reads.
• SaasTenantResolver: A runtime service that depends on this capability check to correctly resolve tenants in a multi-tenant environment.
• OfflineGraceProbe: Another component that uses a similar pattern of reading a shared setting published by the Admin API.

All SOAP-to-REST docs