/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>
8.1 KiB
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). 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 haszones_publish(also writtenzones.publishwhen 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_levelor higher, read from the database on every request. - HTTPS, or the server's own machine. The dashboard speaks plain HTTP: with
behind_proxy=1the proxy'sX-Forwarded-Proto: httpscounts; 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.