Add doc for portnumber-file

Document the format and the fields in the portnumber file (and
modify the format so that it match the format we need in the
upcoming rewrite of interface manipulation)

Change-Id: I006f6b5de52d602ee304822f0efcf8e603ba3769
Reviewed-on: http://review.couchbase.org/c/kv_engine/+/142351
Reviewed-by: Paolo Cocchi <paolo.cocchi@couchbase.com>
Tested-by: Build Bot <build@couchbase.com>

daemon/server_socket.cc

@@ -20,14 +20,14 @@
 #include "front_end_thread.h"
 #include "listening_port.h"
 #include "memcached.h"
-#include "network_interface.h"
 #include "settings.h"
 #include "stats.h"
 
 #include <logger/logger.h>
 #include <nlohmann/json.hpp>
 #include <platform/socket.h>
 #include <platform/strerror.h>
+#include <platform/uuid.h>
 #include <exception>
 #include <memory>
 #include <string>
@@ -63,6 +63,7 @@ ServerSocket::ServerSocket(SOCKET fd,
                            event_base* b,
                            std::shared_ptr<ListeningPort> interf)
     : sfd(fd),
+      uuid(to_string(cb::uuid::random())),
       interface(std::move(interf)),
       sockname(cb::net::getsockname(fd)),
       ev(event_new(b,
@@ -200,18 +201,21 @@ void ServerSocket::acceptNewClient() {
 nlohmann::json ServerSocket::toJson() const {
     nlohmann::json ret;
 
-    ret["ssl"] = interface->isSslPort();
+    const auto sockinfo = cb::net::getSockNameAsJson(sfd);
+    ret["host"] = sockinfo["ip"];
+    ret["port"] = sockinfo["port"];
 
     if (interface->family == AF_INET) {
-        ret["family"] = "AF_INET";
+        ret["family"] = "inet";
     } else {
-        ret["family"] = "AF_INET6";
+        ret["family"] = "inet6";
     }
 
-    ret["name"] = sockname;
-    ret["port"] = interface->port;
+    ret["tls"] = interface->isSslPort();
     ret["system"] = interface->system;
     ret["tag"] = interface->tag;
+    ret["type"] = "mcbp";
+    ret["uuid"] = uuid;
 
     return ret;
 }

daemon/server_socket.h

@@ -73,10 +73,17 @@ class ServerSocket {
         return numInstances.load();
     }
 
+    const std::string& getUuid() const {
+        return uuid;
+    }
+
 protected:
     /// The socket object to accept clients from
     const SOCKET sfd;
 
+    /// The unique id used to identify _this_ port
+    const std::string uuid;
+
     std::shared_ptr<ListeningPort> interface;
 
     /// The sockets name (used for debug)

docs/PortumberFileFormat.md

@@ -0,0 +1,70 @@
+# Portnumber file format
+
+The file specified as `portnumber_file` in [memcached.json](memcached.json.adoc)
+contains a JSON object with the following format:
+
+    {
+      "ports": [
+        {
+          "family": "inet",
+          "host": "0.0.0.0",
+          "port": 35273,
+          "system": false,
+          "tag": "plain",
+          "tls": false,
+          "type": "mcbp",
+          "uuid": "c54e2ec2-277e-4531-87ad-3955cb4236c5"
+        },
+        {
+          "family": "inet6",
+          "host": "::",
+          "port": 39369,
+          "system": false,
+          "tag": "plain",
+          "tls": false,
+          "type": "mcbp",
+          "uuid": "cc480095-7e1c-4f24-f7c7-deb32f413076"
+        },
+        {
+          "family": "inet",
+          "host": "0.0.0.0",
+          "port": 40385,
+          "system": true,
+          "tag": "TLS IPv4",
+          "tls": true,
+          "type": "mcbp",
+          "uuid": "28ecaebb-8350-4bf6-f08f-58fadc6642a8"
+        },
+        {
+          "family": "inet6",
+          "host": "::",
+          "port": 42441,
+          "system": true,
+          "tag": "TLS Ipv6",
+          "tls": true,
+          "type": "mcbp",
+          "uuid": "5c3b9813-f58f-458e-f713-cf8db3aae18e"
+        }
+      ],
+      "prometheus": {
+        "family": "inet",
+        "port": 43455
+      }
+    }
+
+`ports` contains an array of all ports the server listen to which supports
+the memcached binary protocol
+
+`prometheus` contains an object describing the port providing support for
+prometheus stats collection.
+
+## Ports entry
+
+* `family` may be `inet` (for IPv4) or `inet6`(for IPv6)
+* `host` is the hostname the interface address port is bound to
+* `port` is the port number it is bound to
+* `system` if connections should be counted as system connections or user
+* `tag` a free form name for the interface
+* `tls` set to true if the port is configured to use TLS
+* `type` should always be `mcbp` (memcached binary protocol)
+* `uuid` a unique identifier for the port

protocol/connection/client_connection_map.cc

@@ -69,32 +69,32 @@ void ConnectionMap::addPorts(const nlohmann::json& ports) {
 
     sa_family_t family;
     for (const auto& obj : *array) {
+        auto host = cb::jsonGet<std::string>(obj, "host");
+        auto port = static_cast<in_port_t>(cb::jsonGet<size_t>(obj, "port"));
+        if (port == in_port_t(-1)) {
+            throw std::runtime_error("port cannot be -1");
+        }
+
         auto fam = cb::jsonGet<std::string>(obj, "family");
-        if (fam == "AF_INET") {
+        if (fam == "inet") {
             family = AF_INET;
         } else {
             family = AF_INET6;
         }
 
-        bool ssl = obj.find("tls") != obj.cend();
-        if (obj.find("ssl") != obj.cend()) {
-            ssl = cb::jsonGet<bool>(obj, "ssl");
-        }
-        auto port = static_cast<in_port_t>(cb::jsonGet<size_t>(obj, "port"));
-        if (port == in_port_t(-1)) {
-            throw std::runtime_error("port cannot be -1");
-        }
+        bool tls = cb::jsonGet<bool>(obj, "tls");
         connections.push_back(
-                std::make_unique<MemcachedConnection>("", port, family, ssl));
+                std::make_unique<MemcachedConnection>("", port, family, tls));
         if (obj.find("tag") != obj.cend()) {
             connections.back()->setTag(obj["tag"]);
         }
-        if (obj.find("name") != obj.cend()) {
-            connections.back()->setName(obj["name"]);
-        }
-        if (obj.find("uuid") != obj.cend()) {
-            connections.back()->setServerInterfaceUuid(obj["uuid"]);
+        if (family == AF_INET) {
+            connections.back()->setName(host + ":" + std::to_string(port));
+        } else {
+            connections.back()->setName("[" + host +
+                                        "]:" + std::to_string(port));
         }
+        connections.back()->setServerInterfaceUuid(obj["uuid"]);
     }
 }