diff --git a/doc/Makefile b/doc/Makefile index 4dce77333..783a528d8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -15,8 +15,10 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-connect.7 \ doc/lightning-createonion.7 \ doc/lightning-createinvoice.7 \ + doc/lightning-datastore.7 \ doc/lightning-decodepay.7 \ doc/lightning-decode.7 \ + doc/lightning-deldatastore.7 \ doc/lightning-delexpiredinvoice.7 \ doc/lightning-delinvoice.7 \ doc/lightning-delpay.7 \ @@ -36,6 +38,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-invoice.7 \ doc/lightning-keysend.7 \ doc/lightning-listchannels.7 \ + doc/lightning-listdatastore.7 \ doc/lightning-listforwards.7 \ doc/lightning-listfunds.7 \ doc/lightning-listinvoices.7 \ diff --git a/doc/lightning-datastore.7 b/doc/lightning-datastore.7 new file mode 100644 index 000000000..f91d9f614 --- /dev/null +++ b/doc/lightning-datastore.7 @@ -0,0 +1,51 @@ +.TH "LIGHTNING-DATASTORE" "7" "" "" "lightning-datastore" +.SH NAME +lightning-datastore - Command for storing (plugin) data +.SH SYNOPSIS + +\fBdatastore\fR \fIkey\fR \fIhex\fR + +.SH DESCRIPTION + +The \fBdatastore\fR RPC command allows plugins to store data in the +c-lightning database, for later retrieval\. + + +There can only be one entry for each \fIkey\fR, so prefixing with the +plugin name (e\.g\. \fBsummary.\fR) is recommended\. + +.SH RETURN VALUE + +On success, an object is returned, containing: + +.RS +.IP \[bu] +\fBkey\fR (string): The key which has been added to the datastore +.IP \[bu] +\fBhex\fR (hex): The hex data which has been added to the datastore + +.RE + +The main cause of failure is an already-existing entry\. + + +The following error codes may occur: + +.RS +.IP \[bu] +-32602: invalid parameters, including already-existing key\. + +.RE +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-listdatastore\fR(7), \fBlightning-deldatastore\fR(7) + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + +\" SHA256STAMP:1972be4c054c35bf2e0fdbf2e7bb9a3870b3322a008ae29e6a84207c7b527458 diff --git a/doc/lightning-datastore.7.md b/doc/lightning-datastore.7.md new file mode 100644 index 000000000..157013da7 --- /dev/null +++ b/doc/lightning-datastore.7.md @@ -0,0 +1,47 @@ +lightning-datastore -- Command for storing (plugin) data +======================================================== + +SYNOPSIS +-------- + +**datastore** *key* *hex* + +DESCRIPTION +----------- + +The **datastore** RPC command allows plugins to store data in the +c-lightning database, for later retrieval. + +There can only be one entry for each *key*, so prefixing with the +plugin name (e.g. `summary.`) is recommended. + +RETURN VALUE +------------ + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **key** (string): The key which has been added to the datastore +- **hex** (hex): The hex data which has been added to the datastore +[comment]: # (GENERATE-FROM-SCHEMA-END) + +The main cause of failure is an already-existing entry. + +The following error codes may occur: +- -32602: invalid parameters, including already-existing key. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listdatastore(7), lightning-deldatastore(7) + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:692c74ea1dea25266d8d562bc23e5c3c14223f62c9152a223cbd9c2de4d01efb) diff --git a/doc/lightning-deldatastore.7 b/doc/lightning-deldatastore.7 new file mode 100644 index 000000000..c3470d6a3 --- /dev/null +++ b/doc/lightning-deldatastore.7 @@ -0,0 +1,50 @@ +.TH "LIGHTNING-DELDATASTORE" "7" "" "" "lightning-deldatastore" +.SH NAME +lightning-deldatastore - Command for removing (plugin) data +.SH SYNOPSIS + +\fBdeldatastore\fR \fIkey\fR + +.SH DESCRIPTION + +The \fBdeldatastore\fR RPC command allows plugins to delete data it has +stored in the c-lightning database\. + + +The command fails if the \fIkey\fR isn't present\. + +.SH RETURN VALUE + +On success, an object is returned, containing: + +.RS +.IP \[bu] +\fBkey\fR (string): The key which has been removed from the datastore +.IP \[bu] +\fBhex\fR (hex): The hex data which has removed from the datastore + +.RE + +The main cause of failure is an non-existing entry\. + + +The following error codes may occur: + +.RS +.IP \[bu] +-32602: invalid parameters, including non-existing key\. + +.RE +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-listdatastore\fR(7), \fBlightning-datastore\fR(7) + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + +\" SHA256STAMP:61af040ae88b08a8cc0e5f0d510a9613fbdc89e6e8d5b7dfebedcd134a91fb4b diff --git a/doc/lightning-deldatastore.7.md b/doc/lightning-deldatastore.7.md new file mode 100644 index 000000000..52f749916 --- /dev/null +++ b/doc/lightning-deldatastore.7.md @@ -0,0 +1,46 @@ +lightning-deldatastore -- Command for removing (plugin) data +============================================================ + +SYNOPSIS +-------- + +**deldatastore** *key* + +DESCRIPTION +----------- + +The **deldatastore** RPC command allows plugins to delete data it has +stored in the c-lightning database. + +The command fails if the *key* isn't present. + +RETURN VALUE +------------ + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **key** (string): The key which has been removed from the datastore +- **hex** (hex): The hex data which has removed from the datastore +[comment]: # (GENERATE-FROM-SCHEMA-END) + +The main cause of failure is an non-existing entry. + +The following error codes may occur: +- -32602: invalid parameters, including non-existing key. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-listdatastore(7), lightning-datastore(7) + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:8e732382fa499ed98dc015a1525b4fa07a2d20d5009c305945f06dae84b408c7) diff --git a/doc/lightning-listdatastore.7 b/doc/lightning-listdatastore.7 new file mode 100644 index 000000000..7dfb6b173 --- /dev/null +++ b/doc/lightning-listdatastore.7 @@ -0,0 +1,48 @@ +.TH "LIGHTNING-LISTDATASTORE" "7" "" "" "lightning-listdatastore" +.SH NAME +lightning-listdatastore - Command for listing (plugin) data +.SH SYNOPSIS + +\fBlistdatastore\fR [\fIkey\fR] + +.SH DESCRIPTION + +The \fBlistdatastore\fR RPC command allows plugins to fetch data which was +stored in the c-lightning database\. + + +All entries are returned in \fIkey\fR isn't present; if \fIkey\fR is present, +zero or one entries are returned\. + +.SH RETURN VALUE + +On success, an object containing \fBdatastore\fR is returned\. It is an array of objects, where each object contains: + +.RS +.IP \[bu] +\fBkey\fR (string): The key which from the datastore +.IP \[bu] +\fBhex\fR (hex): The hex data from the datastore + +.RE + +The following error codes may occur: + +.RS +.IP \[bu] +-32602: invalid parameters\. + +.RE +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-datastore\fR(7), \fBlightning-deldatastore\fR(7) + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + +\" SHA256STAMP:a501f1c8a7517726a49e48180c5d20966df7158f1af3afdd1654a435473efb5d diff --git a/doc/lightning-listdatastore.7.md b/doc/lightning-listdatastore.7.md new file mode 100644 index 000000000..6530110ad --- /dev/null +++ b/doc/lightning-listdatastore.7.md @@ -0,0 +1,45 @@ +lightning-listdatastore -- Command for listing (plugin) data +============================================================ + +SYNOPSIS +-------- + +**listdatastore** [*key*] + +DESCRIPTION +----------- + +The **listdatastore** RPC command allows plugins to fetch data which was +stored in the c-lightning database. + +All entries are returned in *key* isn't present; if *key* is present, +zero or one entries are returned. + +RETURN VALUE +------------ + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **datastore** is returned. It is an array of objects, where each object contains: +- **key** (string): The key which from the datastore +- **hex** (hex): The hex data from the datastore +[comment]: # (GENERATE-FROM-SCHEMA-END) + +The following error codes may occur: +- -32602: invalid parameters. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-datastore(7), lightning-deldatastore(7) + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:660d1723bcea3d4800db72a9204ed577426e7b3ab99f491145e633df89a46fac) diff --git a/doc/schemas/datastore.schema.json b/doc/schemas/datastore.schema.json new file mode 100644 index 000000000..849637ddc --- /dev/null +++ b/doc/schemas/datastore.schema.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "key", "hex" ], + "properties": { + "key": { + "type": "string", + "description": "The key which has been added to the datastore" + }, + "hex": { + "type": "hex", + "description": "The hex data which has been added to the datastore" + } + } +} diff --git a/doc/schemas/deldatastore.schema.json b/doc/schemas/deldatastore.schema.json new file mode 100644 index 000000000..0e28aff2d --- /dev/null +++ b/doc/schemas/deldatastore.schema.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "key", "hex" ], + "properties": { + "key": { + "type": "string", + "description": "The key which has been removed from the datastore" + }, + "hex": { + "type": "hex", + "description": "The hex data which has removed from the datastore" + } + } +} diff --git a/doc/schemas/listdatastore.schema.json b/doc/schemas/listdatastore.schema.json new file mode 100644 index 000000000..2b200e546 --- /dev/null +++ b/doc/schemas/listdatastore.schema.json @@ -0,0 +1,26 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "datastore" ], + "properties": { + "datastore": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "key", "hex" ], + "properties": { + "key": { + "type": "string", + "description": "The key which from the datastore" + }, + "hex": { + "type": "hex", + "description": "The hex data from the datastore" + } + } + } + } + } +} diff --git a/tests/test_misc.py b/tests/test_misc.py index e6277716e..41b3dbf08 100644 --- a/tests/test_misc.py +++ b/tests/test_misc.py @@ -2624,3 +2624,56 @@ def test_force_feerates(node_factory): "penalty": 6666, "min_acceptable": 1875, "max_acceptable": 150000} + + +def test_datastore(node_factory): + l1 = node_factory.get_node() + + # Starts empty + assert l1.rpc.listdatastore() == {'datastore': []} + assert l1.rpc.listdatastore('somekey') == {'datastore': []} + + # Add entries. + somedata = b'somedata'.hex() + assert l1.rpc.datastore('somekey', somedata) == {'key': 'somekey', + 'hex': somedata} + + assert l1.rpc.listdatastore() == {'datastore': [{'key': 'somekey', + 'hex': somedata}]} + assert l1.rpc.listdatastore('somekey') == {'datastore': [{'key': 'somekey', + 'hex': somedata}]} + assert l1.rpc.listdatastore('otherkey') == {'datastore': []} + + otherdata = b'otherdata'.hex() + assert l1.rpc.datastore('otherkey', otherdata) == {'key': 'otherkey', + 'hex': otherdata} + + assert l1.rpc.listdatastore('somekey') == {'datastore': [{'key': 'somekey', + 'hex': somedata}]} + assert l1.rpc.listdatastore('otherkey') == {'datastore': [{'key': 'otherkey', + 'hex': otherdata}]} + assert l1.rpc.listdatastore('badkey') == {'datastore': []} + + ds = l1.rpc.listdatastore() + # Order is undefined! + assert (ds == {'datastore': [{'key': 'somekey', 'hex': somedata}, + {'key': 'otherkey', 'hex': otherdata}]} + or ds == {'datastore': [{'key': 'otherkey', 'hex': otherdata}, + {'key': 'somekey', 'hex': somedata}]}) + + assert l1.rpc.deldatastore('somekey') == {'key': 'somekey', + 'hex': somedata} + assert l1.rpc.listdatastore() == {'datastore': [{'key': 'otherkey', + 'hex': otherdata}]} + assert l1.rpc.listdatastore('somekey') == {'datastore': []} + assert l1.rpc.listdatastore('otherkey') == {'datastore': [{'key': 'otherkey', + 'hex': otherdata}]} + assert l1.rpc.listdatastore('badkey') == {'datastore': []} + assert l1.rpc.listdatastore() == {'datastore': [{'key': 'otherkey', + 'hex': otherdata}]} + + # It's persistent + l1.restart() + + assert l1.rpc.listdatastore() == {'datastore': [{'key': 'otherkey', + 'hex': otherdata}]}