dataplane

type Backend interface {
	Participant
	// EnsureDevice brings the WireGuard device up and converges everything but its peers (key,
	// listen port, address, MTU) to cfg, returning the changes it made, one line each, for the log.
	// It runs once at startup, before the first transaction. cfg.Peers is not applied (the kernel
	// backend only shows it in the dry run of a refusal); the peers are converged by the
	// transactions (Desired.WG).
	EnsureDevice(cfg WGConfig) ([]string, error)
	// WGStatus returns the device and its peers (endpoint, last handshake, counters).
	WGStatus() (*wgtypes.Device, error)
	// Dial connects to addr (an agent's wg address and port) through the tunnel.
	Dial(network, addr string) (net.Conn, error)
}

type Committed struct {
	// Drops are the drop counters of the replaced state, one entry per rule and kind, for the
	// control plane to accumulate.
	Drops []Drop
	// WGChanges are the WireGuard changes Prepare and Commit made, one line each, for the log.
	WGChanges []string
	// Closed is how many established flows the convergence after the publication closed.
	Closed int
	// Errors are the failures after the point of no return (reading the drop counters, removing
	// peers, convergence, reading back what was published). They are logged.
	Errors []error
	// RepairPending is set while a step after the point of no return failed in a way that a retry
	// can repair (design.md 7a.3 節: 戻れない地点の後の修復): removing the peers the declaration
	// dropped, the convergence of established flows, or reading back what was published. The
	// Reconciler then asks for a retry, which runs Participant.Repair even when it would publish
	// the same again. A failure to read the drop counters is not a repair: the replaced state is
	// gone and its counters cannot be read any more.
	RepairPending bool
}

type Desired struct {
	// Plan is what to publish. Rules the frontend could not prepare are already left out of it
	// (planner.Plan.Without), so the dataplane publishes no dispatch for them (design.md 7a.3 節:
	// fail-closed).
	Plan planner.Plan
	// RelayListening is the set of Relay ports the frontend will be listening on once it commits:
	// the listeners it keeps plus the ones its Prepare newly opened. Ports being removed and ports
	// that failed to bind are not in it (design.md 6.1, 7a.4 節: ingress rows only for ports wgft
	// actually listens on). nil when the Runtime has no frontend.
	RelayListening map[uint16]bool
	// WG is the WireGuard declaration, its peer set included. nil leaves the device and its peers
	// untouched.
	WG *WGConfig
	// ActivePeers is the peer set the device has now: what the last successful Commit left, or
	// what Observe found before the first one. When WG.Peers differs from it, Prepare adds the new
	// peers before anything is published, Commit removes the peers WG no longer declares after the
	// publication, and Rollback restores this set (design.md 7a.3 節: WireGuard のピアは、公開の
	// 前に足し、公開をやめた後に消す).
	ActivePeers []Peer
	// Resync is set when an Observe found that the state the last Commit left has drifted
	// (Observed.Drift). Prepare then converges the whole WireGuard device to WG (creating it if it is
	// gone, and its key, listen port, address, MTU and peers), not only the peer changes (design.md
	// 7a.3 節: 実際の状態への収束).
	Resync bool
}

type Drop struct {
	RuleID  string
	Kind    string // deny | allow | per_source | src_flow | new_flow | packet
	Packets uint64
	Bytes   uint64
}

type HeldPeer struct {
	PublicKey wgtypes.Key
	Address   netip.Addr
	Endpoint  netip.AddrPort
}

type Observed struct {
	// Peers is the WireGuard peer set the device has now (none when the device is gone).
	Peers []Peer
	// Drift lists, one short phrase each, what of the state the last successful Commit left the
	// dataplane no longer has as committed: for the kernel backend, table inet wgft missing or
	// changed, the wg interface missing, or its key, listen port, address, up state or peers
	// changed. Empty before the first Commit, when nothing drifted, and always for a dataplane
	// whose state lives only inside the process (userspace).
	Drift []string
}

type Participant interface {
	// Observe reads what the dataplane has now. The Reconciler calls it before its first
	// transaction, since a restarted process does not know what the previous one left behind, and
	// afterwards whenever the control plane checks the actual state against what was committed
	// (design.md 7a.3 節: 実際の状態への収束). It must be cheap (a few netlink reads) and must not
	// change anything. An error means the state could not be read, or that a resource wgft
	// converges is now held by someone else and must be left alone (design.md 9 節: 所有判定).
	Observe() (Observed, error)
	// Prepare stages d without publishing it. Everything that can fail belongs here (design.md 7a.2
	// 節): binding listeners, building the nftables transaction, adding WireGuard peers. An error is
	// a backend-wide failure (design.md 7a.3 節): nothing stays staged and the Runtime rolls back
	// the frontend. A failure confined to one rule (a listener that cannot bind) is not an error:
	// the rule is reported by Prepared.Failed and left out of what Commit publishes.
	Prepare(d Desired) (Prepared, error)
	// Repair reruns the repairs the last Commit (or Repair) left failed, without publishing
	// anything again: for the kernel backend, removing peers and the conntrack convergence, so the
	// nftables table is not replaced and its meters and ct count sets are kept (design.md 7a.3 節:
	// 戻れない地点の後の修復). A failed read-back of the published table is not repaired here: the
	// next Observe reports it as drift, which republishes. RepairPending in the result stays set
	// while anything is still pending. It does nothing when nothing is pending.
	Repair() Committed
}

type Peer struct {
	PublicKey wgtypes.Key
	Address   netip.Addr
}

type Prepared interface {
	// Failed returns the rules whose own Prepare failed, with the reason (design.md 7a.3 節). They
	// are not staged: Commit publishes no dispatch for them.
	Failed() map[string]error
	// Commit publishes the staged change as one atomic step (for the kernel backend, one nftables
	// transaction). On error the commit did not succeed; which state the kernel is still forwarding
	// depends on where it failed and cannot be told from here (design.md 11b 節: 転送 の項). The
	// Runtime rolls back regardless. Success is the point of no return (design.md 7a.2 節).
	//
	// Around the publication, Commit also does what belongs to the same transaction: it reads the
	// drop counters of the state it replaces (returned only on success, so a failed publication
	// cannot hand the same counts out twice), removes the WireGuard peers the declaration dropped,
	// and closes the established flows the published Plan no longer admits (design.md 6.1, 6.3 節).
	// The flows of each retiring rule are judged against its Retiring value instead (design.md 7a.3
	// 節). These steps run after the point of no return, so they cannot fail the Commit; their
	// errors are returned in Committed.Errors.
	Commit(retiring []Retiring) (Committed, error)
	// Rollback releases what Prepare staged and restores the peer set it changed. It is called when
	// Commit was not reached or failed, never after a successful Commit, and cannot fail.
	Rollback()
}

type Retiring struct {
	// Previous is the rule's last Active value. Established flows are judged against it, not
	// against the new value, which was never published.
	Previous planner.PortPlan
	// Desired is the rule's source policy in the new declaration. A flow it no longer admits (a new
	// source_deny, for example) is not safe and is closed.
	Desired policy.RulePolicy
}

type Sensor interface {
	// Watch subscribes to the kernel's change notifications and calls wake after each one, until
	// ctx is done (then it returns nil) or the subscription fails (then it returns the error, having
	// called wake once more, since a failure such as a receive buffer overflow can lose
	// notifications). wake must not block. The caller restarts Watch after a failure.
	Watch(ctx context.Context, wake func()) error
}

type UDPReply struct {
	// Since is when the Backend began watching this rule without a gap: the rule's first
	// publication in this process, the publication after its identity changed (UDPReplyIdentity), or
	// the first reading after the watch was interrupted. Zero while Err is set.
	Since time.Time
	// Last is the last time a reply was seen, not before Since. Zero when none was seen since.
	Last time.Time
	// Err is set while the Backend cannot observe the rule's replies (the kernel backend could not
	// read its reply counters, for example). It is not "no reply": nothing is known either way.
	Err error
}

type UDPReplyObserver interface {
	// UDPReplies returns one entry per UDP rule the Backend publishes now, by rule ID. A rule it does
	// not publish (disabled, failed, or of an unregistered agent) has no entry.
	UDPReplies() map[string]UDPReply
}

type WGConfig struct {
	PrivateKey wgtypes.Key
	ListenPort int
	Address    netip.Prefix // the server's address and the wg network, e.g. 10.200.0.1/24
	MTU        int
	Peers      []Peer
}