# gizgame/cluster

serves a set of games from a cluster of workers behind one gateway (`giz games`).

giz games deploy CLUSTER.json     build this tree's release and switch the cluster to it giz games rollback CLUSTER.json   switch the cluster back to the release before giz games status CLUSTER.json     the live color, each worker and the gateway giz games routes CLUSTER.json     print the gateway's routes, checked, and change nothing

CLUSTER.json is a Cluster: the SERVER program (a server of several games, as examples/games/arcade: --list, --only, --rooms, --vault, /health), the hosts, the workers, the gateway in front of them, and the DOMAIN its games are served under (each game at GAME.DOMAIN, the list at DOMAIN and every other name under it). Every worker runs the same release; each serves the games ONLY names (all) and runs the rooms ROOMS names, so a game's room has one worker. The gateway (gizlang/gateway) sends a game's pages to every worker that serves it in turn, and its room's socket (/net) to the room's worker. Paths are relative to the gizlang tree the tool runs in.

A deploy is blue/green. Each worker has two ports, one for each color, and serves from FOLDER/COLOR, a link to a release (FOLDER/releases/REV, REV this tree's commit: a tree with changes is refused). The deploy builds the release once, copies it to every host with the files a tool made that its games' locks name (from:, in no store a host fetches from), starts the idle color's workers and waits until each answers /health. Only then the gateway's routes name the new color (the gateway reads its file again, keeping its connections), every game is asked through the gateway, and the old color stops. A worker that does not start stops the deploy with the old color serving; a game that does not answer through the gateway puts the old routes back. The color before keeps its release, so a rollback starts it again and switches back. Each host keeps the last KEEP releases (3).

On each host the workers are systemd user units NAME-COLOR@WORKER, the gateway NAME-gateway; their journals are `journalctl --user -u NAME-a@WORKER`. A game's cover (FOLDER/covers/GAME.png, the list's picture of it) is taken here (--shot) when a host lacks it.

```gizlang
import * as Cluster from "gizgame/cluster";
```

## Types

### `Host`

```gizlang
type Host = { ssh: string; address: string; }
```

A host of the cluster: SSH, the name ssh reaches it by, and ADDRESS, where the gateway reaches its workers.

- `ssh`: `string`
- `address`: `string`

### `Worker`

```gizlang
type Worker = { name: string; host: string; ports: Vec<i64>; only?: Vec<string>; rooms?: Vec<string>; }
```

A worker: its NAME, its HOST, its PORTS (color a, color b), the games ONLY names (all), and the games whose ROOMS it
runs (none).

- `name`: `string`
- `host`: `string`
- `ports`: `Vec<i64>`
- `only`: `_gizlang_sdk_core.Option<Vec<string>>`
- `rooms`: `_gizlang_sdk_core.Option<Vec<string>>`

### `Front`

```gizlang
type Front = { host: string; port: i64; metrics?: string; log?: string; }
```

The gateway: its HOST and the PORT it serves on at that host's address; METRICS an address "host:port" of its counts
("" none) and LOG the file of its access log ("" none).

- `host`: `string`
- `port`: `i64`
- `metrics`: `_gizlang_sdk_core.Option<string>`
- `log`: `_gizlang_sdk_core.Option<string>`

### `Edge`

```gizlang
type Edge = { host: string; file: string; entry?: string; list?: string; }
```

A traefik proxy in front of the gateway, which holds the certificates: the ssh name of its HOST, the FILE of its
dynamic configuration that the cluster writes (with sudo), its ENTRY point ("websecure"), and LIST, the label of the
list's host there ("game": game.DOMAIN). The edge names only these hosts: the bare DOMAIN may be another site's.

- `host`: `string`
- `file`: `string`
- `entry`: `_gizlang_sdk_core.Option<string>`
- `list`: `_gizlang_sdk_core.Option<string>`

### `Cluster`

```gizlang
type Cluster = { name: string; server: string; games: string; domain: string; folder: string; front: Front; hosts: Map<string, Host>; workers: Vec<Worker>; memory?: string; vault?: string; keep?: i64; edge?: Edge; }
```

A cluster (see the head of this file). NAME names its units; GAMES is the folder of the games' folders (each its
world and lock files, and its game.giz for its module); FOLDER is its folder under each host's home; MEMORY
caps each worker (systemd MemoryMax, "4G"); VAULT is the state service socket that keeps the rooms' accounts; EDGE is
a proxy in front, whose route names the list's host and each game's.

- `name`: `string`
- `server`: `string`
- `games`: `string`
- `domain`: `string`
- `folder`: `string`
- `front`: `M189.Front`
- `hosts`: `_gizlang_sdk_collections.Map<string, M189.Host>`
- `workers`: `Vec<M189.Worker>`
- `memory`: `_gizlang_sdk_core.Option<string>`
- `vault`: `_gizlang_sdk_core.Option<string>`
- `keep`: `_gizlang_sdk_core.Option<i64>`
- `edge`: `_gizlang_sdk_core.Option<M189.Edge>`

## Functions

### `checked`

```gizlang
function checked(c: Cluster, games: Vec<string>): void throws string
```

Refuses a cluster whose workers name a game the server lacks, leave a game with no worker, or give a room to two
workers or to one that does not serve its game.

Effects: fail, alloc.

### `routes`

```gizlang
function routes(c: Cluster, color: string, games: Vec<string>): string throws string
```

The gateway's file for the workers of COLOR serving GAMES: a route for each game's host to the workers that serve it,
one for its room's socket to its room's worker, and one for the list and every other name.

Effects: fail, alloc.

### `command`

```gizlang
function command(args: Vec<string>): i64
```

Runs `giz games VERB CLUSTER.json` (ARGS: the verb and the file; see the head of this file): its exit status.

Effects: fail, read, write, console, io, alloc.

