doc/schemas: schema for connect.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

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
+On success, an object is returned, containing:
-\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\.
 
+.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<fixone@gmail.com\fR> is the original author of this manpage\.
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:a392b6683fad5fe218e7a985e1eaf5d7439f38d7c74212c275cfa64db284efc0
+\" SHA256STAMP:ff422184feb295e6d3e17e88c0305405edcb24eac59482a43caf750ef281e0ed

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
+[comment]: # (GENERATE-FROM-SCHEMA-START)
-*features* bitmap, a *direction* ("in" if they connected to us, "out"
+On success, an object is returned, containing:
-if we connected to them") and an *address* object as per
+- **id** (pubkey): the peer we connected to
-lightning-listnodes(7).  Note that *address* will be less useful if 
+- **features** (hex): BOLT 9 features bitmap offered by peer
-"direction" is "in", especially if a proxy is in use.
+- **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: <https://github.com/ElementsProject/lightning>
 
+[comment]: # ( SHA256STAMP:5b168e7998d3db6a842eabf92bcbb74352fe831726ea42a801e39ff5c3f812ca)

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"
+			    }
+			}
+		    }
+		}
+	    ]
+	}
+    }
+}