Interface DurableLog

All Superinterfaces:
AutoCloseable
public interface DurableLog extends AutoCloseable
Thread-safe append-only durable log contract.

The durable log is the local persistence substrate for higher-level J7M reliability services. Implementations own file handles or equivalent local durable resources and may block on append, fsync, segment rotation, cursor reads, snapshot marker writes, and recovery scans. The API is local-only: it is not a replicated log consensus protocol, not a queue, not a broker, and not a transaction coordinator.

Implementations must validate stream identifiers, offsets, record sizes, checksums, frame boundaries, and recovery semantics. Durable-log failures, corrupted records, invalid arguments, and unavailable/closed resources must map to stable middleware error codes. Status and recovery reports are redacted safe summaries and must not expose application payload contents unless the caller explicitly reads records through a cursor.

  • Method Details

    • append

      LogAppendResult append(LogStreamId stream, List<LogRecord> records, AppendOptions options)
      Appends records atomically to one stream.

      Either every record in the supplied batch receives an offset in order or the append fails without reporting partial success. Implementations may apply configured sync and batching policy before returning.

      Parameters:
      stream - logical stream identifier
      records - records to append in order
      options - append options controlling durability and validation policy
      Returns:
      append result with assigned offsets

    • openCursor

      LogCursor openCursor(LogStreamId stream, LogOffset offset, CursorOptions options)
      Opens a deterministic replay cursor.

      The returned cursor owns read resources and must be closed by the caller. Cursor reads may block on local I/O but do not perform network access.

      Parameters:
      stream - logical stream identifier
      offset - first offset to read
      options - cursor options
      Returns:
      closeable cursor

    • findLatestOffsetByMetadata

      default Optional<LogOffset> findLatestOffsetByMetadata(LogStreamId stream, String metadataKey, String metadataValue, int maxRecordsExamined)
      Finds the latest offset in a stream whose record header metadata contains the supplied key and value while examining no more than the caller's bound.

      This method is an optional bounded metadata discovery facility for higher-level services that publish compact checkpoint or marker records. It exposes only logical offsets and header metadata matching semantics; it does not expose segment names, local paths, frame locations, checksums, payload bytes, storage layout, or implementation-specific indexes. The returned offset is a hint for a prompt replay cursor and may become unavailable if retention removes the record before the caller opens the cursor.

      The default implementation returns empty because the base LogCursor contract does not expose each returned record's durable offset after retention has possibly advanced the stream. Implementations with safe metadata indexes or cursor-offset tracking may override this method with a bounded lookup, but they must preserve the same bound, redaction, lifecycle, and error semantics. The method does not require network access.

      If the log is closed, unavailable, corrupted, or interrupted through an implementation-specific blocking I/O mechanism, implementations should report the same stable durable-log error model used by cursor reads. This interface does not clear the interrupted status and does not treat the metadata key or value as authorization; callers remain responsible for authentication and authorization at the service boundary. Error messages and status derived from this operation must not contain payload bytes, secrets, absolute paths, or storage internals.

      Parameters:
      stream - logical stream identifier to inspect
      metadataKey - required header metadata key
      metadataValue - required header metadata value
      maxRecordsExamined - hard upper bound on non-empty records inspected
      Returns:
      newest matching offset within the bound, or empty when none is found
      Throws:
      DurableLogException - when the log is closed, the arguments are invalid, or implementation-specific metadata lookup detects a durable-log failure

    • createSnapshot

      LogSnapshot createSnapshot(LogStreamId stream, SnapshotOptions options)
      Writes a snapshot marker record.

      A snapshot marker is metadata for consumers that compact their own state. The durable log does not interpret application snapshot payloads or install consensus snapshots.

      Parameters:
      stream - logical stream identifier
      options - snapshot marker options
      Returns:
      snapshot marker metadata

    • recover

      LogRecoveryReport recover(RecoveryOptions options)
      Scans storage and rebuilds in-memory/index state.

      Recovery must detect malformed frames, checksum mismatches, truncated tails, and semantic offset/index inconsistencies according to options. The returned report is safe for logs and status.

      Parameters:
      options - recovery options
      Returns:
      recovery report

    • status

      LogStatus status()
      Returns current status and metrics.
      Returns:
      immutable redacted status snapshot for local durable-log resources

    • close

      void close()
      Closes owned resources.

      Close should be idempotent. After close, operations should reject with a stable unavailable/closed error. Implementations must not hide append or recovery failures by silently dropping records.

      Specified by:
      close in interface AutoCloseable