License Enforcement Probe

Overview

The EnforcementProbe is a component within the data-plane runtime responsible for monitoring the platform's license enforcement status. It provides an efficient, low-latency mechanism for the runtime to check the current enforcement state on a per-request basis.

This component solves the problem of needing to enforce licensing rules in the high-throughput data plane without incurring the performance cost of verifying a license JWT on every request. It achieves this by separating concerns:

1. The admin-api component performs the computationally intensive task of parsing and verifying the license. It then resolves the license terms into a simple, authoritative enforcement state.
2. admin-api persists this state to a central database table (s2r_system_setting).
3. The EnforcementProbe in each runtime instance reads this pre-calculated state from the database, caches it in memory, and makes it available to other runtime components, such as a request-path filter.

This design ensures that the runtime acts only on the resolved state and does not need to contain any license verification logic itself.

How It Works

The EnforcementProbe maintains an in-memory, atomically updated cache of the current EnforcementState. This cache is consulted by a request filter on every incoming request, avoiding any database overhead during request processing. The cache is populated and kept up-to-date through a scheduled refresh mechanism.

flowchart TD
    subgraph Admin API
        A[License JWT Verification] --> B{Enforcement State Machine};
        B --> C[Write to DB];
    end

    subgraph Database
        D[s2r_system_setting table];
    end

    subgraph Runtime
        subgraph EnforcementProbe
            E[Scheduled Refresh] --> F{Read from DB};
            F --> G[Update In-Memory Cache];
        end
        H[Request Filter] --> I[Read from Cache];
        I --> J{Enforce Policy};
    end

    C -- "Writes 'specaria.enforcement_state'" --> D;
    F -- "Reads 'specaria.enforcement_state'" --> D;
    G -- "Provides state via currentState()" --> I;

The operational lifecycle is as follows:

1. Initial State: The probe starts with a conservative default state of EnforcementState.NORMAL.
2. Startup Priming: Immediately upon application startup (triggered by ApplicationStartedEvent), the probe executes its first refresh. This ensures that the cache is populated with the true state from the database before the runtime serves its first request.
3. Periodic Refresh: The probe is scheduled to refresh its state from the database at a regular interval (default is every 60 seconds).
4. Refresh Logic: During a refresh, the refresh() method is called:
   • It executes a SQL query to read the value of the specaria.enforcement_state key from the s2r_system_setting table.
   • The database read is performed under a special __platform__ tenant context to guarantee it retrieves the global, system-wide setting.
   • If the database read fails, the probe "fails open": it logs a warning and keeps the existing cached value, ensuring that a transient database issue does not cause a service disruption.
   • If the setting is not found in the database or its value is empty, it is decoded as EnforcementState.NORMAL. The runtime never hardens its enforcement level due to a missing upstream value.
   • If the new state differs from the previously cached state, the probe updates its cache and logs an informational message (S2R-LIC-RUN enforcement state transition...) detailing the change. It also fetches the specaria.enforcement_mode value for inclusion in this log message.
5. State Consumption: Consumers, such as a request-path filter, call the currentState() method to get the current cached EnforcementState. This is a fast, in-memory read that is safe to call on every request.

Configuration

The probe's refresh schedule is controlled by the following configuration properties. The values must be specified in ISO-8601 duration format.

Database Interaction

The probe's operation is critically dependent on reading state from the s2r_system_setting table. This table acts as a communication channel between the admin-api and the runtime.

• specaria.enforcement_state: The primary key holding the authoritative enforcement state (e.g., NORMAL).
• specaria.enforcement_mode: An auxiliary key holding a descriptive string about the current state, used for logging purposes.

The probe uses the following SQL query to read the effective value for a given key, scoped to the platform tenant.

select setting_value #>> '{}' as v
from s2r_system_setting
where setting_key = ? and is_effective = true
 and tenant_id = '__platform__' or (tenant_id is null and not exists (select 1 from s2r_system_setting s2 where s2.setting_key = s2r_system_setting.setting_key and s2.tenant_id = '__platform__')) order by tenant_id is null asc, updated_at desc limit 1

Programmatic API Reference

The EnforcementProbe component exposes a programmatic API for internal use within the runtime.

currentState()

Returns the currently cached license enforcement state. This is a fast, non-blocking, in-memory operation and is the primary method for checking the license status on the request path.

• Returns: EnforcementState - The cached enforcement state.

currentMode()

Returns the raw string value of the specaria.enforcement_mode setting as of the last successful refresh. This is intended for logging and diagnostics.

• Returns: String - The last known mode string, or null if a refresh has never completed or the setting was absent.

refresh()

Manually triggers a refresh of the enforcement state from the database. This method is public for testing and targeted diagnostic purposes.

• Returns: EnforcementState - The new state after the refresh attempt. If the database read fails, this will be the same as the previously cached state.

Troubleshooting

Database Read Failure

• Condition: The probe fails to execute its query against the database due to a connection error, permissions issue, or other database exception.
• Indication: A WARN message is logged: S2R-LIC-RUN enforcement setting read failed for <key>: <error>.
• Effect: The probe "fails open." It preserves the last successfully fetched enforcement state in its cache and continues to serve that state. The system's enforcement level will not change as a result of a transient database failure.

Missing or Invalid State in Database

• Condition: The specaria.enforcement_state row is not present in the s2r_system_setting table, or its value is blank.
• Indication: No error is logged. The probe will function normally.
• Effect: The probe decodes the absent or blank value as EnforcementState.NORMAL. This is a fail-open design choice to prevent the system from becoming overly restrictive if the admin-api has not yet written the state or has written an invalid one.

Auditing State Changes

• Condition: The enforcement state changes (e.g., from NORMAL to a more restrictive state).
• Indication: An INFO message is logged: S2R-LIC-RUN enforcement state transition <PREVIOUS>-><NEXT> (mode=<mode>).
• Effect: This log provides a clear audit trail for when and why the runtime's enforcement behavior changed.

See Also

• Admin API: The administrative component responsible for verifying the license and persisting the resolved EnforcementState to the database for this probe to consume.
• Offline Grace Period Probe: A component with a similar design (OfflineGraceProbe) that reads the specaria.last_platform_contact_at setting to determine platform connectivity status.

All SOAP-to-REST docs