License Enforcement State Machine

Overview

The EnforcementStateMachine is a system component that determines the platform's license enforcement status. It centralizes the logic for evaluating the current license, applying a signed enforcement policy, and calculating a definitive EnforcementState (e.g., NORMAL, DEGRADED).

This component solves the problem of distributed license evaluation by creating a single, canonical state that other parts of the system can consume. It runs within the admin service, periodically refreshing the state and persisting it to the platform database. The runtime data plane reads this persisted state to enforce license restrictions without needing to perform its own evaluation.

This mechanism is distinct from the offline grace period handling for valid licenses that cannot currently reach the license authority. The two systems can apply their states independently, and consumers of the state are responsible for resolving them, typically by applying the more restrictive of the two.

How it Works

The state machine's primary function is to execute a refresh cycle. This cycle is triggered on application startup and then on a recurring schedule. The refresh process performs the following sequence of operations:

1. Fetch Inputs: It retrieves the current EnforcementPolicy and LicenseState from the LicenseValidator.
2. Determine Validity: It assesses the validity of the current license.
3. Evaluate State: It uses the pure EnforcementEvaluator function to compute the final EnforcementState based on the policy, validity, and the duration of any invalidity.
4. Persist State: It writes the resulting enforcement mode and state to the s2r_system_setting table in the database.
5. Cache State: It updates an in-memory cache with the new state for immediate access by other components in the admin service.

This architecture decouples the complex evaluation logic from the high-performance data plane, which only needs to perform a simple database read.

flowchart TD
    subgraph "Evaluation & Persistence (Admin API)"
        A[Scheduler / Startup] --> B{Enforcement State Machine};
        B -- "1. Reads" --> C(License & Enforcement Policy);
        B -- "2. Determines validity" --> B;
        B -- "3. Evaluates state" --> B;
        B -- "4. Persists result" --> D[(Platform Database)];
    end

    subgraph "Enforcement (Data Plane)"
        E[API Traffic] --> F{Runtime Enforcement Point};
        F -- "Reads state" --> D;
    end

State Evaluation Flow

During each refresh cycle, the machine follows a clear logic to determine the EnforcementState.

License Validity

The first step is to establish LicenseValidity.

• VALID: If the license licenseMode is MODE_LICENSED or if it is in a bootstrap() state, the license is considered VALID. The invalidSince timestamp is set to null, and any persisted value for specaria.unlicensed_since in the database is deleted.
• ABSENT: If the license is in any other state (e.g., MODE_DISABLED), it is considered ABSENT. The machine then reads the specaria.unlicensed_since system setting.
  • If the setting exists, its timestamp is used as the invalidSince value.
  • If the setting does not exist, the current time (clock.instant()) is written to specaria.unlicensed_since and used as the invalidSince value. This marks the first moment the license was observed to be invalid.

Final State Calculation

With the EnforcementPolicy, LicenseValidity, and invalidSince timestamp established, the machine calls the EnforcementEvaluator.evaluate() function. This function contains the core business logic to produce a final EnforcementState based on how long the license has been invalid according to the policy's defined thresholds.

If the new state is different from the previously cached state, an informational log is generated.

Persistence

The computed state is persisted to the s2r_system_setting table as system-level rows under a dedicated platform tenant. This ensures that the data plane reads a single, authoritative state and that tenant-specific settings cannot interfere.

The following keys are used:

• specaria.enforcement_mode: The mode from the enforcement policy (e.g., permissive, enforcing).
• specaria.enforcement_state: The final computed state (e.g., NORMAL, DEGRADED).
• specaria.unlicensed_since: The timestamp when the license was first found to be invalid.

Fail-Safe Design

Configuration

The refresh interval for the state machine is configurable via the following system properties.

Persisted System Settings

The state machine writes the following key-value pairs to the s2r_system_setting table. These settings are the authoritative source for the runtime data plane.

API Reference

The EnforcementStateMachine component exposes methods for internal use and testing. These are not typically exposed over a public HTTP API.

EnforcementState currentState()

Returns the current, in-memory cached EnforcementState. This state is updated by the scheduled refresh task. This allows other components within the admin service to access the current state without querying the database.

EnforcementState refresh()

Manually triggers a full re-evaluation and persistence of the enforcement state. This method performs the same logic as the scheduled refresh. It is public to allow for direct invocation by other system components or for testing purposes.

• Returns: The newly computed and cached EnforcementState.
• Errors: This method never throws. On failure, it logs a warning and returns the previously cached state.

Troubleshooting

The component is designed to be resilient and provides detailed logging.

See Also

• Offline Grace Period Handling: This component should be distinguished from the SpecariaGraceStateMachine, which manages enforcement when a still-valid license cannot be re-verified with the licensing authority (offline grace).

All SOAP-to-REST docs