diff --git a/doc/Makefile b/doc/Makefile index db06325b5..d89389d58 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -40,6 +40,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-multifundchannel.7 \ doc/lightning-multiwithdraw.7 \ doc/lightning-newaddr.7 \ + doc/lightning-notifications.7 \ doc/lightning-openchannel_init.7 \ doc/lightning-openchannel_signed.7 \ doc/lightning-openchannel_update.7 \ diff --git a/doc/index.rst b/doc/index.rst index d234a6560..83c2744ed 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -68,6 +68,7 @@ c-lightning Documentation lightning-multifundchannel lightning-multiwithdraw lightning-newaddr + lightning-notifications lightning-openchannel_init lightning-openchannel_signed lightning-openchannel_update diff --git a/doc/lightning-notifications.7 b/doc/lightning-notifications.7 new file mode 100644 index 000000000..704682c52 --- /dev/null +++ b/doc/lightning-notifications.7 @@ -0,0 +1,112 @@ +.TH "LIGHTNING-NOTIFICATIONS" "7" "" "" "lightning-notifications" +.SH NAME +lightning-notifications - Command to set up notifications\. +.SH SYNOPSIS + +\fBnotifications\fR \fIenable\fR + +.SH DESCRIPTION + +The \fBnotifications\fR the RPC command enabled notifications for this JSON-RPC +connection\. By default (and for backwards-compatibility) notifications are +disabled\. + + +Various commands, especially complex and slow ones, offer +notifications which indicate their progress\. + +.RS +.IP \[bu] +\fIenable\fR: \fItrue\fR to enable notifications, \fIfalse\fR to disable them\. + +.RE +.SH EXAMPLE JSON REQUEST +.nf +.RS +{ + "id": 82, + "method": "notifications", + "params": { + "enable": true + } +} +.RE + +.fi +.SH NOTIFICATIONS + +Notifications are JSON-RPC objects without an \fIid\fR field\. \fIlightningd\fR sends +notifications (once enabled with this \fInotifications\fR command) with a \fIparams\fR +\fIid\fR field indicating which command the notification refers to\. + + +Implementations should ignore notifications without an \fIid\fR parameter, or +unknown \fImethod\fR\. + + +Common \fImethod\fRs include: + +.RS +.IP \[bu] +\fImessage\fR: param \fImessage\fR: a descriptional string indicating something +which occurred relating to the command\. Param \fIlevel\fR indicates the level, +as per \fBlightning-getlog\fR(7): \fIinfo\fR and \fIdebug\fR are typical\. +.IP \[bu] +\fIprogress\fR: param \fInum\fR and \fItotal\fR, where \fInum\fR starts at 0 and is always +less than \fItotal\fR\. Optional param \fIstage\fR with fields \fInum\fR and \fItotal\fR, +indicating what stage we are progressing through\. + +.RE +.SH RETURN VALUE + +On success, an empty object will be returned, and if the level was +\fItrue\fR, notifications will be forwarded from then on\. + + +On failure, one of the following error codes may be returned: + +.RS +.IP \[bu] +-32602: Error in given parameters\. + +.RE +.SH EXAMPLE NOTIFICATIONS +.nf +.RS +{ + "method": "message", + "params": { + "id": 83, + "message": "This is a test message", + "level": "DEBUG" + } +} +.RE + +.fi +.nf +.RS +{ + "method": "progress", + "params": { + "id": 83, + "num": 0, + "total": 30 + "stage": { + "num": 0, + "total": 2 + } + } +} +.RE + +.fi +.SH AUTHOR + +Rusty Russell \fI wrote the initial version of this man page\. + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + +\" SHA256STAMP:2b6e9c8a814cb8de7b15e70de3563be5311e232e974f546d79c546aec641c3fe diff --git a/doc/lightning-notifications.7.md b/doc/lightning-notifications.7.md new file mode 100644 index 000000000..02086d390 --- /dev/null +++ b/doc/lightning-notifications.7.md @@ -0,0 +1,99 @@ +lightning-notifications -- Command to set up notifications. +========================================= + +SYNOPSIS +-------- + +**notifications** *enable* + +DESCRIPTION +----------- + +The **notifications** the RPC command enabled notifications for this JSON-RPC +connection. By default (and for backwards-compatibility) notifications are +disabled. + +Various commands, especially complex and slow ones, offer +notifications which indicate their progress. + +- *enable*: *true* to enable notifications, *false* to disable them. + +EXAMPLE JSON REQUEST +-------------------- +```json +{ + "id": 82, + "method": "notifications", + "params": { + "enable": true + } +} +``` + +NOTIFICATIONS +------------- + +Notifications are JSON-RPC objects without an *id* field. *lightningd* sends +notifications (once enabled with this *notifications* command) with a *params* +*id* field indicating which command the notification refers to. + +Implementations should ignore notifications without an *id* parameter, or +unknown *method*. + +Common *method*s include: + +- *message*: param *message*: a descriptional string indicating something + which occurred relating to the command. Param *level* indicates the level, + as per lightning-getlog(7): *info* and *debug* are typical. +- *progress*: param *num* and *total*, where *num* starts at 0 and is always + less than *total*. Optional param *stage* with fields *num* and *total*, + indicating what stage we are progressing through. + +RETURN VALUE +------------ + +On success, an empty object will be returned, and if the level was +*true*, notifications will be forwarded from then on. + +On failure, one of the following error codes may be returned: + +- -32602: Error in given parameters. + +EXAMPLE NOTIFICATIONS +--------------------- + +```json +{ + "method": "message", + "params": { + "id": 83, + "message": "This is a test message", + "level": "DEBUG" + } +} +``` + +```json +{ + "method": "progress", + "params": { + "id": 83, + "num": 0, + "total": 30 + "stage": { + "num": 0, + "total": 2 + } + } +} +``` + +AUTHOR +------ + +Rusty Russell <> wrote the initial version of this man page. + +RESOURCES +--------- + +Main web site: diff --git a/lightningd/jsonrpc.c b/lightningd/jsonrpc.c index 49fa83fbb..e70051534 100644 --- a/lightningd/jsonrpc.c +++ b/lightningd/jsonrpc.c @@ -96,6 +96,9 @@ struct json_connection { /* Our commands */ struct list_head commands; + /* Are notifications enabled? */ + bool notifications_enabled; + /* Our json_streams (owned by the commands themselves while running). * Since multiple streams could start returning data at once, we * always service these in order, freeing once empty. */ @@ -973,6 +976,7 @@ static struct io_plan *jcon_connected(struct io_conn *conn, jcon->len_read = 0; jsmn_init(&jcon->input_parser); jcon->input_toks = toks_alloc(jcon); + jcon->notifications_enabled = false; list_head_init(&jcon->commands); /* We want to log on destruction, so we free this in destructor. */ @@ -1292,3 +1296,28 @@ static const struct json_command check_command = { }; AUTODATA(json_command, &check_command); + +static struct command_result *json_notifications(struct command *cmd, + const char *buffer, + const jsmntok_t *obj UNNEEDED, + const jsmntok_t *params) +{ + bool *enable; + + if (!param(cmd, buffer, params, + p_req("enable", param_bool, &enable), + NULL)) + return command_param_failed(); + + cmd->jcon->notifications_enabled = *enable; + return command_success(cmd, json_stream_success(cmd)); +} + +static const struct json_command notifications_command = { + "notifications", + "utility", + json_notifications, + "Enable notifications for {level} (or 'false' to disable)", +}; + +AUTODATA(json_command, ¬ifications_command); diff --git a/lightningd/test/run-jsonrpc.c b/lightningd/test/run-jsonrpc.c index 19d95c540..444401c08 100644 --- a/lightningd/test/run-jsonrpc.c +++ b/lightningd/test/run-jsonrpc.c @@ -68,6 +68,11 @@ struct oneshot *new_reltimer_(struct timers *timers UNNEEDED, bool param(struct command *cmd UNNEEDED, const char *buffer UNNEEDED, const jsmntok_t params[] UNNEEDED, ...) { fprintf(stderr, "param called!\n"); abort(); } +/* Generated stub for param_bool */ +struct command_result *param_bool(struct command *cmd UNNEEDED, const char *name UNNEEDED, + const char *buffer UNNEEDED, const jsmntok_t *tok UNNEEDED, + bool **b UNNEEDED) +{ fprintf(stderr, "param_bool called!\n"); abort(); } /* Generated stub for param_feerate_estimate */ struct command_result *param_feerate_estimate(struct command *cmd UNNEEDED, u32 **feerate_per_kw UNNEEDED,