Nrepl.next: Use Cases

NOTE: Details about message and response content as well as I/O handling to clarified.

Basic IDE interaction

This is the most simple case! The client simply sends some command to the server for evaluation and expects back some result. Examples would be completion information, docstrings, etc. This corresponds to one shot messages where we are only interested in the result and not in the environment. After the evaluation of the message is finished the evaluation environment is discarded.

1. Client sends message: {:message-id "uuid-string-123" :code "(do-something)"}.
2. Server creates a fresh transient session.
3. Server evaluates the code from the message in the transient session.
4. Server sends response: {:message-id "uuid-string-123" :value "[:done :something]"}.
5. Server sends response: {:message-id "uuid-string-123" :status "evaluation finished"}.
6. Server discards transient session.

Persistent session

This situation is more complex. It requires the server to keep a persistent session around between the client messages. An example might be an interactive REPL session on the client side.

1. Client sends message: {:message-id "uuid-string-123" :code "(clojure.tools.nrepl/retain-session!)"}.
2. Server creates a fresh transient session.
3. Server evaluates the code from the message in the transient session. The normal function call registers a persistent session. A session id is generated and returned as result.
4. Server sends response: {:message-id "uuid-string-123" :value "uuid-string-abc"}.
5. Server sends response: {:message-id "uuid-string-123" :status "evaluation finished"}.
6. The transient session is discarded. The persistent session is retained for further usage.
7. Client sends message: {:message-id "uuid-string-124" :session-id "uuid-string-abc" :code "(+ 1 2)"}.
8. Server sees session id and evaluates code in referenced session.
9. Further communication is usual.
10. Client sends message: {:message-id "uuid-string-256" :code "(clojure.tools.nrepl/release-session! \"uuid-string-abc\")"}.
11. Server creates a fresh transient session. (No session id is referenced in the message!)
12. Server sends response: {:message-id "uuid-string-256" :value "nil"}.
13. Server sends response: {:message-id "uuid-string-256" :status "evaluation finished"}.
14. Server discards the session and the last message's transient session.