Import bookmarks in TeamSpeak's order

TeamSpeak stores sync items in creation order; each names the item above
it in its folder, and a reorder only rewrites those links. The decoder
now keeps that link and SyncOrder follows the chains, so items read from
settings.db or myTeamSpeak come out as the official client lists them,
a folder's contents in its place. Broken links and loops go last in
stored order. Bookmarks imported earlier keep their place.

The reordered.db fixture was written by the official client.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-10 13:15:28 +00:00
co-authored by Claude Opus 5.5
parent 8d04cc5ba4
commit 1a762c2689
8 changed files with 146 additions and 16 deletions
@@ -4,6 +4,7 @@ import com.ts3client.proto.ProtobufReader;
import com.ts3client.proto.ProtobufWriter;
import com.ts3client.teamspeak.SyncItem;
import com.ts3client.teamspeak.SyncItemDecoder;
import com.ts3client.teamspeak.SyncOrder;
import java.io.IOException;
import java.net.URI;
@@ -181,7 +182,7 @@ public final class MyTeamSpeak {
}
if (item != null) items.add(item);
}
return items;
return SyncOrder.sorted(items);
}
/**
@@ -14,14 +14,17 @@ public sealed interface SyncItem {
/** UUID of the {@link Folder} the item sits in, or empty at the top level. */
String parentUuid();
record Folder(String uuid, String parentUuid, String name) implements SyncItem {
/** UUID of the item just above it in its folder, or empty when it is the first. */
String previousUuid();
record Folder(String uuid, String parentUuid, String previousUuid, String name) implements SyncItem {
}
/**
* @param identity the key in TeamSpeak's obfuscated {@code <offset>V<data>} identity form
* @param nickname the nickname used with this identity when a bookmark names none
*/
record Identity(String uuid, String parentUuid, String identity, String name,
record Identity(String uuid, String parentUuid, String previousUuid, String identity, String name,
String nickname, String phoneticNickname, boolean isDefault) implements SyncItem {
}
@@ -31,7 +34,7 @@ public sealed interface SyncItem {
* @param defaultChannel channel path to join, "/"-separated; empty for the server default
* @param defaultChannelId the same channel by id, {@code 0} when unknown
*/
record Bookmark(String uuid, String parentUuid, String name, String address, int port,
record Bookmark(String uuid, String parentUuid, String previousUuid, String name, String address, int port,
String nickname, String phoneticNickname, String identityUuid,
String serverPassword, String defaultChannel, String defaultChannelPassword,
long defaultChannelId, boolean autoconnect) implements SyncItem {
@@ -26,6 +26,7 @@ public final class SyncItemDecoder {
public static SyncItem decode(byte[] blob) throws IOException {
String uuid = "";
String parent = "";
String previous = "";
boolean deleted = false;
ProtobufReader content = null;
int contentField = 0;
@@ -36,6 +37,7 @@ public final class SyncItemDecoder {
case 2 -> uuid = r.readString();
case 4 -> deleted = r.readVarint() == ITEM_DELETED;
case 7 -> parent = r.readString();
case 8 -> previous = r.readString();
case 16, 17, 22 -> {
contentField = r.fieldNumber();
content = r.readMessage();
@@ -46,13 +48,13 @@ public final class SyncItemDecoder {
if (deleted || content == null) return null;
if (parent.equals(ROOT_PARENT)) parent = "";
return switch (contentField) {
case 16 -> bookmark(uuid, parent, content);
case 17 -> identity(uuid, parent, content);
default -> folder(uuid, parent, content);
case 16 -> bookmark(uuid, parent, previous, content);
case 17 -> identity(uuid, parent, previous, content);
default -> folder(uuid, parent, previous, content);
};
}
private static SyncItem.Bookmark bookmark(String uuid, String parent, ProtobufReader r) throws IOException {
private static SyncItem.Bookmark bookmark(String uuid, String parent, String previous, ProtobufReader r) throws IOException {
String name = "", address = "", nickname = "", phonetic = "", identity = "";
String serverPassword = "", channel = "", channelPassword = "";
int port = 9987;
@@ -74,11 +76,11 @@ public final class SyncItemDecoder {
default -> r.skip();
}
}
return new SyncItem.Bookmark(uuid, parent, name, address, port, nickname, phonetic, identity,
return new SyncItem.Bookmark(uuid, parent, previous, name, address, port, nickname, phonetic, identity,
serverPassword, channel, channelPassword, channelId, autoconnect);
}
private static SyncItem.Identity identity(String uuid, String parent, ProtobufReader r) throws IOException {
private static SyncItem.Identity identity(String uuid, String parent, String previous, ProtobufReader r) throws IOException {
String identity = "", name = "", nickname = "", phonetic = "";
boolean isDefault = false;
while (r.next()) {
@@ -91,15 +93,15 @@ public final class SyncItemDecoder {
default -> r.skip();
}
}
return new SyncItem.Identity(uuid, parent, identity, name, nickname, phonetic, isDefault);
return new SyncItem.Identity(uuid, parent, previous, identity, name, nickname, phonetic, isDefault);
}
private static SyncItem.Folder folder(String uuid, String parent, ProtobufReader r) throws IOException {
private static SyncItem.Folder folder(String uuid, String parent, String previous, ProtobufReader r) throws IOException {
String name = "";
while (r.next()) {
if (r.fieldNumber() == 1) name = r.readString();
else r.skip();
}
return new SyncItem.Folder(uuid, parent, name);
return new SyncItem.Folder(uuid, parent, previous, name);
}
}
@@ -0,0 +1,69 @@
package com.ts3client.teamspeak;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* Puts sync items in the order the TeamSpeak client lists them. The store keeps them in the
* order they were created; each item names the one above it in its folder, so a reorder only
* rewrites those links.
*/
public final class SyncOrder {
private SyncOrder() {
}
/**
* The items top to bottom, each folder's contents right after the folder. Items whose
* links lead nowhere, or whose folder is missing, come last in their stored order.
*/
public static List<SyncItem> sorted(List<SyncItem> items) {
Map<String, List<SyncItem>> byFolder = new LinkedHashMap<>();
for (SyncItem item : items) byFolder.computeIfAbsent(item.parentUuid(), k -> new ArrayList<>()).add(item);
List<SyncItem> out = new ArrayList<>(items.size());
Set<SyncItem> placed = new HashSet<>();
appendFolder("", byFolder, placed, out);
for (List<SyncItem> stray : byFolder.values()) {
for (SyncItem item : stray) {
if (!placed.contains(item)) appendFolder(item.parentUuid(), byFolder, placed, out);
}
}
return out;
}
private static void appendFolder(String folder, Map<String, List<SyncItem>> byFolder, Set<SyncItem> placed,
List<SyncItem> out) {
List<SyncItem> members = byFolder.getOrDefault(folder, List.of());
Map<String, List<SyncItem>> byPrevious = new LinkedHashMap<>();
for (SyncItem item : members) byPrevious.computeIfAbsent(item.previousUuid(), k -> new ArrayList<>()).add(item);
List<SyncItem> chain = new ArrayList<>(members.size());
follow(byPrevious.getOrDefault("", List.of()), byPrevious, placed, chain);
// Broken links: the rest start chains of their own.
for (SyncItem item : members) follow(List.of(item), byPrevious, placed, chain);
for (SyncItem item : chain) {
out.add(item);
if (item instanceof SyncItem.Folder) appendFolder(item.uuid(), byFolder, placed, out);
}
}
/** Appends {@code heads} and, after each, the items below it, depth first. */
private static void follow(List<SyncItem> heads, Map<String, List<SyncItem>> byPrevious, Set<SyncItem> placed,
List<SyncItem> chain) {
ArrayDeque<SyncItem> stack = new ArrayDeque<>();
for (int i = heads.size() - 1; i >= 0; i--) stack.push(heads.get(i));
while (!stack.isEmpty()) {
SyncItem item = stack.pop();
if (!placed.add(item)) continue;
chain.add(item);
List<SyncItem> below = byPrevious.getOrDefault(item.uuid(), List.of());
for (int i = below.size() - 1; i >= 0; i--) stack.push(below.get(i));
}
}
}
@@ -63,7 +63,7 @@ public final class TeamSpeakSettingsDb {
}
/**
* The synchronised items in database order. Rows that are not items — the
* The synchronised items in the order the client lists them. Rows that are not items — the
* table's checksum, unmodelled classes, pending deletions — are left out.
*
* @throws IOException when the file is not a readable SQLite database
@@ -80,7 +80,7 @@ public final class TeamSpeakSettingsDb {
}
if (item != null) items.add(item);
}
return items;
return SyncOrder.sorted(items);
}
/** The {@code value} column of a key/value table, in row order; empty when the table is absent. */