Class NetworkConsensusNode

java.lang.Object
org.j7m.middleware.consensus.NetworkConsensusNode
All Implemented Interfaces:
AutoCloseable
public final class NetworkConsensusNode extends Object implements AutoCloseable
Persistent Raft group member with authenticated bounded RPC, automatic elections and joint consensus. Acknowledged commands survive loss of a minority; storage must honor force and atomic rename. One instance exclusively owns its directory. Client methods are thread safe; callers retry another leader after NOT_LEADER and reuse request IDs after UNKNOWN. Request IDs are retained indefinitely (including snapshots), and cannot identify different commands. Admission stops with UNAVAILABLE when the request journal reaches maxSnapshotBytes/128 entries; deployments must provision that bound for the group lifetime or start a new group generation. Deadlines bound caller waiting, not rollback of a committed command. Applications implement cooperative cancellation inside their commands; transport timeout never cancels committed work.

  • Constructor Summary

    Constructors
    Constructor
    Description
    NetworkConsensusNode(NetworkConsensusConfig config, ReplicatedStateMachine machine)
    Opens and recovers a node, but does not start its network endpoint.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    append(String requestId, byte[] command, Instant deadline)
    Commits a command, or waits for an earlier identical request, and returns after local apply.
    long
    appendControl(byte[] command, Instant deadline)
    Commits a trusted deterministic maintenance command without retaining a request identity.
    void
    close()
    Stops background work and releases sockets and durable directory ownership.
    boolean
    hosts(ReplicatedStateMachine candidate)
    Tests callback ownership without exposing mutable application state.
    long
    readIndex(Instant deadline)
    Establishes a linearizable read barrier using a fresh current-term quorum confirmation.
    long
    reconfigure(long expectedConfigEpoch, Set<String> newMembers, Instant deadline)
    Changes voters through learner catch-up followed by durable joint and final configurations.
    long
    recoveredIndex()
    Returns the committed prefix restored during construction, before any new commands.
    long
    snapshot()
    Atomically captures the applied prefix and compacts only that committed prefix.
    void
    start()
    Starts automatic elections, heartbeats and the authenticated endpoint.
    NetworkConsensusStatus
    status()
    Returns a diagnostic local view without contacting a quorum.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • NetworkConsensusNode

      public NetworkConsensusNode(NetworkConsensusConfig config, ReplicatedStateMachine machine) throws IOException
      Opens and recovers a node, but does not start its network endpoint.
      Parameters:
      config - bootstrap, identity and resource bounds
      machine - deterministic application callbacks
      Throws:
      IOException - if storage is locked, corrupt, unsupported or cannot be recovered

  • Method Details

    • start

      public void start() throws IOException
      Starts automatic elections, heartbeats and the authenticated endpoint.
      Throws:
      IOException - if binding fails or the node has closed

    • append

      public long append(String requestId, byte[] command, Instant deadline) throws IOException
      Commits a command, or waits for an earlier identical request, and returns after local apply.
      Parameters:
      requestId - stable nonempty application-scoped id, at most 1024 UTF-8 bytes
      command - immutable copied command, bounded by the frame budget
      deadline - absolute caller deadline
      Returns:
      durable committed log position
      Throws:
      IOException - NOT_LEADER, UNAVAILABLE before admission, UNKNOWN after admission, or CONFLICT when the id was used with a different command

    • appendControl

      public long appendControl(byte[] command, Instant deadline) throws IOException
      Commits a trusted deterministic maintenance command without retaining a request identity. The state machine must make repeated controls harmless through its own monotonic sequence or logical version. This operation is unsuitable for ordinary application requests, which must use append with persistent request deduplication. Timeout never rolls back a control.
      Parameters:
      command - bounded copied maintenance command bytes
      deadline - absolute caller deadline
      Returns:
      committed and locally applied log position
      Throws:
      IOException - UNAVAILABLE before admission or UNKNOWN after admission

    • readIndex

      public long readIndex(Instant deadline) throws IOException
      Establishes a linearizable read barrier using a fresh current-term quorum confirmation.
      Parameters:
      deadline - absolute caller deadline
      Returns:
      locally applied committed prefix at the barrier
      Throws:
      IOException - if the node is not leader, loses quorum, or misses the deadline

    • hosts

      public boolean hosts(ReplicatedStateMachine candidate)
      Tests callback ownership without exposing mutable application state.
      Parameters:
      candidate - application callback instance
      Returns:
      true only when this node owns that exact instance

    • recoveredIndex

      public long recoveredIndex()
      Returns the committed prefix restored during construction, before any new commands. Unlike status progress, this immutable diagnostic distinguishes recovery from a fresh group observed only after it accepted new writes. Zero means no committed startup history.
      Returns:
      immutable recovered committed index, never the uncommitted tail

    • status

      public NetworkConsensusStatus status()
      Returns a diagnostic local view without contacting a quorum.
      Returns:
      immutable local status

    • reconfigure

      public long reconfigure(long expectedConfigEpoch, Set<String> newMembers, Instant deadline) throws IOException
      Changes voters through learner catch-up followed by durable joint and final configurations. Only one change may be in flight. All endpoints must be explicitly authorized in peers.
      Parameters:
      expectedConfigEpoch - caller's committed configuration epoch
      newMembers - nonempty target voter set
      deadline - absolute deadline; timeout does not undo a submitted configuration
      Returns:
      committed new epoch
      Throws:
      IOException - CONFLICT, NOT_CAUGHT_UP, NOT_LEADER or UNKNOWN

    • snapshot

      public long snapshot() throws IOException
      Atomically captures the applied prefix and compacts only that committed prefix. Configuration, joint transition, request journal, term and vote survive the compacted file.
      Returns:
      included committed index
      Throws:
      IOException - if snapshot is too large or atomic durable publication fails

    • close

      public void close() throws IOException
      Stops background work and releases sockets and durable directory ownership.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException - if the durable file cannot be closed