From 9b721ceca7d180be78ecc1a803d774af1da203e2 Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Fri, 8 Feb 2019 16:15:44 +0100 Subject: [PATCH] plugin: Add docs for hooks Signed-off-by: Christian Decker --- doc/PLUGINS.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/doc/PLUGINS.md b/doc/PLUGINS.md index 447de1296..cbab9562e 100644 --- a/doc/PLUGINS.md +++ b/doc/PLUGINS.md @@ -222,8 +222,53 @@ to a peer was lost. ``` ## Hooks -*TBD* +Hooks allow a plugin to define custom behavior for `lightningd` +without having to modify the c-lightning source code itself. A plugin +declares that it'd like to consulted on what to do next for certain +events in the daemon. A hook can then decide how `lightningd` should +react to the given event. +Hooks and notifications sounds very similar, however there are a few +key differences: + + - Notifications are asynchronous, i.e., `lightningd` will send the + notifications but not wait for the plugin to process them. Hooks on + the other hand are synchronous, `lightningd` cannot finish + processing the event until the plugin has returned. + - Any number of plugins can subscribe to a notification topic, + however only one plugin may register for any hook topic at any + point in time (we cannot disambiguate between multiple plugins + returning contradictory results from a hook callback). + +Hooks are considered to be an advanced feature due to the fact that +`lightningd` relies on the plugin to tell it what to do next. Use them +carefully, and make sure your plugins always return a valid response +to any hook invocation. + +### Hook Types + +#### `peer_connected` + +This hook is called whenever a peer has connected and successfully completed +the cryptographic handshake. The parameters have the following structure if there is a channel with the peer: + +```json +{ + "peer": { + "id": "03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f", + "addr": "34.239.230.56:9735", + "globalfeatures": "", + "localfeatures": "" + } +} +``` + +The hook is sparse on purpose, since the plugin can use the JSON-RPC +`listpeers` command to get additional details should they be required. The +`addr` field shows the address that we are connected to ourselves, not the +gossiped list of known addresses. In particular this means that the port for +incoming connections is an ephemeral port, that may not be available for +reconnections. [jsonrpc-spec]: https://www.jsonrpc.org/specification [jsonrpc-notification-spec]: https://www.jsonrpc.org/specification#notification