compose-rust 0.0.11

Declarative UI in Rust, rendered by an AOT-compiled Compose Multiplatform engine.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
package dev.darkpyonix.composerust.ui.platform

import dev.darkpyonix.composerust.protocol.FileDelivery
import dev.darkpyonix.composerust.protocol.FileDialogKind
import dev.darkpyonix.composerust.protocol.FileDialogStatus
import dev.darkpyonix.composerust.protocol.HostEvent
import dev.darkpyonix.composerust.protocol.Mutation
import dev.darkpyonix.composerust.runtime.EventDispatcher
import kotlinx.coroutines.channels.Channel

/** The limits a request and its answer are held to. */
object FileDialogLimits {
    /** Filters kept from one request; the rest are dropped. */
    const val MAX_FILTERS = 16

    /** Extensions kept from one filter; the rest are dropped. */
    const val MAX_EXTENSIONS = 32

    /** Paths one answer may carry. More is not delivered as a shorter list: it is unavailable. */
    const val MAX_PATHS = 10_000

    /**
     * Bytes of paths one answer may carry, separators included.
     *
     * Half of what the largest event buffer the desktop connection will grow to, so the
     * record around the paths always fits. A platform with a smaller buffer sets a smaller
     * limit on its [FileDialogCenter].
     */
    const val MAX_PAYLOAD_BYTES = 32 * 1024 * 1024
}

/** One filter of a dialog: what the user sees, and the extensions it lets through. */
data class FileDialogFilter(
    val label: String,
    /** Lower case, without a leading dot or `*.`. Empty means every file. */
    val extensions: List<String>,
)

/**
 * One dialog, as a platform is asked to show it, after the request was checked and
 * normalised.
 *
 * [windowNode] is the `Window` node the dialog belongs to, or 0 for the implicit root
 * window. [name] is a bare file name, and only a save dialog has one. [filters] is empty for
 * the folder kinds. [defaultFilter] is a position inside [filters], or 0.
 */
data class FileDialogSpec(
    val request: Int,
    val windowNode: Int,
    val kind: FileDialogKind,
    val title: String,
    val directory: String,
    val name: String,
    val filters: List<FileDialogFilter>,
    val defaultFilter: Int,
    /**
     * For each entry of [filters], its position in the list the Host sent. A filter dropped
     * on the way makes this differ from the identity; the result's `filter` is mapped back
     * through it. Empty means the identity.
     */
    val sentPositions: List<Int> = emptyList(),
)

/**
 * One path a dialog returned. A platform that hands over text passes [Text]; one whose paths
 * are bytes (a Linux file system does not promise UTF-8) passes [Bytes]. One that is not UTF-8
 * makes the whole choice unavailable.
 */
sealed interface FileDialogPath {
    class Text(val value: String) : FileDialogPath
    class Bytes(val value: ByteArray) : FileDialogPath
}

/** How a platform's dialog ended. */
sealed interface FileDialogOutcome {
    /**
     * The user chose. [filter] is the position of the filter that was selected, or null when
     * the dialog had none.
     */
    class Chosen(val paths: List<FileDialogPath>, val filter: Int? = null) : FileDialogOutcome {
        companion object {
            fun ofText(paths: List<String>, filter: Int? = null): Chosen =
                Chosen(paths.map { FileDialogPath.Text(it) }, filter)
        }
    }

    /**
     * The user chose, on a platform with no paths: the platform holds a handle for each
     * entry of [files], numbered [firstHandle], [firstHandle] + 1 and so on, and the Host is
     * told their names. [filter] is as for [Chosen].
     */
    class Handles(
        val delivery: FileDelivery,
        val firstHandle: Int,
        val files: List<HeldFile>,
        val filter: Int? = null,
    ) : FileDialogOutcome

    /** The user closed the dialog. */
    data object Cancelled : FileDialogOutcome

    /** The dialog could not be shown. */
    data object Unavailable : FileDialogOutcome
}

/**
 * One platform's file dialogs.
 *
 * [show] is called on the UI thread and must return without waiting for the user. The
 * outcome goes to [onResult], from whichever thread the platform answers on, once. Calling
 * it again is harmless: only the first counts.
 */
interface FileDialogPlatform {
    /**
     * Shows [request] on [window], the handle for the window it belongs to. The handle is
     * whatever [FileDialogCenter.windowResolver] gave for the request's window node, and is
     * null for the implicit root window or when nothing resolves one.
     */
    fun show(window: Any?, request: FileDialogSpec, onResult: (FileDialogOutcome) -> Unit)

    /**
     * The window a dialog was shown on is going away. The platform closes that window's
     * dialog if it has one open. The request ends with a cancel whether or not it does.
     */
    fun cancelWindow(window: Any?) {}

    /**
     * The handles a [FileDialogOutcome.Handles] numbered were never delivered (the answer did
     * not fit, or a name could not travel), so nothing will ever name them. A platform that
     * holds handles lets go of them.
     */
    fun discardHandles(firstHandle: Int, count: Int) {}
}

/**
 * A platform with no file dialog yet, or a run that cannot show one. Every request is
 * answered at once with [FileDialogOutcome.Unavailable]; that is not a protocol error.
 */
object UnsupportedFileDialogs : FileDialogPlatform {
    override fun show(window: Any?, request: FileDialogSpec, onResult: (FileDialogOutcome) -> Unit) =
        onResult(FileDialogOutcome.Unavailable)
}

/**
 * The file dialogs this process uses.
 *
 * Installed by each platform's entry point before the Host starts, the way the notification
 * centre is. A run nobody installed anything for answers every request as unavailable.
 */
object FileDialogs {
    var platform: FileDialogPlatform = UnsupportedFileDialogs

    /**
     * The largest event this process can hand the Host, record and strings together. A
     * connection whose event buffer stops growing at a known size (the web's, at the largest
     * buffer its Host lends) sets it, and an answer that would not fit is unavailable rather
     * than cut short.
     */
    var maxEventBytes: Int = Int.MAX_VALUE
}

/**
 * What the interpreter does with file dialog requests, and the one route the answers take
 * back to the Host.
 *
 * It owns the rules that do not depend on a platform: a request number waits for one answer
 * only, requests on one window are shown one after the other in the order they came, a
 * window that goes away ends its dialog with a cancel, and an answer is delivered on the UI
 * thread inside a frame, whole or not at all. The platform underneath only shows and reports.
 */
class FileDialogCenter(
    private val platform: FileDialogPlatform = FileDialogs.platform,
    private val maxPayloadBytes: Int = FileDialogLimits.MAX_PAYLOAD_BYTES,
    private val maxEventBytes: Int = FileDialogs.maxEventBytes,
) {
    /** What `request` made of the request, for the table to report. */
    enum class Accepted { Accepted, Duplicate, UnknownWindow }

    private class Entry(val spec: FileDialogSpec) {
        /** The platform was asked, or the request is already answered and only waits to be delivered. */
        var started = false

        /** An answer is on its way to being delivered, so nothing else starts on this window yet. */
        var finishing = false
        var handle: Any? = null
    }

    private class Completion(val request: Int, val outcome: FileDialogOutcome)

    /**
     * Answers from the platform, from any thread. A channel because it is the one queue every
     * target can share across threads without a lock of its own, and unlimited because what
     * goes in is a handful of answers.
     */
    private val inbox = Channel<Completion>(Channel.UNLIMITED)

    /** Requests that have not been delivered an answer yet, in the order they came. */
    private val pending = LinkedHashMap<Int, Entry>()

    private var dispatcher: EventDispatcher? = null
    private var draining = false

    /** How an answer asks for the frame that delivers it. */
    var wake: () -> Unit = {}

    /**
     * Gives the platform's handle for a `Window` node, read when the dialog is shown. Node 0
     * has none. The window manager of a multi-window application installs this.
     */
    var windowResolver: (Int) -> Any? = { null }

    /** How many requests are waiting for an answer. */
    internal val pendingCount: Int get() = pending.size

    /**
     * Takes the request, normalised, unless its number is already waiting for an answer.
     *
     * [windowKnown] says whether the window it names is the implicit root or an existing
     * `Window` node. A request on an unknown window is still answered, as unavailable.
     */
    fun request(mutation: Mutation.ShowFileDialog, windowKnown: Boolean): Accepted {
        if (pending.containsKey(mutation.request)) return Accepted.Duplicate
        val entry = Entry(normalize(mutation))
        pending[mutation.request] = entry
        if (!windowKnown) {
            entry.started = true
            entry.finishing = true
            inbox.trySend(Completion(mutation.request, FileDialogOutcome.Unavailable))
            wake()
            return Accepted.UnknownWindow
        }
        wake()
        return Accepted.Accepted
    }

    /**
     * The `Window` node [windowNode] was removed. Its dialog is closed and every request on it
     * ends with one cancel.
     */
    fun windowRemoved(windowNode: Int) {
        if (windowNode == 0) return
        var any = false
        for (entry in pending.values.toList()) {
            if (entry.spec.windowNode != windowNode || entry.finishing) continue
            any = true
            entry.finishing = true
            if (entry.started) platform.cancelWindow(entry.handle)
            inbox.trySend(Completion(entry.spec.request, FileDialogOutcome.Cancelled))
        }
        if (any) wake()
    }

    /** Connects the center to the Host, once its first batch has been applied. */
    fun attach(host: EventDispatcher) {
        dispatcher = host
        drain()
    }

    /** The process is ending. */
    fun shutdown() {
        dispatcher = null
        pending.clear()
        while (inbox.tryReceive().getOrNull() != null) Unit
    }

    /**
     * Starts what may start and hands every answer to the Host, on the UI thread.
     *
     * Called where the Host can be entered: after its start, and at the top of every frame
     * an answer asked for. A request is started here and not where it arrives, because the
     * batch that carried it may also have created the window it belongs to, and the platform
     * window exists only once the batch is through.
     */
    fun drain() {
        val host = dispatcher ?: return
        if (draining) return
        draining = true
        try {
            var progress = true
            while (progress) {
                progress = false
                while (true) {
                    val done = inbox.tryReceive().getOrNull() ?: break
                    // Only the first answer to a request counts; a second finds nothing waiting.
                    val entry = pending.remove(done.request) ?: continue
                    progress = true
                    host.dispatch(resultEvent(entry.spec, done.outcome))
                }
                for (entry in pending.values.toList()) {
                    if (entry.started || entry.finishing) continue
                    if (pending.values.any { it !== entry && it.spec.windowNode == entry.spec.windowNode && (it.started || it.finishing) }) continue
                    start(entry)
                    progress = true
                }
            }
        } finally {
            draining = false
        }
    }

    private fun start(entry: Entry) {
        entry.started = true
        val request = entry.spec.request
        val handle = windowResolver(entry.spec.windowNode)
        entry.handle = handle
        try {
            platform.show(handle, entry.spec) { outcome ->
                inbox.trySend(Completion(request, outcome))
                wake()
            }
        } catch (failure: Exception) {
            // A platform that throws has no dialog to show, which is the same answer.
            inbox.trySend(Completion(request, FileDialogOutcome.Unavailable))
        }
    }

    private fun resultEvent(spec: FileDialogSpec, outcome: FileDialogOutcome): HostEvent {
        val none = -1
        if (outcome is FileDialogOutcome.Handles) return handlesResult(spec, outcome)
        return when (val checked = judge(outcome)) {
            is Checked.Paths -> HostEvent.FileDialogResult(
                nodeId = 0,
                handlerId = 0,
                request = spec.request,
                status = FileDialogStatus.Chosen,
                // The platform answers with a position in the cleaned list; the Host is told the
                // position in the list it sent.
                filter = checked.filter
                    ?.takeIf { chosen -> chosen in spec.filters.indices }
                    ?.let { chosen -> spec.sentPositions.getOrElse(chosen) { chosen } }
                    ?: none,
                paths = checked.joined,
            )
            is Checked.Ended -> HostEvent.FileDialogResult(
                nodeId = 0,
                handlerId = 0,
                request = spec.request,
                status = checked.status,
                filter = none,
                paths = "",
            )
        }
    }

    /**
     * A choice on a platform with no paths, as a `FileHandles` event, or as an unavailable
     * result when it cannot be delivered whole: more files than one answer may carry, a name
     * that cannot travel, or more bytes than the event buffer holds. The handles of an answer
     * that is not delivered are let go of, because nothing will ever name them.
     */
    private fun handlesResult(spec: FileDialogSpec, outcome: FileDialogOutcome.Handles): HostEvent {
        val ended = { status: FileDialogStatus ->
            platform.discardHandles(outcome.firstHandle, outcome.files.size)
            HostEvent.FileDialogResult(0, 0, spec.request, status, -1, "")
        }
        if (outcome.files.isEmpty()) return ended(FileDialogStatus.Cancelled)
        if (outcome.files.size > FileDialogLimits.MAX_PATHS) return ended(FileDialogStatus.Unavailable)
        val filter = outcome.filter
            ?.takeIf { chosen -> chosen in spec.filters.indices }
            ?.let { chosen -> spec.sentPositions.getOrElse(chosen) { chosen } }
            ?: -1
        val event = FileCallCenter.handlesEvent(spec.request, outcome.delivery, outcome.firstHandle, outcome.files, filter)
            ?: return ended(FileDialogStatus.Unavailable)
        val size = FileCallCenter.encodedSize(event)
        if (size > maxEventBytes || size > maxPayloadBytes) return ended(FileDialogStatus.Unavailable)
        return event
    }

    private sealed interface Checked {
        class Paths(val joined: String, val filter: Int?) : Checked
        class Ended(val status: FileDialogStatus) : Checked
    }

    /**
     * What the Host is told about an outcome.
     *
     * A path that is not well formed text makes the whole choice unavailable: the other paths
     * are not sent either, because the application could not tell that the list is shorter
     * than what the user picked, and a cancel would be false. A choice with too many paths, or too many bytes of them, is
     * unavailable too, never a shorter list: the application would not know it was short.
     */
    private fun judge(outcome: FileDialogOutcome): Checked = when (outcome) {
        FileDialogOutcome.Cancelled -> Checked.Ended(FileDialogStatus.Cancelled)
        FileDialogOutcome.Unavailable -> Checked.Ended(FileDialogStatus.Unavailable)
        // Answered by handlesResult before it gets here.
        is FileDialogOutcome.Handles -> Checked.Ended(FileDialogStatus.Unavailable)
        is FileDialogOutcome.Chosen -> when {
            outcome.paths.isEmpty() -> Checked.Ended(FileDialogStatus.Cancelled)
            outcome.paths.size > FileDialogLimits.MAX_PATHS -> Checked.Ended(FileDialogStatus.Unavailable)
            else -> {
                val checked = outcome.paths.map { wellFormedPath(it) }
                val texts = checked.filterNotNull()
                when {
                    texts.size != checked.size -> Checked.Ended(FileDialogStatus.Unavailable)
                    texts.sumOf { it.encodeToByteArray().size.toLong() + 1L } > maxPayloadBytes.toLong() ->
                        Checked.Ended(FileDialogStatus.Unavailable)
                    // The record in front of the paths, and the paths, in a buffer that does not grow.
                    texts.sumOf { it.encodeToByteArray().size.toLong() + 1L } - 1L + FILE_DIALOG_RESULT_RECORD_BYTES >
                        maxEventBytes.toLong() -> Checked.Ended(FileDialogStatus.Unavailable)
                    else -> Checked.Paths(texts.joinToString("\u0000"), outcome.filter)
                }
            }
        }
    }

    companion object {
        /** `FileDialogResult`'s record in front of the paths it carries. */
        private const val FILE_DIALOG_RESULT_RECORD_BYTES = 36L

        /**
         * Checks a request and puts it in the form a platform can rely on: filters and
         * extensions within their limits, extensions lower case without a leading dot or
         * `*.`, a default filter that exists, a bare file name, and nothing in the fields a
         * kind does not use.
         */
        fun normalize(mutation: Mutation.ShowFileDialog): FileDialogSpec {
            val folders = mutation.kind == FileDialogKind.OpenFolder || mutation.kind == FileDialogKind.OpenFolders
            val parsed = if (folders) emptyList() else parseFilters(mutation.filters)
            val filters = parsed.map { it.second }
            val name = if (mutation.kind == FileDialogKind.Save) {
                mutation.name.substringAfterLast('/').substringAfterLast('\\')
            } else {
                ""
            }
            return FileDialogSpec(
                request = mutation.request,
                windowNode = mutation.window,
                kind = mutation.kind,
                title = mutation.title,
                directory = mutation.directory,
                name = name,
                filters = filters,
                // The default is a position in the list the Host sent, so it follows its filter
                // when an earlier one was dropped.
                defaultFilter = parsed.indexOfFirst { it.first == mutation.defaultFilter }.takeIf { it >= 0 } ?: 0,
                sentPositions = parsed.map { it.first },
            )
        }

        private fun parseFilters(encoded: String): List<Pair<Int, FileDialogFilter>> {
            if (encoded.isEmpty()) return emptyList()
            // Label, extensions, label, extensions. A label with nothing after it lets every
            // file through, like one with no extensions.
            val parts = encoded.split('\u0000')
            val filters = ArrayList<Pair<Int, FileDialogFilter>>()
            var index = 0
            var position = 0
            while (index < parts.size && position < FileDialogLimits.MAX_FILTERS) {
                val named = (parts.getOrNull(index + 1) ?: "").split(',').filter { it.isNotBlank() }
                val extensions = named
                    .map { it.trim().removePrefix("*.").removePrefix(".").lowercase() }
                    .filter { it.isNotEmpty() }
                    .take(FileDialogLimits.MAX_EXTENSIONS)
                // A filter that names extensions and keeps none of them (a lone ".") would
                // otherwise mean every file, the opposite of what it asked for.
                if (named.isEmpty() || extensions.isNotEmpty()) {
                    filters += position to FileDialogFilter(parts[index], extensions)
                }
                position++
                index += 2
            }
            return filters
        }

        /** The path as text, or null for one that is empty, holds a NUL, or is not valid Unicode text. */
        private fun wellFormedPath(path: FileDialogPath): String? {
            val text = when (path) {
                is FileDialogPath.Text -> path.value
                is FileDialogPath.Bytes -> try {
                    path.value.decodeToString(throwOnInvalidSequence = true)
                } catch (failure: Exception) {
                    return null
                }
            }
            if (text.isEmpty()) return null
            var index = 0
            while (index < text.length) {
                val unit = text[index]
                when {
                    unit == '\u0000' -> return null
                    unit.isHighSurrogate() -> {
                        if (index + 1 >= text.length || !text[index + 1].isLowSurrogate()) return null
                        index++
                    }
                    unit.isLowSurrogate() -> return null
                }
                index++
            }
            return text
        }
    }
}