Browse Source

JSON-RPC: notifications command.

This lets callers enable notifications; we won't send any if they don't.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Changelog-Added: JSON-RPC: `notifications` command to enable notifications.
travis-experimental
Rusty Russell 4 years ago
parent
commit
c732d8707a
  1. 1
      doc/Makefile
  2. 1
      doc/index.rst
  3. 112
      doc/lightning-notifications.7
  4. 99
      doc/lightning-notifications.7.md
  5. 29
      lightningd/jsonrpc.c
  6. 5
      lightningd/test/run-jsonrpc.c

1
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 \

1
doc/index.rst

@ -68,6 +68,7 @@ c-lightning Documentation
lightning-multifundchannel <lightning-multifundchannel.7.md>
lightning-multiwithdraw <lightning-multiwithdraw.7.md>
lightning-newaddr <lightning-newaddr.7.md>
lightning-notifications <lightning-notifications.7.md>
lightning-openchannel_init <lightning-openchannel_init.7.md>
lightning-openchannel_signed <lightning-openchannel_signed.7.md>
lightning-openchannel_update <lightning-openchannel_update.7.md>

112
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<rusty@blockstream.com\fR> wrote the initial version of this man page\.
.SH RESOURCES
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:2b6e9c8a814cb8de7b15e70de3563be5311e232e974f546d79c546aec641c3fe

99
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 <<rusty@blockstream.com>> wrote the initial version of this man page.
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>

29
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, &notifications_command);

5
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,

Loading…
Cancel
Save