From ae614c2e96bbb574c1dd591bdcf5741752cbe0c0 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 18 Mar 2019 13:10:32 +1030 Subject: [PATCH] doc: document the current limitations of the db_write hook. In theory we could allow a db_write-using plugin to have other hooks/commands by embargoing their other responses until the exclusive period is over. That would be nice for a 'dbmirrorinfo' command, for example. The other option would be to *always* go exclusive on a db_write-using plugin, so responses can never get intermingled. Signed-off-by: Rusty Russell --- doc/PLUGINS.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/doc/PLUGINS.md b/doc/PLUGINS.md index cbab9562e..6f05ae7ce 100644 --- a/doc/PLUGINS.md +++ b/doc/PLUGINS.md @@ -16,8 +16,6 @@ variety of ways: internal events in `lightningd` and alter its behavior or inject custom behaviors. -*Note: Hooks are not yet implemented, and the API is under active development.* - A plugin may be written in any language, and communicates with `lightningd` through the plugin's `stdin` and `stdout`. JSON-RPCv2 is used as protocol on top of the two streams, with the plugin acting as @@ -270,5 +268,25 @@ 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. +#### `db_write` + +This hook is called whenever a change is about to be committed to the database. +It is currently extremely restricted: + +1. a plugin registering for this hook should not perform anything that may cause + a db operation in response (pretty much, anything but logging). +2. a plugin registering for this hook should not register for other hooks or + commands, as these may become intermingled and break rule #1. +3. the hook will be called before your plugin is initialized! + +```json +{ + "writes": [ "PRAGMA foreign_keys = ON" ] +} +``` + +Any response but "true" will cause lightningd to error without +committing to the database! + [jsonrpc-spec]: https://www.jsonrpc.org/specification [jsonrpc-notification-spec]: https://www.jsonrpc.org/specification#notification