protofsm: add new package for driving generic protocol FSMs

In this PR, we create a new package, `protofsm` which is intended to
abstract away from something we've done dozens of time in the daemon:
create a new event-drive protocol FSM. One example of this is the co-op
close state machine, and also the channel state machine itself.

This packages picks out the common themes of:

  * clear states and transitions between them
  * calling out to special daemon adapters for I/O such as transaction
    broadcast or sending a message to a peer
  * cleaning up after state machine execution
  * notifying relevant callers of updates to the state machine

The goal of this PR, is that devs can now implement a state machine
based off of this primary interface:
```go
// State defines an abstract state along, namely its state transition function
// that takes as input an event and an environment, and returns a state
// transition (next state, and set of events to emit). As state can also either
// be terminal, or not, a terminal event causes state execution to halt.
type State[Event any, Env Environment] interface {
	// ProcessEvent takes an event and an environment, and returns a new
	// state transition. This will be iteratively called until either a
	// terminal state is reached, or no further internal events are
	// emitted.
	ProcessEvent(event Event, env Env) (*StateTransition[Event, Env], error)

	// IsTerminal returns true if this state is terminal, and false otherwise.
	IsTerminal() bool
}
```

With their focus being _only_ on each state transition, rather than all
the boiler plate involved (processing new events, advancing to
completion, doing I/O, etc, etc).

Instead, they just make their states, then create the state machine
given the starting state and env. The only other custom component needed
is something capable of mapping wire messages or other events from the
"outside world" into the domain of the state machine.

The set of types is based on a pseudo sum type system wherein you
declare an interface, make the sole method private, then create other
instances based on that interface. This restricts call sites (must pass
in that interface) type, and with some tooling, exhaustive matching can
also be enforced via a linter.

The best way to get a hang of the pattern proposed here is to check out
the tests. They make a mock state machine, and then use the new executor
to drive it to completion. You'll also get a view of how the code will
actually look, with the focus being on the: input event, current state,
and output transition (can also emit events to drive itself forward).

Author: Roasbeef

protofsm/daemon_events.go

@@ -0,0 +1,66 @@
+package protofsm
+
+import (
+	"github.com/btcsuite/btcd/btcec/v2"
+	"github.com/btcsuite/btcd/wire"
+	"github.com/lightningnetwork/lnd/fn"
+	"github.com/lightningnetwork/lnd/lnwire"
+)
+
+// DaemonEvent is a special event that can be emmitted by a state transition
+// function. A state machine can use this to perform side effects, such as
+// sending a message to a peer, or broadcasting a transaction.
+type DaemonEvent interface {
+	daemonSealed()
+}
+
+// DaemonEventSet is a set of daemon events that can be emitted by a state
+// transition.
+type DaemonEventSet []DaemonEvent
+
+// DaemonEvents is a special type constraint that enumerates all the possible
+// types of daemon events.
+type DaemonEvents interface {
+	SendMsgEvent[any] | BroadcastTxn
+}
+
+// SendPredicate is a function that returns true if the target message should
+// sent.
+type SendPredicate = func() bool
+
+// SendMsgEvent is a special event that can be emitted by a state transition
+// that instructs the daemon to send the contained message to the target peer.
+type SendMsgEvent[Event any] struct {
+	// TargetPeer is the peer to send the message to.
+	TargetPeer btcec.PublicKey
+
+	// Msgs is the set of messages to send to the target peer.
+	Msgs []lnwire.Message
+
+	// SendWhen implements a system for a conditional send once a special
+	// send predicate has been met.
+	//
+	// TODO(roasbeef): contrast with usage of OnCommitFlush, etc
+	SendWhen fn.Option[SendPredicate]
+
+	// PostSendEvent is an optional event that is to be emitted after the
+	// message has been sent. If a SendWhen is specified, then this will
+	// only be executed after that returns true to unblock the send.
+	PostSendEvent fn.Option[Event]
+}
+
+// daemonSealed indicates that this struct is a DaemonEvent instance.
+func (s *SendMsgEvent[E]) daemonSealed() {}
+
+// BroadcastTxn indicates the target transaction should be broadcast to the
+// network.
+type BroadcastTxn struct {
+	// Tx is the transaction to broadcast.
+	Tx *wire.MsgTx
+
+	// Label is an optional label to attach to the transaction.
+	Label string
+}
+
+// daemonSealed indicates that this struct is a DaemonEvent instance.
+func (b *BroadcastTxn) daemonSealed() {}

protofsm/log.go

@@ -0,0 +1,29 @@
+package protofsm
+
+import (
+	"github.com/btcsuite/btclog"
+	"github.com/lightningnetwork/lnd/build"
+)
+
+// log is a logger that is initialized with no output filters.  This
+// means the package will not perform any logging by default until the caller
+// requests it.
+var log btclog.Logger
+
+// The default amount of logging is none.
+func init() {
+	UseLogger(build.NewSubLogger("PRCL", nil))
+}
+
+// DisableLog disables all library log output.  Logging output is disabled
+// by default until UseLogger is called.
+func DisableLog() {
+	UseLogger(btclog.Disabled)
+}
+
+// UseLogger uses a specified Logger to output package logging info.
+// This should be used in preference to SetLogWriter if the caller is also
+// using btclog.
+func UseLogger(logger btclog.Logger) {
+	log = logger
+}