Files
ts3java/ts3-client/AUDIT-STRUCTURE.md
T
erikbrockoandClaude Opus 5.5 a2a12804ad Chat lines are routed once, in core
session.ChatFeed decides which conversation a message, history, server
event or notice goes to and renders it; frontends get the lines through
chat.ChatSink and key conversations by chat.ChatKey. ServerSession.Listener
no longer passes on raw chat events. Swing now labels our own messages
with our nickname on the server and links our name to us in private chats.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 23:37:33 +00:00

7.4 KiB

Structural audit — ts3-client and Android

Audit: 2026-10-11. Design and maintainability (DRY, SOLID, separation of concerns); the correctness audit is AUDIT.md. Not reviewed: the audio/DSP packages, tray/X11, D-Bus and the ts3j submodule.

Items are worked through in the order below. Status: open, done (commit), or closed (reason).

# Finding Status
1 Request failures reach frontends as strings, so they guess the kind by substring (BanListDialog, ServerLogDialog) and core needs a sentinel message (SEARCH_NOT_PERMITTED); success is signalled by a null error, here and in Android's ServerController (String?) done (0552ed8): requests return CompletableFuture, failing with RequestException (kind + message); Replies/Edt split success and failure; Android uses Result
2 Client properties parsed twice: ConnectionEventHandler.onClientJoin sets every field, onClientChanged the same ones again; channels already share applyChannelProperties done (e255a46): one applyClientProperties. It also fixed a joining channel commander shown as none, and picks up the description a client enters with
3 What we may do is answered in five places: ServerSession.can*, ServerModel.can*/permits/mayHavePower, TeamspeakConnection.canSendOfflineMessages/canTransferFiles, and raw permission names in Swing dialogs and ServerController.canCreateBans done (13e3a62): Permissions owns the table, the rules and one named question per capability; ServerSession.permissions() is NONE while disconnected; no permission names outside core except channel-permission editing
4 TeamspeakConnection (2,157 lines) still does lifecycle, mic/speaker, recording, chat logs, log/sound text, contacts, avatars, icons, file transfers, myTeamSpeak and job plumbing. The *Admin helpers take the whole connection, which forwards ~90 methods to them in progress, in sub-steps:
4a … chat log and what we tell the user (log lines, sounds, links and sound variables) done (1bc7eb5): ChatLog, Announcer
4b … request plumbing into its own class; *Admin helpers on narrow dependencies instead of the whole connection done (da908f7; renamed Uplink in 4c, as session.ServerLink is the ts3server:// link): ServerLink owns the socket, event and request threads and file transfers, and runs requests; the helpers take it (plus the model, permissions or avatars where they need them)
4c … frontends reach the admin helpers directly instead of ~40 one-line forwarders done (959f7ed): the helpers are public with non-blocking methods, reached through ServerSession/TeamspeakConnection getters; 30 forwarders gone, and what they added (stop-at-first-refusal loops, log lines, description refresh, own avatar flag) moved into the helpers. Swing dialogs still take the whole connection for the model and our ids (item 5)
4d … our own state (mic, speakers, away, talk request, recording) out of the connection done (9107bdd): OwnClient owns the devices and our flags, and publishes them; Recording the recorder. ServerSession no longer keeps its own copy of the flags, and they are cleared when a connect starts rather than once it is done
5 Two front doors: frontends use both ServerSession and session.connection() with no rule for which done (de42429): connection() is gone; frontends reach the model, our ids, devices and the helpers through ServerSession. New helpers took the remaining actions off the connection: ClientAdmin (move, kick, ban, groups, talk power, poke, details), ChannelFiles, ClientContacts; ChannelAdmin also joins, moves and subscribes. Dialogs take the session, or only the helper they use
6 Menu bar, toolbar and hotkeys each implement the same commands: MainMenuBar.Listener (~50 methods, ~210 lines of forwarding in MainFrame), MainToolbar.Listener, HotkeyActions done (f7cf040): MainCommands holds each command once, acting on the server on screen or, for hotkeys, on a list of sessions; the menu, toolbar and hotkeys call it directly and both Listener interfaces are gone. The menu's mute items no longer click the toolbar's buttons, and the menu's commander toggle now repaints the toolbar and tray
7 The admin list dialogs (bans, complaints, offline messages, privilege keys, server log) repeat the load/status/table-model scaffolding done (e214f21): the five extend AbstractServerListDialog, which lays out the toolbar, list, status line and Reload/Close, follows the server's name, binds F5/Ctrl+W/Escape, guards loading, reloads after a change and reports its failure; ServerTab keeps them in one map. All five now take F5, show load failures in red, and keep the status line's height; the ban list's own placeholder field is FlatLaf's. The table models stay per dialog: their rows and columns share nothing
8 Settings: 58 public fields, each key spelled twice (load and save), no change notification, so callers fan changes out by hand done (203082d): each value is a Setting<T> (get/set, listeners), declared once with its key, type and range, and loaded and saved from that list. Output device, volume and receive buffer reach every connection, and the status bar and master volume slider follow their toggles, through listeners instead of calls at each place that changes them; Android puts output settings and country flags into effect the same way. SplitRatio takes the setting itself. The sections with their own load/store (row colours, server log, notifications, contact defaults) are unchanged. The Playback page now previews the voice volume with the master volume applied, as Apply sets it
9 Duplicates: three byte-size formatters (FileBrowserDialog, ChatHtml, ConnectionStatsFormat); four "which chat" enums (ChatScope, ChatLogScope, ChatPanel.Target, Android ChatKey); the conversation model lives in each frontend done, in sub-steps:
9a … byte-size formatters done (5358599): text.ByteSize writes sizes and rates as TeamSpeak does (1023 Bytes, 353.98 KiB); chat attachments and the file browser now use it too, so they show KiB/MiB with two decimals
9b … "which chat" enums done (5358599): one chat.ChatScope replaces ConnectionListener.ChatScope, ChatLogScope and ChatPanel.Target, and the mappings between them are gone. Android's ChatKey also carries the peer, so it goes with the conversation model
9c … the conversation model (Swing ChatPanel.Tab, Android Chats) done: session.ChatFeed decides which conversation a message, history or server event goes to and renders it, and the frontends get the lines through chat.ChatSink (ServerSession.Listener no longer passes on raw chat events). chat.ChatKey replaces Android's own key and ChatPanel's scope and client id. Each frontend still keeps and draws the lines its own way. Fixes Swing labelling our messages with the global nickname instead of the one we have on the server, and linking our name in a private chat to the peer
10 Android ServerScreen: one 456-line composable holding ~25 pieces of state open
11 Android SessionController (669 lines) is the app-wide view model and service locator; every screen gets all of it open
12 Swing ui package: 118 files, flat open
13 ClientEntry/ChannelNode are bags of public volatile fields; a reader can see a half-applied update open
14 Core produces English UI copy (status lines, log lines) open