Requests return futures that fail with a typed RequestException

Server requests on TeamspeakConnection took callbacks given a value and an
error string, null on success, so frontends told a permission refusal from
other failures by the message's wording (ban list, server log) and core
needed a sentinel message for a refused search. They now return a
CompletableFuture that fails with a RequestException carrying the kind
(not connected, permission, failed) and the server's reason.

Replies hands the outcome to a success or a failure handler on a given
executor; Swing's Edt runs them on the event thread, so call sites no
longer marshal by hand. Android's ServerController, whose suspend calls
answered a String? that was null once done, returns Result instead.
lookupDatabaseClient answers an Optional rather than null.

Starts the structural audit in AUDIT-STRUCTURE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-11 16:25:07 +00:00
co-authored by Claude Opus 5.5
parent 985c54a362
commit 0552ed8be6
27 changed files with 566 additions and 480 deletions
+24
View File
@@ -0,0 +1,24 @@
# Structural audit — ts3-client and Android
Audit: 2026-10-11. Design and maintainability (DRY, SOLID, separation of concerns); the
correctness audit is [AUDIT.md](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: 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` | open |
| 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` | open |
| 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 | open |
| 5 | Two front doors: frontends use both `ServerSession` and `session.connection()` with no rule for which | open |
| 6 | Menu bar, toolbar and hotkeys each implement the same commands: `MainMenuBar.Listener` (~50 methods, ~210 lines of forwarding in `MainFrame`), `MainToolbar.Listener`, `HotkeyActions` | open |
| 7 | The admin list dialogs (bans, complaints, offline messages, privilege keys, server log) repeat the load/status/table-model scaffolding | open |
| 8 | `Settings`: 58 public fields, each key spelled twice (load and save), no change notification, so callers fan changes out by hand | open |
| 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 | open |
| 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 |