mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-21 19:25:56 +00:00
Imports a canonical snapshot into a stopped disposable realm through the existing Db abstraction, in one MySQL transaction: guids allocated inside the transaction from the realm's own tables and every reference remapped, orphan cleanup, name and start-position handling, self-asserting result, and a marker row. Untrusted strings and blobs reach SQL only as hex literals from a typed encoder. Manager mappings are recorded only after the realm commit, in one local transaction; an import journal (schema 3) plus the marker recover a crash between the two commits. Preflight refuses wrong ruleset, running realm, missing account/content and more before anything is written. Stock character_talent rows are never written: a real worldserver asserts on a non-talent row. Item identity no longer includes the crafter (v2). Production import remains the designed in-core PortableImportService (docs/PORTABLE_IMPORT_SERVICE.md); nothing of it is implemented. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
78 lines
5.1 KiB
Markdown
78 lines
5.1 KiB
Markdown
# PortableImportService (production importer): design
|
|
|
|
Status: **design only, approved, not implemented.** It is a core-side workstream (the fork's `src/server/game/Tools/`, next to
|
|
`PlayerDump`). The offline importer ([`PORTABLE_IMPORT.md`](PORTABLE_IMPORT.md)) stays the tool for stopped realms and for
|
|
tests.
|
|
|
|
## Why in-core
|
|
|
|
A running worldserver owns the id counters, the character name cache and the realm character count in memory
|
|
(`ObjectMgr::SetHighestGuids`, `CharacterCache`, `World::UpdateRealmCharCount`). Anything written from outside collides with
|
|
ids the server is about to hand out and is invisible to name lookups until a restart. `PlayerDumpReader::LoadDump`
|
|
(`PlayerDump.cpp:764`) already solves this inside the server; the service follows its runtime invariants and adds the CoA
|
|
tables and the portable model.
|
|
|
|
## Trigger: an opaque job id, never a payload
|
|
|
|
```text
|
|
Manager worldserver
|
|
1. writes <JobDir>/<job_id>.job (atomically)
|
|
2. RA: `.portable import <job_id>` -------------> validates job_id, reads ONLY that file from the fixed JobDir
|
|
runs the import, writes <JobDir>/<job_id>.result (atomically)
|
|
3. RA reply: "OK <job_id>" / "ERR <code>" <--------
|
|
4. reads the .result file, deletes both files
|
|
```
|
|
|
|
* `PortableImport.JobDir` is a worldserver setting (default `<realm>/PortableImport/`). The command takes **only** `job_id`, a
|
|
UUIDv7 string matched against `^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`; the file name is
|
|
built by the service as `<JobDir>/<job_id>.job`. No path, no separator, no payload, no SQL travels through RA, and RA's
|
|
typed-operation rule in `ra.rs` is kept (one new typed operation, `import_job(job_id)`).
|
|
* Console only, with its own RBAC permission; one job at a time; the reply never contains character data.
|
|
* The job file is the snapshot envelope of `PORTABLE_FORMAT.md` (compressed canonical JSON + SHA-256) plus a small header:
|
|
`{job_id, character_id, revision, account, nonce, expected_content_hash, ruleset}`. Size limits and the decompression cap are
|
|
enforced **before** parsing; the decoder is strict (unknown fields refused, bounded lists) and validates the same limits as
|
|
`PortableCharacter::validate`.
|
|
|
|
## The runtime invariants (taken from `PlayerDumpReader`)
|
|
|
|
All of these happen **inside the server, in one `CharacterDatabaseTransaction`**, on the world thread's DB path:
|
|
|
|
1. Refuse when the account does not exist, is a bot/Manager account, is full (`CharactersPerAccount`), or a character with this
|
|
marker already exists (idempotency, below).
|
|
2. Allocate ids from the **live generators**: `GetGenerator<HighGuid::Player>().GetNextAfterMaxUsed()`, the item generator,
|
|
`_hiPetNumber`; remap every reference through those maps (the same remap rules as the offline importer).
|
|
3. Name check with `normalizePlayerName` / `CheckPlayerName` and the name cache; a taken or invalid name gets the temporary
|
|
name and `AT_LOGIN_RENAME` (as `.pdump load`).
|
|
4. Validate against the realm's *own* data, which the offline importer cannot see: `sObjectMgr->GetItemTemplate`, creature
|
|
templates, `sSpellMgr`, **`sTalentStore` (so stock talents can be validated instead of skipped)**, `playercreateinfo`.
|
|
5. Write with **prepared statements** (`CharacterDatabasePreparedStatement::SetData`), never string-built SQL; all rows of the
|
|
character (including the marker `coa.portable.import`) in the one transaction.
|
|
6. `CharacterDatabase.CommitTransaction(trans)`; **after** a successful commit only:
|
|
`sCharacterCache->AddCharacterCacheEntry(...)`, advance the generators/`_hiPetNumber` exactly as `LoadDump` does,
|
|
`sWorld->UpdateRealmCharCount(account)`.
|
|
7. Never touch a character that is online; never overwrite an existing one (replacing is the separate, backed-up operation of
|
|
Phase 4).
|
|
|
|
## Idempotency and crash recovery
|
|
|
|
The marker row is written in the same transaction as the character, with the job's nonce. Re-running the same job id finds the
|
|
marker, writes the same `.result` and does nothing else. The Manager keeps the same `import_journal` as the offline path, so
|
|
the recovery table of `PORTABLE_IMPORT.md` applies unchanged; only the "who writes the realm side" part differs.
|
|
|
|
## Result file
|
|
|
|
`<job_id>.result` (JSON, written to a temp name and renamed): `{status, local_guid, item_base, pet_base, renamed, final_name,
|
|
counts, not_applied[], warnings[]}` or `{status:"refused", problems[]}` with the same problem codes as the offline preflight. The
|
|
Manager turns it into `finish_import`.
|
|
|
|
## What it must also cover (beyond the offline importer)
|
|
|
|
Online accounts (the character list on a connected client is stale until relog), the cache refresh above, per-character module
|
|
state through the module extension API of Phase 7, collections of the account (Phase 6, keyed by the destination account), and
|
|
the level-cap projection hooks of Phase 8.
|
|
|
|
## Not part of this design
|
|
|
|
Exports from a running realm (checkpoints need a per-character save command, `.character save <name>`, tracked separately),
|
|
a payload over RA, a path argument, a remote caller of any kind.
|