plugins: allow deprecated for registered commands to be an array of versions.

We still accept boolean: the plugin may not want to commit to a deprecation schedule.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Changelog-Added: Plugins: rpcmethods and options can set `deprecated` to a pair of version strings, not just a boolean.

doc/developers-guide/deprecations.md

@@ -5,8 +5,9 @@ excerpt: "Deprecated features and timeline for old feature removals."
 hidden: false
 ---
 
-| Name      | Type  | First Deprecated | Last Supported | Description |
-|-----------|-------|------------------|----------------|-------------|
+| Name              | Type    | First Deprecated | Last Supported | Description                       |
+|-------------------|---------|------------------|----------------|-----------------------------------|
+| delexpiredinvoice | Command | v22.11           | v24.02         | `autoclean-once` is more powerful |
 
 Inevitably there are features which need to change: either to be generalized, or removed when they can no longer be supported.
 

lightningd/invoice.c

@@ -1530,7 +1530,8 @@ static const struct json_command delexpiredinvoice_command = {
 	"payment",
 	json_delexpiredinvoice,
 	"Delete all expired invoices that expired as of given {maxexpirytime} (a UNIX epoch time), or all expired invoices if not specified",
-	.deprecated = true,
+	.depr_start = "v22.11",
+	.depr_end = "v24.02",
 };
 AUTODATA(json_command, &delexpiredinvoice_command);
 

lightningd/jsonrpc.c

@@ -464,12 +464,15 @@ static void json_add_help_command(struct command *cmd,
 	char *usage;
 
 	/* If they disallow deprecated APIs, don't even list them */
-	if (!cmd->ld->deprecated_apis && json_command->deprecated)
+	if (!command_deprecated_out_ok(cmd, NULL,
+				       json_command->depr_start,
+				       json_command->depr_end)) {
 		return;
+	}
 
 	usage = tal_fmt(cmd, "%s%s %s",
 			json_command->name,
-			json_command->deprecated ? " (DEPRECATED!)" : "",
+			json_command->depr_start ? " (DEPRECATED!)" : "",
 			strmap_get(&cmd->ld->jsonrpc->usagemap,
 				   json_command->name));
 	json_object_start(response, NULL);
@@ -532,7 +535,9 @@ static struct command_result *json_help(struct command *cmd,
 			return command_fail(cmd, JSONRPC2_METHOD_NOT_FOUND,
 					    "Unknown command %s",
 					    cmdname);
-		if (!cmd->ld->deprecated_apis && one_cmd->deprecated)
+		if (!command_deprecated_in_ok(cmd, NULL,
+					      one_cmd->depr_start,
+					      one_cmd->depr_end))
 			return command_fail(cmd, JSONRPC2_METHOD_NOT_FOUND,
 					    "Deprecated command %s",
 					    cmdname);
@@ -917,7 +922,10 @@ static void replace_command(struct rpc_command_hook_payload *p,
 			      buffer + method->start);
 		goto fail;
 	}
-	if (p->cmd->json_cmd->deprecated && !p->cmd->ld->deprecated_apis) {
+	if (!command_deprecated_in_ok(p->cmd,
+				      json_strdup(tmpctx, buffer, method),
+				      p->cmd->json_cmd->depr_start,
+				      p->cmd->json_cmd->depr_end)) {
 		bad = tal_fmt(tmpctx, "redirected to deprecated command '%.*s'",
 			      method->end - method->start,
 			      buffer + method->start);
@@ -1148,7 +1156,10 @@ parse_request(struct json_connection *jcon, const jsmntok_t tok[])
 		    c, JSONRPC2_METHOD_NOT_FOUND, "Unknown command '%.*s'",
 		    method->end - method->start, jcon->buffer + method->start);
 	}
-	if (c->json_cmd->deprecated && !jcon->ld->deprecated_apis) {
+	if (!command_deprecated_in_ok(c,
+				      json_strdup(tmpctx, jcon->buffer, method),
+				      c->json_cmd->depr_start,
+				      c->json_cmd->depr_end)) {
 		return command_fail(c, JSONRPC2_METHOD_NOT_FOUND,
 				    "Command %.*s is deprecated",
 				    json_tok_full_len(method),

lightningd/jsonrpc.h

@@ -63,7 +63,7 @@ struct json_command {
 	const char *description;
 	const char *verbose;
 	bool dev_only;
-	bool deprecated;
+	const char *depr_start, *depr_end;
 };
 
 struct jsonrpc_notification {

lightningd/plugin.c

@@ -11,6 +11,7 @@
 #include <ccan/utf8/utf8.h>
 #include <common/configdir.h>
 #include <common/configvar.h>
+#include <common/deprecation.h>
 #include <common/features.h>
 #include <common/json_command.h>
 #include <common/memleak.h>
@@ -995,6 +996,50 @@ static char *bool_setting(tal_t *ctx,
 	return NULL;
 }
 
+/* Parse deprecated field, as either bool or an array of strings */
+static const char *json_parse_deprecated(const tal_t *ctx,
+					 const char *buffer,
+					 const jsmntok_t *deprtok,
+					 const char **depr_start,
+					 const char **depr_end)
+{
+	bool is_depr;
+
+	*depr_start = *depr_end = NULL;
+
+	if (!deprtok)
+		return NULL;
+
+	/* Not every plugin will track deprecation cycles (and that's OK!):
+	 * pretend it's just been deprecated. */
+	if (json_to_bool(buffer, deprtok, &is_depr)) {
+		if (is_depr)
+			*depr_start = CLN_NEXT_VERSION;
+		return NULL;
+	}
+
+	if (deprtok->type != JSMN_ARRAY || deprtok->size > 2) {
+		return tal_fmt(ctx, "\"deprecated\" must be an array of 1 or 2 elements, not %.*s",
+			       deprtok->end - deprtok->start,
+			       buffer + deprtok->start);
+	}
+
+	*depr_start = json_strdup(ctx, buffer, deprtok + 1);
+	if (version_to_number(*depr_start) == 0)
+		return tal_fmt(ctx,
+			       "invalid \"deprecated\" start version %s",
+			       *depr_start);
+
+	if (deprtok->size == 2) {
+		*depr_end = json_strdup(ctx, buffer, deprtok + 2);
+		if (version_to_number(*depr_end) == 0)
+			return tal_fmt(ctx,
+				       "invalid \"deprecated\" end version %s",
+				       *depr_end);
+	}
+	return NULL;
+}
+
 /* Add a single plugin option to the plugin as well as registering it with the
  * command line options. */
 static const char *plugin_opt_add(struct plugin *plugin, const char *buffer,
@@ -1268,16 +1313,16 @@ static const char *plugin_rpcmethod_add(struct plugin *plugin,
 					const jsmntok_t *meth)
 {
 	const jsmntok_t *nametok, *categorytok, *desctok, *longdesctok,
-		*usagetok, *deptok;
+		*usagetok, *deprtok;
 	struct json_command *cmd;
-	const char *usage;
+	const char *usage, *err;
 
 	nametok = json_get_member(buffer, meth, "name");
 	categorytok = json_get_member(buffer, meth, "category");
 	desctok = json_get_member(buffer, meth, "description");
 	longdesctok = json_get_member(buffer, meth, "long_description");
 	usagetok = json_get_member(buffer, meth, "usage");
-	deptok = json_get_member(buffer, meth, "deprecated");
+	deprtok = json_get_member(buffer, meth, "deprecated");
 
 	if (!nametok || nametok->type != JSMN_STRING) {
 		return tal_fmt(plugin,
@@ -1321,15 +1366,9 @@ static const char *plugin_rpcmethod_add(struct plugin *plugin,
 		return tal_fmt(plugin,
 			    "\"usage\" not provided by plugin");
 
-	if (deptok) {
-		if (!json_to_bool(buffer, deptok, &cmd->deprecated))
-			return tal_fmt(plugin,
-				       "%s: invalid \"deprecated\" field %.*s",
-				       cmd->name,
-			               deptok->end - deptok->start,
-				       buffer + deptok->start);
-	} else
-		cmd->deprecated = false;
+	err = json_parse_deprecated(cmd, buffer, deprtok, &cmd->depr_start, &cmd->depr_end);
+	if (err)
+		return tal_steal(plugin, err);
 
 	cmd->dev_only = false;
 	cmd->dispatch = plugin_rpcmethod_dispatch;