In this commit, we add an option to allow a conf req caller to receive
the full block. This is useful if the caller wants to be able to create
an SPV proof.
This commit introduces a new generic type assertion function
`assertState` to the state machine tests. This function asserts that the
state machine is currently in the expected state type and returns the
state cast to that type. This allows us to directly access the fields of
the state without having to perform a type assertion manually.
In this commit, we add a new ConfMapper which is useful for state
machines that want to project some of the conf attributes into a new
event to be sent post conf.
This commit introduces a new `IsRunning()` method to the `StateMachine`.
This method allows callers to safely query whether the state machine
is currently active after it has been started and before it has been
stopped.
To ensure thread-safety, the internal `running` status flag is
implemented using `atomic.Bool` (from `sync/atomic`). Without atomic
operations, concurrent accesses to a simple boolean flag from different
goroutines (e.g., one goroutine calling `IsRunning()` while another
executes `Start()` or `Stop()`) could lead to stale reads or data races.
In this commit, we reduce log spam a bit during state transitions. We
only log the type of the event when sending the event, as we'll print
the same event when creating the queue "applying", and later when
processing". Next we remove the "applying" log as that first event will
always be logged twice.
The combo of these to changes makes the logs much easier to follow.
In this commit, we add an upfront check for `SendWhen` predicates before
deciding to launch a goroutine. This ensures that when a message comes
along that is already ready to send, we do the send in a synchronous
manner.
We don't return an error on broadcast fail as the broadcast might have
failed due to insufficient fees, or inability to be replaced, which may
happen when one side attempts to unnecessarily bump their coop close
fee.
This commit updates the fn dep to the version containing the updates to
the ContextGuard implementation. Only the htlcswitch/link uses the guard
at the moment so this is updated to make use of the new implementation.
Find and replace all nolint instances refering to the `lll` linter and
replace with `ll` which is the name of our custom version of the `lll`
linter which can be used to ignore log lines during linting.
The next commit will do the configuration of the custom linter and
disable the default one.
In this commit, we fix an existing race in the new `protofsm` state
machine executor tests.
The race would appear as such:
```
--- FAIL: TestStateMachineMsgMapper (0.00s)
state_machine_test.go:165:
Error Trace:/home/runner/work/lnd/lnd/protofsm/state_machine_test.go:165
/home/runner/work/lnd/lnd/protofsm/state_machine_test.go:451
Error: Object expected to be of type *protofsm.dummyStateStart, but was *protofsm.dummyStateFin
Test: TestStateMachineMsgMapper
FAIL
FAILgithub.com/lightningnetwork/lnd/protofsm0.116s
FAIL
```
This race condition was triggered as before we would start the state
machine _then_ register for notifications. In `Start` we emit the
starting event, then enter the main loop. If that event gets emitted
before our subscription, then we'll miss the event, as the terminal
event will be the only one received.
We fix this by registering for the events before the daemon has started.
In this commit, we update the execution logic to allow multiple internal
events to be emitted. This is useful to handle potential out of order
state transitions, as they can be cached, then emitted once the relevant
pre-conditions have been met.
In this commit, we add the SpendMapper which allows callers to create
custom spent events. Before this commit, the caller would be able to
have an event sent to them in the case a spend happens, but that event
wouldn't have any of the relevant spend details.
With this new addition, the caller can specify how to take a generic
spend event, and transform it into the state machine specific spend
event.
In this commit, we add the ability for the state machine to consume wire
messages. This'll allow the creation of a new generic message router
that takes the place of the current peer `readHandler` in an upcoming
commit.
In this commit, we add an optional daemon event that can be specified to
dispatch during init. This is useful for instances where before we
start, we want to make sure we have a registered spend/conf notification
before normal operation starts.
We also add new unit tests to cover this, and the prior spend/conf event
additions.
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).
