@pictor-sdk/video-android 0.1.0

package/android/src/main/java/dev/pictor/video/GateDestination.kt

@@ -0,0 +1,445 @@
+package dev.pictor.video
+
+import android.media.MediaExtractor
+import android.media.MediaFormat
+import android.system.ErrnoException
+import android.system.Os
+import android.system.OsConstants
+import org.json.JSONObject
+import java.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+
+/**
+ * Getting the finished file where the caller asked for it, or not at all.
+ *
+ * ## Why this is not a copy
+ *
+ * A destination that is written in place is visible while it is half-written. A
+ * player that opens it sees a truncated container; a gallery scanner indexes a
+ * file that will change under it; a failure at 90% leaves something that looks
+ * like a video and is not one. So the bytes go to a staging file **in the
+ * destination's own directory** — same filesystem, so the last step can be a
+ * rename — and the target only ever appears complete.
+ *
+ * ## Why the existence check is not the guard
+ *
+ * `if (!target.exists()) write(target)` is two operations with a gap in it, and
+ * something else can create the target inside that gap. The preflight check
+ * remains, but only so a doomed export can be refused before it encodes for
+ * eight seconds — it is a courtesy, not the guarantee.
+ *
+ * The guarantee is `renameat2(RENAME_NOREPLACE)`: one syscall that either
+ * publishes the complete staging file or reports `EEXIST`. Race-safe and
+ * crash-safe, because there is no state between those outcomes for a process
+ * death to land in. `link(2)` is tried second, for filesystems that predate it.
+ *
+ * `O_CREAT | O_EXCL` followed by a rename is **not** a fallback, though it is
+ * race-safe and was one for a while. It is two operations, and a process that
+ * dies between them leaves a zero-byte file that nothing can distinguish from a
+ * destination somebody meant to create — so it blocks every later
+ * `overwrite: false` export to that path until a human deletes it. Offering it
+ * silently would mean the contract said atomic while the behaviour was not.
+ * When no atomic create-if-absent exists, the export is refused and says so.
+ *
+ * ## Why replacement is a single rename
+ *
+ * `rename(2)` over an existing path is atomic: the old contents are there until
+ * the instant the new ones are, and nothing observes a gap. Moving the old file
+ * aside first would be strictly worse — two atomic steps with a window between
+ * them where the destination does not exist at all.
+ *
+ * ## Paths do not appear in errors
+ *
+ * Every reason names the file and nothing above it. A message that quotes a
+ * directory puts it in a log, a crash report and whatever the host displays.
+ */
+internal object GateDestination {
+
+    init {
+        // The same library the presentation surface lives in. Loading it here
+        // as well is idempotent, and means publication does not depend on the
+        // module having been constructed first.
+        runCatching { System.loadLibrary("pictor_video") }
+    }
+
+    /**
+     * `renameat2(RENAME_NOREPLACE)`: publish, or `EEXIST`. Nothing in between.
+     *
+     * Returns 0 or an errno. `ENOSYS` is a kernel with no such call; `EINVAL` is
+     * a kernel that has it and a filesystem that will not take the flag.
+     */
+    private external fun nativeRenameNoReplace(from: String, to: String): Int
+
+    /** Gate-only: pretend the syscall is missing, to exercise the refusal. */
+    @Volatile var pretendNoAtomicNoReplace: Boolean = false
+
+    /**
+     * Gate-only: use the pre-`renameat2` claim-then-rename sequence.
+     *
+     * Kept solely so the window it has can still be demonstrated. It is not a
+     * fallback — see `publish`.
+     */
+    @Volatile var legacyPlaceholderPublish: Boolean = false
+
+    /** Gate-only: run between the claim and the rename, to simulate a crash. */
+    @Volatile var betweenClaimAndRename: (() -> Unit)? = null
+
+    /** Gate-only: die inside the copy, which is the only window left. */
+    @Volatile var killDuringCopy: Boolean = false
+
+    /** The last segment. Directories are the private part. */
+    fun describe(path: String): String {
+        val trimmed = path.trimEnd('/')
+        val name = trimmed.substringAfterLast('/')
+        return if (name.isEmpty()) "(unnamed)" else name
+    }
+
+    /** Parsed from JavaScript, which has already refused every non-`file:` form. */
+    data class Target(val path: String, val overwrite: Boolean)
+
+    fun parse(json: String): Target? {
+        val o = runCatching { JSONObject(json) }.getOrNull() ?: return null
+        if (o.optString("kind") != "file") return null
+        val path = o.optString("path")
+        if (path.isEmpty()) return null
+        return Target(path, o.optBoolean("overwrite", false))
+    }
+
+    /**
+     * Everything knowable before eight seconds of encoding.
+     *
+     * Not the guarantee — the directory can be unmounted and the target created
+     * while the export runs — but the difference between failing now and failing
+     * after the work.
+     */
+    fun validate(target: Target): String? {
+        val file = File(target.path)
+        val name = describe(target.path)
+        val parent = file.parentFile
+            ?: return "the destination '$name' has no directory to write into"
+        if (!parent.exists()) return "the directory for '$name' does not exist"
+        if (!parent.isDirectory) return "the destination for '$name' is not a directory"
+        if (!parent.canWrite()) return "the directory for '$name' is not writable"
+        if (file.isDirectory) return "the destination '$name' is an existing directory"
+        if (file.exists() && !target.overwrite) {
+            return "'$name' already exists; pass overwrite to replace it"
+        }
+        return null
+    }
+
+    /** What a finished container has to be before anyone is told it is done. */
+    fun probe(path: String): JSONObject {
+        val result = JSONObject()
+        var extractor: MediaExtractor? = null
+        try {
+            val file = File(path)
+            val bytes = if (file.exists()) file.length() else 0L
+            extractor = MediaExtractor()
+            extractor.setDataSource(path)
+            var video = false
+            var audio = false
+            var durationUs = 0L
+            for (i in 0 until extractor.trackCount) {
+                val format = extractor.getTrackFormat(i)
+                val mime = format.getString(MediaFormat.KEY_MIME) ?: ""
+                if (mime.startsWith("video/")) video = true
+                if (mime.startsWith("audio/")) audio = true
+                if (format.containsKey(MediaFormat.KEY_DURATION)) {
+                    durationUs = maxOf(durationUs, format.getLong(MediaFormat.KEY_DURATION))
+                }
+            }
+            result.put("readable", bytes > 0 && video)
+                .put("bytes", bytes)
+                .put("tracks", extractor.trackCount)
+                .put("hasVideo", video)
+                .put("hasAudio", audio)
+                .put("durationUs", durationUs)
+        } catch (e: Exception) {
+            result.put("readable", false).put("error", e.javaClass.simpleName)
+        } finally {
+            runCatching { extractor?.release() }
+        }
+        return result
+    }
+
+    /**
+     * Gate-only: try the primitive here, and report what happened.
+     *
+     * Answered by performing it in the directory an export would publish into,
+     * rather than inferred from an API level. Whether the kernel has the call
+     * and whether *this mount* accepts the flag are different questions, and
+     * only the second one decides anything.
+     */
+    fun probeNoReplace(directory: File): JSONObject {
+        val a = File(directory, ".pictor-probe-a.tmp")
+        val b = File(directory, ".pictor-probe-b.tmp")
+        val result = JSONObject()
+        try {
+            runCatching { a.writeText("probe") }
+            runCatching { b.delete() }
+            val fresh = runCatching { nativeRenameNoReplace(a.absolutePath, b.absolutePath) }
+                .getOrDefault(OsConstants.ENOSYS)
+            result.put("renameat2Fresh", fresh).put("freshName", errnoName(fresh))
+            // And again, onto a name that now exists: EEXIST is the whole point.
+            runCatching { a.writeText("probe") }
+            val onto = runCatching { nativeRenameNoReplace(a.absolutePath, b.absolutePath) }
+                .getOrDefault(OsConstants.ENOSYS)
+            result.put("renameat2Existing", onto).put("existingName", errnoName(onto))
+            result.put("supported", fresh == 0 && onto == OsConstants.EEXIST)
+            val linked = try {
+                runCatching { b.delete() }
+                Os.link(a.absolutePath, b.absolutePath)
+                0
+            } catch (e: ErrnoException) {
+                e.errno
+            }
+            result.put("link", linked).put("linkName", errnoName(linked))
+        } finally {
+            runCatching { a.delete() }
+            runCatching { b.delete() }
+        }
+        return result
+    }
+
+    /** A staging name in the destination's directory, so publication is a rename. */
+    fun stagingFor(target: Target, unique: Long): File =
+        File(File(target.path).parentFile, ".pictor-staging-$unique.tmp")
+
+    /**
+     * Remove staging files a previous run did not.
+     *
+     * They live in the destination's directory, not the cache, so the temporary
+     * sweep never sees them — and a process killed mid-publication leaves one
+     * the size of the whole export. Measured after a deliberate kill: a 159 597
+     * byte orphan that nothing was ever going to collect.
+     *
+     * Safe to do unconditionally because the module runs one export per process
+     * and the directory is the app's own: any staging file present is from a run
+     * that is no longer happening.
+     */
+    fun sweepStaging(target: Target): Int {
+        val parent = File(target.path).parentFile ?: return 0
+        val stale = parent.listFiles { f ->
+            f.name.startsWith(".pictor-staging-") && f.name.endsWith(".tmp")
+        } ?: return 0
+        return stale.count { runCatching { it.delete() }.getOrDefault(false) }
+    }
+
+    /**
+     * Copy, flush, close.
+     *
+     * `sync()` before close because a rename can be durable while the bytes it
+     * points at are not: the metadata operation and the data are ordered
+     * separately, and a device that loses power between them publishes a
+     * complete-looking file full of nothing.
+     *
+     * Returns an error reason, or `null`. Beats as it goes, and stops when
+     * `keepGoing` says the job was cancelled.
+     */
+    fun stage(
+        source: File,
+        staging: File,
+        keepGoing: () -> Boolean,
+        beatEpoch: Long,
+        /** Gate-only: hold inside the copy so a cancel can land in it. */
+        hold: Boolean = false,
+    ): String? {
+        val name = describe(staging.absolutePath)
+        try {
+            FileInputStream(source).use { input ->
+                FileOutputStream(staging).use { output ->
+                    val buffer = ByteArray(256 * 1024)
+                    while (true) {
+                        if (!keepGoing()) return "cancelled"
+                        val read = input.read(buffer)
+                        if (read <= 0) break
+                        output.write(buffer, 0, read)
+                        if (killDuringCopy) {
+                            // The only window the settled design has: a crash
+                            // here leaves a staging file and no target at all.
+                            android.os.Process.killProcess(android.os.Process.myPid())
+                        }
+                        if (hold) {
+                            // A deterministic hold, not a sleep and a hope: the
+                            // copy of a two-second clip is milliseconds, and no
+                            // amount of timing lands a cancel inside it.
+                            while (keepGoing()) Thread.sleep(20)
+                            return "cancelled"
+                        }
+                        // Copying a large file is minutes of work that moves the
+                        // bar by one reserved share. Without this it is silence.
+                        ExportHeartbeat.beat("publishBytes", beatEpoch)
+                    }
+                    output.flush()
+                    output.fd.sync()
+                }
+            }
+        } catch (e: Exception) {
+            return "staging '$name' failed: " + e.javaClass.simpleName
+        }
+        return null
+    }
+
+    /**
+     * The last step, and the only one that makes the target appear.
+     *
+     * Returns an error reason, or `null`. Never leaves the staging file behind
+     * on failure, and never leaves an existing target damaged.
+     */
+    fun publish(staging: File, target: Target): String? {
+        val name = describe(target.path)
+        if (target.overwrite) {
+            /*
+              One rename, not a backup and a rename.
+
+              `rename(2)` replaces atomically: the old contents are readable
+              until the instant the new ones are. Moving the old file aside first
+              would add a window in which the destination does not exist, which
+              is the failure this is supposed to prevent.
+            */
+            return try {
+                Os.rename(staging.absolutePath, target.path)
+                null
+            } catch (e: ErrnoException) {
+                runCatching { staging.delete() }
+                "publishing '$name' failed: " + errnoName(e.errno)
+            }
+        }
+        /*
+          One syscall, because publication has to survive a power cut.
+
+          `renameat2(RENAME_NOREPLACE)` either publishes the complete staging
+          file or reports EEXIST. There is no state between those two outcomes,
+          so a process that dies mid-publication leaves either the old world or
+          the new one — never a claimed-but-empty name that blocks every later
+          export to the same path.
+
+          `link(2)` has the same property and is tried second, because it works
+          on filesystems old enough to predate `renameat2`. It does not work on
+          Android's emulated volume: /storage/emulated/0/Android/data/... is a
+          FUSE mount with no hard links, and the call raises EACCES on a
+          directory the app writes to freely.
+
+          If neither is available the export is **refused**. The alternative —
+          claim the name with O_CREAT|O_EXCL and then rename — is race-safe and
+          not crash-safe, and offering it silently would mean the contract said
+          atomic while the behaviour was not. See `legacyPlaceholderPublish`.
+        */
+        if (legacyPlaceholderPublish) return claimThenRename(staging, target, name)
+
+        val renamed = if (pretendNoAtomicNoReplace) OsConstants.ENOSYS
+        else runCatching { nativeRenameNoReplace(staging.absolutePath, target.path) }
+            .getOrDefault(OsConstants.ENOSYS)
+        if (renamed == 0) return null
+        if (renamed == OsConstants.EEXIST) {
+            runCatching { staging.delete() }
+            return "'$name' already exists; pass overwrite to replace it"
+        }
+        if (!noReplaceUnsupported(renamed)) {
+            runCatching { staging.delete() }
+            return "publishing '$name' failed: " + errnoName(renamed)
+        }
+
+        try {
+            Os.link(staging.absolutePath, target.path)
+            runCatching { staging.delete() }
+            return null
+        } catch (e: ErrnoException) {
+            if (e.errno == OsConstants.EEXIST) {
+                runCatching { staging.delete() }
+                return "'$name' already exists; pass overwrite to replace it"
+            }
+            if (!noReplaceUnsupported(e.errno)) {
+                runCatching { staging.delete() }
+                return "publishing '$name' failed: " + errnoName(e.errno)
+            }
+        }
+
+        /*
+          Refused, rather than published by a sequence that is not atomic.
+
+          Every remaining way to create a file without replacing one is two
+          operations, and a crash between them leaves an empty destination that
+          nothing can distinguish from a real one. A caller who wants that trade
+          can pass `overwrite: true`, which is a single atomic rename and always
+          available.
+        */
+        runCatching { staging.delete() }
+        return "'$name' cannot be written without overwrite: this filesystem " +
+            "has no atomic create-if-absent, so a crash could leave an empty file; " +
+            "pass overwrite to replace it instead"
+    }
+
+    /**
+     * The pre-`renameat2` sequence, kept only so its window stays demonstrable.
+     *
+     * `O_CREAT | O_EXCL` claims the name in one kernel operation, so the race is
+     * closed — but the publication is two operations, and a process that dies
+     * between them leaves a zero-byte file at the destination. That file looks
+     * exactly like one somebody meant to create, so it blocks every later
+     * `overwrite: false` export to the same path until a human removes it.
+     *
+     * Never reached in production. It exists because "this was measured to be
+     * unsafe" is worth more than "this was removed".
+     */
+    private fun claimThenRename(staging: File, target: Target, name: String): String? {
+        val flags = OsConstants.O_WRONLY or OsConstants.O_CREAT or OsConstants.O_EXCL
+        try {
+            val fd = Os.open(target.path, flags, 384 /* 0600 */)
+            runCatching { Os.close(fd) }
+        } catch (e: ErrnoException) {
+            runCatching { staging.delete() }
+            return if (e.errno == OsConstants.EEXIST) {
+                "'$name' already exists; pass overwrite to replace it"
+            } else {
+                "publishing '$name' failed: " + errnoName(e.errno)
+            }
+        }
+        betweenClaimAndRename?.invoke()
+        return try {
+            Os.rename(staging.absolutePath, target.path)
+            null
+        } catch (e: ErrnoException) {
+            runCatching { File(target.path).delete() }
+            runCatching { staging.delete() }
+            "publishing '$name' failed: " + errnoName(e.errno)
+        }
+    }
+
+    /**
+     * Errnos that mean "not this operation, here" rather than "not you".
+     *
+     * `EACCES` is in here, which looks wrong for a permission error and is not.
+     * Measured on a Pixel 7: `link` into the app's own external files directory
+     * — a directory it can and does write to — raises `EACCES`, because the FUSE
+     * volume refuses the *operation*, not the caller.
+     *
+     * Being permissive costs nothing, because the next thing tried is another
+     * way of creating the same file in the same directory. What a genuinely
+     * unwritable directory produces is the preflight refusal, which runs before
+     * anything is encoded.
+     */
+    private fun noReplaceUnsupported(errno: Int): Boolean =
+        errno == OsConstants.ENOSYS ||
+            errno == OsConstants.EINVAL ||
+            errno == OsConstants.EPERM ||
+            errno == OsConstants.EACCES ||
+            errno == OsConstants.EOPNOTSUPP ||
+            errno == OsConstants.EMLINK ||
+            errno == OsConstants.EXDEV
+
+    /** The constant's name, never the path it was raised for. */
+    private fun errnoName(errno: Int): String = when (errno) {
+        OsConstants.ENOSPC -> "no space left on the device"
+        OsConstants.EACCES -> "permission denied (EACCES)"
+        OsConstants.EPERM -> "the operation is not permitted here (EPERM)"
+        OsConstants.EXDEV -> "the staging file and the destination are on different filesystems"
+        OsConstants.EROFS -> "the filesystem is read-only"
+        OsConstants.ENOENT -> "the directory no longer exists"
+        OsConstants.ENOSYS -> "the kernel has no renameat2"
+        OsConstants.EEXIST -> "the destination already exists"
+        0 -> "ok"
+        else -> "errno " + errno
+    }
+}