Sidecar Overview

The Stigg Sidecar is a lightweight service that runs alongside your application and proxies calls to the Stigg API. It provides:

• Low-latency entitlement evaluations
• Local caching of entitlements and current usage
• Subscription to real-time updates for entitlement and usage changes

You can call it over REST or gRPC. See Calling the Sidecar.

​

Benefits for your application host

Key benefits of using the Sidecar:

• In-memory caching for every SDK: entitlement checks are answered from a local cache, whatever language or client you use, including plain REST
• Persistent cache: back the cache with Redis so it survives restarts and can be shared across instances
• Reduced CPU and memory usage in the host application compared to embedding the SDK directly
• Can be scaled together with the main application or as an independent, shared service

​

What the Sidecar caches

Requests for entities that aren’t cached are proxied to the Stigg API.

​

Fail-safe resilience goals

The main design goal of the Sidecar is to remain operational during network issues while still returning valid read responses. Under normal conditions, reads resolve instantly from the local Redis cache. When the upstream Stigg API becomes unreachable, cached responses are returned directly from Redis. When Redis itself is down, Sidecar doesn’t call Stigg: it answers with the configured fallback entitlements, which deny access by default (accessDeniedReason: Unknown). Over gRPC, the response marks this with isFallback; a REST response doesn’t, so it can’t be told apart from a real denial. Write paths, such as POST /api/v2/usage and POST /api/v1/events in the REST API or ReportUsage and ReportEvents over gRPC, do not return fallback values. Errors are returned explicitly and should be handled by your own observability and logging layer using try/catch and structured logging.

​

Synchronous execution and latency guardrails

Sidecar is synchronous by design. The host can call Sidecar and wait safely for an immediate response in the same request path, without risk of background or deferred execution. When a cache miss occurs, Sidecar fetches entitlements from the Edge API, where typical latency is around 100 ms. To block upstream latency from cascading into the host, Sidecar applies a 10-second network timeout (configurable). If the timeout is exceeded, Sidecar returns default values instead of hanging or retrying indefinitely.

​

Isolation from upstream network conditions

Short Stigg API latency spikes do not affect cached reads. Only uncached or Edge-fetched reads are exposed to network conditions. When the Stigg API experiences long or sustained latency or connectivity loss, reads continue being served from cache without degradation. Timeout guardrails prevent external calls from creating cascading delays inside the main application.

​

Security and request handling guarantees

Sidecar must remain internal-only and must not be internet-exposed. Reads always resolve synchronously and immediately from Redis when available. Write-path errors must be handled explicitly at the host level, then surfaced into your own monitoring, alerting, and structured logging layer.