* TODOs

- [ ] make an egg
- [ ] test on windows
- [ ] write a blog post

* High-level overview

- There's =emacsclient= and =emacs --daemon= (which ends up running
  ~server-start~ in =startup.el=)
- =emacsclient= talks to the daemon via UNIX socket (default option on
  non-Windows platforms) or TCP (the only supported option on Windows)
- It speaks a textual, line-based protocol to send and receive
  commands, such as a request to evaluate data and a response to print
  the result

* UNIX socket specifics

- Just connect to it and send commands (=socat - UNIX-CONNECT:<path>=)
- The following paths are tried (with =$UID= being replaced by the
  user id of the process):
  - =$XDG_RUNTIME_DIR/emacs/server=
  - =$TMPDIR/emacs$UID/server=
  - =/tmp/emacs$UID/server=
- It's possible to directly specify the path by using the =-s= option
  or setting =$EMACS_SOCKET_NAME=

* TCP specifics

- The connection details are stored in a file holding host, port, pid
  and secret
- The following paths are tried:
  - =$HOME/$XDG_CONFIG_HOME/emacs/server/server=
  - =$HOME/.config/emacs/server/server=
  - =$HOME/.emacs.d/server/server=
  - =$APPDATA/$XDG_CONFIG_HOME/emacs/server/server=
  - =$APPDATA/.config/emacs/server/server=
  - =$APPDATA/.emacs.d/server/server=
- It's possible to directly specify the path by using the =-f= option
  or setting =$EMACS_SERVER_FILE=
- The TCP connection is established by connecting to the host and port
  (=nc <host> <port>=)
- The =SO_LINGER= option is set to 1 (enable) and 1 (timeout in seconds)
- Upon successful connection, the =-auth= command is used with the
  secret as argument

* TCP control file

#+BEGIN_SRC text
<host>:<port> <pid>
<64-char secret>
#+END_SRC

* Protocol

- The protocol is textual and line-based
- Each line contains one or more commands
- Commands are separated by a newline (\n)
- A command starts with a dash and may have a space-separated argument
- Arguments generally use quoting (except for the TCP secret one)
- The client sends commands to the server and the server answers with
  commands for the client to interpret
- The following list of server and client commands is not exhaustive,
  but instead covers all commands necessary for code evaluation

** Server commands

The client sends these commands to control the server.

***  =-auth <secret>=

Performs authentication. This must be used as the first command when
communicating via TCP. The secret can be found in the TCP control
file. Unlike all other commands, the argument does *not* need to be
quoted (as it's fixed-length). If authentication is not successful,
the server replies with an =-error= command.

*** =-eval <code>=

Evaluate the given code. The argument must be quoted. If evaluation is
not successful, the server replies with an =-error= command.

** Client commands

The server replies with these commands to control the client.

*** =-emacs-pid <pid>=

This command seems to be always sent after a successful evaluation
request. It can be safely ignored, unless you need to know the PID of
the Emacs process for a reason.

*** =-print <output>=

Print the initial evaluation result. Long evaluation resuls are split
into a =-print= and as many =-print-nonl= commands as necessary. The
argument is always quoted.

*** =-print-nonl <output>=

Print the continuation of an evaluation result. The argument is always
quoted.

*** =-error <message>=

Print an error message. The argument is always quoted. Note that
unlike all other commands, this one is not guaranteed to be terminated
by a newline.

** Quoting

The control characters of the protocol are the dash (command starter),
space (argument separator) and newline (line separator). Quoting uses
the ampersand character, similar to backslash escaping:

#+BEGIN_SRC
"&"  <=> "&&"
"-"  <=> "&-"
"\n" <=> "&n"
" "  <=> "&_"
#+END_SRC