mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-18 19:25:56 +00:00
Phase 0/1a: architecture audit and coa-core foundation (fsx, registry, manifest, logging, errors)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
commit
c39ff556a3
11 files changed
+2277
No files matched your search
@@ -0,0 +1,430 @@
|
||||
# CoA Server Manager — Phase 0 audit & architecture
|
||||
|
||||
Status: Phase 0 output. Everything under **Audit findings** was checked against the real repositories and a real
|
||||
local install (`C:\games\CoA-Repack`); nothing there is invented. Everything under **Decisions** is a proposal
|
||||
that the phases below implement.
|
||||
|
||||
---------------------------------------------------------------------------------------------------------
|
||||
|
||||
## 1. Audit findings (facts)
|
||||
|
||||
### 1.1 The repack already defines the on-disk layout
|
||||
|
||||
`C:\games\CoA-Repack` (RELEASE.json `mainRevision c3beca68`, `sourceRevision b8615469`, 2026-09-11):
|
||||
|
||||
```
|
||||
Core\ authserver.exe worldserver.exe, DLLs, configs\, configs\modules\, Logs\, Crashes\
|
||||
Data\ maps vmaps mmaps dbc (incl. dbc\Ascension) Cameras 3.8 GB
|
||||
mysql\ MySQL 8.4.9 (mysqld, mysql, mysqladmin, mysqldump), data\ (3.3 GB), data.7z (141 MB)
|
||||
Runtime\python\ embedded Python used by Scripts\
|
||||
Scripts\manage.py the launcher/supervisor (604 lines) + gui_server.py (local web GUI)
|
||||
Settings\ repack.json (ports, RA creds), database.json (generated DB passwords),
|
||||
*.conf.template (+ .original)
|
||||
BugReport\ relay.py, reports\, Logs\
|
||||
Source\ server-source (2.2 GB) + zip + source-manifest.json
|
||||
.state\ <name>.json = {pid, exe, created(FILETIME)} for mysql/auth/world/supervisor/relay,
|
||||
control.lock, configuration.json, debug-logs.json
|
||||
RELEASE.json {mainRevision, sourceRevision, binaries[{Name,SHA256,Bytes}], account, ...}
|
||||
MANIFEST.json {fileCount 19382, bytes 3.2 GB, files{path:{bytes,sha256}}} <- per-file hashes
|
||||
*.bat thin wrappers around Runtime\python\python.exe Scripts\manage.py <verb>
|
||||
```
|
||||
|
||||
Consequences:
|
||||
|
||||
* **A per-file hash manifest already exists** (`MANIFEST.json`). It is the baseline for the file-ownership
|
||||
system on imported repacks: file present in MANIFEST with the same hash → `core/repack, pristine`; present with a
|
||||
different hash → `modified`; not in MANIFEST → `user`. No need to hash 3 GB to classify.
|
||||
* **Generated configs are overwritten on every start.** `manage.py prepare()` renders
|
||||
`Settings\*.template` → `Core\configs\{authserver,worldserver}.conf` and
|
||||
`modules\mod_ascension_compat.conf` (placeholders `@DATA@ @LOGS@ @LoginDatabaseInfo@ ...`), also writes
|
||||
`mysql\my.ini`, `mysql\admin-client.ini` (contains the root password) and `modules\coa_bugreport.conf`.
|
||||
The README says so explicitly. **The templates, not the `.conf` files, are the source of truth** for those three
|
||||
configs. Other module confs (e.g. `mod_coa_playerbots.conf`) are *not* templated and are edited in place.
|
||||
* **Process identity is already solved in the repack** the way the spec demands: `{pid, exe, creation FILETIME}`
|
||||
via `QueryFullProcessImageNameW` + `GetProcessTimes`; listeners via `GetExtendedTcpTable` with owning PID;
|
||||
a start/stop mutex via `msvcrt.locking` on `.state\control.lock` (1 byte at offset 0 — compatible with
|
||||
`LockFileEx`); graceful stop = RA `server shutdown 1s 0`, then auth terminate, then `mysqladmin shutdown`.
|
||||
`stop_all` never hard-kills worldserver. Port offset support exists (`--port-offset`).
|
||||
* **World is started under a supervisor** (`watch-world`) that also runs the Python bug-report relay; starting
|
||||
`worldserver.exe` directly skips the relay. The relay ships reports to the maintainers.
|
||||
* **Ports:** MySQL 3307 (bind 127.0.0.1), auth 3724, world 8085, RA 3443 (RA user/pass in `repack.json`).
|
||||
* **DB credentials are the *same for every repack download*** (`database.json` is packaged, 48-hex passwords).
|
||||
Safe only because MySQL is loopback-only. New Manager-created installs must regenerate them.
|
||||
* **Readiness marker** in `Core\Logs\Server.log`:
|
||||
`AzerothCore rev. <12-hex> <date> (main branch) (...) (worldserver-daemon) ready...` and
|
||||
`WORLD: World Initialized In N Minutes M Seconds`. The worldserver banner also **reports its own core commit**
|
||||
(12 hex) — usable to identify the core version of an imported binary when RELEASE.json is stale.
|
||||
|
||||
### 1.2 The reference machine is a real, customised, *running* install
|
||||
|
||||
* `Core\worldserver.exe` sha256 `b9aa8f36…` ≠ RELEASE.json (`715bd375…`): the owner's dev build. `Core\`
|
||||
holds ~60 `worldserver.exe.pre-*` backups and `.pdb`s — **157 GB**. Import must not walk-and-hash everything;
|
||||
it hashes only what it needs (exes, configs, templates, addon) and enumerates the rest by name/size.
|
||||
* `mod_coa_playerbots.conf` has 71 `CoaBots.*` keys while the repo's `dist/conf/*.dist` has ~30: real configs
|
||||
are ahead of the shipped template. The bot schema must therefore tolerate unknown keys (spec §10 already
|
||||
demands it) and be validated against the *deployed* `.dist`, not only the repo's.
|
||||
* The worldserver on this machine is **running now (pid 22080)** and the owner runs long bot experiments on it.
|
||||
**Testing rule: the live install is only ever read.** Start/stop/update tests run on a disposable fixture copy
|
||||
on different ports (`--port-offset`), never on `C:\games\CoA-Repack`.
|
||||
* `C:` has 86 GB free (94 % full). Backup/staging code must check free space *before* writing and default
|
||||
large artefacts (staging, DB dumps) to a user-selectable location.
|
||||
|
||||
### 1.3 mod-coa-playerbots is not a plug-in — it is a rebuilt worldserver
|
||||
|
||||
`Corfirean/mod-coa-playerbots` (`master`, no GitHub Releases yet) ships `dist\`:
|
||||
|
||||
```
|
||||
bin\worldserver.exe (not in git) Install-CoaBots.ps1/.bat Uninstall-CoaBots.ps1/.bat
|
||||
conf\mod_coa_playerbots.conf.dist reference\ascensionsidekick-level-builds.json (282 KB)
|
||||
addon\CoABotUI\{CoABotUI.lua,.toc} sql\2026_09_15_00_ascension_character_selection.sql
|
||||
release.json {builtForRepack{mainRevision, sourceRevision}, originalWorldserverSha256[], patchedWorldserverSha256[]}
|
||||
```
|
||||
|
||||
* The module is compiled **statically into `worldserver.exe`** (`-DMODULES=static`) *and* needs three small
|
||||
**core patches** (`docs/core-patches.md`: `LoginQueryHolder` moved to `WorldSession.h`,
|
||||
`IWorld::AddQueryHolderCallback`, `Group::GetRolls`, plus an Ascension talent accessor). The doc says some of
|
||||
these were still uncommitted in the core working tree — **must be verified before CI can build bots
|
||||
from clean commits** (§6 risk R1).
|
||||
* "Install bots" today = replace `Core\worldserver.exe` (backup → `.orig`), drop `.conf.dist`, create `.conf`
|
||||
only if absent, copy `Core\reference\ascensionsidekick-level-builds.json`, copy the addon to
|
||||
`<repack>\Client\Interface\AddOns\CoABotUI` (a `Client\` folder that the repack does not have — the client is
|
||||
distributed separately), apply `dist\sql\*.sql` to the characters DB with the password read out of
|
||||
`worldserver.conf` (visible on the command line).
|
||||
* The installer already does **hash-gated binary replacement** (original ∈ known hashes or patched ∈ known
|
||||
hashes, else refuse unless `-Force`) and refuses if worldserver is running. The Manager generalises this.
|
||||
* Bots are real characters on their own accounts (`CoaBotHost*`) in `acore_characters`; no extra database.
|
||||
Bot creation throttles (`BatchSize 5 / 500 ms`) exist because a 1000-bot synchronous spawn once killed the
|
||||
server — presets must never lower these. (Confirmed by the owner's own incident notes.)
|
||||
* The `.conf.dist` is well commented prose — usable as the source for the initial `schemas/bots.json`.
|
||||
|
||||
### 1.4 azerothcore-wotlk-coa (core)
|
||||
|
||||
* `main`, 1.1 GB, **no releases, no tags, no Windows build workflow**. Only `quality.yml` (ubuntu, source
|
||||
boundaries) exists. CI for binaries must be written from scratch.
|
||||
* Build: CMake ≥ out-of-source, `-DSCRIPTS=static -DMODULES=static`, C++20, Boost.PropertyTree (vcpkg
|
||||
`boost-property-tree`), OpenSSL 3, MySQL client libs. Repo rules (`AGENTS.md`): never edit
|
||||
`data/sql/base|archive|updates/db_*`; new SQL goes only in `data/sql/updates/pending_db_*/`; **automatic DB
|
||||
updater is disabled in this project's config** (the bots doc: `AUTOUPDATER: ... disabled`). So schema
|
||||
migrations are *not* applied by worldserver — the Manager must own a tracked migration runner (spec §18).
|
||||
* `modules\` contains 24 in-tree modules (mod-ascension, mod-coa-*, …); bots would be the 25th.
|
||||
Runtime module configs are `Core\configs\modules\*.conf` (+ `.dist`).
|
||||
* Core HEAD 442cf4c9 (2026-09-30) is ahead of the repack's `mainRevision c3beca68` and the running binary
|
||||
(`3567e2f8e9d5`): three different revisions are in play on one machine. The compatibility matrix must be
|
||||
keyed by **exact core commit**, never by "latest".
|
||||
|
||||
### 1.5 Toolchain on this machine
|
||||
|
||||
Node 26, npm 11, git 2.55, gh (authed as Corfirean), VS 18 Insiders with MSVC 14.51 and WebView2 present.
|
||||
Rust was **not** installed; `rustup` stable 1.98.1 (msvc) was installed as part of this task. cmake/pnpm absent
|
||||
(npm is used; CMake is only needed by the *build* repo, on the CI runner).
|
||||
|
||||
---------------------------------------------------------------------------------------------------------
|
||||
|
||||
## 2. Decisions (architecture)
|
||||
|
||||
### D1. One supported layout: the "CoA Repack layout v1"
|
||||
|
||||
Both flows converge on the same folder shape:
|
||||
|
||||
* **Import** adopts an existing repack-shaped folder (classification: Healthy / Partial / Unknown-custom /
|
||||
Incompatible, §5).
|
||||
* **New install** downloads the *base package* (= a repack) and extracts it into staging, verifies, then moves
|
||||
it into place. Every install is therefore a repack plus Manager metadata.
|
||||
|
||||
Result: one code path for process control, config, DB and update. "Unknown custom server" gets the restricted
|
||||
mode from spec §52 (start/stop via detected exes, backups, console, no update/bots).
|
||||
|
||||
A `Layout` trait isolates this (`RepackLayout` now; a hypothetical `NativeLayout` later) so nothing hardcodes
|
||||
`Core\worldserver.exe`; paths come from `Installation.layout`.
|
||||
|
||||
### D2. Manager metadata lives *next to*, not inside, the server folder
|
||||
|
||||
`D:\CoA-Repack` ⇒ `D:\CoA-Repack.manager\` (the example in the spec). Rationale: import stays byte-for-byte
|
||||
read-only on the server folder, folder can be copied/moved without dragging Manager state, backups get a
|
||||
natural home the user can redirect to another drive.
|
||||
|
||||
```
|
||||
<install>.manager\
|
||||
install.json identity + detected versions + db info (no secrets) + client path
|
||||
state.json last known process state, update-transaction status pointer
|
||||
ownership.sqlite (or ownership.json in v1) path → {owner, hash, version, replacePolicy, origin}
|
||||
manifests\ copies of every applied release manifest
|
||||
backups\<id>\ recovery points (each has backup.json + payload)
|
||||
migrations\ applied-migration ledger (mirrors the DB table, see D7)
|
||||
staging\ update/install staging (same volume as install → atomic rename)
|
||||
logs\ manager.log (rotated 5×2 MB) ; cache\
|
||||
```
|
||||
|
||||
A registry at `%LOCALAPPDATA%\CoAServerManager\installs.json` maps `installationId → path`, so a *moved* folder
|
||||
is re-linkable (the `.manager` folder holds the id; if the path is gone the UI offers "Locate server").
|
||||
Secrets (DB/RA passwords generated by the Manager) go to **Windows DPAPI-protected** files in the same
|
||||
`.manager` folder (`secrets.bin`, `CryptProtectData`, user scope). Imported servers keep their own
|
||||
`Settings\database.json`; the Manager reads it in memory, never displays or logs it.
|
||||
|
||||
### D3. Process model (Rust, `process` module)
|
||||
|
||||
* `ProcessIdentity {pid, exe_path, creation_time_filetime}` — identical to `.state\*.json`, so records are
|
||||
interchangeable with the repack's own scripts.
|
||||
* A process "belongs" to an installation iff `exe_path` is under the installation root (or equals a
|
||||
configured exe) **and** creation time matches a recorded identity *or* it owns a listening socket on a
|
||||
configured port. Never by image name alone; never by bare PID.
|
||||
* Discovery on startup = scan running processes for the installation's exes + `GetExtendedTcpTable` owner PIDs →
|
||||
rebuild state (works after a Manager crash, PC crash → stale PID dropped because creation-time/exe mismatch).
|
||||
* Start/stop are serialised with the repack's `.state\control.lock` via `LockFileEx` (same byte), so Manager and
|
||||
`.bat` files cannot race.
|
||||
* **Driver strategy.** Phase 2 delegates start/stop to the repack's own `manage.py` through its bundled Python
|
||||
(`Runtime\python\python.exe -B Scripts\manage.py start-all|stop-all`), because it already handles config
|
||||
rendering, relay, RA shutdown and readiness, and because behaviour must not regress on a production install.
|
||||
Observation (identity, ports, health, logs) is native from day one. A native Rust driver for the same
|
||||
sequence replaces the delegate later, gated behind the same `ServerDriver` trait and validated against the
|
||||
delegate by the same integration tests. Startup order/health follows spec §7–8.
|
||||
* States: `Stopped | Starting | Running | Stopping | Crashed | Updating | Unknown`; overall health adds
|
||||
`Ready | NeedsAttention` using: process alive → port owned by that PID → log `ready...` marker after this
|
||||
start's timestamp → no `FATAL`/`ERROR` startup lines.
|
||||
* Forced kill exists only as an explicit, warned last resort after graceful stop times out.
|
||||
|
||||
### D4. Config engine (`config` module)
|
||||
|
||||
* Line-preserving parser: keeps comments, blank lines, unknown keys, line endings and encoding (UTF-8, LF/CRLF
|
||||
detected). A `set(key, value)` rewrites only that key's line; missing keys are appended under a
|
||||
`# Added by CoA Server Manager` comment. Never re-serialises the file.
|
||||
* Layered targets via the layout: for templated configs the edit is applied to `Settings\<name>.template`
|
||||
(source of truth) **and** the rendered `.conf` (so the running/next state agrees without a restart of the
|
||||
renderer); for `mod_coa_playerbots.conf` edit in place.
|
||||
* Save = validate against schema → write `<file>.tmp` in same dir → re-parse and compare → snapshot previous
|
||||
into `.manager\backups\config\` → `MoveFileEx(REPLACE_EXISTING)`.
|
||||
* Merge (`.dist` v1 → v2): add keys present in new `.dist` but missing; never overwrite user values; keys
|
||||
removed upstream → flagged `deprecated`, kept.
|
||||
* Schemas: `schemas/bots.json`, `schemas/server.json` (curated whitelist), fields exactly per spec §10
|
||||
(`key type category title description default min max options advanced restartRequired dangerous`;
|
||||
`restartRequired ∈ runtime|world|full`). Presets are separate JSON diffs shown as "will change N settings".
|
||||
|
||||
### D5. File ownership & manifests
|
||||
|
||||
Every release ships `manifest.json`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"schema": 1,
|
||||
"kind": "base|update|bots",
|
||||
"version": "0.4.1",
|
||||
"core": { "commit": "<40 hex>" },
|
||||
"bots": { "commit": "<40 hex>" | null },
|
||||
"builtAt": "2026-…Z",
|
||||
"minManagerVersion": "0.1.0",
|
||||
"requires": { "core": ["<commit>"|"range"], "dbSchema": ">=N" },
|
||||
"files": [ { "path":"Core/worldserver.exe", "sha256":"…", "size":123, "owner":"core|bots|manager",
|
||||
"policy":"replace|replace-if-pristine|merge-config|create-if-missing|never-touch" } ],
|
||||
"migrations": [ { "id":"2026_09_15_00_…", "db":"characters", "sha256":"…", "destructive":false } ],
|
||||
"signature": { "alg":"ed25519", "keyId":"…", "sig":"…" } // verified when a public key is embedded (§54)
|
||||
}
|
||||
```
|
||||
|
||||
`ownership` table per install: `path, owner(core|bots|manager|user), sha256_at_install, installed_version,
|
||||
policy, origin(imported|installed)`. Update algorithm compares **current hash vs recorded hash vs incoming
|
||||
hash**: current == recorded → safe to replace; current ≠ recorded → *modified outside Manager* → prompt
|
||||
(Keep / Replace / Compare / Cancel); path unknown → `user`, never touched. Import seeds the table from
|
||||
`MANIFEST.json` where present (imports are read-only; hashes computed lazily and only for managed paths).
|
||||
|
||||
### D6. Update transaction (Prepare → Verify → Snapshot → Apply → Validate → Commit)
|
||||
|
||||
1. **Prepare** — fetch manifest (HTTPS only, signature checked), compatibility matrix check, disk-space check on
|
||||
staging volume and backup volume.
|
||||
2. **Download** to `staging\<txid>\dl\` with `.part` files, HTTP Range resume, retry/backoff, cancel, progress.
|
||||
3. **Verify** — SHA-256 of every artefact; nothing is executed or extracted into the live tree before this.
|
||||
4. **Snapshot** — server must be stopped (never copy over a running worldserver); create recovery point:
|
||||
replaced binaries, changed managed configs, module state, `characters`+`auth` dump (world optional);
|
||||
write `txn.json {state: Snapshotted}`.
|
||||
5. **Apply** into `staging\<txid>\tree\`, resolve ownership conflicts, merge configs, then swap file-by-file with
|
||||
same-volume atomic renames, journaling each step (`txn.json` lists done/undone operations).
|
||||
6. **Migrate** — run pending SQL through the tracked runner (D7); failure ⇒ stop, keep DB backup, offer restore.
|
||||
7. **Validate** — start server, health check (D3) with timeout.
|
||||
8. **Commit** — ownership table + `install.json` version bump, mark txn `Committed`, prune staging.
|
||||
Any crash before Commit leaves `txn.json` in a non-terminal state; on next launch the Manager detects it and
|
||||
offers *Roll forward* or *Roll back* — the install is "recoverable" by construction.
|
||||
|
||||
Rollback = binaries + managed config state + module state only. Database restore is a **separate explicit
|
||||
action** (spec §19–20).
|
||||
|
||||
### D7. Database strategy (`db` module)
|
||||
|
||||
* Driver: talk to the repack's own `mysql.exe` / `mysqldump.exe` / `mysqladmin.exe` (bundled, 8.4.9). Passwords
|
||||
are passed via a temp `--defaults-extra-file` with restrictive ACL, deleted immediately — never on argv. A
|
||||
native Rust client (`mysql_async`) is used for health pings and migration ledger reads.
|
||||
* Ledger: table `acore_world.coa_manager_migrations(id, db, sha256, applied_at, status, error)` (created by the
|
||||
Manager, in a dedicated table — no core schema is changed) mirrored to `.manager\migrations\`.
|
||||
Statuses `Applied | Pending | Failed`. Each file runs in a single connection; DDL is not transactional, so
|
||||
"destructive" migrations (flag in manifest, or heuristic scan for `DROP|TRUNCATE|DELETE|ALTER ... DROP`) force
|
||||
a fresh DB backup first and require explicit confirmation.
|
||||
* Backups: `mysqldump --single-transaction --routines --quick` per DB. Quick = characters + auth + configs +
|
||||
metadata; Full adds world (large); Config-only; DB-only. Compressed with zstd. Restore is always to a
|
||||
staging schema first (`…_restore`), swapped only after a row-count sanity check, with the current DB dumped
|
||||
beforehand.
|
||||
* Never: `DROP DATABASE`, resetting characters, overwriting DBs, or restoring DB on a binary rollback. Delete/
|
||||
reset lives only in **Settings → Advanced → Danger Zone**, deletes tracked files only, and refuses to remove a
|
||||
directory that still contains untracked files.
|
||||
* Clean install: extract `mysql\data.7z` (packaged data dir), then **rotate** root/app passwords to fresh random
|
||||
values (`ALTER USER`), rewrite `Settings\database.json`/templates via the layout renderer, store copies in
|
||||
DPAPI. `bind-address=127.0.0.1` enforced.
|
||||
|
||||
### D8. Bot install/update (needs server-side cooperation — see §4)
|
||||
|
||||
Compatibility matrix `compat.json` (published with releases): `[{manager, core, bots, dbSchema}]` keyed by exact
|
||||
core commit. Bots install = "install the bot-enabled `worldserver.exe` built for **this** core commit" +
|
||||
conf.dist + talent JSON + SQL migration + (if client attached) addon. Same hash-gated + backup-first rules as
|
||||
the existing `Install-CoaBots.ps1`, executed through the D6 transaction. Force-install on unknown core =
|
||||
Advanced override, snapshot first.
|
||||
|
||||
### D9. Client integration
|
||||
|
||||
The client is a separate object. Manager only: detect (`Wow.exe`/`Ascension.exe` + `Data\`), read/write
|
||||
`realmlist.wtf` after backing it up, and copy `Interface\AddOns\CoABotUI` (backing that one directory up only if
|
||||
its files differ from the manifest). No touching of `WTF`, `Cache`, other AddOns, or the exe.
|
||||
*Reference machine note:* `C:\games\Ascension` is a heavily modified Ascension client (custom `d3d9.dll`,
|
||||
renderer files, many `.bak`s) — client detection must be strictly read-only + additive.
|
||||
|
||||
### D10. Network / friends
|
||||
|
||||
Detect LAN IP and public IP (HTTPS to a small set of IP-echo endpoints, user-toggle), listening check via
|
||||
outbound self-test, **CGNAT heuristic** (WAN address of router ∈ 100.64.0.0/10 or private / ≠ public IP),
|
||||
UPnP/NAT-PMP later. Firewall rules created only through a separate elevated helper (UAC on demand, never whole
|
||||
app as admin), fixed names `CoA Server Manager - Auth` / `- World`, idempotent (query before add), delete only
|
||||
own rules. Never exposed: MySQL 3307, RA 3443, Manager control channel (Tauri IPC only, no listener). Private
|
||||
network = Tailscale detection/guided enable in v1; interface `NetworkProvider` so "CoA Connect" can slot in.
|
||||
Friend package contains only `realmlist`/instructions/optional addon; secrets structurally excluded (whitelist
|
||||
copy, not blacklist).
|
||||
|
||||
### D11. Stack & code layout
|
||||
|
||||
```
|
||||
coa-server-manager/
|
||||
docs/ ARCHITECTURE.md, flows, wireframes
|
||||
schemas/ bots.json, server.json, presets/, manifest.schema.json, compat.schema.json
|
||||
src-tauri/src/
|
||||
main.rs, commands/ thin Tauri command layer (validate → call service)
|
||||
fsx/ path validation, safe join, atomic write/replace, disk space, ownership
|
||||
layout/ RepackLayout, detection & classification
|
||||
registry/ installs.json, .manager dir, install.json
|
||||
process/ identity, listeners, lock, drivers (delegate → native)
|
||||
health/ probes, log-marker scan, error translation
|
||||
config/ parser, merge, schema, presets
|
||||
db/ mysql tool wrapper, ledger, migrations, dump/restore
|
||||
backup/ recovery points, retention
|
||||
update/ manifest, download, verify, txn (journal), rollback
|
||||
client/ detection, realmlist, addon
|
||||
net/ ips, ports, cgnat, firewall, tailscale
|
||||
errors/ error catalogue → human message + actions
|
||||
diag/ diagnostics, export package (redacting)
|
||||
src/ React + TS + Vite + Tailwind + shadcn/ui (presentation only)
|
||||
tests/ integration fixtures (fake repack generator), failure-injection harness
|
||||
coa-server-build/ (separate repo) workflows + packaging + manifest signing
|
||||
```
|
||||
|
||||
All destructive filesystem operations exist only in `fsx`; frontend never has `fs` scope in Tauri capabilities.
|
||||
Every command that mutates goes through `fsx::Transaction`-style helpers that (a) validate the path is inside a
|
||||
registered installation *or* the `.manager` dir, (b) refuse symlink/junction escapes, (c) log an audit record.
|
||||
|
||||
### D12. Build/release repo (`coa-server-build`)
|
||||
|
||||
Windows runner: checkout **exact** core SHA and bots SHA from workflow inputs (refuse branch names), place bots at
|
||||
`modules/mod-coa-playerbots`, verify core patches are already in the core commit (fail the build if the patch set
|
||||
is not applied — never apply ad-hoc patches at build time unless they are versioned `.patch` files in the build
|
||||
repo), vcpkg-cached deps, CMake Release/RelWithDebInfo static, produce **two binaries per core commit**:
|
||||
`worldserver` (no bots) and `worldserver+bots`, then `authserver`, DLLs, config `.dist`s, talent JSON, addon, SQL
|
||||
migrations, `RELEASE.json`, `manifest.json` (+SHA256, +ed25519 signature), zstd-compressed update package.
|
||||
Base package (≈3.2 GB; Data 3.8 GB + mysql data) is split into ≤ 1.9 GB parts (GitHub release asset cap is 2 GiB)
|
||||
with a parts manifest. Reproducibility: pinned runner image label, recorded compiler/vcpkg versions, source SHAs,
|
||||
build timestamp written into RELEASE.json.
|
||||
|
||||
---------------------------------------------------------------------------------------------------------
|
||||
|
||||
## 3. Flows
|
||||
|
||||
### 3.1 First run
|
||||
`Welcome → [Install new server] | [I already have a server] | (link) Manage another install`.
|
||||
New: choose folder (default `C:\Games\CoA Server`; checks: free space ≥ base+backup headroom, folder empty or
|
||||
absent, not a client folder, not `Documents`/system dirs, not already registered) → single progress screen
|
||||
(Download → Verify → Extract → Database → Bots(optional) → Start → Health) → "Your server is ready" →
|
||||
Create account → PLAY. Technical log behind "Show details" only.
|
||||
|
||||
### 3.2 Existing-server import (strictly read-only)
|
||||
select folder → `layout::scan()` (read-only opens, `FILE_SHARE_READ|WRITE` so a live server is unaffected) →
|
||||
report: core exes + hashes vs RELEASE.json/MANIFEST.json, detected core commit (RELEASE.json → else banner rev in
|
||||
Server.log → else unknown), configs & modules present, DB running/reachable (ping only), bots detected (conf
|
||||
present ∧ patched-hash or `CoaBots.*` keys), client detected, classification + "No files will be changed" →
|
||||
**[Add server]** writes only `<folder>.manager\` and the registry entry. Import never "fixes" anything.
|
||||
Verification for the fixture test: recursive (path,size,mtime) snapshot of the server folder excluding
|
||||
files the running server itself changes, diffed before/after.
|
||||
|
||||
### 3.3 Update — see D6. Failure matrix (spec §60) is executable via a fault-injection harness: kill at step k,
|
||||
disk-full at write n, network cut at byte n, migration returns error, new worldserver exits non-zero, port
|
||||
taken, exe quarantined (file vanishes), folder moved, user-modified managed file, unknown config keys.
|
||||
|
||||
### 3.4 Rollback — restore recovery point's binaries/configs/module state; database untouched unless the user
|
||||
picks "Restore database" separately (shows dump timestamp and warns that progress since then is lost).
|
||||
|
||||
---------------------------------------------------------------------------------------------------------
|
||||
|
||||
## 4. Required changes in the two source repositories
|
||||
|
||||
Prefer server-side cleanliness over Manager hacks. Proposed (each is an issue/PR on the owner's side, none is
|
||||
made without approval):
|
||||
|
||||
| # | Repo | Change | Why |
|
||||
|---|------|--------|-----|
|
||||
| S1 | mod-coa-playerbots | Master switch `CoaBots.Enable` (0 = module registered but inert; no login/hooks/commands) | Lets a **single** worldserver ship for everyone. "Disable bots" becomes a config flip with restart, not a binary swap; drops the 2-binary matrix and most of §D8 risk. |
|
||||
| S2 | mod-coa-playerbots | Commit **all** core patches in the core repo; delete "uncommitted working-tree" state from docs | CI must build from clean SHAs (R1). |
|
||||
| S3 | mod-coa-playerbots | Real Releases + `dist/release.json` replaced by the shared `manifest.json` schema; `TalentBuildsPath` default = `Core/reference/…`, remove the hard-coded dev path fallback | Manager and installer share one truth; no absolute dev paths. |
|
||||
| S4 | mod-coa-playerbots | Ship a machine-readable config schema (`conf/…schema.json`) next to `.dist`, or generate it in CI from the `.dist` comments | Avoid schema drift (71 vs 30 keys today). |
|
||||
| S5 | core | Windows build+release workflow (or the build repo builds it); publish `worldserver --version --json` (core commit, bots commit, DB schema id) | Reliable version detection instead of log scraping. |
|
||||
| S6 | core | Health endpoint alternative: worldserver already prints `ready...`; add a stable machine line (`COA-READY {...}`) or a tiny loopback status file `Core\Logs\ready.json` | Health without regex on human text. |
|
||||
| S7 | core/repack | Ship a `manager-hooks.json` in the repack describing service names, ports, exes, config templates, RA settings | Layout detection without hard-coded knowledge; unknown custom builds can opt in. |
|
||||
| S8 | core | Keep the auto DB updater disabled but expose `--dry-run-updates` listing pending updates | Manager migration UI without re-implementing the updater. |
|
||||
| S9 | repack | Per-download random DB passwords and `Settings\database.json` generated on first start, not packaged | Security (§1.1). Manager does it itself for new installs meanwhile. |
|
||||
|
||||
Everything still works without S1–S9 (Manager has fallbacks), they just remove fragility.
|
||||
|
||||
---------------------------------------------------------------------------------------------------------
|
||||
|
||||
## 5. Import classification rules
|
||||
|
||||
* **Healthy** — `Core\{worldserver,authserver}.exe`, `Core\configs\*.conf`, `Data\dbc`, `mysql\bin\mysqld.exe` +
|
||||
`mysql\data\acore_{auth,characters,world}`, `Settings\repack.json`, `Scripts\manage.py`, all present.
|
||||
* **Partial** — a repack skeleton with pieces missing (e.g. no Data\maps, DB dirs absent).
|
||||
* **Unknown/custom** — has `worldserver.exe` + `authserver.exe` but not the repack scaffolding.
|
||||
* **Incompatible** — not a 3.3.5 AzerothCore layout / two installations nested / client folder.
|
||||
The reference install classifies as **Healthy (customised)**: repack shape, binary hash differs from RELEASE.json.
|
||||
|
||||
---------------------------------------------------------------------------------------------------------
|
||||
|
||||
## 6. Risks & open questions
|
||||
|
||||
* **R1 (blocking for Phase 7/6)** — are all core patches committed? Owner action: confirm/commit (S2).
|
||||
* **R2** — Legal/hosting of the base package: `Data\` (maps/vmaps/mmaps/dbc) derives from the game client;
|
||||
and Ascension-specific DBC. Where does the owner want to host the 3–4 GB base (GitHub Releases in the build repo,
|
||||
parts ≤ 1.9 GB; or own storage)? The Manager's downloader is source-agnostic; the choice affects Phase 5–6.
|
||||
* **R3** — Manager signing key: needs an Ed25519 key pair generated by the owner; public key embedded in the app,
|
||||
private key in GitHub Actions secrets. Phase 6 can start with unsigned + hash-only and flip the enforcement flag.
|
||||
* **R4** — Bug-report relay (Python, sends reports to maintainers) is part of the repack's world startup; Manager
|
||||
keeps it (privacy note surfaced in Settings, user can disable via the existing `coa_bugreport.conf` mechanism
|
||||
only if the repack supports it — currently it forces `Enable = 1` on every start; not touched by Manager).
|
||||
* **R5** — Tauri updater needs a hosted, signed `latest.json`; Manager self-update is Phase 10.
|
||||
* **R6** — Windows long paths / non-ASCII install paths: repack requires a Latin path (uses 8.3 short names);
|
||||
new-install folder chooser enforces it.
|
||||
|
||||
---------------------------------------------------------------------------------------------------------
|
||||
|
||||
## 7. Phase plan (each phase ends: compile → tests → run against fixture → verify live install untouched → commit)
|
||||
|
||||
| Phase | Deliverable | Done when |
|
||||
|-------|-------------|-----------|
|
||||
| 1 | Tauri+Rust+React skeleton, `fsx`, registry, `.manager` layout, logging w/ rotation, manifest structs + JSON schema, error catalogue skeleton | `cargo test` green; app launches; metadata round-trips |
|
||||
| 2 | Read-only scan/classify/import; process discovery; Start/Stop via delegate driver; health | Import of `C:\games\CoA-Repack` leaves it byte-identical (proved by snapshot diff); Start/Stop verified on **fixture copy, offset ports** |
|
||||
| 3 | Config parser/merge/atomic save; bots+server schemas; presets; UI | Property tests: unknown keys/comments preserved; round-trip identity |
|
||||
| 4 | Recovery points, DB dumps, config snapshots, restore-to-staging | Backup→restore fixture test; fails safe when disk full |
|
||||
| 5 | Clean install from base package; DB bootstrap + password rotation; account creation | Fresh VM/folder install reaches "ready" |
|
||||
| 6 | Build repo & workflows; signed manifests; update transaction, rollback | Fault-injection suite green (spec §60) |
|
||||
| 7 | Bots install/update via txn; compat matrix; GUI settings | Install → disable → restore on fixture |
|
||||
| 8 | Client detection, addon, realmlist, PLAY | Client tree hash unchanged except addon dir + realmlist |
|
||||
| 9 | Friends: net diagnostics, firewall service, Tailscale | Idempotent rule add/remove test |
|
||||
| 10 | Error translation, diagnostics, repair, a11y, self-update | Spec §61 checklist |
|
||||
Reference in new issue
Block a user