# Host files on cdn.gamestage.ai

Publish a file that Studio or a game's clients fetch by URL, such as an App
Spec document or your organisation's logo, at an address that never changes.

```
$ gamestage cdn put spec.json --app predictor --app-version 1.0.0
Published spec.json for predictor 1.0.0. It will never change at this address.
  URL                https://cdn.gamestage.ai/apps/nba/predictor/1.0.0/spec.json
  Type               application/json
  Size               2114 bytes
  SHA-256            9f2c4e...
```

Give Studio that URL. Studio's spec fetcher gets the file with a `200`, and so
does any browser, from any page.

Publishing needs an organisation admin: the owner of a workspace that a
Monterosa operator has made an admin of the organisation. Anybody else in the
organisation can list the files.

## Publish a file

1. Name the app the file belongs to with `--app`, and its version with
   `--app-version`.
2. Run `gamestage cdn put <file> --app <app> --app-version <version>`.
3. Copy the URL it prints. The file is served from that URL straight away.

The file keeps its own name unless you pass `--name`. Each file is one name,
with no folders, so publish an App Spec's documents one at a time under the
same app and version:

```
gamestage cdn put spec.json --app predictor --app-version 1.0.0
gamestage cdn put elements.json --app predictor --app-version 1.0.0
gamestage cdn put preview.html --app predictor --app-version 1.0.0
```

## Change a published file

Publish it under a new version. A file at an address is never replaced, because
Studio and every client that fetched it keep what they fetched: Studio
registers an App Spec URL once, and the file is served with a cache header of a
year.

```
gamestage cdn put spec.json --app predictor --app-version 1.0.1
```

Then point Studio at the new URL. The old version stays where it was.

## List your organisation's files

```
$ gamestage cdn ls --app predictor
nba's files on cdn.gamestage.ai, 3 in all:
  https://cdn.gamestage.ai/apps/nba/predictor/1.0.0/elements.json  5120 bytes
  https://cdn.gamestage.ai/apps/nba/predictor/1.0.0/preview.html  830 bytes
  https://cdn.gamestage.ai/apps/nba/predictor/1.0.0/spec.json  2114 bytes
```

Leave out `--app` to list every app's files.

## Reference

### `gamestage cdn put <file>`

| Option | Type | Required | Default | What it does |
| --- | --- | --- | --- | --- |
| `<file>` | path | Yes | | The file to publish. JSON, HTML, PNG, JPEG, SVG or WebP, up to 2 MB (2,097,152 bytes). |
| `--app <app>` | string | Yes | | The app it belongs to. Lowercase letters, numbers and hyphens, up to 63 characters. |
| `--app-version <version>` | string | Yes | | Its version: `major.minor.patch`, such as `1.0.0`, with an optional pre-release such as `1.0.0-rc.1`. |
| `--name <name>` | string | No | The file's own name | The name to publish it as. Letters, numbers, dots, hyphens and underscores, ending in one of the extensions below. |
| `--org <id>` | string | No | Your organisation | Publish as another organisation for this command only, when you are its admin. Your active organisation is not changed. |

The version option is `--app-version` because `--version` prints the CLI's own
version.

### `gamestage cdn ls`

| Option | Type | Required | Default | What it does |
| --- | --- | --- | --- | --- |
| `--app <app>` | string | No | Every app | List only this app's files. |
| `--org <id>` | string | No | Your organisation | List another organisation's files for this command only, when you are its admin. |

### Addresses

Every file is at:

```
https://cdn.gamestage.ai/apps/<org>/<app>/<version>/<name>
```

`<org>` is your organisation's id. It comes from your workspace, so you cannot
publish under another organisation's path.

### File types

The name's extension decides the type the file is served with, and the file's
contents must match it.

| Extension | Served as | Checked |
| --- | --- | --- |
| `.json` | `application/json` | Parses as JSON in UTF-8. |
| `.html` | `text/html; charset=utf-8` | Is UTF-8. |
| `.png` | `image/png` | Starts with the PNG signature. |
| `.jpg`, `.jpeg` | `image/jpeg` | Starts with the JPEG signature. |
| `.svg` | `image/svg+xml` | Is UTF-8 with an `<svg` element. |
| `.webp` | `image/webp` | Starts with the WebP signature. |

### What a fetch gets back

| Header | Value |
| --- | --- |
| `Cache-Control` | `public, max-age=31536000, immutable` |
| `Access-Control-Allow-Origin` | `*` |
| `X-Content-Type-Options` | `nosniff` |

There is no firewall rule on the user agent, so a server-side fetcher such as
Studio's gets the file like a browser does.

### `--json` output

`gamestage --json cdn put` prints `{ "ok": true, "file": { ... } }`, where
`file` carries `org`, `app`, `version`, `name`, `key`, `url`, `contentType`,
`size` and `sha256`. `gamestage --json cdn ls` prints `{ "ok": true, "org",
"origin", "files": [ ... ] }`.

A refusal prints `{ "ok": false, "error": { "code", "message" } }` and exits
`1`. Success exits `0`.

## When it refuses

| Code | Why | What to do |
| --- | --- | --- |
| `file_exists` | That app and version already have a file with that name. | Publish under a new version with `--app-version`. |
| `invalid_path` | The app, version or name is not one the host accepts, or the type is not on the list above. | Change it to match the rules in the reference. |
| `type_mismatch` | The file's contents are not what its extension says. | Check the file, or rename it with the extension of what it is. |
| `too_large` | The file is over 2 MB. | Make it smaller. For an image, compress it. |
| `empty_file` | The file is empty. | Publish a file with something in it. |
| `no_file` | The path is not a file. | Check the path. |
| `not_org_admin` | Your workspace is not an admin of the organisation. | Ask a Monterosa operator to make your workspace an admin for it. |
| `owner_only` | You are a member of the workspace, not its owner. | Ask the owner to run `gamestage cdn put`. |
| `no_org` | Your workspace belongs to no organisation. | Ask a Monterosa operator to attach it to yours. |
| `not_configured` | This Space does not host files. | Use the Space that serves cdn.gamestage.ai. |
