From 61c07bca45baaeeb2df8be541f7e3b3537392776 Mon Sep 17 00:00:00 2001 From: darosior Date: Mon, 16 Sep 2019 11:36:05 +0200 Subject: [PATCH] doc: Document the changes to the 'plugin' command --- CHANGELOG.md | 3 +++ doc/lightning-plugin.7 | 25 ++++++++++++++----------- doc/lightning-plugin.7.md | 18 ++++++++++++------ 3 files changed, 29 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e635a35be..8e4659f63 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - JSON API: `fundchannel_cancel` is extended to work before funding broadcast. - JSON API: The parameter `exclude` of `getroute` now also support node-id. - JSON-API: `pay` can exclude error nodes if the failcode of `sendpay` has the NODE bit set +- JSON API: The `plugin` command now returns on error. A timeout of 20 seconds is added to `start` and `startdir` + subcommands at the end of which the plugin is errored if it did not complete the handshake with `lightningd`. +- JSON API: The `plugin` command does not allow to start static plugins after `lightningd` startup anymore. ### Deprecated diff --git a/doc/lightning-plugin.7 b/doc/lightning-plugin.7 index dcd6e0cc4..f1e86968f 100644 --- a/doc/lightning-plugin.7 +++ b/doc/lightning-plugin.7 @@ -14,16 +14,18 @@ optionally one or two parameters which describes the plugin on which the action has to be taken\. -The \fIstart\fR command takes a path as parameter and will load the plugin -available from this path\. +The \fIstart\fR command takes a path as the first parameter and will load the +plugin available from this path\. It will wait for the plugin to complete +the handshake with \fBlightningd\fR for 20 seconds at the most\. -The \fIstop\fR command takes a plugin name as parameter and will kill and +The \fIstop\fR command takes a plugin name as parameter\. It will kill and unload the specified plugin\. -The \fIstartdir\fR command takes a directory path as parameter and will load -all plugins this directory contains\. +The \fIstartdir\fR command takes a directory path as first parameter and will +load all plugins this directory contains\. It will wait for each plugin to +complete the handshake with \fBlightningd\fR for 20 seconds at the most\. The \fIrescan\fR command starts all not-already-loaded plugins from the @@ -34,20 +36,21 @@ The \fIlist\fR command will return all the active plugins\. .SH RETURN VALUE -On success, this returns an array \fIplugins\fR of objects, one by plugin\. +On success, all subcommands but \fIstop\fR return an array \fIplugins\fR of +objects, one by plugin\. Each object contains the name of the plugin (\fIname\fR field) and its status (\fIactive\fR boolean field)\. Since plugins are configured asynchronously, a freshly started plugin may not appear immediately\. + +On error, the reason why the action could not be taken upon the +plugin is returned\. + .SH AUTHOR -Antoine Poinsot \fI is mainly responsible\. +Antoine Poinsot (\fIdarosior@protonmail.com\fR) is mainly responsible\. .SH RESOURCES Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -.HL - -Last updated 2019-07-29 12:57:57 CEST - diff --git a/doc/lightning-plugin.7.md b/doc/lightning-plugin.7.md index 467e083e9..1cec9a94b 100644 --- a/doc/lightning-plugin.7.md +++ b/doc/lightning-plugin.7.md @@ -15,14 +15,16 @@ restart lightningd. It takes 1 to 3 parameters: a command optionally one or two parameters which describes the plugin on which the action has to be taken. -The *start* command takes a path as parameter and will load the plugin -available from this path. +The *start* command takes a path as the first parameter and will load the +plugin available from this path. It will wait for the plugin to complete +the handshake with `lightningd` for 20 seconds at the most. -The *stop* command takes a plugin name as parameter and will kill and +The *stop* command takes a plugin name as parameter. It will kill and unload the specified plugin. -The *startdir* command takes a directory path as parameter and will load -all plugins this directory contains. +The *startdir* command takes a directory path as first parameter and will +load all plugins this directory contains. It will wait for each plugin to +complete the handshake with `lightningd` for 20 seconds at the most. The *rescan* command starts all not-already-loaded plugins from the default plugins directory (by default *~/.lightning/plugins*). @@ -32,11 +34,15 @@ The *list* command will return all the active plugins. RETURN VALUE ------------ -On success, this returns an array *plugins* of objects, one by plugin. +On success, all subcommands but *stop* return an array *plugins* of +objects, one by plugin. Each object contains the name of the plugin (*name* field) and its status (*active* boolean field). Since plugins are configured asynchronously, a freshly started plugin may not appear immediately. +On error, the reason why the action could not be taken upon the +plugin is returned. + AUTHOR ------