From 612f3de0d4a07851c8f25ed8e2c359ecea7e3e2f Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 19 Sep 2022 10:23:00 +0930 Subject: [PATCH] doc: manpages and schemas for autoclean-status. And remove deprecated autocleaninvoice docs. Signed-off-by: Rusty Russell Changelog-Added: Plugins: `autoclean-status` command to see what autoclean is doing. Changelog-Deprecated: JSON-RPC: `autocleaninvoice` (use option `autoclean-expiredinvoices-age`) --- doc/Makefile | 2 +- doc/index.rst | 2 +- doc/lightning-autoclean-status.7.md | 94 ++++++ doc/lightning-autocleaninvoice.7.md | 55 ---- doc/lightning-delexpiredinvoice.7.md | 2 +- doc/lightning-delinvoice.7.md | 2 +- doc/lightning-listforwards.7.md | 2 +- doc/schemas/autoclean-status.request.json | 20 ++ doc/schemas/autoclean-status.schema.json | 346 ++++++++++++++++++++++ 9 files changed, 465 insertions(+), 60 deletions(-) create mode 100644 doc/lightning-autoclean-status.7.md delete mode 100644 doc/lightning-autocleaninvoice.7.md create mode 100644 doc/schemas/autoclean-status.request.json create mode 100644 doc/schemas/autoclean-status.schema.json diff --git a/doc/Makefile b/doc/Makefile index 6beb0d852..cb3b3d411 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -8,7 +8,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightningd.8 \ doc/lightningd-config.5 \ doc/lightning-addgossip.7 \ - doc/lightning-autocleaninvoice.7 \ + doc/lightning-autoclean-status.7 \ doc/lightning-bkpr-channelsapy.7 \ doc/lightning-bkpr-dumpincomecsv.7 \ doc/lightning-bkpr-inspect.7 \ diff --git a/doc/index.rst b/doc/index.rst index 80331e079..13bdbb48a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -30,7 +30,7 @@ Core Lightning Documentation :caption: Manpages lightning-addgossip - lightning-autocleaninvoice + lightning-autoclean-status lightning-bkpr-channelsapy lightning-bkpr-dumpincomecsv lightning-bkpr-inspect diff --git a/doc/lightning-autoclean-status.7.md b/doc/lightning-autoclean-status.7.md new file mode 100644 index 000000000..ca22f2675 --- /dev/null +++ b/doc/lightning-autoclean-status.7.md @@ -0,0 +1,94 @@ +lightning-autoclean-status -- Examine auto-delete of old invoices/payments/forwards +=================================================================================== + +SYNOPSIS +-------- + +**autoclean-status** [*subsystem*] + +DESCRIPTION +----------- + +The **autoclean-status** RPC command tells you about the status of +the autclean plugin, optionally for only one subsystem. + +The subsystems currently supported are: + +* `failedforwards`: routed payments which did not succeed (`failed` or `local_failed` in listforwards `status`). +* `succeededforwards`: routed payments which succeeded (`settled` in listforwards `status`). +* `failedpays`: payment attempts which did not succeed (`failed` in listpays `status`). +* `succededpays`: payment attempts which succeeded (`complete` in listpays `status`). +* `expiredinvoices`: invoices which were not paid (and cannot be) (`expired` in listinvoices `status`). +* `paidinvoices`: invoices which were paid (`paid` in listinvoices `status). + +RETURN VALUE +------------ + +Note that the ages parameters are set by various `autoclean-...-age` +parameters in your configuration: see lightningd-config(5). + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **autoclean** is returned. It is an object containing: + +- **succeededforwards** (object, optional): + - **enabled** (boolean): whether autocleaning is enabled for successful listforwards + - **cleaned** (u64): total number of deletions done (ever) + + If **enabled** is *true*: + + - **age** (u64): age (in seconds) to delete successful listforwards +- **failedforwards** (object, optional): + - **enabled** (boolean): whether autocleaning is enabled for failed listforwards + - **cleaned** (u64): total number of deletions done (ever) + + If **enabled** is *true*: + + - **age** (u64): age (in seconds) to delete failed listforwards +- **succeededpays** (object, optional): + - **enabled** (boolean): whether autocleaning is enabled for successful listpays/listsendpays + - **cleaned** (u64): total number of deletions done (ever) + + If **enabled** is *true*: + + - **age** (u64): age (in seconds) to delete successful listpays/listsendpays +- **failedpays** (object, optional): + - **enabled** (boolean): whether autocleaning is enabled for failed listpays/listsendpays + - **cleaned** (u64): total number of deletions done (ever) + + If **enabled** is *true*: + + - **age** (u64): age (in seconds) to delete failed listpays/listsendpays +- **paidinvoices** (object, optional): + - **enabled** (boolean): whether autocleaning is enabled for paid listinvoices + - **cleaned** (u64): total number of deletions done (ever) + + If **enabled** is *true*: + + - **age** (u64): age (in seconds) to paid listinvoices +- **expiredinvoices** (object, optional): + - **enabled** (boolean): whether autocleaning is enabled for expired (unpaid) listinvoices + - **cleaned** (u64): total number of deletions done (ever) + + If **enabled** is *true*: + + - **age** (u64): age (in seconds) to expired listinvoices + +[comment]: # (GENERATE-FROM-SCHEMA-END) + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightningd-config(5), lightning-listinvoices(7), +lightning-listpays(7), lightning-listforwards(7). + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:9431024693a7c26f9519ef24bdfb8b5c26902bdc0631d427f89c9e49ecd88e13) diff --git a/doc/lightning-autocleaninvoice.7.md b/doc/lightning-autocleaninvoice.7.md deleted file mode 100644 index 1aa59ef1c..000000000 --- a/doc/lightning-autocleaninvoice.7.md +++ /dev/null @@ -1,55 +0,0 @@ -lightning-autocleaninvoice -- Set up auto-delete of expired invoice -=================================================================== - -SYNOPSIS --------- - -**autocleaninvoice** [*cycle\_seconds*] [*expired\_by*] - -DESCRIPTION ------------ - -The **autocleaninvoice** RPC command sets up automatic cleaning of -expired invoices. - -Autoclean will be done every *cycle\_seconds* seconds. Setting -*cycle\_seconds* to 0 disables autoclean. If not specified, this -defaults to 3600 (one hour). - -Every autoclean cycle, expired invoices, which have already been expired -for at least *expired\_by* seconds, will be deleted. If *expired\_by* is -not specified, this defaults to 86400 (one day). - -On startup of the daemon, no autoclean is set up. - -RETURN VALUE ------------- - -[comment]: # (GENERATE-FROM-SCHEMA-START) -On success, an object is returned, containing: - -- **enabled** (boolean): whether invoice autocleaning is active - -If **enabled** is *true*: - - - **expired\_by** (u64): how long an invoice must be expired (seconds) before we delete it - - **cycle\_seconds** (u64): how long an invoice must be expired (seconds) before we delete it - -[comment]: # (GENERATE-FROM-SCHEMA-END) - -AUTHOR ------- - -ZmnSCPxj <> is mainly responsible. - -SEE ALSO --------- - -lightning-delexpiredinvoice(7), lightning-delinvoice(7) - -RESOURCES ---------- - -Main web site: - -[comment]: # ( SHA256STAMP:994e8f17bf35fc704f13206bf4c6909b525f9edcb1c8c4508345c720b007d34c) diff --git a/doc/lightning-delexpiredinvoice.7.md b/doc/lightning-delexpiredinvoice.7.md index c670f543e..e2a9c3c45 100644 --- a/doc/lightning-delexpiredinvoice.7.md +++ b/doc/lightning-delexpiredinvoice.7.md @@ -31,7 +31,7 @@ ZmnSCPxj <> is mainly responsible. SEE ALSO -------- -lightning-delinvoice(7), lightning-autocleaninvoice(7) +lightning-delinvoice(7), lightning-autoclean-status(7) RESOURCES --------- diff --git a/doc/lightning-delinvoice.7.md b/doc/lightning-delinvoice.7.md index 38408b516..71f34b78d 100644 --- a/doc/lightning-delinvoice.7.md +++ b/doc/lightning-delinvoice.7.md @@ -74,7 +74,7 @@ SEE ALSO lightning-listinvoice(7), lightning-waitinvoice(7), lightning-invoice(7), lightning-delexpiredinvoice(7), -lightning-autocleaninvoice(7) +lightning-autoclean-status(7) RESOURCES --------- diff --git a/doc/lightning-listforwards.7.md b/doc/lightning-listforwards.7.md index 08ab60bfd..d4b7cefe4 100644 --- a/doc/lightning-listforwards.7.md +++ b/doc/lightning-listforwards.7.md @@ -57,7 +57,7 @@ Rene Pickhardt <> is mainly responsible. SEE ALSO -------- -lightning-getinfo(7) +lightning-autoclean-status(7), lightning-getinfo(7) RESOURCES --------- diff --git a/doc/schemas/autoclean-status.request.json b/doc/schemas/autoclean-status.request.json new file mode 100644 index 000000000..b289de135 --- /dev/null +++ b/doc/schemas/autoclean-status.request.json @@ -0,0 +1,20 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "subsystem": { + "type": "string", + "enum": [ + "succeededforwards", + "failedforwards", + "succeededpays", + "failedpays", + "paidinvoices", + "expiredinvoices" + ], + "description": "What subsystem to ask about" + } + } +} diff --git a/doc/schemas/autoclean-status.schema.json b/doc/schemas/autoclean-status.schema.json new file mode 100644 index 000000000..bb5234f7b --- /dev/null +++ b/doc/schemas/autoclean-status.schema.json @@ -0,0 +1,346 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "autoclean" + ], + "properties": { + "autoclean": { + "type": "object", + "additionalProperties": false, + "properties": { + "succeededforwards": { + "type": "object", + "additionalProperties": true, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "whether autocleaning is enabled for successful listforwards" + }, + "cleaned": { + "type": "u64", + "description": "total number of deletions done (ever)" + } + }, + "if": { + "properties": { + "enabled": { + "type": "boolean", + "enum": [ + true + ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ + "enabled", + "age", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {}, + "age": { + "type": "u64", + "description": "age (in seconds) to delete successful listforwards" + } + } + }, + "else": { + "additionalProperties": false, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {} + } + } + }, + "failedforwards": { + "type": "object", + "additionalProperties": true, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "whether autocleaning is enabled for failed listforwards" + }, + "cleaned": { + "type": "u64", + "description": "total number of deletions done (ever)" + } + }, + "if": { + "properties": { + "enabled": { + "type": "boolean", + "enum": [ + true + ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ + "enabled", + "age", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {}, + "age": { + "type": "u64", + "description": "age (in seconds) to delete failed listforwards" + } + } + }, + "else": { + "additionalProperties": false, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {} + } + } + }, + "succeededpays": { + "type": "object", + "additionalProperties": true, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "whether autocleaning is enabled for successful listpays/listsendpays" + }, + "cleaned": { + "type": "u64", + "description": "total number of deletions done (ever)" + } + }, + "if": { + "properties": { + "enabled": { + "type": "boolean", + "enum": [ + true + ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ + "enabled", + "age", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {}, + "age": { + "type": "u64", + "description": "age (in seconds) to delete successful listpays/listsendpays" + } + } + }, + "else": { + "additionalProperties": false, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {} + } + } + }, + "failedpays": { + "type": "object", + "additionalProperties": true, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "whether autocleaning is enabled for failed listpays/listsendpays" + }, + "cleaned": { + "type": "u64", + "description": "total number of deletions done (ever)" + } + }, + "if": { + "properties": { + "enabled": { + "type": "boolean", + "enum": [ + true + ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ + "enabled", + "age", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {}, + "age": { + "type": "u64", + "description": "age (in seconds) to delete failed listpays/listsendpays" + } + } + }, + "else": { + "additionalProperties": false, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {} + } + } + }, + "paidinvoices": { + "type": "object", + "additionalProperties": true, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "whether autocleaning is enabled for paid listinvoices" + }, + "cleaned": { + "type": "u64", + "description": "total number of deletions done (ever)" + } + }, + "if": { + "properties": { + "enabled": { + "type": "boolean", + "enum": [ + true + ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ + "enabled", + "age", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {}, + "age": { + "type": "u64", + "description": "age (in seconds) to paid listinvoices" + } + } + }, + "else": { + "additionalProperties": false, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {} + } + } + }, + "expiredinvoices": { + "type": "object", + "additionalProperties": true, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": { + "type": "boolean", + "description": "whether autocleaning is enabled for expired (unpaid) listinvoices" + }, + "cleaned": { + "type": "u64", + "description": "total number of deletions done (ever)" + } + }, + "if": { + "properties": { + "enabled": { + "type": "boolean", + "enum": [ + true + ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ + "enabled", + "age", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {}, + "age": { + "type": "u64", + "description": "age (in seconds) to expired listinvoices" + } + } + }, + "else": { + "additionalProperties": false, + "required": [ + "enabled", + "cleaned" + ], + "properties": { + "enabled": {}, + "cleaned": {} + } + } + } + } + } + } +}