fixes #1746 Create a new socket:// transport for socketpair() based connections

This transport only listens, and creates connections when
the application calls setopt on the lister with NNG_OPT_SOCKET_FD,
to pass a file descriptor.  The FD is turned into an nng_stream,
and utilized for SP.  The protocol over the descriptor is identical
to the TCP protocol (not the IPC protocol).

The options for peer information are borrowed from the IPC transport,
as they may be useful for these purposes.

This includes a test suite and full documentation.

2 files changed, 33 insertions, 10 deletions

diff --git a/include/nng/nng.h b/include/nng/nng.h
index ce58fb3a..06733d77 100644
--- a/include/nng/nng.h
+++ b/include/nng/nng.h
@@ -709,8 +709,8 @@ NNG_DECL nng_listener nng_pipe_listener(nng_pipe);
 
 // TLS options are only used when the underlying transport supports TLS.
 
-// NNG_OPT_TLS_CONFIG is a pointer to an nng_tls_config object.  Generally
-// this can used with endpoints, although once an endpoint is started, or
+// NNG_OPT_TLS_CONFIG is a pointer to a nng_tls_config object.  Generally
+// this can be used with endpoints, although once an endpoint is started, or
 // once a configuration is used, the value becomes read-only. Note that
 // when configuring the object, a hold is placed on the TLS configuration,
 // using a reference count.  When retrieving the object, no such hold is
@@ -730,7 +730,7 @@ NNG_DECL nng_listener nng_pipe_listener(nng_pipe);
 
 // NNG_OPT_TLS_CERT_KEY_FILE names a single file that contains a certificate
 // and key identifying the endpoint.  This is a write-only value.  This can be
-// set multiple times for times for different keys/certs corresponding to
+// set multiple times for different keys/certs corresponding to
 // different algorithms on listeners, whereas dialers only support one.  The
 // file must contain both cert and key as PEM blocks, and the key must
 // not be encrypted.  (If more flexibility is needed, use the TLS configuration
@@ -750,13 +750,13 @@ NNG_DECL nng_listener nng_pipe_listener(nng_pipe);
 #define NNG_OPT_TLS_SERVER_NAME "tls-server-name"
 
 // NNG_OPT_TLS_VERIFIED returns a boolean indicating whether the peer has
-// been verified (true) or not (false). Typically this is read-only, and
+// been verified (true) or not (false). Typically, this is read-only, and
 // only available for pipes. This option may return incorrect results if
 // peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`.
 #define NNG_OPT_TLS_VERIFIED "tls-verified"
 
 // NNG_OPT_TLS_PEER_CN returns the string with the common name
-// of the peer certificate. Typically this is read-only and
+// of the peer certificate. Typically, this is read-only and
 // only available for pipes. This option may return incorrect results if
 // peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`.
 #define NNG_OPT_TLS_PEER_CN "tls-peer-cn"
@@ -811,24 +811,30 @@ NNG_DECL nng_listener nng_pipe_listener(nng_pipe);
 // this for security.
 #define NNG_OPT_IPC_PERMISSIONS "ipc:permissions"
 
+// IPC peer options may also be used in some cases with other socket types.
+
 // Peer UID.  This is only available on POSIX style systems.
-#define NNG_OPT_IPC_PEER_UID "ipc:peer-uid"
+#define NNG_OPT_PEER_UID "ipc:peer-uid"
+#define NNG_OPT_IPC_PEER_UID NNG_OPT_PEER_UID
 
 // Peer GID (primary group).  This is only available on POSIX style systems.
-#define NNG_OPT_IPC_PEER_GID "ipc:peer-gid"
+#define NNG_OPT_PEER_GID "ipc:peer-gid"
+#define NNG_OPT_IPC_PEER_GID NNG_OPT_PEER_GID
 
 // Peer process ID.  Available on Windows, Linux, and SunOS.
-// In theory we could obtain this with the first message sent,
+// In theory, we could obtain this with the first message sent,
 // but we have elected not to do this for now. (Nice RFE for a FreeBSD
 // guru though.)
-#define NNG_OPT_IPC_PEER_PID "ipc:peer-pid"
+#define NNG_OPT_PEER_PID "ipc:peer-pid"
+#define NNG_OPT_IPC_PEER_PID NNG_OPT_PEER_PID
 
 // Peer Zone ID.  Only on SunOS systems.  (Linux containers have no
 // definable kernel identity; they are a user-land fabrication made up
 // from various pieces of different namespaces. FreeBSD does have
 // something called JailIDs, but it isn't obvious how to determine this,
 // or even if processes can use IPC across jail boundaries.)
-#define NNG_OPT_IPC_PEER_ZONEID "ipc:peer-zoneid"
+#define NNG_OPT_PEER_ZONEID "ipc:peer-zoneid"
+#define NNG_OPT_IPC_PEER_ZONEID NNG_OPT_PEER_ZONEID
 
 // WebSocket Options.
 
@@ -893,6 +899,16 @@ NNG_DECL nng_listener nng_pipe_listener(nng_pipe);
 // peers that cannot be coerced into sending binary frames.
 #define NNG_OPT_WS_RECV_TEXT "ws:recv-text"
 
+// NNG_OPT_SOCKET_FD is a write-only integer property that is used to
+// file descriptors (or FILE HANDLE objects on Windows) to a
+// socket:// based listener.  This file descriptor will be taken
+// over and used as a stream connection.  The protocol is compatible
+// with SP over TCP.  This facility is experimental, and intended to
+// allow use with descriptors created via socketpair() or similar.
+// Note that unidirectional pipes (such as those from pipe(2) or mkfifo)
+// are not supported.
+#define NNG_OPT_SOCKET_FD "socket:fd"
+
 // XXX: TBD: priorities, ipv4only
 
 // Statistics. These are for informational purposes only, and subject
diff --git a/include/nng/supplemental/util/platform.h b/include/nng/supplemental/util/platform.h
index feca858a..dc3c47dd 100644
--- a/include/nng/supplemental/util/platform.h
+++ b/include/nng/supplemental/util/platform.h
@@ -104,6 +104,13 @@ NNG_DECL void nng_cv_wake1(nng_cv *);
 // nng_random returns a "strong" (cryptographic sense) random number.
 NNG_DECL uint32_t nng_random(void);
 
+// nng_socket_pair is used to create a bound pair of file descriptors
+// typically using the socketpair() call.  The descriptors are backed
+// by reliable, bidirectional, byte streams.  This will return NNG_ENOTSUP
+// if the platform lacks support for this.  The argument is a pointer
+// to an array of file descriptors (or HANDLES or similar).
+NNG_DECL int nng_socket_pair(int [2]);
+
 #ifdef __cplusplus
 }
 #endif