# Stigg Sidecar Service

## What does Stigg Sidecar do?

Stigg Sidecar is a tiny service that runs alongside the main application, acting as a proxy between the host and the Stigg API,
while ensuring low latency entitlement checks, handles caching and provides simplified access to real-time data.

The benefits of deploying the Sidecar:

- Less CPU consumption and memory footprint for the host application when compared to embedding the SDK directly
- Language neutral API via Protocol Buffers and gRPC
- Support for in-memory cache or external cache (Redis) for entitlements and usage data
- Scaled together with the main application, or independently if deployed as a standalone service
- Synergy with persistent-cache-service if external cache is in use
- Easy generation of SDK clients in multiple languages, backed by well-known RPC frameworks and tools

## Architecture

![Architecture](docs/images/architecture.png)

## Prerequisites:

- Docker
- Redis instance, if redis cache is used

## Usage:

Login to AWS ECR:

```bash
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/stigg
```

Run the service:

```bash
docker run  --rm --name stigg-sidecar --memory=1gb --cpus="1" \
  --publish=80:80 --publish=8080:8080 \
  -e SERVER_API_KEY="<SERVER_API_KEY>" \
  public.ecr.aws/stigg/sidecar:latest
```

## Configuration:

| Environment Variable       | Type     | Default                     | Description                                                           |
|----------------------------|----------|-----------------------------|-----------------------------------------------------------------------|
| `SERVER_API_KEY`           | String\* |                             | Environment server API key                                            |
| `API_URL`                  | String   | `https://api.stigg.io`      | Stigg API address URL                                                 |
| `EDGE_ENABLED`             | Boolean  | `1`                         | Edge API enabled                                                      |
| `EDGE_API_URL`             | String   | `https://edge.api.stigg.io` | Edge API URL                                                          |
| `WS_ENABLED`               | Boolean  | `1`                         | Websocket enabled                                                     |
| `WS_URL`                   | String   | `wss://api.stigg.io`        | Websocket API URL                                                     |
| `REDIS_ENVIRONMENT_PREFIX` | String   |                             | Identifier of the environment. If provided, Redis cache will be used. |
| `REDIS_HOST`               | String   | `localhost`                 | Redis host address                                                    |
| `REDIS_PORT`               | Number   | `6379`                      | Port of your redis                                                    |
| `REDIS_DB`                 | Number   | `0`                         | DB identifier to use when writing to Redis                            |
| `REDIS_USERNAME`           | String   |                             | Redis username                                                        |
| `REDIS_PASSWORD`           | String   |                             | Redis password                                                        |
| `REDIS_KEYS_TTL_IN_SECS`   | Number   | `7 * 24 * 60 * 60`          | Time in seconds entitlements are cached. Pass `-1` (or any negative value) to write cache entries without an expiration — useful when the cache must survive extended Stigg Cloud outages. |
| `GRPC_PORT`                | Number   | `80`                        | Service port (HTTP/2)                                                 |
| `PORT`                     | Number   | `8443`                      | *Deprecated* TLS service port (HTTP/2 TLS)                            |
| `METRICS_PORT`             | Number   | `8080`                      | Metrics and health endpoints port (HTTP/1)                            |
| `ENTITLEMENTS_FALLBACK`    | String   | ``                          | Fallback entitlements in a JSON string format.                        |
| `HEALTH_ENDPOINT_URL`      | String   | `livez`                     | Health endpoint URL                                                   |
| `READY_ENDPOINT_URL`       | String   | `readyz`                    | Ready endpoint URL                                                    |
| `OFFLINE`                  | Boolean  |                             | Enable offline mode for local development                             |
| `ENTITLEMENTS_TIMEOUT`     | Number   | `10 * 1000`                 | Entitlements request timeout in milliseconds                          |

\*Required fields

## Health and Metrics:

The service exposes health and metrics endpoints on HTTP server (default port 8080).

### `GET /livez`

Returns `200` if the service is alive.

Healthy response: `{"status":"UP"}`

### `GET /readyz`

Returns `200` if the service is ready.

Healthy response: `{ "status": "UP" }`

### `GET /metrics`

Returns Prometheus metrics in text format.

