mirror of
https://github.com/DarkflameUniverse/DarkflameServer.git
synced 2026-11-18 01:35:27 +00:00
/api/v1/zones/{zoneId}: send a zone's edited files (multipart), follow the reload,
list, restore and clear the zone's sets, and take, release and look at its lock.
Every request needs an API key that names the zones_publish permission, an owner at
zone_publish_gm_level, and HTTPS or the server's own machine; refusals are counted
per address and every use is in the audit log. A publish is checked at its headers
before any of its body is taken, the files are checked and written on a worker
thread, and the zone's instances are replaced through the world reload, held while
players are there unless told to move them.
The Worlds page lists each zone's editors and lock holder for an admin.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
123 lines
8.1 KiB
Markdown
123 lines
8.1 KiB
Markdown
# Edited zone files
|
|
|
|
Taking a zone's edited files from an external level editor, keeping them apart from the client's files, and loading
|
|
them by replacing the zone's instances ([WorldHotReload.md](WorldHotReload.md)). The server's client files are never
|
|
written.
|
|
|
|
Code: `dCommon/ZonePublish` (checking a set), `dCommon/ZoneOverrideStore` (the override folder: apply, backups,
|
|
restore, clear), `dCommon/ZoneEditLock.h` (who may: lock and reload rules), `dCommon/dClient/AssetManager` (reading
|
|
overrides), `dDatabase/.../IZoneEditing.h` (locks and editors), `dWeb/MultipartFile` and `Web::RegisterUploadRoute`
|
|
(large uploads), `dDashboardServer/auth/ZonePublishAuth.h` (the API's gate),
|
|
`dDashboardServer/routes/ZonePublishRoutes` (the API). The first four know nothing of HTTP, so another way in uses the
|
|
same checks, store, locks and reload.
|
|
|
|
## Override folder
|
|
|
|
`zone_override_dir` (sharedconfig.ini; empty: off; relative to the servers' folder unless absolute).
|
|
|
|
| Path | Holds |
|
|
| --- | --- |
|
|
| `maps/<zone folder>/...` | the files in use |
|
|
| `maps/<zone folder>/.zone-<id>.json` | which files are zone `<id>`'s set, who sent it, when, its note |
|
|
| `staging/<id>/` | a set while it is checked and built |
|
|
| `backups/<zone id>/<unix time>-<id>/` | the sets a zone had before (`files/`, `manifest.json`) |
|
|
|
|
For a name under `maps/` the asset manager reads `<zone_override_dir>/maps/...` when the file is there, else the
|
|
client's. Names are lowercase with forward slashes. Master watches the same file a world would read: an override that
|
|
appears, changes or goes away makes the instances that read another version stale.
|
|
|
|
A zone's set is replaced whole. The folder's new contents are built in `staging`, flushed to disk and swapped in with
|
|
one rename (an exchange where the system has one). The set replaced is copied to `backups` first; the newest
|
|
`zone_publish_max_backups` are kept. Restore and clear are the same swap. Files of another zone in the same folder
|
|
stay.
|
|
|
|
## Who may
|
|
|
|
- An API key (`Authorization: Bearer`) whose own permission list has `zones_publish` (also written `zones.publish`
|
|
when a key is made). A key with all of its owner's permissions does not count. Keys are stored as a SHA-256 hash.
|
|
- The key's owner at GM level `zone_publish_gm_level` or higher, read from the database on every request.
|
|
- HTTPS, or the server's own machine. The dashboard speaks plain HTTP: with `behind_proxy=1` the proxy's
|
|
`X-Forwarded-Proto: https` counts; without it only loopback does. Anything else is refused and audited.
|
|
- Ten refused requests from one address in ten minutes refuse the address for the rest of that time, on top of the
|
|
key's own rate limit.
|
|
- Every use and every refusal is in the audit log (action `zone_publish`: key ID, zone, action, result; the account is
|
|
the entry's actor). Reads are written at most once a minute per key, zone and action.
|
|
|
|
Locks: a zone has up to 10 assigned editors and one lock holder. Taking the lock needs an assigned editor, or GM level
|
|
`zone_lock_admin_gm_level`. Releasing: the holder, or an admin. Sending, restoring and clearing need the caller to
|
|
hold the lock. Locks do not expire. Results where a number is given: 0 ok, 1 level too low, 2 not assigned, 3 locked
|
|
by another account, 4 no change.
|
|
|
|
## Checks
|
|
|
|
All files are checked before any is written; one failure refuses the set.
|
|
|
|
| Code | Meaning |
|
|
| --- | --- |
|
|
| `name_not_allowed` | Not a path in the zone's folder the `.luz` lists: `..`, absolute, backslash, NUL, non-ASCII, another zone's folder, an unlisted file |
|
|
| `duplicate` | The same path twice (compared in lowercase) |
|
|
| `missing_luz` | The set lacks the zone's `.luz` (its path comes from the ZoneTable) |
|
|
| `too_large` | A file over `zone_publish_max_file_mb`, the set over `zone_publish_max_total_mb` or `zone_publish_max_files` |
|
|
| `parse_failed` | The server's own reader does not read the file to its end (`offset`: where it stopped) |
|
|
| `unsupported_version` | `.luz` outside 30 to 41, `.lvl` over 48 |
|
|
| `scene_mismatch` | The `.luz` lists a scene the zone does not have in the client files, or one that is in neither the set nor the client |
|
|
| `terrain_mismatch` | The `.raw` sent is not the one the `.luz` names, or the one named is nowhere |
|
|
| `trigger_missing_target` | A trigger command without a `target` |
|
|
| `unknown_trigger_event`, `unknown_trigger_command` | An ID the server does not know |
|
|
| `bad_object_config` | An object setting that does not parse |
|
|
| `too_many_objects` | Over `zone_publish_max_objects` objects in the set's scenes |
|
|
|
|
Allowed names: the `.luz`, each listed scene's `.lvl` and `.lutriggers`, the `.raw` the `.luz` names. A set cannot add
|
|
scenes. Before a file is written its path is resolved (`std::filesystem::weakly_canonical`) and must be inside the
|
|
override folder.
|
|
|
|
## API
|
|
|
|
Base `/api/v1`. Errors are `{"error", "message"}`. `zoneId` is the ZoneTable ID.
|
|
|
|
| Route | Does |
|
|
| --- | --- |
|
|
| `POST /zones/{zoneId}/publish` | multipart/form-data: one file part per file (filename: its path relative to `res/maps/`), fields `reload` (default true), `dryRun`, `note`, `ifPlayersPresent` (`hold` default, `move`) |
|
|
| `GET /zones/{zoneId}/publish/{publishId}` | `{publishId, zoneId, action, state, players, reload: {instances, playersMoved, errors}, finishedAt}`; states `validating`, `applying`, `held`, `reloading`, `done`, `failed` |
|
|
| `POST /zones/{zoneId}/publish/{publishId}/reload` | `{"ifPlayersPresent": "move"}` goes on with a held reload |
|
|
| `GET /zones/{zoneId}/overrides` | `{current: {files: [{path, bytes, sha256, publishedBy, publishedAt}]} or null, backups: [{backupId, createdAt, createdBy, note}]}` |
|
|
| `POST /zones/{zoneId}/overrides/restore` | `{backupId, reload, ifPlayersPresent}`; answers `{publishId, zoneId}` at once |
|
|
| `DELETE /zones/{zoneId}/overrides` | optional `{reload, ifPlayersPresent}`; answers `{publishId, zoneId}` at once |
|
|
| `GET /zones/{zoneId}/lock` | `{holder, since, holder_is_you, editors}` |
|
|
| `POST /zones/{zoneId}/lock` | take (200 again for the holder, `holder_is_you: true`); 409 `{error: zone_locked, holder, since, holder_is_you: false}` |
|
|
| `DELETE /zones/{zoneId}/lock` | release (holder, or an admin) |
|
|
|
|
A publish answers `{publishId, zoneId, backupId, files: [{path, bytes, sha256, version}], reload: {state}}` with
|
|
`state` `started`, `held` or `skipped`. A dry run answers `{zoneId, dryRun: true, files, reload}` and keeps nothing.
|
|
Restore and clear answer with their `publishId` and are followed with the status route like a publish. A `failed`
|
|
status has `error` and `message` beside its state; reload problems are also in `reload.errors`. Every file part's form
|
|
field name is `file`. Names are compared without regard to case and kept lowercase, as the servers read them. Times
|
|
are unix seconds.
|
|
|
|
| Status | When |
|
|
| --- | --- |
|
|
| 400 | `malformed` |
|
|
| 401 | `unauthorized`, `api_key_required` |
|
|
| 403 | `https_required`, `scope_required`, `read_only_key`, `gm_level`, `lock_required`, `not_an_editor` |
|
|
| 404 | `unknown_zone`, `unknown_publish`, `unknown_backup` |
|
|
| 409 | `publish_in_progress`, `zone_locked`, `not_held` |
|
|
| 411 | `length_required` (no Content-Length) |
|
|
| 413 | `too_large` |
|
|
| 422 | `validation_failed` with `files: [{path, ok: false, errors: [{code, message, offset?}]}]` |
|
|
| 429 | `rate_limited`, or the key's own limit |
|
|
| 503 | `disabled` (no `zone_override_dir`), `master_unavailable` |
|
|
|
|
The publish request's headers are checked (key, level, transport, zone, lock, size) before any of its body is taken.
|
|
The body is written to `staging` as it arrives, not held in memory.
|
|
|
|
## Reload
|
|
|
|
Only the zone's instances, through master's world reload. With players in the zone and `ifPlayersPresent=hold` the
|
|
state is `held` until `.../reload` says to move them, or nobody is left when it is asked again with `hold`. From
|
|
before the files change until a reload of the zone is asked for, the dashboard tells master to leave the zone's
|
|
instances alone (`WORLD_RELOAD_HOLD`), so the file watch does not reload a held zone by itself. `reload=false` leaves
|
|
the instances as they are; the files are read when an instance next starts, or on a later reload.
|
|
|
|
The dashboard's Worlds page lists each zone's editors and lock holder (permission `zone_editors_manage` and GM level
|
|
`zone_lock_admin_gm_level`): add and remove editors, take a lock away.
|