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
@@ -0,0 +1,19 @@
package eu.lixko.ts3j.client.android
import eu.lixko.ts3j.client.net.RequestException
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.future.await
import java.util.concurrent.CompletableFuture
/** A server request's outcome, failing with its [RequestException]. */
internal suspend fun <T> CompletableFuture<T>.result(): Result<T> =
try {
Result.success(await())
} catch (e: CancellationException) {
throw e
} catch (e: Exception) {
Result.failure(RequestException.of(e))
}
/** The same for a request with no result. */
internal suspend fun CompletableFuture<Void>.done(): Result<Unit> = result().map { }
@@ -10,6 +10,7 @@ import eu.lixko.ts3j.client.net.ChannelSettings
import eu.lixko.ts3j.client.net.ConnectionStats
import eu.lixko.ts3j.client.net.Details
import eu.lixko.ts3j.client.net.GroupChoice
import eu.lixko.ts3j.client.net.RequestException
import eu.lixko.ts3j.client.net.Whisper
import eu.lixko.ts3j.client.net.ban.BanEntry
import eu.lixko.ts3j.client.net.ban.BanRule
@@ -249,24 +250,17 @@ class ServerController internal constructor(
if (channelId > 0) conn.model.siblingsOf(channelId) else conn.model.childrenOf(parentId)
/** A channel's editable properties as the server has them. */
suspend fun channelSettings(channelId: Int): Result<ChannelSettings> = suspendCoroutine { done ->
conn.requestChannelSettings(channelId) { settings, error ->
done.resume(if (error == null) Result.success(settings) else Result.failure(IllegalStateException(error)))
}
}
suspend fun channelSettings(channelId: Int): Result<ChannelSettings> = conn.requestChannelSettings(channelId).result()
/** Each of these answers null once done, else why not. */
suspend fun editChannel(channelId: Int, changes: Map<String, String>): String? =
if (changes.isEmpty()) null
else suspendCoroutine { done -> conn.applyChannelEdit(channelId, changes, emptyMap(), emptyList()) { done.resume(it) } }
suspend fun editChannel(channelId: Int, changes: Map<String, String>): Result<Unit> =
if (changes.isEmpty()) Result.success(Unit)
else conn.applyChannelEdit(channelId, changes, emptyMap(), emptyList()).done()
suspend fun createChannel(parentId: Int, settings: ChannelSettings): String? = suspendCoroutine { done ->
conn.createChannel(parentId, settings.creationParameters(), emptyMap()) { _, error -> done.resume(error) }
}
suspend fun createChannel(parentId: Int, settings: ChannelSettings): Result<Unit> =
conn.createChannel(parentId, settings.creationParameters(), emptyMap()).result().map { }
/** Deletes a channel, with its sub-channels and the clients in it moved out. */
suspend fun deleteChannel(channelId: Int): String? =
suspendCoroutine { done -> conn.deleteChannel(channelId, true) { done.resume(it) } }
suspend fun deleteChannel(channelId: Int): Result<Unit> = conn.deleteChannel(channelId, true).done()
// ---- files ----
@@ -276,19 +270,16 @@ class ServerController internal constructor(
suspend fun listFiles(channelId: Int, password: String, path: String): Result<List<RemoteFile>> =
withContext(Dispatchers.IO) { runCatching { conn.listFiles(channelId, password, path) } }
/** Each of these answers null once done, else why not. */
suspend fun createDirectory(channelId: Int, password: String, path: String): String? =
suspend fun createDirectory(channelId: Int, password: String, path: String): Result<Unit> =
fileCall { conn.createDirectory(channelId, password, path) }
suspend fun deleteFile(channelId: Int, password: String, path: String): String? =
suspend fun deleteFile(channelId: Int, password: String, path: String): Result<Unit> =
fileCall { conn.deleteFile(channelId, password, path) }
suspend fun renameFile(channelId: Int, password: String, from: String, to: String): String? =
suspend fun renameFile(channelId: Int, password: String, from: String, to: String): Result<Unit> =
fileCall { conn.renameFile(channelId, password, from, to) }
private suspend fun fileCall(call: () -> Unit): String? = withContext(Dispatchers.IO) {
runCatching(call).exceptionOrNull()?.let { it.message ?: it.javaClass.simpleName }
}
private suspend fun fileCall(call: () -> Unit): Result<Unit> = withContext(Dispatchers.IO) { runCatching(call) }
// ---- moderation ----
@@ -340,26 +331,19 @@ class ServerController internal constructor(
// ---- ban list ----
/** The server's bans, or why they could not be read. */
/** One reading of a client's connection figures, or null when not connected. */
suspend fun connectionStats(clientId: Int): ConnectionStats? =
if (!session.isConnected) null
else suspendCoroutine { done -> conn.requestConnectionInfo(clientId) { done.resume(it) } }
suspend fun banList(): Result<List<BanEntry>> = suspendCoroutine { done ->
conn.requestBanList { bans, error ->
done.resume(if (error == null) Result.success(bans) else Result.failure(IllegalStateException(error)))
}
}
/** The server's bans, or why they could not be read. */
suspend fun banList(): Result<List<BanEntry>> = conn.requestBanList().result()
/** Each of these answers null once done, else why not. */
suspend fun addBan(rule: BanRule): String? = suspendCoroutine { done -> conn.addBan(rule) { done.resume(it) } }
suspend fun addBan(rule: BanRule): Result<Unit> = conn.addBan(rule).done()
suspend fun replaceBan(banId: Int, rule: BanRule): String? =
suspendCoroutine { done -> conn.replaceBan(banId, rule) { done.resume(it) } }
suspend fun replaceBan(banId: Int, rule: BanRule): Result<Unit> = conn.replaceBan(banId, rule).done()
suspend fun deleteBans(banIds: Collection<Int>): String? =
suspendCoroutine { done -> conn.deleteBans(banIds) { done.resume(it) } }
suspend fun deleteBans(banIds: Collection<Int>): Result<Unit> = conn.deleteBans(banIds).done()
fun canDeleteBans(bans: Collection<BanEntry>): Boolean = conn.model.canDeleteBans(bans, conn.selfUniqueId)
@@ -367,14 +351,14 @@ class ServerController internal constructor(
fun isOwnBan(ban: BanEntry): Boolean = ban.createdBy(conn.selfUniqueId)
/** Uploads [data] as our avatar; null once it is set, else why not. */
suspend fun setAvatar(data: ByteArray): String? {
if (!session.isConnected) return "Not connected"
/** Uploads [data] as our avatar. */
suspend fun setAvatar(data: ByteArray): Result<Unit> {
if (!session.isConnected) return Result.failure(RequestException.notConnected())
val file = withContext(Dispatchers.IO) {
File.createTempFile("avatar", null, app.cacheDir).apply { writeBytes(data) }
}
return try {
suspendCoroutine { done -> conn.setAvatar(file) { done.resume(it) } }
conn.setAvatar(file).done()
} finally {
file.delete()
}
@@ -92,10 +92,9 @@ fun BanListScreen(server: ServerController, presets: BanReasonPresets, onBack: (
}
/** Reports a failed change, or re-reads the list to show what the server now holds. */
val change = { action: suspend () -> String?, failure: String ->
val change = { action: suspend () -> Result<Unit>, failure: String ->
scope.launch {
val error = action()
if (error != null) snackbar.showSnackbar("$failure: $error")
action().onFailure { snackbar.showSnackbar("$failure: ${it.message}") }
generation++
}
Unit
@@ -83,11 +83,12 @@ fun ChannelEditScreen(server: ServerController, edit: ChannelEdit, onDone: () ->
saving = true
scope.launch {
val trimmed = e.copy().apply { name = name.trim() }
val error = if (creating) server.createChannel(edit.parentId, trimmed)
val saved = if (creating) server.createChannel(edit.parentId, trimmed)
else server.editChannel(edit.channelId, trimmed.changesFrom(o))
saving = false
if (error == null) onDone()
else snackbar.showSnackbar((if (creating) "Could not create the channel: " else "Could not save the channel: ") + error)
saved.onSuccess { onDone() }.onFailure {
snackbar.showSnackbar((if (creating) "Could not create the channel: " else "Could not save the channel: ") + it.message)
}
}
}
@@ -78,10 +78,9 @@ fun FilesScreen(server: ServerController, channelId: Int, channelName: String, p
LaunchedEffect(uploadedHere) { if (uploadedHere > 0) reloads++ }
val tell = { message: String -> scope.launch { snackbar.showSnackbar(message) }; Unit }
val act = { call: suspend () -> String? ->
val act = { call: suspend () -> Result<Unit> ->
scope.launch {
val error = call()
if (error != null) snackbar.showSnackbar(error) else reloads++
call().onSuccess { reloads++ }.onFailure { snackbar.showSnackbar(it.message ?: it.javaClass.simpleName) }
}
Unit
}
@@ -79,8 +79,8 @@ fun PictureViewerHost(server: ServerController, content: @Composable () -> Unit)
PictureViewer(
picture,
onSteal = if (picture.ownAvatar) null else { data ->
val error = server.setAvatar(data)
Toast.makeText(context, error ?: "Avatar set.", Toast.LENGTH_SHORT).show()
val message = server.setAvatar(data).fold({ "Avatar set." }, { it.message })
Toast.makeText(context, message, Toast.LENGTH_SHORT).show()
},
onDismiss = { viewed = null },
)
@@ -551,7 +551,7 @@ fun ServerScreen(
confirmButton = {
TextButton(onClick = {
deletingChannel = null
scope.launch { server.deleteChannel(id)?.let { snackbar.showSnackbar("Could not delete the channel: $it") } }
scope.launch { server.deleteChannel(id).onFailure { snackbar.showSnackbar("Could not delete the channel: ${it.message}") } }
}) { Text("Delete") }
},
dismissButton = { TextButton(onClick = { deletingChannel = null }) { Text("Cancel") } },