Offline Grace Period and Degraded Mode

Overview

This document describes how the product behaves when it cannot connect to the central licensing platform. The system is designed to ensure that a temporary loss of connectivity does not interrupt API traffic. It achieves this by operating normally for a bounded offline period and then degrading gracefully, rather than failing abruptly.

The product distinguishes between two types of interactions with the central platform:

• Telemetry: Best-effort signals like capacity heartbeats and update polls. Failures are logged, but operations continue. This is a "fail open" approach.
• Entitlement: License verification. If the license cannot be re-validated, the product eventually restricts certain operations after a grace period. This is a "fail closed" approach.

This design ensures that a network outage does not silently place the installation into a state that is either more or less privileged than its license allows.

How it works

When the product cannot reach the central platform (api.specaria.io) to re-verify its license, it relies on a cached verification result and enters a temporary "offline grace" window.

The Offline Grace Window

For the first 14 days of being unable to contact the licensing platform, the product continues to operate normally based on its last successful license verification. This period is known as the offline grace window. All features and operations remain available.

If connectivity is not restored within this 14-day window, the product transitions into a staged, degraded mode.

Staged Degraded Mode

Degradation is a gradual process designed to provide operators with ample time to address the underlying issue before traffic is impacted.

flowchart TD
    subgraph Normal Operation
        A[Full Functionality]
    end

    subgraph Offline Period
        B{Connectivity Lost}
        C{Offline > 14 days?}
    end

    subgraph Degraded Operation
        D[Degraded Mode: Read-only]
        E[Hard Stop]
    end

    A -- Network connection fails --> B
    B -- "Continues for 14 days" --> C
    C -- No --> A
    C -- Yes --> D

    D -- "Existing traffic continues" --> D
    D -- "Writes & new onboarding blocked" --> D
    D -- Connectivity restored --> A
    D -- "Remains offline for extended period" --> E

The stages are as follows:

1. Normal Operation (0 to 14 days offline): The product operates with full functionality, using its cached license verification.
2. Degraded Mode (After 14 days offline): The product enters a read-only state.
   • Blocked Operations:
     • Onboarding new services
     • Activating new mappings
     • Accepting new discovered services
   • Permitted Operations:
     • Existing runtime traffic for already-published services continues to be served without interruption.
   • A warning is displayed to operators indicating that the system is in a degraded state and explaining why write operations are blocked.
3. Hard Stop (After an extended period): If the installation remains unreachable well beyond the 14-day grace period and subsequent read-only stage, it will eventually perform a hard stop. This final stage is a last resort, and the staged degradation is intended to prevent this from happening unexpectedly.

Restoring Normal Operation

Normal operation is restored once the product can successfully re-verify its license against the central platform.

• If the issue was network connectivity: Restoring the egress path to api.specaria.io allows the next verification attempt to succeed, which automatically clears the degraded state and restores full functionality.
• If the issue was the license itself (e.g., expired): The API publisher must obtain and apply a renewed license. Once the product verifies the new, valid license, it will return to normal operation.

Example Scenario: Temporary Network Outage

This example illustrates the product's behavior during a multi-day network outage.

1. Day 0: A network configuration change accidentally blocks the product's outbound HTTPS access to the central licensing platform at api.specaria.io. The product's last license verification was successful.
2. Day 1-13: The product fails its daily license re-verification check. It logs the failure but continues to operate normally, serving all traffic and allowing all write operations based on its cached license status. This is the offline grace window.
3. Day 15: The product has been offline for more than 14 days. It transitions into degraded mode.
   • An operator attempting to onboard a new service finds the action is blocked. A warning banner in the UI indicates the system is in a read-only state due to a persistent licensing communication failure.
   • All existing API traffic continues to flow without interruption.
4. Day 16: An operator investigates the warning, discovers the firewall misconfiguration, and restores connectivity to api.specaria.io.
5. Day 16 (later): At the next verification interval, the product successfully contacts the platform, re-validates its license, and automatically exits degraded mode. Full write functionality is restored.

Troubleshooting and Operator Guidance

To prevent or resolve a degraded state, follow these steps:

1. Check Network Connectivity: Ensure your firewall and network routing permit outbound HTTPS (port 443) traffic to api.specaria.io. For a complete list of required endpoints, see the egress allow-list.
2. Distinguish Failure Types: Review system logs to understand the nature of the failure.
   • Failures related to telemetry (heartbeats, update polls) are generally harmless and are logged as part of a "fail open" design.
   • Failures related to license verification are serious and will eventually lead to degraded mode as part of the "fail closed" design.
3. Check License Validity: If network connectivity is confirmed, the issue may be with the license itself (e.g., it has expired). In this case, contact your account representative to renew or refresh the license.

Normal operation is restored as soon as a successful license verification occurs.

See Also

• Licensing Overview
• License Model
• Egress Allow-List

All SOAP-to-REST docs