api.go

// Package swimlab is a teaching lab for the SWIM membership and failure-detection
// protocol, in the style of the MIT 6.5840 labs: you implement the protocol, and a
// deterministic test suite grades it.
//
// This file defines the shared types every implementation and the simulated
// network agree on. You do not edit it. Implement your protocol in swim.go.
package swimlab

// NodeID identifies a process in the cluster.
type NodeID int

// State is what one node believes about another (or itself).
//
// The lifecycle is Alive -> Suspect -> Dead. Suspect is the heart of SWIM: a node
// that misses a probe is not declared dead immediately — it is *suspected*, and a
// suspected-but-alive node is given the chance to refute (see Incarnation).
type State int

const (
	Alive State = iota
	Suspect
	Dead
)

func (s State) String() string {
	switch s {
	case Alive:
		return "alive"
	case Suspect:
		return "suspect"
	case Dead:
		return "dead"
	default:
		return "?"
	}
}

// MsgType is the kind of a message on the wire.
type MsgType int

const (
	// Ping probes a target directly ("are you alive?").
	Ping MsgType = iota
	// Ack answers a Ping ("yes"). Target names the node confirmed alive, so a
	// requester can match an ack even when it is relayed by a third node.
	Ack
	// PingReq asks the receiver to probe Target on the sender's behalf — this is
	// SWIM's indirect probing, the mechanism that stops one dropped packet from
	// looking like a death.
	PingReq
)

// Update is one piece of membership gossip: "I believe Node is in State at this
// Incarnation." Updates ride piggybacked on every message (the Updates field) so
// knowledge spreads infection-style, without a separate gossip round.
type Update struct {
	Node        NodeID
	State       State
	Incarnation int
}

// Message is what nodes exchange. Send it through the send function handed to
// NewNode; you receive it in Handle.
type Message struct {
	Type    MsgType
	From    NodeID
	Target  NodeID   // PingReq: node to probe. Ack: node confirmed alive.
	Seq     int      // matches an Ack back to the Ping (or PingReq) that caused it.
	Updates []Update // piggybacked membership gossip.
}

// Config tunes the protocol. All times are in logical ticks; the simulated network
// advances one tick at a time.
type Config struct {
	Period         int   // ticks between protocol periods (one probe per period)
	PingTimeout    int   // ticks to wait for a direct Ack before probing indirectly
	IndirectNodes  int   // k: how many helpers to ask for an indirect probe
	SuspicionTicks int   // ticks a node stays Suspect before it is declared Dead
	Seed           int64 // per-node randomness (target selection); set by the harness
}

// DefaultConfig is tuned so that, under 10% packet loss, correct SWIM produces no
// false positives while still detecting a real death well within the test window.
//
// SuspicionTicks is the key trade: it is the grace period a suspected node gets to
// refute before it is declared dead. Too small and unlucky packet loss kills a live
// node (a false positive); too large and real deaths take longer to confirm. Eight
// periods is a deliberately safe setting for a 10% loss rate.
func DefaultConfig() Config {
	return Config{
		Period:         10,
		PingTimeout:    3,
		IndirectNodes:  4,
		SuspicionTicks: 80,
		Seed:           1,
	}
}