Clarify and consolidate event handling requirements

We've seen a bit of user confusion about the requirements for event
handling, largely because the idempotency and consistency
requirements weren't super clearly phrased. While we're at it, we
also consolidate some documentation out of the event handling
function onto the trait itself.

Fixes #1675.

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 3b83726958b3a655b681f9a821d114b5a97e7c8a..81bcb3b8c0a1b409e9bef3dfaeb6bdd96644effc 100644 (file)
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -5671,10 +5671,6 @@ where
        ///
        /// An [`EventHandler`] may safely call back to the provider in order to handle an event.
        /// However, it must not call [`Writeable::write`] as doing so would result in a deadlock.
-       ///
-       /// Pending events are persisted as part of [`ChannelManager`]. While these events are cleared
-       /// when processed, an [`EventHandler`] must be able to handle previously seen events when
-       /// restarting from an old state.
        fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler {
                PersistenceNotifierGuard::optionally_notify(&self.total_consistency_lock, &self.persistence_notifier, || {
                        let mut result = NotifyOption::SkipPersist;

diff --git a/lightning/src/util/events.rs b/lightning/src/util/events.rs
index e86eae3c813a8af7a3684480171df913ea0883bd..4277e7496abeb8ad8b8de812fc52740e75184095 100644 (file)
--- a/lightning/src/util/events.rs
+++ b/lightning/src/util/events.rs
@@ -1207,11 +1207,17 @@ pub trait OnionMessageProvider {
 ///
 /// # Requirements
 ///
-/// See [`process_pending_events`] for requirements around event processing.
-///
 /// When using this trait, [`process_pending_events`] will call [`handle_event`] for each pending
-/// event since the last invocation. The handler must either act upon the event immediately
-/// or preserve it for later handling.
+/// event since the last invocation.
+///
+/// In order to ensure no [`Event`]s are lost, implementors of this trait will persist [`Event`]s
+/// and replay any unhandled events on startup. An [`Event`] is considered handled when
+/// [`process_pending_events`] returns, thus handlers MUST fully handle [`Event`]s and persist any
+/// relevant changes to disk *before* returning.
+///
+/// Further, because an application may crash between an [`Event`] being handled and the
+/// implementor of this trait being re-serialized, [`Event`] handling must be idempotent - in
+/// effect, [`Event`]s may be replayed.
 ///
 /// Note, handlers may call back into the provider and thus deadlocking must be avoided. Be sure to
 /// consult the provider's documentation on the implication of processing events and how a handler
@@ -1228,9 +1234,7 @@ pub trait OnionMessageProvider {
 pub trait EventsProvider {
        /// Processes any events generated since the last call using the given event handler.
        ///
-       /// Subsequent calls must only process new events. However, handlers must be capable of handling
-       /// duplicate events across process restarts. This may occur if the provider was recovered from
-       /// an old state (i.e., it hadn't been successfully persisted after processing pending events).
+       /// See the trait-level documentation for requirements.
        fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler;
 }