= Transports

////
 talk about strings vs. bytestrings, the encoding thereof, etc when we
figure that out
////

_Transports_ are roughly analogous to Ring's adapters: they provide an
implementation of a common protocol (`nrepl.transport.Transport`)
to enable nREPL clients and servers to send and receive messages without regard
for the underlying channel or particulars of message encoding.

nREPL includes two transports, both of which are socket-based: a "tty"
transport that allows one to connect to an nREPL endpoint using e.g. `telnet`
(which therefore supports only the most simplistic interactive evaluation of
expressions), and one that uses
link:https://wiki.theory.org/index.php/BitTorrentSpecification#Bencoding[bencode] to encode
nREPL messages over sockets.  It is the latter that is used by default by
`nrepl.server/start-server` and `nrepl.core/connect`.

link:https://github.com/nrepl/nrepl/wiki/Extensions[Other nREPL transports are provided by the community].

== TTY Transport

Using the TTY transport is pretty simple. You just need to start an nREPL server with TTY transport and you're good to go:

[source,clojure]
----
(require
 '[nrepl.server :as server]
 '[nrepl.transport :as transport])

(server/start-server :port 12345 :transport-fn transport/tty :greeting-fn transport/tty-greeting)
----

NOTE: The `:greeting-fn` is responsible for printing the initial message you'll see
upon connecting.

Afterwards you can simply connect to the server with some TTY client like `telnet`, `nc` or `inf-clojure`.

[source,shell]
----
$ nc localhost 12345

;; Clojure 1.9.0
user=>
----

Starting with nREPL 0.5 you can also start an nREPL with a TTY transport using `clj`:

[source,shell]
----
$ clj -R:nrepl -m nrepl.cmdline -t nrepl.transport/tty
nREPL server started on port 63266 on host localhost - telnet://localhost:63266
----

== Bencode Transport

There's nothing special you have to do to use the bencode transport,
as it's the default transport for `nrepl.server/start-server`.

You'll need a bencode capable client to connect to an nREPL server that transport.

TIP: nREPL's bencode implementation is available as a https://github.com/nrepl/bencode[standalone library].
Keep in mind that nREPL itself doesn't use this library, as it's committed to having 0 runtime dependencies.
The code in the library and in nREPL `nrepl.bencode` namespace in identical, though, and will be kept in sync
in the future.
