From 1f2c2a35ad14cfac002d87073471bd84a52860bf Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Wed, 1 Jun 2022 11:28:14 -0700
Subject: feat(server): instance "name", store pipes in stdpath(state)

Problem:
- Unix sockets are created in random /tmp dirs.
  - /tmp is messy, unclear when OSes actually clear it.
  - The generated paths are very ugly. This adds friction to reasoning
    about which paths belong to which Nvim instances.
- No way to provide a human-friendly way to identify Nvim instances in
  logs or server addresses.

Solution:
- Store unix sockets in stdpath('state')
- Allow --listen "name" and serverstart("name") to given a name (which
  is appended to a generated path).

TODO:
- is stdpath(state) the right place?
---
 runtime/doc/builtin.txt | 41 ++++++++++++++++++++---------------------
 1 file changed, 20 insertions(+), 21 deletions(-)

(limited to 'runtime')

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 57b45f33c1..0b32b3a420 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -6628,30 +6628,29 @@ serverlist()						*serverlist()*
 
 serverstart([{address}])				*serverstart()*
 		Opens a socket or named pipe at {address} and listens for
-		|RPC| messages. Clients can send |API| commands to the address
-		to control Nvim.
-
-		Returns the address string.
-
-		If {address} does not contain a colon ":" it is interpreted as
-		a named pipe or Unix domain socket path.
-
-		Example: >
+		|RPC| messages. Clients can send |API| commands to the
+		returned address to control Nvim.
+
+		Returns the address string (may differ from the requested
+		{address}).
+		 
+		- If {address} contains a colon ":" it is interpreted as
+		  a TCP/IPv4/IPv6 address where the last ":" separates host
+		  and port (empty or zero assigns a random port).
+		- Else it is interpreted as a named pipe or Unix domain socket
+		  path. If there are no slashes it is treated as a name and
+		  appended to a generated path.
+		- If {address} is empty it generates a path.
+
+		Example named pipe: >
 			if has('win32')
-			  call serverstart('\\.\pipe\nvim-pipe-1234')
+			  echo serverstart('\\.\pipe\nvim-pipe-1234')
 			else
-			  call serverstart('nvim.sock')
+			  echo serverstart('nvim.sock')
 			endif
 <
-		If {address} contains a colon ":" it is interpreted as a TCP
-		address where the last ":" separates the host and port.
-		Assigns a random port if it is empty or 0. Supports IPv4/IPv6.
-
-		Example: >
-			:call serverstart('::1:12345')
-<
-		If no address is given, it is equivalent to: >
-			:call serverstart(tempname())
+		Example TCP/IP address: >
+			echo serverstart('::1:12345')
 
 serverstop({address})					*serverstop()*
 		Closes the pipe or socket at {address}.
@@ -7545,7 +7544,7 @@ stdpath({what})					*stdpath()* *E6100*
 		data_dirs    List    Other data directories.
 		log          String  Logs directory (for use by plugins too).
 		state        String  Session state directory: storage for file
-				     drafts, undo history, shada, etc.
+				     drafts, undo, shada, named pipes, ...
 
 		Example: >
 			:echo stdpath("config")
-- 
cgit