Add support for Unix domain socket connection (#3088)

Author: bendlas

cider-connection.el

@@ -85,7 +85,8 @@ PARAMS is a plist containing :host, :port, :server and other parameters for
     (plist-get params :port)
     (plist-get params :server)
     (lambda (_)
-      (cider-repl-create params)))))
+      (cider-repl-create params))
+    (plist-get params :socket-file))))
 
 (defun cider-sessions ()
   "Return a list of all active CIDER sessions."

cider.el

@@ -1398,7 +1398,7 @@ non-nil, don't start if ClojureScript requirements are not met."
       (user-error "The %s executable isn't on your `exec-path'" command))))
 
 (defun cider--update-host-port (params)
-  "Update :host and :port in PARAMS."
+  "Update :host and :port; or :socket-file in PARAMS."
   (with-current-buffer (or (plist-get params :--context-buffer)
                            (current-buffer))
     (let* ((params (cider--update-do-prompt params))
@@ -1409,9 +1409,11 @@ non-nil, don't start if ClojureScript requirements are not met."
                        (if (and host port)
                            (cons host port)
                          (cider-select-endpoint)))))
-      (thread-first params
-        (plist-put :host (car endpoint))
-        (plist-put :port (cdr endpoint))))))
+      (if (equal "local-unix-domain-socket" (car endpoint))
+          (plist-put params :socket-file (cdr endpoint))
+        (thread-first params
+          (plist-put :host (car endpoint))
+          (plist-put :port (cdr endpoint)))))))
 
 (defun cider--update-cljs-init-function (params)
   "Update PARAMS :repl-init-function for cljs connections."
@@ -1491,11 +1493,14 @@ canceled the action, signal quit."
                                   cider-known-endpoints
                                   ssh-hosts
                                   ;; always add localhost
-                                  '(("localhost")))))
+                                  '(("localhost")
+                                    ("local-unix-domain-socket")))))
          (sel-host (cider--completing-read-host hosts))
          (host (car sel-host))
          (port (or (cadr sel-host)
-                   (cider--completing-read-port host (cider--infer-ports host ssh-hosts)))))
+                   (if (equal host "local-unix-domain-socket")
+                       (cider--completing-read-socket-file)
+                     (cider--completing-read-port host (cider--infer-ports host ssh-hosts))))))
     (cons host port)))
 
 (defun cider--ssh-hosts ()
@@ -1563,6 +1568,18 @@ of remote SSH hosts."
          (port (if (listp port) (cadr port) port)))
     (if (stringp port) (string-to-number port) port)))
 
+(defun cider--completing-read-socket-file ()
+  "Interactively select unix domain socket file name."
+  (read-file-name "Socket File: " nil nil t nil
+                  (lambda (filename)
+                    "Predicate: auto-complete only socket-files and directories"
+                    (let ((filetype (string-to-char
+                                     (file-attribute-modes
+                                      (file-attributes
+                                       filename)))))
+                      (or (eq ?s filetype)
+                          (eq ?d filetype))))))
+
 (defun cider-locate-running-nrepl-ports (&optional dir)
   "Locate ports of running nREPL servers.
 When DIR is non-nil also look for nREPL port files in DIR.  Return a list

doc/modules/ROOT/pages/basics/up_and_running.adoc

@@ -269,6 +269,26 @@ cause problems with complex or nonstandard ssh configs.
 You can safely run `cider-jack-in-*` while working with remote files over TRAMP. CIDER
 will handle this use-case transparently for you.
 
+== Connecting via unix domain file socket
+
+When locally running nREPL servers, there is the option to listen on a
+socket file instead of opening a network port. This can have
+advantages in some use cases, e.g. when working with virtual networks
+(containers) where sharing a file socket can be vastly simpler than
+managing bridge networks and firewall setups.
+
+After having started an nREPL server on a file socket, e.g. with the
+`clj` command (see https://nrepl.org/nrepl/usage/server.html for other
+examples),
+
+[source,sh]
+----
+$ clj -R:nREPL -m nrepl.cmdline --socket nrepl.sock
+----
+
+you can then connect CIDER by using the `local-unix-domain-socket`
+special hostname with `cider-connect`: kbd:[M-x] `cider-connect` kbd:[RET] `local-unix-domain-socket` kbd:[RET] `nrepl.sock` kbd:[RET]
+
 == What's Next?
 
 So, what to do next now that CIDER's ready for action? Here are a few ideas:

nrepl-client.el

@@ -491,6 +491,26 @@ and kill the process buffer."
 
 ;;; Network
 
+(defun nrepl--unix-connect (socket-file &optional no-error)
+  "If SOCKET-FILE is given, try to `make-network-process'.
+If NO-ERROR is non-nil, show messages instead of throwing an error."
+  (if (not socket-file)
+      (unless no-error
+        (error "[nREPL] Socket file not provided"))
+    (message "[nREPL] Establishing unix socket connection to %s ..." socket-file)
+    (condition-case nil
+        (prog1 (list :proc (make-network-process :name "nrepl-connection" :buffer nil
+                                                 :family 'local :service socket-file)
+                     :host "local-unix-domain-socket"
+                     :port socket-file
+                     :socket-file socket-file)
+          (message "[nREPL] Unix socket connection to %s established" socket-file))
+      (error (let ((msg (format "[nREPL] Unix socket connection to %s failed" socket-file)))
+               (if no-error
+                   (message msg)
+                 (error msg))
+               nil)))))
+
 (defun nrepl-connect (host port)
   "Connect to the nREPL server identified by HOST and PORT.
 For local hosts use a direct connection.  For remote hosts, if
@@ -629,14 +649,16 @@ Do not kill the server if there is a REPL connected to that server."
                            (buffer-list)))
         (nrepl-kill-server-buffer server-buf)))))
 
-(defun nrepl-start-client-process (&optional host port server-proc buffer-builder)
-  "Create new client process identified by HOST and PORT.
-In remote buffers, HOST and PORT are taken from the current tramp
-connection.  SERVER-PROC must be a running nREPL server process within
-Emacs.  BUFFER-BUILDER is a function of one argument (endpoint returned by
-`nrepl-connect') which returns a client buffer.  Return the newly created
-client process."
-  (let* ((endpoint (nrepl-connect host port))
+(defun nrepl-start-client-process (&optional host port server-proc buffer-builder socket-file)
+  "Create new client process identified by either HOST and PORT or SOCKET-FILE.
+If SOCKET-FILE is non-nil, it takes precedence.  In remote buffers, HOST
+and PORT are taken from the current tramp connection.  SERVER-PROC must be
+a running nREPL server process within Emacs.  BUFFER-BUILDER is a function
+of one argument (endpoint returned by `nrepl-connect') which returns a
+client buffer.  Return the newly created client process."
+  (let* ((endpoint (if socket-file
+                       (nrepl--unix-connect (expand-file-name socket-file))
+                     (nrepl-connect host port)))
          (client-proc (plist-get endpoint :proc))
          (builder (or buffer-builder (error "`buffer-builder' must be provided")))
          (client-buf (funcall builder endpoint)))

test/nrepl-client-tests.el

@@ -168,7 +168,8 @@
                                     (plist-get server-endpoint :port)
                                     server-process
                                     (lambda (client-endpoint)
-                                      client-buffer))))
+                                      client-buffer)
+                                    (plist-get params :socket-file))))
 
               ;; client connection is open
               (expect (process-status process-client)