Reliability | Logbun

MemoryReliabilityAdapter, FileReliabilityAdapter, and CloudflareReliabilityAdapter options.

The public seam owns journal, DLQ lifecycle, recovery, statistics, lifecycle, and exclusive ownership. Methods: init, close, appendJournal, acknowledgeJournal, recoverJournal, compactJournal, writeDlq, listDlq, claimDlq, settleDlqSuccess, settleDlqFailure, poisonDlq, requeueDead, deleteDead, readDlq, recoverOrphans, getStats. persistent is a readonly boolean (false for memory).

Optional host-scheduler hooks: pendingMaintenanceDelayMs(), requestMaintenance(). Deprecated: rearmMaintenance().

recoverJournal accepts { maxLogs?, maxBytes? }. A finite maxBytes is strict: returned encoded records never exceed it, and an oversized first record yields zero logs with truncated: true. Finite negative values normalize to zero; non-finite values are treated as unbounded.

MemoryReliabilityAdapter

Root default. persistent: false. No filesystem I/O.

import { MemoryReliabilityAdapter } from 'logbun';

new MemoryReliabilityAdapter({
  maxDlqEntries: 10_000,      // pending+processing cap; default 10_000
  enableJournal: false,       // in-process journal for tests; still lost on exit
  maxJournalEntries: 100_000, // used only when enableJournal is true
});

FileReliabilityAdapter

Import from logbun/durability/filesystem. All filesystem options live here, not on LogbunConfig. Requires namespace.

Adapter option	Default	Meaning
`namespace`	required	Isolates data under `dataDir/namespace` (`[a-zA-Z0-9_-]{1,64}`)
`dataDir`	`.logbun`	Parent directory; `..` segments are rejected
`wal.fsync`	true	fsync journal appends / compaction
`wal.segmentBytes`	16 MiB	WAL rotation threshold for `current.aof` → `seg-NNNNNN.aof`
`wal.compactAckThreshold`	256	Compact when this many ack ids sit in `acked.ids`
`wal.hardMaxBytes`	true	Refuse over-limit append with `wal_full` (equality is permitted)
`maxWalBytes`	64 MiB	Journal size cap across current + segments
`dlq.fsync`	true	fsync DLQ writes / transitions
`dlq.maxEntries`	10_000	Pending + processing entry cap (`dlq_full`)
`encryptionKey`	—	AES-256-GCM; 32 bytes / 64-hex / base64-of-32; passphrases rejected
`instanceLock`	true	Exclusive namespace ownership

This adapter does not schedule host wake-ups. Call runMaintenance() from the process.

Also exported from the filesystem subpath: resolveLogbunDir (alias resolveDataDir), sanitizeNamespace, InstanceLock, InstanceLockError, WALStorage, DLQStorage, WAL_SIZE_SOFT_LIMIT_BYTES, WAL_SEGMENT_BYTES_DEFAULT, DLQ_MAX_FILES_DEFAULT.

CloudflareReliabilityAdapter

Import from logbun/durability/cloudflare inside a SQLite-backed Durable Object. ESM-only.

new CloudflareReliabilityAdapter({
  state: ctx,
  tablePrefix: 'logbun',
  maxJournalEntries: 100_000,
  maxDlqEntries: 10_000,
  scheduleAlarms: true,
  alarmDelayMs: 1_000,
});

The subpath re-exports DurableAdmissionSchedulingError and isDurableAdmissionSchedulingError. Also exports types DurableObjectSqlStorage and DurableObjectStateLike.

`DLQEntry`

interface DLQEntry {
  id: string;
  state: 'pending' | 'processing' | 'dead';
  kind: 'pending' | 'processing' | 'dead'; // always equal to state
  tenantId: string | null;
  attempts: number;
  logCount: number;
  metadata?: Record<string, unknown>;
}

Scheduling error

class DurableAdmissionSchedulingError extends Error {
  readonly durableAdmissionCommitted = true;
  // message: "durable admission committed but maintenance scheduling failed: …"
  name = 'DurableAdmissionSchedulingError';
}

Exported from logbun and from logbun/durability/cloudflare.