---
layout: doc
title: HTTP server
---

  <h2>Ring adapter(HTTP server) with async and websocket extenstion</h2>
{% highlight clojure %}
(:use org.httpkit.server)
{% endhighlight %}
  <p>The server uses an event-driven, non-blocking I/O model that makes it lightweight and scalable.
    It's written to conform to the standard Clojure web server
    <a href="https://github.com/ring-clojure/ring">Ring spec</a>, with asynchronous and websocket extenstion.
    HTTP Kit is (<a href="migration.html">almost</a>) drop-in replacement of ring-jetty-adapter
  </p>

          <p class="note"><a href="channel.html">A new unified Async/Websocket API(working in progress)</a></p>

  <h3 id="options" class="anchor">Hello, Clojure HTTP server</h3>
  <p> <code>run-server</code> starts a Ring-compatible HTTP server, <a href="#routing">routing using compojure</a></p>

{% highlight clojure %}
(defn app [req]
  {:status  200
   :headers {"Content-Type" "text/html"}
   :body    "hello HTTP!"})
(run-server app {:port 8080})
{% endhighlight %}

  <h4>Options:</h4>
  <ul>
    <li><code>:ip</code>: which IP to bind, default to <code>0.0.0.0</code></li>
    <li><code>:port</code>: which port listens incomming request, default to 8090</li>
    <li><code>:thread</code>: How many threads to compute response from request, default to 4</li>
    <li><code>:worker-name-prefix</code>: woker thread name prefix, default to <code>worker-</code>: <code>worker-1</code> <code>worker-2</code>....</li>
    <li><code>:queue-size</code>: max requests queued waiting for threadpool to compute response before reject, 503(Service Unavailable) is returned to client if queue is full, default to 20K</li>
    <li><code>:max-body</code>: length limit for request body in bytes, 413(Request Entity Too Large) is returned if exceeds this limit, default to 8388608(8M)</li>
    <li><code>:max-line</code>: length limit for HTTP inital line and per header,
      414(Request-URI Too Long) will be returned if exceeds this limit, default to 4096(4K),
      <a href="http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url">relevant discusstion on stackoverflow</a></li>
  </ul>

  <h3 class="anchor" id="websocket">Websocket extenstion</h3>
  <ul>
    <li>
      <code>if-ws-request</code> or <code>when-ws-request</code>: get the websocket connection, returns websocket handshake
    </li>
    <li><code>on-mesg</code>: register a fn to be called when there is string message from client</li>
    <li><code>send-mesg</code>: send string message to client. <i>Clojure data can be converted to string using
        <a href="https://github.com/clojure/data.json">JSON</a> or <a href="https://github.com/edn-format/edn">edn</a></i></li>
    <li><code>close-conn</code>: close the websocket connection</li>
    <li><code>on-close</code>: register a fn to be called when the connecton is closed</li>
  </ul>
  <p>For WebSocket Secure connection, one option is <a href="https://github.com/bumptech/stud">stud</a> (self-signed certificate may not work with websocket)</p>
  <p>A realtime chart example: <a href="https://github.com/http-kit/chat-websocket">https://github.com/http-kit/chat-websocket</a></p>

  {% highlight clojure %}

(defn chat-handler [req]
  (when-ws-request req ws-con  ; ws-con bind to the websocket connection
     (on-mesg ws-con (fn [msg]
                         (send-mesg ws-con msg) ;; echo back
                         (close-conn ws-con)))  ;; close the connection
     (on-close ws-con (fn [status] (println ws-con "closed")))))

(run-server chat-handler {:port 8080})
{% endhighlight %}

  <h3 class="anchor"  id="async">Asynchronous (long polling) extenstion</h3>
  <p><code>respond</code> accept a standard ring-response (:status :headers :body) or just the :body</p>
  <p>All request-level middlewares applied to <code>req</code> before passing to <code>aync-handler</code> (like any other handler)</p>
  <p><b class="message">The response is sent to client without response-level middlewares applied (a limitation, suggestions welcome)</b> </p>
  <p>Optional timeout facilities: <a href="timer.html">timer</a></p>
  <p>A realtime chart example: <a href="https://github.com/http-kit/chat-polling">https://github.com/http-kit/chat-polling</a></p>

{% highlight clojure %}
(defn async-handler [req]
  ; respond is a one-time function, can be called on any thread to send the response to client
  (async-response respond
                  ; just :body, can also be {:status _ :headers _ :body _}
                  (future (respond "hello world async"))))

(run-server async-handler {:port 8080})
{% endhighlight %}

  <h3 id="routing" class="anchor">Routing with Compojure</h3>
  <p>
    <a href="https://github.com/weavejester/compojure">Compojure</a> Can be used to do the routing, based on uri and method
  </p>

{% highlight clojure %}
(:use [compojure.route :only [files not-found]]
      [compojure.handler :only [site]] ; form, query params decode; cookie; session, etc
      [compojure.core :only [defroutes GET POST DELETE ANY context]]
      org.httpkit.server)

(defn show-landing-page [req] ;; ordinary clojure function, accept request map
  ;; return landing page's html string. possible template library:
  ;; mustache (https://github.com/shenfeng/mustache.clj, https://github.com/fhd/clostache...)
  ;; enlive (https://github.com/cgrand/enlive),  hiccup(https://github.com/weavejester/hiccup)
  )

(defn update-userinfo [req]          ;; ordinary clojure function
  (let [user-id (-> req :params :id)    ; param from uri
        password (-> req :params :password)] ; form param
    ....
    ))

(defroutes all-routes
  (GET "/" [] show-landing-page)
  (GET "/ws" [] chat-handler)     ;; websocket
  (GET "/async" [] async-handler) ;; asynchronous(long polling)
  (context "/user/:id" []
           (GET / [] get-user-by-id)
           (POST / [] update-userinfo))
  (route/files "/static/") ;; static file url prefix /static, in `public` folder
  (route/not-found "<p>Page not found.</p>")) ;; all other, return 404

(run-server (site #'all-routes) {:port 8080})
  {% endhighlight %}

  <h3 class="anchor" id="deploy">Recommended server deployment</h3>
  <p>http-kit runs alone happly, handy for development and quick deployment.
    Use reverse proxy like <a href="http://wiki.nginx.org/Main">Nginx</a>,
    <a href="http://www.lighttpd.net/">Lighthttpd</a>, etc in serious production is encouraged. They also <a href="migration.html#https">add https support</a>.</p>
  <ul>
    <li>They are fast, heavily optimized for static content.</li>
    <li>They can be configured to compress the content sent to browsers</li>
  </ul>
  <p>Sample Nginx configration:</p>
  {% highlight sh %}
upstream http_backend {
    server 127.0.0.1:8090;  # http-kit listen on 8090
    # keepalive(resue TCP connection) improves performance
    keepalive 32;  # both http-kit and nginx are good at concurrency
}

server {
    location /static/ {  # static content
        alias   /var/www/xxxx/public/;
    }
    location / {
        proxy_pass  http://http_backend;

        # tell http-kit to keep the connection
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;

        access_log  /var/log/nginx/xxxx.access.log;
    }
}
  {% endhighlight %}