react-native-nitro-logger 0.1.0

package/android/src/main/java/com/margelo/nitro/nitrologger/LogRotationPolicy.kt

@@ -0,0 +1,186 @@
+package com.margelo.nitro.nitrologger
+
+/**
+ * Rotation and retention for one log file.
+ *
+ * Every field is clamped on the way in. These numbers arrive from JavaScript,
+ * where `NaN`, `Infinity` and `-1` are all ordinary values, and an unchecked
+ * `Double.toLong()` of any of them is silently wrong rather than loud — `NaN`
+ * becomes 0, which would turn "rotate at 10 MB" into "rotate on every write".
+ *
+ * The clamping rules are the iOS writer's, deliberately: a policy that behaves
+ * differently on the two platforms is a bug report nobody can reproduce.
+ */
+data class LogRotationPolicy(
+  val maxFileSizeBytes: Long,
+  val maxArchivedFilesCount: Int,
+  val maxFileAgeSeconds: Double?,
+  val compressArchives: Boolean,
+  val maxArchiveAgeSeconds: Double?,
+  val maxTotalLogBytes: Long?
+) {
+  companion object {
+    /** Effectively "no limit" while still fitting in the types below. */
+    private const val BYTE_CEILING = 1_000_000_000_000_000L
+    private const val COUNT_CEILING = 10_000
+    private const val SECONDS_CEILING = 1e9
+
+    const val DEFAULT_MAX_FILE_SIZE_BYTES = 10_485_760L
+    const val DEFAULT_MAX_ARCHIVED_FILES = 5
+
+    fun of(
+      maxFileSizeBytes: Double = DEFAULT_MAX_FILE_SIZE_BYTES.toDouble(),
+      maxArchivedFilesCount: Double = DEFAULT_MAX_ARCHIVED_FILES.toDouble(),
+      maxFileAgeSeconds: Double? = null,
+      compressArchives: Boolean = false,
+      maxArchiveAgeSeconds: Double? = null,
+      maxTotalLogBytes: Double? = null
+    ): LogRotationPolicy = LogRotationPolicy(
+      maxFileSizeBytes = bytes(maxFileSizeBytes, DEFAULT_MAX_FILE_SIZE_BYTES),
+      maxArchivedFilesCount = count(maxArchivedFilesCount, DEFAULT_MAX_ARCHIVED_FILES),
+      maxFileAgeSeconds = seconds(maxFileAgeSeconds),
+      compressArchives = compressArchives,
+      maxArchiveAgeSeconds = seconds(maxArchiveAgeSeconds),
+      maxTotalLogBytes = optionalBytes(maxTotalLogBytes)
+    )
+
+    /**
+     * `Infinity` clamps UP, to the ceiling. It reads as "never rotate", and
+     * folding it into the default — or into zero — would turn a request for no
+     * rotation into constant rotation. Only `NaN` and non-positive values fall
+     * back, because those carry no intent to honour.
+     */
+    private fun bytes(value: Double, fallback: Long): Long = when {
+      value.isNaN() || value < 1 -> fallback
+      value.isInfinite() -> BYTE_CEILING
+      else -> minOf(value, BYTE_CEILING.toDouble()).toLong()
+    }
+
+    /**
+     * Same rule as [bytes], and for a sharper reason: this limit is what
+     * pruning deletes down to.
+     *
+     * A literal zero is a real instruction — "keep no archives" — so it is
+     * honoured. `NaN` and negatives are not instructions at all, and folding
+     * them into zero would make one malformed number from JavaScript delete
+     * every rotated file on the next sweep. They fall back to the default
+     * instead: retaining five archives nobody asked for is recoverable, and
+     * deleting the lot is not.
+     */
+    private fun count(value: Double, fallback: Int): Int = when {
+      value.isNaN() || value < 0 -> fallback
+      value.isInfinite() -> COUNT_CEILING
+      else -> minOf(value, COUNT_CEILING.toDouble()).toInt()
+    }
+
+    /**
+     * Optional limits read `Infinity` as absence: "no age cap" and "no cap at
+     * all" are the same instruction, and null is how this type spells it.
+     */
+    private fun seconds(value: Double?): Double? {
+      if (value == null || !value.isFinite() || value <= 0) return null
+      return minOf(value, SECONDS_CEILING)
+    }
+
+    private fun optionalBytes(value: Double?): Long? {
+      if (value == null || !value.isFinite() || value < 1) return null
+      return minOf(value, BYTE_CEILING.toDouble()).toLong()
+    }
+  }
+}
+
+/**
+ * Payload-free record of what has stopped working.
+ *
+ * A bitmask rather than messages on purpose: these cross into JavaScript and
+ * eventually into a log file, and a path or an errno string is exactly the kind
+ * of thing that carries a username in it.
+ */
+object LogDegradation {
+  const val NONE = 0
+  const val ROTATION = 1 shl 0
+  const val GZIP = 1 shl 1
+  const val PRUNE = 1 shl 2
+  const val SIDECAR = 1 shl 3
+  const val PROTECTION = 1 shl 4
+}
+
+enum class LogRejectReason(val wire: String) {
+  FULL("full"),
+  STALE_GENERATION("staleGeneration"),
+  CLOSED("closed"),
+  FAILED("failed")
+}
+
+data class LogSinkStatus(
+  val queuedBytes: Long,
+  val lostBytes: Long,
+  val lostEntries: Long,
+  val degraded: Int
+)
+
+data class LogAppendResult(
+  val accepted: Boolean,
+  val rejectReason: LogRejectReason?,
+  val status: LogSinkStatus
+)
+
+/**
+ * Numbers arriving from JavaScript, which reach Kotlin as [Double].
+ *
+ * This lives here rather than in the Nitro adapter so the JUnit suite can
+ * reach it: the adapter needs a device, and this is the part worth testing.
+ */
+object BridgeNumber {
+  /**
+   * [value] as an exact [Long], or null if it was never one.
+   *
+   * `Double.toLong()` saturates and truncates rather than failing, so every
+   * check has to happen before the conversion. NaN would become 0 — which then
+   * passes the writer's own checks whenever the batch is empty too — each
+   * infinity would become a bound, and 2.5 would become 2, an accepted batch
+   * carrying a count nobody sent. iOS refuses all of these via `Int(exactly:)`;
+   * this is the same refusal.
+   */
+  fun exactLong(value: Double): Long? {
+    if (!value.isFinite()) return null
+    if (value != Math.floor(value)) return null
+    // Integral is not sufficient: 1e19 has no fractional part and still does
+    // not fit, and `toLong()` would clamp it to Long.MAX_VALUE.
+    //
+    // The two bounds are deliberately not symmetric, because the two constants
+    // are not. Long.MIN_VALUE is -2^63, exactly representable as a Double, so
+    // it converts and the comparison is inclusive. Long.MAX_VALUE is 2^63 - 1,
+    // which is NOT representable — `Long.MAX_VALUE.toDouble()` rounds UP to
+    // 2^63. An inclusive upper bound would therefore admit 2^63 itself and let
+    // `toLong()` saturate it to 2^63 - 1: a silently different number, which is
+    // the precise failure this function exists to prevent. Hence `>=`.
+    if (value < Long.MIN_VALUE.toDouble() || value >= Long.MAX_VALUE.toDouble()) return null
+    return value.toLong()
+  }
+}
+
+data class LogFlushOutcome(
+  val durable: Boolean,
+  val timedOut: Boolean,
+  val pendingBytes: Long,
+  val status: LogSinkStatus
+)
+
+data class LogClearOutcome(
+  val deletedCount: Int,
+  val failedPaths: List<String>,
+  /** Every artifact is gone. This is the compliance question. */
+  val durable: Boolean,
+  /**
+   * The writer has a usable file again. Separate from [durable] because a
+   * complete deletion can still be followed by a failed reopen, and a caller
+   * that resumes on [durable] alone writes into a writer with nowhere to put
+   * anything.
+   */
+  val rebound: Boolean = false
+)
+
+class LogWriterException(val kind: Kind, message: String) : Exception(message) {
+  enum class Kind { OPEN_FAILED, CONFIG_CONFLICT, SYMLINK_ESCAPE, STILL_CLOSING }
+}

package/android/src/main/java/com/margelo/nitro/nitrologger/LogSecureFile.kt

@@ -0,0 +1,80 @@
+package com.margelo.nitro.nitrologger
+
+import java.io.File
+
+/**
+ * Creating and locking down the files this package writes.
+ *
+ * The iOS twin has more to do here: a data-protection class and a backup
+ * exclusion attribute, both applied per artifact. Android's equivalents are
+ * structural rather than per file — the log directory lives under
+ * `noBackupFilesDir`, which keeps it out of Auto Backup, and app-private
+ * storage is already unreadable by other apps — so what is left for this file
+ * is the second layer: owner-only modes on every artifact, and a refusal to
+ * follow a symlink out of the directory the registry believes it owns.
+ *
+ * Every function reports whether it fully succeeded rather than throwing.
+ * Failing to tighten a mode is worth recording as a `protection` degradation;
+ * it is not worth refusing to log over.
+ */
+object LogSecureFile {
+  /**
+   * Creates the directory chain and restricts each level to its owner.
+   *
+   * Each level, not just the leaf: a 0700 directory inside a world-readable one
+   * still hides its contents, but the intermediate `logs` name and the
+   * timestamps on it are visible, and there is no reason to leak them.
+   */
+  fun createDirectory(directory: File, platform: PlatformIo): Boolean {
+    var ok = true
+
+    if (!directory.isDirectory) {
+      // Walk down from the highest missing ancestor so each level can be
+      // tightened as it appears. `mkdirs()` alone creates the whole chain with
+      // default modes and gives no hook in between.
+      val missing = generateSequence(directory) { it.parentFile }
+        .takeWhile { !it.isDirectory }
+        .toList()
+        .asReversed()
+
+      for (level in missing) {
+        if (!level.mkdir() && !level.isDirectory) return false
+        if (!platform.restrictToOwner(level, isDirectory = true)) ok = false
+      }
+    } else if (!platform.restrictToOwner(directory, isDirectory = true)) {
+      ok = false
+    }
+
+    return ok && directory.isDirectory
+  }
+
+  /** Restricts one artifact to its owner. */
+  fun secure(file: File, platform: PlatformIo): Boolean {
+    if (!file.exists()) return true
+    return platform.restrictToOwner(file, isDirectory = file.isDirectory)
+  }
+
+  /**
+   * Whether the final component of a path is a symlink.
+   *
+   * Following one would write the app's log wherever the link points — a path
+   * the caller never named and the purge would never clean — and would let two
+   * different registry keys resolve to the same file. This is the `lstat` +
+   * `S_IFLNK` check the iOS writer does, and it deliberately asks about the
+   * leaf alone.
+   *
+   * **Only the leaf.** A symlinked *ancestor* is not a problem to refuse over:
+   * the registry resolves the directory canonically before the writer ever
+   * sees the path, precisely so that two names for one directory collapse to
+   * one key. Comparing `canonicalFile` to `absoluteFile` would fold that
+   * intended resolution into the check and refuse to open anything under a
+   * symlinked parent at all — which on macOS is every `createTempFile`
+   * directory, since `/var` is a link to `/private/var`.
+   *
+   * Delegated to [PlatformIo] rather than answered here: `Files.isSymbolicLink`
+   * is API 26 and this library supports 24, so Android answers it with
+   * `Os.lstat` instead.
+   */
+  fun isSymbolicLink(file: File, platform: PlatformIo): Boolean =
+    platform.isSymbolicLink(file)
+}

package/android/src/main/java/com/margelo/nitro/nitrologger/LogWriterRegistry.kt

@@ -0,0 +1,420 @@
+package com.margelo.nitro.nitrologger
+
+import java.io.File
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.locks.ReentrantLock
+import kotlin.concurrent.withLock
+
+/**
+ * One writer per file, no matter how many destinations point at it.
+ *
+ * Two streams appending to the same path from different threads interleave
+ * mid-record, and two rotation schedules racing over the same file archive each
+ * other's fresh output. The registry makes that impossible by construction:
+ * everything that resolves to the same file gets the same [LogFileWriter].
+ *
+ * **The key is the canonical path.** `logs/app.log`, `logs/../logs/app.log`,
+ * and a `logs` symlink into the real directory are the same file and must land
+ * on the same entry — comparing the strings the caller passed in would hand out
+ * two writers for one file, which is exactly the collision the registry exists
+ * to stop.
+ */
+class LogWriterRegistry {
+  companion object {
+    val shared = LogWriterRegistry()
+
+    /**
+     * How long an acquire will wait for a previous writer on the same path to
+     * finish shutting down before giving up.
+     */
+    const val CLOSE_WAIT_MS = 5_000L
+
+    /**
+     * Turns a caller-supplied path into the canonical file it names.
+     *
+     * The parent directory is created before resolution, because canonical
+     * resolution answers only for things that exist — resolving first would
+     * fall back to the literal string on a fresh install and hand out a key
+     * that stops matching the moment the directory appears.
+     */
+    @Throws(LogWriterException::class)
+    fun resolve(path: String, platform: PlatformIo): Resolved {
+      if (path.isEmpty()) {
+        throw LogWriterException(LogWriterException.Kind.OPEN_FAILED, "empty path")
+      }
+      // Collapse `.` and `..` lexically before anything looks at the parent.
+      // `logs/sub/../app.log` names a file in `logs`, but taken literally its
+      // parent is `logs/sub/..` — a directory that only exists if `sub` does,
+      // so creating it fails and the open dies on a path that was perfectly
+      // valid. iOS gets this from `standardizedFileURL`.
+      val requested = lexicallyNormalized(File(path).absoluteFile)
+      val name = requested.name
+      if (name.isEmpty() || name == "." || name == "..") {
+        throw LogWriterException(
+          LogWriterException.Kind.OPEN_FAILED,
+          "path does not name a file"
+        )
+      }
+      val directory = requested.parentFile
+        ?: throw LogWriterException(
+          LogWriterException.Kind.OPEN_FAILED,
+          "path has no directory"
+        )
+
+      if (!LogSecureFile.createDirectory(directory, platform) && !directory.isDirectory) {
+        throw LogWriterException(
+          LogWriterException.Kind.OPEN_FAILED,
+          "could not create the log directory"
+        )
+      }
+
+      val canonicalDirectory = try {
+        directory.canonicalFile
+      } catch (_: Exception) {
+        throw LogWriterException(
+          LogWriterException.Kind.OPEN_FAILED,
+          "could not resolve the log directory"
+        )
+      }
+
+      // The log file itself must not be a symlink, even though the directory
+      // above it was resolved through one deliberately.
+      val candidate = File(canonicalDirectory, name)
+      if (LogSecureFile.isSymbolicLink(candidate, platform)) {
+        throw LogWriterException(
+          LogWriterException.Kind.SYMLINK_ESCAPE,
+          "the log file is a symbolic link"
+        )
+      }
+
+      return Resolved(candidate, candidate.absolutePath)
+    }
+
+    /**
+     * Collapses `.` and `..` in an absolute path, textually.
+     *
+     * `Path.normalize()` would be the obvious call and was the original one, but
+     * `java.nio.file` arrived in API 26 and this library supports 24. A missing
+     * class there raises `NoClassDefFoundError` — an `Error`, which passes
+     * straight through `catch (Exception)` — so on an older device the failure
+     * would not have been a fallback but an unhandled throw out of `open()`.
+     *
+     * Purely lexical, like the original: it does not touch the filesystem, so
+     * `a/symlink/../b` collapses to `a/b` whether or not that is where the link
+     * pointed. That is the same trade `standardizedFileURL` makes on iOS, and it
+     * is safe here because the *directory* is canonicalised for real straight
+     * afterwards, and the leaf is `lstat`-checked.
+     */
+    private fun lexicallyNormalized(file: File): File {
+      val separator = File.separatorChar
+      val stack = ArrayList<String>()
+      for (part in file.absolutePath.split(separator)) {
+        when (part) {
+          "", "." -> Unit
+          ".." -> if (stack.isNotEmpty()) stack.removeAt(stack.size - 1)
+          else -> stack.add(part)
+        }
+      }
+      return File(separator + stack.joinToString(separator.toString()))
+    }
+
+    /** A registry with no shared state, so tests do not leak writers. */
+    fun isolated() = LogWriterRegistry()
+  }
+
+  data class Resolved(val file: File, val canonicalPath: String)
+
+  /**
+   * A lock with a condition, because acquisition sometimes has to *wait* — see
+   * [closing].
+   */
+  private val lock = ReentrantLock()
+  private val pathFreed = lock.newCondition()
+  private val writers = HashMap<String, LogFileWriter>()
+
+  /**
+   * Paths whose writer has been evicted but is still draining and closing.
+   *
+   * Eviction and close cannot be one atomic step: closing waits on the write
+   * executor, and holding the registry lock across that would stall every other
+   * file. But between the two, the map has no entry for the path — so an
+   * acquire arriving in that window would build a *second* writer while the
+   * first still has accepted batches queued, giving one file two executors and
+   * two rotation schedules. That is the exact collision this registry exists to
+   * prevent, so acquisition waits out the close instead.
+   *
+   * Counted rather than a set: it costs nothing and stops a stray double
+   * release from clearing a marker another close still needs.
+   */
+  private val closing = HashMap<String, Int>()
+  private var nextHandleId = 1L
+
+  /**
+   * Acquires a handle on the writer for [path], creating it if needed.
+   *
+   * Acquisition happens entirely under the lock, so two runtimes opening the
+   * same file concurrently cannot both construct a writer and have one silently
+   * replace the other.
+   */
+  @Throws(LogWriterException::class)
+  fun acquire(
+    path: String,
+    policy: LogRotationPolicy,
+    lineFramed: Boolean,
+    /**
+     * Required, with no default on purpose — see [LogFileWriter.open]. Falling
+     * back to [PlatformIo.Jvm] on Android would put `java.nio.file` back on the
+     * open path, where it does not exist below API 26.
+     */
+    platform: PlatformIo,
+    rawWrite: LogFileWriter.RawWrite? = null,
+    compressor: LogFileWriter.Compressor? = null,
+    clock: (() -> Long)? = null,
+    monotonic: (() -> Long)? = null
+  ): LogFileHandle {
+    val resolved = resolve(path, platform)
+
+    lock.withLock {
+      // Wait out a close still in progress on this path — but not forever. The
+      // claim is cleared by the writer's own executor rather than by whoever
+      // called close, so wedged storage means it may never clear at all.
+      // Failing the open is the fail-closed answer: one writer per file is the
+      // invariant worth keeping, and a caller that cannot have it should be
+      // told so rather than handed a second one.
+      var budget = CLOSE_WAIT_MS
+      while (closing.containsKey(resolved.canonicalPath)) {
+        if (budget <= 0) {
+          throw LogWriterException(
+            LogWriterException.Kind.STILL_CLOSING,
+            "a previous writer for this path is still closing"
+          )
+        }
+        val waited = try {
+          pathFreed.awaitNanos(TimeUnit.MILLISECONDS.toNanos(budget))
+        } catch (_: InterruptedException) {
+          // Same answer as running out of budget, and for the same reason: one
+          // writer per file is the invariant, and a caller that cannot be given
+          // it is told so rather than handed a second one.
+          Thread.currentThread().interrupt()
+          throw LogWriterException(
+            LogWriterException.Kind.STILL_CLOSING,
+            "interrupted while a previous writer for this path was closing"
+          )
+        }
+        budget = TimeUnit.NANOSECONDS.toMillis(waited)
+      }
+
+      val existing = writers[resolved.canonicalPath]
+      val writer: LogFileWriter
+      if (existing != null && !existing.isClosed) {
+        // A second destination on the same file must agree about how that file
+        // is written. Silently honouring the first caller's rotation policy
+        // would give the second one a file that behaves nothing like what it
+        // asked for, and silently honouring the last would change it under the
+        // first.
+        if (existing.policy != policy || existing.lineFramed != lineFramed) {
+          throw LogWriterException(
+            LogWriterException.Kind.CONFIG_CONFLICT,
+            "this file is already open with a different configuration"
+          )
+        }
+        writer = existing
+      } else {
+        writer = LogFileWriter.open(
+          file = resolved.file,
+          canonicalPath = resolved.canonicalPath,
+          policy = policy,
+          lineFramed = lineFramed,
+          platform = platform,
+          rawWrite = rawWrite,
+          compressor = compressor,
+          clock = clock,
+          monotonic = monotonic
+        )
+        writers[resolved.canonicalPath] = writer
+      }
+
+      writer.retain()
+      val id = nextHandleId
+      nextHandleId += 1
+      return LogFileHandle(id, writer, this)
+    }
+  }
+
+  /**
+   * Drops one handle's claim, closing and evicting the writer at zero.
+   */
+  internal fun release(writer: LogFileWriter, handleId: Long, deadlineMs: Double) {
+    val path = writer.canonicalPath
+
+    val shouldClose = lock.withLock {
+      val remaining = writer.releaseOne()
+      if (remaining > 0) return@withLock false
+      if (writers[path] === writer) writers.remove(path)
+      // Claim the path for the duration of the close. An acquire arriving now
+      // waits rather than building a rival writer over a file this one is still
+      // draining.
+      closing[path] = (closing[path] ?: 0) + 1
+      true
+    }
+    if (!shouldClose) return
+
+    // The claim is dropped by the writer's own executor, not when this call
+    // stops waiting. A close that hits its deadline leaves work still
+    // executing; releasing the path then would let a replacement writer open
+    // the same file underneath it.
+    writer.close(handleId, deadlineMs) { finishClosing(path) }
+  }
+
+  private fun finishClosing(path: String) {
+    lock.withLock {
+      val outstanding = closing[path] ?: 0
+      if (outstanding > 1) closing[path] = outstanding - 1 else closing.remove(path)
+      pathFreed.signalAll()
+    }
+  }
+
+  val liveWriterCountForTesting: Int get() = lock.withLock { writers.size }
+  val closingCountForTesting: Int get() = lock.withLock { closing.size }
+}
+
+/**
+ * One destination's claim on a writer.
+ *
+ * The generation is the fence. A purge bumps the writer's generation; a handle
+ * that has not rebound to the new one is refused with `staleGeneration` rather
+ * than being allowed to write pre-purge data into the fresh file.
+ */
+class LogFileHandle internal constructor(
+  val id: Long,
+  private val writer: LogFileWriter,
+  private val registry: LogWriterRegistry
+) {
+  private enum class State { ACTIVE, CLOSING, CLOSED }
+
+  private val lock = ReentrantLock()
+  private val purgeFinished = lock.newCondition()
+  private var generation = writer.currentGeneration
+  private var state = State.ACTIVE
+  /** A purge is running on this handle; close has to wait it out. */
+  private var purging = false
+
+  val filePath: String get() = writer.file.absolutePath
+
+  /**
+   * Whether this handle may still speak for the writer.
+   *
+   * Every entry point below is gated on it, and on ACTIVE specifically rather
+   * than "not yet CLOSED". A handle in CLOSING has already had its flush
+   * barrier enqueued by [close]; letting it submit more work, or report a
+   * status it will not be around to make true, is how a released destination
+   * ends up observing — or writing to — a writer that another handle now owns.
+   */
+  private val isLive: Boolean get() = lock.withLock { state == State.ACTIVE }
+
+  private fun inertStatus() = LogSinkStatus(0, 0, 0, 0)
+
+  fun appendBatch(batch: String, entryCount: Long): LogAppendResult = lock.withLock {
+    if (state != State.ACTIVE) {
+      return LogAppendResult(false, LogRejectReason.CLOSED, inertStatus())
+    }
+    writer.append(id, generation, batch, entryCount)
+  }
+
+  fun status(): LogSinkStatus {
+    if (!isLive) return inertStatus()
+    return writer.status(id)
+  }
+
+  fun flush(deadlineMs: Double): LogFlushOutcome {
+    // Not `durable = true`. A released handle flushed nothing, and saying
+    // otherwise invites the caller to treat its pending records as safe.
+    if (!isLive) return LogFlushOutcome(false, false, 0, inertStatus())
+    return writer.flush(id, deadlineMs)
+  }
+
+  fun logFilePaths(): List<String> {
+    if (!isLive) return emptyList()
+    return writer.logFilePaths()
+  }
+
+  /**
+   * Purges, then rebinds only if the writer really came back.
+   *
+   * `rebound` is a fact about THIS handle, not about the writer: if this handle
+   * is closing, or the purge did not end with a usable file, the caller must
+   * stay fenced even though the deletion itself may have been perfectly
+   * durable.
+   */
+  fun clearLogs(deadlineMs: Double): LogClearOutcome {
+    lock.lock()
+    if (state != State.ACTIVE || purging) {
+      lock.unlock()
+      return LogClearOutcome(0, listOf(filePath), durable = false)
+    }
+    purging = true
+    lock.unlock()
+
+    val result = try {
+      writer.clearLogs(deadlineMs)
+    } finally {
+      lock.withLock {
+        purging = false
+        purgeFinished.signalAll()
+      }
+    }
+
+    lock.withLock {
+      var outcome = result.first
+      if (state == State.ACTIVE && outcome.durable && outcome.rebound) {
+        generation = result.second
+      } else {
+        outcome = outcome.copy(rebound = false)
+      }
+      return outcome
+    }
+  }
+
+  /**
+   * Closes this handle, waiting out any purge still running on it.
+   *
+   * One budget across all three waits. Giving each the full deadline means a
+   * caller asking for 200 ms can wait 600.
+   */
+  fun close(deadlineMs: Double): LogFlushOutcome {
+    // Monotonic, not `currentTimeMillis`. This budget spans three waits, and a
+    // device clock that steps backward part-way through — an NTP correction, a
+    // user changing the date — would hand the flush and teardown far more than
+    // the caller asked for. On the crash path that is the difference between a
+    // bounded close and an ANR.
+    val expiry = monotonicMs() + LogFileWriter.clampDeadline(deadlineMs)
+
+    lock.lock()
+    if (state != State.ACTIVE) {
+      lock.unlock()
+      return LogFlushOutcome(false, false, 0, inertStatus())
+    }
+    state = State.CLOSING
+    while (purging) {
+      val left = maxOf(0L, expiry - monotonicMs())
+      if (left <= 0) break
+      try {
+        if (!purgeFinished.await(left, TimeUnit.MILLISECONDS)) break
+      } catch (_: InterruptedException) {
+        Thread.currentThread().interrupt()
+        break
+      }
+    }
+    lock.unlock()
+
+    val outcome = writer.flush(id, remaining(expiry))
+    registry.release(writer, id, remaining(expiry))
+    lock.withLock { state = State.CLOSED }
+    return outcome
+  }
+
+  private fun remaining(expiry: Long): Double =
+    maxOf(0L, expiry - monotonicMs()).toDouble()
+
+  private fun monotonicMs(): Long = System.nanoTime() / 1_000_000L
+}