portable: Phase 5 - live bridge, online importer client, session harness, docs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
ДмитрийandClaude Sonnet 5.5 committed 2026-10-06 14:15:21 +05:00
1 parent d64bb882fa
commit 9870a3814c
34 files changed
+1022 -43

No files matched your search

+21 -2
View File
@@ -1,7 +1,8 @@
# 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
Status: **implemented in Phase 5** (core fork branch `feat/portable-session-bridge`: `src/server/coa/CoAPortableImport.{h,cpp}`,
`CoAPortableJson.{h,cpp}`; Manager side `portable/realm/online.rs`). Differences from this design are listed at the end. It is a core-side
workstream next to `PlayerDump`. The offline importer ([`PORTABLE_IMPORT.md`](PORTABLE_IMPORT.md)) stays the tool for stopped realms and for
tests.
## Why in-core
@@ -75,3 +76,21 @@ the level-cap projection hooks of Phase 8.
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.
## Implementation notes (Phase 5)
* **Job format.** The job file is `<header JSON>
<canonical JSON of the character>`, not zstd: the core has neither a JSON nor a zstd
dependency, and a small strict parser (`CoAPortableJson`: bounded depth/nodes/string size, integers only, duplicate and unknown
fields refused, UTF-8 checked) is easier to audit than a new dependency. The header carries `snapshot_sha256` of the exact bytes of the
second line; the file size is capped at 24 MiB before it is read. The Manager ships the character **without extensions** and without
settings the policy does not carry.
* **Writes.** Every row is written by a prepared `INSERT` (`CHAR_INS_PORTABLE_*`); the only string-built statements are the
`DELETE ... WHERE <fixed column> = <numeric guid>` that clear leftovers of a deleted character with the same guid.
* **Commit.** `DirectCommitTransaction`, then the marker is read back; the name cache entry, the item/pet/player generators and
`UpdateRealmCharCount` change only after that read confirms the commit.
* **Talents.** Stock talent rows are written only when the spell is a talent of the realm's own `TalentSpellPos` (the check the worldserver
asserts on); everything else is reported in `not_applied`.
* **Idempotency.** The marker `coa.portable.import = <nonce words> <revision>` is looked up first; a repeated job id answers `OK` and creates nothing.
* **Session.** With a `session` in the header the same transaction writes the `coa_portable_session` row in state 0, so the character's
first load takes its baseline (see `PORTABLE_SESSIONS.md`).
+15
View File
@@ -184,6 +184,21 @@ Manager writes <JobDir>/<job_id>.job (temp name + rename)
No path, SQL or snapshot travels through RA. Idempotency: the marker row carries the job nonce; re-running a finished job
rewrites the same result. Never touches a character that is online or already exists.
## 7a. Behaviour of the implementation worth knowing
* The gate holds the **session's packet queue** (`WorldSession::Update` skips it while gated) and makes the character non-attackable
and rooted. The timeout is enforced from a world-update hook, not from the session, so sessions without a socket are covered too; a
real client is kicked, a bot session (no socket) is only reported.
* A **clean shutdown logs every player out**: the logout save of each portable character carries `state = 3`, exactly like a normal
logout, and the Host sends the final checkpoint and arms the next session. A **crash** leaves `state = 2`: the next login continues the
same session with no new baseline.
* A character that logs in while its row is still `state = 3` (the Host has not closed the session yet) is disconnected with a
"try again in a moment" message: a baseline would otherwise be taken against a session the Owner already closed.
* The session table is read at login by the login query holder (`CHAR_SEL_PORTABLE_SESSION`), so a realm whose database lacks
`coa_portable_session` refuses to start like any other missing table: the pending SQL ships with the core.
* One checkpoint writes one character: verified on a real worldserver with two other characters online by counting the `characters`
rows the database was asked to write.
## 8. What is not in this phase
VPS Registry/Relay and any network transport, public server list, remote account provisioning, Wildcard, vanity/wardrobe