Handlers are functions that accept a single incoming message as an argument. An nREPL server is started with a single handler function, which will be used to process messages for the lifetime of the server. Note that handler return values are ignored; results of performing operations should be sent back to the client via the transport in use (which will be explained shortly). This may seem peculiar, but is motivated by two factors:
Many operations — including something as simple as code evaluation — is fundamentally asynchronous with respect to the nREPL server
Many operations can produce multiple results (e.g. evaluating a snippet of
code like "(+ 1 2) (def a 6)"
).
Thus, messages provided to nREPL handlers are guaranteed to contain a
:transport
entry containing the transports that should be used
to send all responses precipitated by a given message. (This slot is added by
the nREPL server itself, thus, if a client sends any message containing a
"transport"
entry, it will be bashed out by the Transport
that was the
source of the message.) Further, all messages provided to nREPL handlers have
keyword keys (as per clojure.walk/keywordize-keys
).
Depending on its :op
, a message might be required to contain other slots, and
might optionally contain others. It is generally the case that request
messages should contain a globally-unique :id
.
Every request must provoke at least one and potentially many response messages,
each of which should contain an :id
slot echoing that of the provoking
request.
Once a handler has completely processed a message, a response
containing a :status
of :done
must be sent. Some operations necessitate
that additional responses related to the processing of a request are sent after
a :done
:status
is reported (e.g. delivering content written to out
by
evaluated code that started a future
).
Other statuses are possible, depending upon the semantics of the :op
being
handled; in particular, if the message is malformed or incomplete for a
particular :op
, then a response with an :error
:status
should be sent,
potentially with additional information about the nature of the problem.
It is possible for an nREPL server to send messages to a client that are not a
direct response to a request (e.g. streaming content written to System/out
might be started/stopped by requests, but messages containing such content
can’t be considered responses to those requests).
If the handler being used by an nREPL server does not recognize or cannot
perform the operation indicated by a request message’s :op
, then it should
respond with a message containing a :status
of "unknown-op"
.
It is currently the case that the handler provided as the :handler
to
nrepl.server/start-server
is generally built up as a result of
composing multiple pieces of middleware.
Can you improve this documentation? These fine people already did:
Bozhidar Batsov & Pierre-Luc PerronEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close