Files
ts3java/ts3-client/docs/myteamspeak/IMPLEMENTATION.md
T
erikbrockoandClaude Opus 5.5 212a4bcdbb myTeamSpeak docs: the synced config item, sync edge cases and limits
CONFIG_SYNC.md lists the class 5 config item's fields; none maps onto a
setting of ours, so sync leaves it alone. IMPLEMENTATION.md covers the
session lock, duplicate keys in the account, bookmarks following an
identity's conflict, interrupted runs, and what sync cannot catch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 22:04:26 +00:00

7.5 KiB

myTeamSpeak in the client

What is implemented, and what two-way sync would still need.

Sign-in and read-only import (done)

core/src/main/java/eu/lixko/ts3j/client/myts/ — pure Java, no Swing/Android dependency, and no JDK API that Android 13 lacks (hence HttpURLConnection, not java.net.http).

  • MyTeamSpeakLogin — the account the client stays signed in to. Like the official client's Account_Data (which stores email, the login token in its password field, and the account key as encryption_password), it keeps MyTeamSpeak.Credentials — email, login token, account key — in the private profile file myteamspeak.properties; never the password. signIn derives them, reads the account and only then saves them; fetch reads the account again with the saved ones; signOut deletes the file. When the server rejects saved credentials (ERROR_LOGIN_FAILED, e.g. the password was changed elsewhere) fetch signs out. All requests share one session (MyTeamSpeakLogin.request), as the official client's do: signed in on first use, again when the service reports it expired (102/109), ended on sign-out or exit. Signing in for every request gets the account's logins throttled within a few dozen (seen 2026-10-15: login timed out for minutes). A sign-in runs under its own lock, not the login's, so isSignedIn/email/username answer at once on the UI thread while one is under way.
  • MyTeamSpeak.download(Credentials) — signs in (authentication/login), unwraps the item key, pulls BOOKMARK, IDENTITY and ITEM_FOLDER with one synchronization/requestServerItems against an empty local state (all-zero global and class versions, no details), decrypts every item, then ends the session (authentication/deleteSession); MyTeamSpeakLogin does the same in its shared session.
  • MyTsCrypto — PBKDF2-HMAC-SHA512 login token and account key, LoginSession.key unwrap (AES-256-GCM), item frame decryption (little-endian AES-CTR + SHA-512 trailer). See CRYPTO_RE_SALT.md.
  • MyTsTransport — the application/ts3cloud framing over HTTP/1.1; an interface so tests replay a server.
  • Decrypted items are plain Item_Data, decoded by teamspeak/SyncItemDecoder. TeamSpeakImporter gains importSelected(all, chosen) (chosen bookmarks bring the identities they use) and isPresent(item); the policy is the local settings.db import's: additive and idempotent.

Frontends: Swing Options → "myTeamSpeak" tab (MyTeamSpeakPanel); Android Settings → Account → myTeamSpeak (ui/MyTeamSpeakScreen.kt). Both: sign in/out, the account's bookmarks and identities with a checkbox each and whether they are imported already, Refresh, "Import selected".

Observed on the live account: a bookmark may name its identity by the identity's name ("Default") instead of its item UUID; the importer resolves both.

Tests: MyTsCryptoTest (captured vectors), MyTeamSpeakTest (download against a replayed server built from the captured login and item), MyTeamSpeakLoginTest (persistence, failed sign-in, rejected credentials, a slow sign-in), MyTeamSpeakSyncTest (two-way sync between installations against a fake account).

Two-way sync

MyTeamSpeakSync (with SyncKind, SyncFields, SyncState): bookmarks and identities, run by hand (Swing: Options → myTeamSpeak → Synchronize, conflicts in SyncConflictsDialog; Android: Settings → myTeamSpeak → Synchronize, conflicts in ui/SyncConflictsScreen.kt). A run is fetch (network) → plan (stores' thread) → user settles Plan.conflicts() → upload (network) → apply (stores' thread). Nothing changes on either side before upload, and here only after it succeeded.

The comparison is three-way per item, against SyncState (profile file myteamspeak-sync.properties: the global cursor, each class's cursor, and per item its server revision, plaintext Item_Data and local id). Changed on one side → carried over (deletions too); on both → a Conflict with a field-by-field diff; first run → items paired by identity UID or bookmark name+address, the rest carried over. The default identity is each installation's own: is_default is not compared, an identity new to the account is uploaded as its default only when it has none, and one brought here becomes ours only when we have none (otherwise installations flip each other's default on every run). Edits are written over the item's current Item_Data field by field (ProtobufMessage), so fields this client does not model survive. The synced settings item (class 5) is listed in CONFIG_SYNC.md; none of it maps onto ours.

Cases the plain three-way rule gets wrong:

  • The local store holds one identity per key, the account may hold several (the official client can import the same key twice). Only the first account item for a key is synchronised; the others are kept as the account has them, never merged into ours (which would write one over the other on the next run). A bookmark using such a copy connects with the local identity of that key.
  • Deleting an identity here clears it from our bookmarks. When the identity was meanwhile changed in the account (a conflict), a bookmark whose only change is that cleared link does not go out on its own: it follows the identity's conflict — relinked to the restored identity on "Keep myTeamSpeak's", sent without it on "Delete".
  • A run cut off between upload and apply (process killed, screen left) needs nothing special: the next run sees its own uploads as the same on both sides and keeps them.

Known limits: push checks the cursors, then stores; another client storing in between is not seen until the class changes again, as we keep our own class revision as the cursor. The service gives no way to close that gap. Deletions from elsewhere are carried out like any other change, and deleting an identity deletes its key file.

How the service and the official client behave (live, 2026-10-15)

Probed against the test account and by capturing the official 3.6.2 client's traffic.

  • requestServerItems: a class whose cursor matches comes back empty; any other comes back whole. Item details in the request are ignored; there are no deltas. Deleted items simply vanish.
  • synchronizeItems stores what it is sent: the class revision (client-made, a fresh UUID), each item's wire revision and blob; replies 300 and a new global cursor. It never reports COLLISION, whatever is stale — conflicts are the client's to find. push therefore re-reads the cursors first and fails with changedMeanwhile when any moved.
  • The official client polls about once a minute with its cursors and the global cursor, and on startup with random class cursors (a full read). It applies what it reads live; it writes settings.db only later, so read its state from the UI, not the database, while it runs. Our pushes do not reach its push channel.
  • Its change upload: plaintext sync_version_uuid new, last_known_version := the previous one, manipulated = 3; a fresh wire revision; only the changed items; the global cursor echoed. Adds carry manipulated = 0. Deletion: the detail's item_delte_on_server = 1 under a fresh revision (it also sends the last blob; one without is accepted too). We write the same.
  • It reports "myTeamSpeak account collision detected" and stops applying when a remote change meets an item it still holds as locally changed. Seen once, after mixed probing; not with the writes above.

Etiquette

One sign-in is three requests. Don't loop sign-ins while testing; the service sits behind Cloudflare and rate-limits abuse.