# Development

Sparkle uses [Envoy Proxy](https://www.envoyproxy.io/) to manage authentication
via GitLab's Identity Provider (IdP). When a user makes a request without valid
authentication cookies, Envoy redirects the request to the IdP. It then completes
an OpenID Connect (OIDC) flow to obtain an `id_token`, `access_token`, and
`refresh_token`, sets them as cookies, and forwards the request to Sparkle.

This architecture enables Sparkle to focus solely on application logic, without needing to:

* Handle session cookies manually,
* Exchange refresh tokens for new access tokens, or
* Access client credentials like `client_id` or `client_secret` directly.

## Request Flow Overview

```plaintext
+-------------+           +---------------+                  +-----------------+                +-------+
| User-Agent  |           | Proxy (:1000) |                  | Sparkle (:8080) |                | (IdP) |
+-------------+           +---------------+                  +-----------------+                +-------+
    |                            |                                    |                             |
    |---> HTTP Request ---------->                                    |                             |
    |     (no or invalid cookie) |                                    |                             |
    |                            |                                    |                             |
    |<--- 302 Redirect to IdP ---|                                    |                             |
    |                            |                                    |                             |
    |---------------------------->----------------------------------------------------------------->|
    |     Auth Request (Login)   |                                    |                             |
    |                            |                                    |                             |
    |<------------------------------------------------------------------ Auth Response (Grant) -----|
    |                            |                                    |                             |
    |---> Callback to Proxy ---->|                                    |                             |
    |     (code or token)        |                                    |                             |
    |                            |---> Exchange Grant for Token ----------------------------------->|
    |                            |                                    |                             |
    |                            |<--- ID / Access Token -------------------------------------------|
    |                            |                                    |                             |
    |                            |---> Forward Request            --->|                             |
    |                            |     (Set-Cookie headers)           |                             |
    |                            |                                    |                             |
    |                            |<--- Response ----------------------|                             |
    |<--- Final Response --------|                                    |                             |
```

## Configuration

Both Envoy and Sparkle are configured via environment variables. You can copy the
`.env` file to `.env.local` and fill in the required values:

```bash
cp .env .env.local
```

The following environment variables must be defined:

| Variable Name          | Description                                      |
| ---------------------- | ------------------------------------------------ |
| `APP_ENV`              | Sparkle environment (default: `development`)     |
| `OAUTH_CLIENT_ID`      | The client ID registered with GitLab IdP         |
| `OAUTH_CLIENT_SECRET`  | The corresponding client secret                  |
| `OIDC_ISSUER`          | The issuer URL (e.g., `http://gdk.test:3000`)    |

Follow these instructions to [create a user-owned application](https://docs.gitlab.com/integration/oauth_provider/#create-a-user-owned-application)
and set the `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`.

You can refer to the `Dockerfile` in the root of this repository to determine the
exact version of Envoy required. To install Envoy locally, follow the [official
installation guide](https://www.envoyproxy.io/docs/envoy/latest/start/install).
To install [dumb-init](https://github.com/Yelp/dumb-init) see the
[documentation](https://github.com/Yelp/dumb-init).

Sparkle uses the following Envoy Filters:

* [envoy.filters.http.oauth2](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/oauth2_filter)
* [envoy.filters.http.router](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter)

## Usage

You can run Sparkle and Envoy either natively or in Docker:

* **Run Sparkle + Envoy on the host machine:**

  ```bash
  $ make run
  ```

* **Run Sparkle + Envoy in Docker:**

  ```bash
  $ make run-image
  ```