reckless-rpc: add documentation

ElementsProject · Aug 7, 2024 · 6fbee94 · 6fbee94
1 parent 6d18d40
commit 6fbee94
Show file tree

Hide file tree

Showing 4 changed files with 384 additions and 0 deletions.
diff --git a/contrib/msggen/msggen/schema.json b/contrib/msggen/msggen/schema.json
@@ -25995,6 +25995,197 @@
         "Main web site: <https://github.com/ElementsProject/lightning>"
       ]
     },
+    "lightning-reckless.json": {
+      "$schema": "../rpc-schema-draft.json",
+      "type": "object",
+      "additionalProperties": false,
+      "rpc": "reckless",
+      "title": "Issue a command to the reckless plugin manager utility",
+      "description": [
+        "The **reckless** RPC starts a reckless process with the *command* and *target* provided.  Node configuration, network, and lightning direrctory are automatically passed to the reckless utility."
+      ],
+      "request": {
+        "required": [
+          "command"
+        ],
+        "properties": {
+          "command": {
+            "type": "string",
+            "enum": [
+              "install",
+              "uninstall",
+              "search",
+              "enable",
+              "disable",
+              "source",
+              "--version"
+            ],
+            "description": [
+              "Determines which command to pass to reckless",
+              "  - *command* **install** takes a *plugin_name* to search for and install a named plugin.",
+              "  - *command* **uninstall** takes a *plugin_name* and attempts to uninstall a plugin of the same name.",
+              "  - *command* **search** takes a *plugin_name* to search for a named plugin.",
+              "..."
+            ]
+          },
+          "target/subcommand": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "array"
+              }
+            ],
+            "description": [
+              "Target of a reckless command or a subcommand."
+            ]
+          },
+          "target": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "array"
+              }
+            ],
+            "description": [
+              "*name* of a plugin to install/uninstall/search/enable/disable or source to add/remove."
+            ]
+          }
+        }
+      },
+      "response": {
+        "required": [
+          "log",
+          "result"
+        ],
+        "properties": {
+          "result": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": [
+              "Output of the requested reckless command."
+            ]
+          },
+          "log": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": [
+              "Verbose log entries of the requested reckless command."
+            ]
+          }
+        }
+      },
+      "author": [
+        "Alex Myers <<[email protected]>> is mainly responsible."
+      ],
+      "see_also": [
+        "reckless(7)"
+      ],
+      "resources": [
+        "Main web site: <https://github.com/ElementsProject/lightning>"
+      ],
+      "examples": [
+        {
+          "request": {
+            "id": "example:reckless#1",
+            "method": "reckless",
+            "params": {
+              "command": "search",
+              "target/subcommand": "backup"
+            }
+          },
+          "response": {
+            "result": [
+              "https://github.com/lightningd/plugins"
+            ],
+            "log": [
+              "DEBUG: Warning: Reckless requires write access",
+              "DEBUG: fetching from gh API: https://api.github.com/repos/lightningd/plugins/contents/",
+              "DEBUG: fetching from gh API: https://api.github.com/repos/lightningd/plugins/git/trees/294f93d7060799439c994daa84f534c4d1458325",
+              "INFO: found backup in source: https://github.com/lightningd/plugins",
+              "DEBUG: entry: None",
+              "DEBUG: sub-directory: backup"
+            ]
+          }
+        },
+        {
+          "request": {
+            "id": "example:reckless#2",
+            "method": "reckless",
+            "params": {
+              "command": "install",
+              "target/subcommand": [
+                "summars",
+                "currecyrate"
+              ]
+            }
+          },
+          "response": {
+            "result": [
+              "/tmp/l1/reckless/summars",
+              "/tmp/l1/reckless/currencyrate"
+            ],
+            "log": [
+              "DEBUG: Searching for summars",
+              "DEBUG: fetching from gh API: https://api.github.com/repos/lightningd/plugins/contents/",
+              "DEBUG: fetching from gh API: https://api.github.com/repos/lightningd/plugins/git/trees/294f93d7060799439c994daa84f534c4d1458325",
+              "INFO: found summars in source: https://github.com/lightningd/plugins",
+              "DEBUG: entry: None",
+              "DEBUG: sub-directory: summars",
+              "DEBUG: Retrieving summars from https://github.com/lightningd/plugins",
+              "DEBUG: Install requested from InstInfo(summars, https://github.com/lightningd/plugins, None, None, None, summars).",
+              "INFO: cloning Source.GITHUB_REPO InstInfo(summars, https://github.com/lightningd/plugins, None, None, None, summars)",
+              "DEBUG: cloned_src: InstInfo(summars, /tmp/reckless-726255950dyifh_fh/clone, None, Cargo.toml, Cargo.toml, summars/summars)",
+              "DEBUG: using latest commit of default branch",
+              "DEBUG: checked out HEAD: 5e449468bd57db7d0f33178fe0dc867e0da94133",
+              "DEBUG: using installer rust",
+              "DEBUG: creating /tmp/l1/reckless/summars",
+              "DEBUG: creating /tmp/l1/reckless/summars/source",
+              "DEBUG: copying /tmp/reckless-726255950dyifh_fh/clone/summars/summars tree to /tmp/l1/reckless/summars/source/summars",
+              "DEBUG: linking source /tmp/l1/reckless/summars/source/summars/Cargo.toml to /tmp/l1/reckless/summars/Cargo.toml",
+              "DEBUG: InstInfo(summars, /tmp/l1/reckless/summars, None, Cargo.toml, Cargo.toml, source/summars)",
+              "DEBUG: cargo installing from /tmp/l1/reckless/summars/source/summars",
+              "DEBUG: rust project compiled successfully",
+              "INFO: plugin installed: /tmp/l1/reckless/summars",
+              "DEBUG: activating summars",
+              "INFO: summars enabled",
+              "DEBUG: Searching for currencyrate",
+              "DEBUG: fetching from gh API: https://api.github.com/repos/lightningd/plugins/contents/",
+              "DEBUG: fetching from gh API: https://api.github.com/repos/lightningd/plugins/git/trees/294f93d7060799439c994daa84f534c4d1458325",
+              "INFO: found currencyrate in source: https://github.com/lightningd/plugins",
+              "DEBUG: entry: None",
+              "DEBUG: sub-directory: currencyrate",
+              "DEBUG: Retrieving currencyrate from https://github.com/lightningd/plugins",
+              "DEBUG: Install requested from InstInfo(currencyrate, https://github.com/lightningd/plugins, None, None, None, currencyrate).",
+              "INFO: cloning Source.GITHUB_REPO InstInfo(currencyrate, https://github.com/lightningd/plugins, None, None, None, currencyrate)",
+              "DEBUG: cloned_src: InstInfo(currencyrate, /tmp/reckless-192564272t478naxn/clone, None, currencyrate.py, requirements.txt, currencyrate/currencyrate)",
+              "DEBUG: using latest commit of default branch",
+              "DEBUG: checked out HEAD: 5e449468bd57db7d0f33178fe0dc867e0da94133",
+              "DEBUG: using installer python3venv",
+              "DEBUG: creating /tmp/l1/reckless/currencyrate",
+              "DEBUG: creating /tmp/l1/reckless/currencyrate/source",
+              "DEBUG: copying /tmp/reckless-192564272t478naxn/clone/currencyrate/currencyrate tree to /tmp/l1/reckless/currencyrate/source/currencyrate",
+              "DEBUG: linking source /tmp/l1/reckless/currencyrate/source/currencyrate/currencyrate.py to /tmp/l1/reckless/currencyrate/currencyrate.py",
+              "DEBUG: InstInfo(currencyrate, /tmp/l1/reckless/currencyrate, None, currencyrate.py, requirements.txt, source/currencyrate)",
+              "DEBUG: configuring a python virtual environment (pip) in /tmp/l1/reckless/currencyrate/.venv",
+              "DEBUG: virtual environment created in /tmp/l1/reckless/currencyrate/.venv.",
+              "INFO: dependencies installed successfully",
+              "DEBUG: virtual environment for cloned plugin: .venv",
+              "INFO: plugin installed: /tmp/l1/reckless/currencyrate",
+              "DEBUG: activating currencyrate",
+              "INFO: currencyrate enabled"
+            ]
+          }
+        }
+      ]
+    },
     "lightning-recover.json": {
       "$schema": "../rpc-schema-draft.json",
       "type": "object",

diff --git a/doc/Makefile b/doc/Makefile
@@ -97,6 +97,7 @@ GENERATE_MARKDOWN := doc/lightning-addgossip.7 \
 	doc/lightning-plugin.7 \
 	doc/lightning-preapproveinvoice.7 \
 	doc/lightning-preapprovekeysend.7 \
+	doc/lightning-reckless.7 \
 	doc/lightning-recoverchannel.7 \
 	doc/lightning-recover.7 \
 	doc/lightning-renepay.7 \

diff --git a/doc/index.rst b/doc/index.rst
@@ -108,6 +108,7 @@ Core Lightning Documentation
    lightning-plugin <lightning-plugin.7.md>
    lightning-preapproveinvoice <lightning-preapproveinvoice.7.md>
    lightning-preapprovekeysend <lightning-preapprovekeysend.7.md>
+   lightning-reckless <lightning-reckless.7.md>
    lightning-recover <lightning-recover.7.md>
    lightning-recoverchannel <lightning-recoverchannel.7.md>
    lightning-renepay <lightning-renepay.7.md>