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.

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 \

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>

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

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>

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);

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,