aljaz/lightning
1
0
Fork 0
mirror of https://github.com/aljazceru/lightning.git synced 2025-12-21 16:14:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

datastore: docs, schemas, and a test.

Browse Source 
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell
2021-08-25 12:20:12 +09:30
committed by Christian Decker
parent 1b48545e5b
commit dfe2693bbd
11 changed files with 401 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/Makefile
View File

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

51
doc/lightning-datastore.7 generated Normal file
View File

@@ -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<rusty@rustcorp.com.au\fR> 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

47
doc/lightning-datastore.7.md Normal file
View File

@@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-listdatastore(7), lightning-deldatastore(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:692c74ea1dea25266d8d562bc23e5c3c14223f62c9152a223cbd9c2de4d01efb)

50
doc/lightning-deldatastore.7 generated Normal file
View File

@@ -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<rusty@rustcorp.com.au\fR> 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

46
doc/lightning-deldatastore.7.md Normal file
View File

@@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-listdatastore(7), lightning-datastore(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:8e732382fa499ed98dc015a1525b4fa07a2d20d5009c305945f06dae84b408c7)

48
doc/lightning-listdatastore.7 generated Normal file
View File

@@ -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<rusty@rustcorp.com.au\fR> 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

45
doc/lightning-listdatastore.7.md Normal file
View File

@@ -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 <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-datastore(7), lightning-deldatastore(7)
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:660d1723bcea3d4800db72a9204ed577426e7b3ab99f491145e633df89a46fac)

16
doc/schemas/datastore.schema.json Normal file
View File

@@ -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"
}
}
}

16
doc/schemas/deldatastore.schema.json Normal file
View File

@@ -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"
}
}
}

26
doc/schemas/listdatastore.schema.json Normal file
View File

@@ -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"
}
}
}
}
}
}

53
tests/test_misc.py
View File

@@ -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}]}