kuilt-bolt/us.tractat.kuilt.bolt/AppendResult

AppendResult

An append is best-effort: it reports failure rather than throwing, so a full archive disk cannot take down the application whose telemetry it is archiving.

Samples

when (val result = bolt.append(ops)) {
    // endOffset is where the NEXT frame lands — the resume cursor.
    is AppendResult.Written -> rememberCursor(result.endOffset)
    // Nothing written, nothing lost: an empty append, or one whose ops were all
    // compaction records. Neither carries content, so neither earns a frame.
    AppendResult.Skipped -> Unit
    // The ops are lost from the archive — and the live replica will window them away
    // next, so they are gone from BOTH sides. `insertDots` is what lets a consumer defer
    // that windowing, re-feed, or correlate the gap; a `failed++` tally could do none of
    // those, which is why this reports identities and never a count.
    is AppendResult.Failed -> deferWindowingFor(result.insertDots)
}

Inheritors

Written

Skipped

Failed

Types

Failed

data class Failed(val reason: String, val insertDots: Set<Dot>, val offset: Long?, val endOffset: Long? = null, val cause: Throwable? = null) : AppendResult

The append failed. The ops are lost from the archive.

Skipped

data object Skipped : AppendResult

Nothing was written, and nothing was lost.

Written

data class Written(val offset: Long, val endOffset: Long, val opCount: Int, val insertDots: Set<Dot>) : AppendResult

A frame was written covering [offset, endOffset) of the archive's append-offset space.