Drawbridge (HTTP Transport for nREPL)
Installation
|
The coordinates of the project changed from cemerick/drawbridge to
nrepl/drawbridge in version 0.1.
|
Drawbridge is available in Clojars. Add this :dependency
to your Leiningen
project.clj
:
[nrepl/drawbridge "0.2.1"]
Or, add this to your Maven project’s pom.xml
:
<repository>
<id>clojars</id>
<url>http://clojars.org/repo</url>
</repository>
<dependency>
<groupId>nrepl</groupId>
<artifactId>drawbridge</artifactId>
<version>0.2.1</version>
</dependency>
|
Drawbridge is compatible with Clojure 1.7.0+ and nREPL 0.4+. |
Upgrade notes
If you’re upgrading from 0.0.7 keep in mind that the namespaces of the project were changed as following:
-
cemerick.drawbridge
->drawbridge.core
-
cemerick.drawbridge.client
->drawbridge.client
Usage
While nREPL provides a solid REPL backend for Clojure, typical socket-based channels are often unsuitable. Being able to deploy applications that allow for REPL access via HTTP and HTTPS simplifies configuration and can alleviate security concerns, and works around limitations in various deployment environments where traditional socket-based channels are limited or entirely unavailable.
In a Ring web application
Once you have added Drawbridge to your project’s dependencies, just add its Ring handler to your application. For example, if you’re using Compojure for routing and such:
(require 'drawbridge.core)
(let [nrepl-handler (drawbridge.core/ring-handler)]
(ANY "/repl" request (nrepl-handler request)))
With this, any HTTP or HTTPS client can send nREPL messages to the
/repl
URI, and read responses from the same. Conveniently, any
security measures applied within your application will work fine in
conjunction with Drawbridge; so, if you configure its route to require
authentication or authorization to some application-specific role, those
prerequisites will apply just as with any other Ring handler in the same
context.
Some things to be aware of when using drawbridge.core/ring-handler
:
-
It requires
GET
andPOST
requests to be routed to whatever URI to which it is mapped; other request methods result in an HTTP error response. -
It requires these standard Ring middlewares to function properly:
-
keyword-params
-
nested-params
-
wrap-params
-
Especially if you are going to be connecting to your webapp’s nREPL endpoint with a client that uses Drawbridge’s own HTTP/HTTPS client transport (see below), this is all you need to know.
If you are interested in the implementation details and semantics,
perhaps because you’d like to implement support for Drawbridge in
non-Clojure nREPL clients, you’ll want to review the documentation for
ring-handler
, which contains additional important details.
In Clojure tooling
Drawbridge also provides a client-side nREPL transport implementation
for the Ring handler in drawbridge.client/ring-client-transport
.
Note that the drawbridge.client
namespace implicitly adds
implementations to the nrepl.core/url-connect
multimethod for
"http"
and "https"
schemes. So, once this namespace is loaded, any
tool that uses url-connect
will use ring-client-transport
for
connecting to HTTP and HTTPS nREPL endpoints.
Configuration
The client supports additional HTTP headers, which is useful e.g. for
using Bearer authorization to connect to the endpoint. The headers can
be set in the nREPL configuration. For example, create .nrepl.edn
in
the working directory with the contents:
{:drawbridge {:http-headers {:Authorization "Bearer <JWT token>"}}}
TODO
The biggest outstanding issues are around the semantics of how HTTP session (might optionally) map onto nREPL sessions. Right now, they don’t at all, though HTTP sessions are significant insofar as they retain the message queue nREPL will dispatch responses to that are emitted by asynchronous or long-running operations.
Secondarily, supporting nontextual REPL interactions over HTTP has not yet been addressed at all.
Need Help?
The primary support channel for Drawbridge is the Clojurians Slack. Feel
free to ask any questions on the #nrepl
channel there.
License
Copyright © 2012-2019 Chas Emerick, Bozhidar Batsov and other contributors.
Distributed under the Eclipse Public License, the same as Clojure.