Files
DarkflameServer/docs/ZonePublish.md
Aaron Kimbrell a4c4c24a5c feat(dashboard): the zone file API, with zone edit locks
/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>
2026-11-10 19:34:43 -06:00

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 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.