mirror of
https://github.com/Corfirean/coa-server-manager.git
synced 2026-11-21 03:25:56 +00:00
feat(portable): read-only export of offline characters from a realm (Phase 2)
Reads one offline character out of a realm's characters database through the existing Db abstraction: fixed SQL with the local guid as the only (numeric) input, one consistent READ ONLY snapshot per character, hex-encoded text. Maps the approved minimal v1 scope to the portable model; refuses online, deleted, bot, active challenge/game mode/Manastorm and unknown-table cases. Adds the 163-table registry, the settings policy, "Make Portable" in one store transaction, and item mapping lifecycle with content identity (schema 2) so a recycled local item guid never inherits an old portable item. Recorded answers of a real MySQL drive the unit tests; live tests re-verify them, read-only enforcement and snapshot consistency on a disposable server. No realm database is written and nothing changes for existing installs. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
adefa84885
commit
c590b82d27
34 files changed
+5236
-110
No files matched your search
@@ -0,0 +1,96 @@
|
||||
# Portable export from a realm (Phase 2)
|
||||
|
||||
Code: `crates/coa-core/src/portable/realm/`. Scope decisions: `PORTABLE_CHARACTERS_AUDIT.md` sections 15-16.
|
||||
|
||||
Phase 2 is **read-only**. It reads one **offline** character out of a realm's characters database into a
|
||||
`PortableCharacter` and (for "Make Portable") registers it in the local store. It never writes to a realm.
|
||||
|
||||
## What it does
|
||||
|
||||
| Function | Meaning |
|
||||
|---|---|
|
||||
| `inspect_characters(db)` | "Inspect realm characters": every character of a non-bot account with the reasons it cannot be exported yet |
|
||||
| `export_character(db, guid, character_id, prior_items)` | "Export snapshot": the portable model + item observations + warnings |
|
||||
| `make_portable(db, store, profile, server_id, guid)` | "Make Portable": export, then register in the local store in one transaction (revision 1, bound to the realm, items mapped) |
|
||||
|
||||
No Tauri command or UI exists yet (Phase 9).
|
||||
|
||||
## How the realm is read
|
||||
|
||||
* Through the Manager's existing `Db` abstraction (the bundled `mysql` client, or the same client inside a Docker
|
||||
database container). No driver, no new connection type, no published port. The Wildcard realm profile is routed by
|
||||
`Db` exactly like everything else, and **the database decides the ruleset**, not the caller.
|
||||
* **Fixed SQL, typed input.** Every statement is a literal in `script.rs`. The only input is the character's local
|
||||
guid as a `u32` formatted as a number. Table and column names of *unknown* tables come from `information_schema`,
|
||||
are checked as plain identifiers and appear only in `SELECT COUNT(*)`.
|
||||
* **One consistent read-only snapshot.** All statements for a character run in one `mysql` session inside
|
||||
`SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ; START TRANSACTION WITH CONSISTENT SNAPSHOT, READ ONLY;`.
|
||||
Verified against a real server: a write inside the script fails, and a concurrent write by someone else in the
|
||||
middle of the script is not seen.
|
||||
* **Hex-encoded text.** Names, item texts, settings and macro blobs are returned as `x<hex>`, so tabs, newlines, quotes
|
||||
and backslashes cannot confuse the parser.
|
||||
* Writing into a realm (Phase 3) must use prepared statements or the realm's own in-core import; this read path is not
|
||||
a basis for it.
|
||||
|
||||
## Who may be exported (`Blocker`)
|
||||
|
||||
| Blocker | Rule |
|
||||
|---|---|
|
||||
| `Online` | `characters.online <> 0` (also after a crash, when the flag is stale: stop the realm or log in/out) |
|
||||
| `Deleted` | `deleteDate` is set |
|
||||
| `BotAccount` | account `COABOT*` or `COAMANAGER` |
|
||||
| `ActiveChallenge` | a row in `coa_character_challenge` |
|
||||
| `ActiveGameMode` | `coa_character_gamemode.gameMode <> 0` |
|
||||
| `ActiveCustomTrial` | a row in `coa_custom_trial_active` |
|
||||
| `PendingManastormCaches` | a row in `ascension_manastorm_cache` (it names item guids that would be orphaned) |
|
||||
| `UnclassifiedState(table)` | a table this Manager does not know has a per-character column with rows for this character |
|
||||
|
||||
Finished challenges, game mode 0 and condition flags are history, not active state, and do not block (decision D6:
|
||||
*active* state blocks). A realm that lacks a core table (`SchemaMismatch`) cannot be exported from.
|
||||
|
||||
## What is exported (v1)
|
||||
|
||||
17 tables: `characters`, `character_inventory`, `item_instance`, `character_gifts`, `character_spell`,
|
||||
`character_talent`, `character_skills`, `character_glyphs`, `character_reputation`, `character_queststatus`,
|
||||
`character_queststatus_rewarded` (`active = 1`, as the realm loads it), `character_action`, `character_pet`, `pet_spell`,
|
||||
`character_pet_declinedname`, `character_settings` (by policy), `character_account_data` (macros, type 5).
|
||||
|
||||
**Not exported by decision** (deferred): collections, the personal Ascension bank, equipment sets, per-character wardrobe
|
||||
(`character_appearance*`), `mod_craftsmans_codex`. Auras, cooldowns, mail, guild, social, achievements, daily/weekly
|
||||
quests, position and homebind are never part of v1.
|
||||
|
||||
Left out *with a warning* (the realm would delete them on load anyway): inventory rows without an `item_instance`,
|
||||
items in a bag that is not on the character, items in buyback slots.
|
||||
|
||||
### `character_settings` policy (`policy.rs`, version 1)
|
||||
|
||||
* **Carry**: known CoA gameplay state (`core.ascension_*`, `core.spell_charge.*`, `core.destiny_weaver`, ...), and
|
||||
`core.wildcard*` on a Wildcard realm.
|
||||
* **Drop**: `coa.bot*`, `coa.gameplay_test`, `coa.highrisk`.
|
||||
* **Quarantine**: everything else is kept in the snapshot as the opaque extension `coa:unlisted-settings` (never
|
||||
destroyed, never applied at a realm).
|
||||
|
||||
### Table registry (`registry.rs`)
|
||||
|
||||
All 163 tables of the characters schema are classified (`Portable`, `Deferred`, `Collection`, `AccountLocal`,
|
||||
`CharacterLocal`, `Blocking`, `Realm`). A test fails if the real schema has a table the registry does not know, and at
|
||||
export time an unknown table that holds this character's rows blocks the export. A silent half-export is not possible.
|
||||
|
||||
## Item identity
|
||||
|
||||
Realms recycle local item guids. `ItemObservation.identity` hashes what cannot change during an item's life (entry,
|
||||
random property, crafter). A re-export keeps an item's portable id only if the identity behind the local guid is
|
||||
unchanged; a recycled guid produces a new portable item. The store side is in `PORTABLE_FORMAT.md` (item mapping
|
||||
lifecycle).
|
||||
|
||||
## Tests
|
||||
|
||||
* `realm/tests.rs`: on **recorded answers of a real MySQL** (`testdata/golden/`), no database needed: naked level 1,
|
||||
geared level 80 (bags, enchants, gems, random suffix, crafted-by, texts, charges, gift, currency tokens), quests,
|
||||
reputation, action bars, 300 spells + talents + glyphs + skills + CoA settings + binary macros, hunter and summon
|
||||
pets with declined names, every blocker, item id stability and recycling, Wildcard ruleset, CRLF, 400 damaged
|
||||
answers (no panics), registration in the store (one transaction, refused twice, rolled back on failure).
|
||||
* `realm/live.rs` (`#[ignore]`): the same answers re-recorded/verified against a **real disposable MySQL**, plus the
|
||||
read-only and snapshot-consistency proofs, the 21 genuine template characters of the schema fixture, and the proof that
|
||||
`make_portable` changes nothing in the realm. Instructions are at the top of the file.
|
||||
* `tools/gen_portable_fixture.py` writes `testdata/realm-fixture.sql` (deterministic).
|
||||
+22
-3
@@ -76,7 +76,7 @@ Account-wide sets of numeric ids (`coa:wardrobe`, `coa:vanity`, ...), stored per
|
||||
## Store (`%LOCALAPPDATA%\CoAServerManager\portable\portable.db`)
|
||||
|
||||
SQLite, WAL, `synchronous=FULL`, `foreign_keys=ON`, `application_id = 0x434F4150`, forward-only migrations tracked in
|
||||
`PRAGMA user_version`. A database from a newer Manager, or a foreign SQLite file, is refused and left untouched.
|
||||
`PRAGMA user_version` (currently 2). A database from a newer Manager, or a foreign SQLite file, is refused and left untouched.
|
||||
|
||||
| Table | Purpose |
|
||||
|---|---|
|
||||
@@ -84,8 +84,27 @@ SQLite, WAL, `synchronous=FULL`, `foreign_keys=ON`, `application_id = 0x434F4150
|
||||
| `character` | summary row + canonical revision |
|
||||
| `snapshot` | `(character_id, revision)` -> compressed canonical payload + hash |
|
||||
| `character_server_mapping` | `(character_id, server_id)` -> local guid; `UNIQUE(server_id, local_guid)` |
|
||||
| `item_mapping` | `(character_id, server_id, portable_item_id)` -> local item guid; `UNIQUE(character_id, server_id, local_item_guid)` |
|
||||
| `item_mapping` | one row per mapping with a lifecycle (schema 2, see below) |
|
||||
| `collection` | per profile and kind: revision, hash, encoded set |
|
||||
| `setting` | `history_keep` |
|
||||
|
||||
The store never reads or writes a realm database and never leaves the machine.
|
||||
## Item mapping lifecycle (schema 2)
|
||||
|
||||
A realm's item guid counter restarts at `MAX(guid)+1`, so a freed guid can be given to a different item. A bare
|
||||
`guid -> portable item` mapping would attach the new item to the old portable id. Every mapping therefore records what
|
||||
the item *was* (`entry`, `identity`) and has a state:
|
||||
|
||||
* `active`: at most one per portable item and at most one per local item guid
|
||||
(`UNIQUE(character_id, server_id, local_item_guid)` and `UNIQUE(.., portable_item_id)`, both for active rows);
|
||||
* `retired` (kept for the record) with a reason: `guid_reused`, `moved`, `absent`, `character_rebound`.
|
||||
|
||||
`Store::reconcile_item_mappings` takes the complete observation of a character on a realm and confirms, adds or retires
|
||||
mappings; `Store::resolve_item_ids` answers `Known`, `Reused` (recycled guid) or `Unmapped` for a local guid and its
|
||||
current identity. Schema-1 rows are migrated with an empty identity, which matches nothing: they are re-verified, never
|
||||
trusted. Rebinding a portable character to another local guid retires its item mappings.
|
||||
|
||||
The identity covers what cannot change during an item's life (entry, random property, crafter); two different items that
|
||||
share all of these are interchangeable for mapping purposes.
|
||||
|
||||
The store never reads or writes a realm database and never leaves the machine. (Phase 2's realm reader lives in
|
||||
`portable/realm/` and is documented in `PORTABLE_EXPORT.md`; it only reads.)
|
||||
Reference in new issue
Block a user