From 4b46190cc47ae99d4a0546487b7efc2d3e3f56cb Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 26 May 2021 15:23:01 +0930 Subject: [PATCH] doc/schemas: schema for connect. Signed-off-by: Rusty Russell --- doc/lightning-connect.7 | 45 +++++++++++++++--- doc/lightning-connect.7.md | 21 +++++++-- doc/schemas/connect.schema.json | 82 +++++++++++++++++++++++++++++++++ 3 files changed, 137 insertions(+), 11 deletions(-) create mode 100644 doc/schemas/connect.schema.json diff --git a/doc/lightning-connect.7 b/doc/lightning-connect.7 index 5ee4cb737..4bafbaf8a 100644 --- a/doc/lightning-connect.7 +++ b/doc/lightning-connect.7 @@ -42,12 +42,45 @@ another node\. Once the peer is connected a channel can be opened with .SH RETURN VALUE -On success the peer \fIid\fR is returned, as well as a hexidecimal -\fIfeatures\fR bitmap, a \fIdirection\fR ("in" if they connected to us, "out" -if we connected to them") and an \fIaddress\fR object as per -\fBlightning-listnodes\fR(7)\. Note that \fIaddress\fR will be less useful if -"direction" is "in", especially if a proxy is in use\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBid\fR (pubkey): the peer we connected to +.IP \[bu] +\fBfeatures\fR (hex): BOLT 9 features bitmap offered by peer +.IP \[bu] +\fBdirection\fR (string): Whether they initiated connection or we did (one of "in", "out") +.IP \[bu] + +\fBaddress\fR (object): Address information (mainly useful if \fBdirection\fR is \fIout\fR): + +.RS +.IP \[bu] +\fBtype\fR (string): Type of connection (\fItorv2\fR/\fItorv3\fR only if \fBdirection\fR is \fIout\fR) (one of "local socket", "ipv4", "ipv6", "torv2", "torv3") + +.RE + +If \fBtype\fR is "local socket": + +.RS +.IP \[bu] +\fBsocket\fR (string): socket filename + +.RE + +If \fBtype\fR is "ipv4", "ipv6", "torv2" or "torv3": + +.RS +.IP \[bu] +\fBaddress\fR (string): address in expected format for \fBtype\fR +.IP \[bu] +\fBport\fR (u16): port number + +.RE + + +.RE .SH ERRORS On failure, one of the following errors will be returned: @@ -97,4 +130,4 @@ Felix \fI is the original author of this manpage\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:a392b6683fad5fe218e7a985e1eaf5d7439f38d7c74212c275cfa64db284efc0 +\" SHA256STAMP:ff422184feb295e6d3e17e88c0305405edcb24eac59482a43caf750ef281e0ed diff --git a/doc/lightning-connect.7.md b/doc/lightning-connect.7.md index 823cadda7..be1df3d74 100644 --- a/doc/lightning-connect.7.md +++ b/doc/lightning-connect.7.md @@ -39,11 +39,21 @@ lightning-fundchannel(7). RETURN VALUE ------------ -On success the peer *id* is returned, as well as a hexidecimal -*features* bitmap, a *direction* ("in" if they connected to us, "out" -if we connected to them") and an *address* object as per -lightning-listnodes(7). Note that *address* will be less useful if -"direction" is "in", especially if a proxy is in use. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **id** (pubkey): the peer we connected to +- **features** (hex): BOLT 9 features bitmap offered by peer +- **direction** (string): Whether they initiated connection or we did (one of "in", "out") +- **address** (object): Address information (mainly useful if **direction** is *out*): + - **type** (string): Type of connection (*torv2*/*torv3* only if **direction** is *out*) (one of "local socket", "ipv4", "ipv6", "torv2", "torv3") + + If **type** is "local socket": + - **socket** (string): socket filename + + If **type** is "ipv4", "ipv6", "torv2" or "torv3": + - **address** (string): address in expected format for **type** + - **port** (u16): port number +[comment]: # (GENERATE-FROM-SCHEMA-END) ERRORS ------ @@ -78,3 +88,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:5b168e7998d3db6a842eabf92bcbb74352fe831726ea42a801e39ff5c3f812ca) diff --git a/doc/schemas/connect.schema.json b/doc/schemas/connect.schema.json new file mode 100644 index 000000000..3ce55591c --- /dev/null +++ b/doc/schemas/connect.schema.json @@ -0,0 +1,82 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "id", "features", "direction", "address" ], + "properties": { + "id": { + "type": "pubkey", + "description": "the peer we connected to" + }, + "features": { + "type": "hex", + "description": "BOLT 9 features bitmap offered by peer" + }, + "direction": { + "type": "string", + "enum": [ "in", "out" ], + "description": "Whether they initiated connection or we did" + }, + "address": { + "type": "object", + "description": "Address information (mainly useful if **direction** is *out*)", + "additionalProperties": true, + "required": [ "type" ], + "properties": { + "type": { + "type": "string", + "enum": [ "local socket", "ipv4", "ipv6", "torv2", "torv3" ], + "description": "Type of connection (*torv2*/*torv3* only if **direction** is *out*)" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "local socket" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "socket" ], + "properties": { + "type": { }, + "socket": { + "type": "string", + "description": "socket filename" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "ipv4", "ipv6", "torv2", "torv3" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "address", "port" ], + "properties": { + "type": { }, + "address": { + "type": "string", + "description": "address in expected format for **type**" + }, + "port": { + "type": "u16", + "description": "port number" + } + } + } + } + ] + } + } +}