From 654a60ca4e1367b49094cb86cd1ca04741cb51dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oto=20=C5=A0=C5=A5=C3=A1va?= <oto.stava@nic.cz>
Date: Wed, 28 Aug 2024 17:32:43 +0200
Subject: [PATCH] daemon/session2: comment on event propagation
Minor, but I believe quite important. I stumbled across this while
writing the protocol layer article and thought it was not emphasized
enough in the docs.
---
daemon/session2.h | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/daemon/session2.h b/daemon/session2.h
index 604c43a1d..514e7b7ad 100644
--- a/daemon/session2.h
+++ b/daemon/session2.h
@@ -575,7 +575,12 @@ enum protolayer_event_cb_result {
*
* When `PROTOLAYER_EVENT_PROPAGATE` is returned, iteration over the sequence
* of layers continues. When `PROTOLAYER_EVENT_CONSUME` is returned, iteration
- * stops. */
+ * stops.
+ *
+ * **IMPORTANT:** A well-behaved layer will **ALWAYS** propagate events it knows
+ * nothing about. Only ever consume events you actually have good reason to
+ * consume (like TLS consumes `CONNECT` from TCP, because it needs to perform
+ * its own handshake first). */
typedef enum protolayer_event_cb_result (*protolayer_event_cb)(
enum protolayer_event_type event, void **baton,
struct session2 *session, void *sess_data);
--
GitLab