server.html

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

  <h2>Ring adapter(HTTP server) with async and websocket extension</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 extension.
    HTTP Kit is (<a href="migration.html">almost</a>) drop-in replacement of ring-jetty-adapter
  </p>

  <h3 id="options" class="anchor">Hello, Clojure HTTP server</h3>
  <p> <code>run-server</code> starts a Ring-compatible HTTP server. You may want to do <a href="#routing">routing with 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 for incoming requests, 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>: worker 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 thread pool to compute response before rejecting, 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 request exceeds this limit, default to 8388608(8M)</li>
    <li><code>:max-line</code>: length limit for HTTP initial line and per header,
      414(Request-URI Too Long) will be returned if exceeding this limit, default to 8192(8K),
      <a href="http://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url">relevant discussion on Stack Overflow</a></li>
  </ul>

  <h3 class="anchor" id="stop-server">Stop/Restart Server</h3>

<p>
  <code>run-server</code> returns a function that stops the server, which can take an optional timeout(ms) param to wait for existing requests to be finished.
</p>

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

(defonce server (atom nil))

(defn stop-server []
  (when-not (nil? @server)
    ;; graceful shutdown: wait 100ms for existing requests to be finished
    ;; :timeout is optional, when no timeout, stop immediately
    (@server :timeout 100)
    (reset! server nil)))

(defn -main [& args]
  ;; The #' is useful when you want to hot-reload code
  ;; You may want to take a look: https://github.com/clojure/tools.namespace
  ;; and https://http-kit.github.io/migration.html#reload
  (reset! server (run-server #'app {:port 8080})))
{% endhighlight %}


  <h3 class="anchor" id="channel">Unified Async/Websocket API</h3>
<p class="red">The with-channel API is not compatible with the RC releases. The new one is better and much easier to understand and use. The old documentation is <a href="server_old.html">here</a></p>

<p>Unified asynchronous channel interface for HTTP (streaming or long-polling) and WebSocket.</p>

Channel defines the following contract:
<ul>
  <li>
    <code>open?</code>: Returns true iff channel is open.
  </li>
  <li>
    <code>close</code>: Closes the channel. Idempotent: returns true if the channel was actually closed, or false if it was already closed.
  </li>
  <li>
    <code>websocket?</code>: Returns true iff channel is a WebSocket.
  </li>
  <li>
    <code>send!</code>:
   Sends data to client and returns true if the data was successfully written to the output queue, or false if the
    channel is closed. Normally, checking the returned value is not needed. This function returns immediately (does not
    block).
    <div class="send-doc">
      <p class="red">Data is sent directly to the client, NO RING MIDDLEWARE IS APPLIED.</p>
      <p>Data form: {:headers _ :status _ :body _} or just body. Note that :headers
        and :status will be stripped for WebSockets and for HTTP streaming responses
        after the first.</p>
    </div>

  </li>
  <li>
    <code>on-receive</code>:
    Sets handler (fn [message-string || byte[]) for notification of client WebSocket
    messages. Message ordering is guaranteed by server.
  </li>
  <li>
    <code>on-close</code>:
    Sets handler (fn [status]) for notification of channel being closed by the
    server or client. Handler will be invoked at most once. Useful for clean-up. Status can be `:normal`, `:going-away`, `:protocol-error`, `:unsupported`, `:unknown`, `:server-close`, `:client-close`
  </li>
</ul>


  <!-- <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 handler [req]
  (with-channel req channel              ; get the channel
    ;; communicate with client using method defined above
    (on-close channel (fn [status]
                        (println "channel closed")))
    (if (websocket? channel)
      (println "WebSocket channel")
      (println "HTTP channel"))
    (on-receive channel (fn [data]       ; data received from client
           ;; An optional param can pass to send!: close-after-send?
           ;; When unspecified, `close-after-send?` defaults to true for HTTP channels
           ;; and false for WebSocket.  (send! channel data close-after-send?)
                          (send! channel data))))) ; data is sent directly to the client
(run-server handler {:port 8080})
{% endhighlight %}

  <h3 class="anchor" id="async">HTTP Streaming example</h3>

  <ul>
    <li>First call of <code>send!</code>,
      sends HTTP status and Headers to client</li>
    <li>After the first, <code>send!</code> sends a chunk to client</li>
    <li> <code>close</code> sends an empty chunk to client, marking the end of the response</li>
    <li>Client close notification printed via <code>on-close</code></li>
  </ul>

{% highlight clojure %}
(use 'org.httpkit.timer)

(defn handler [request]
  (with-channel request channel
    (on-close channel (fn [status] (println "channel closed, " status)))
    (loop [id 0]
      (when (< id 10)
        (schedule-task (* id 200) ;; send a message every 200ms
                       (send! channel (str "message from server #" id) false)) ; false => don't close after send
        (recur (inc id))))
    (schedule-task 10000 (close channel)))) ;; close in 10s.

;;; open you browser http://127.0.0.1:9090, a new message show up every 200ms
(run-server handler {:port 9090})
{% endhighlight %}

    <h3 id="polling" class="anchor">Long polling example</h3>
    <p>Long polling is very much like streaming</p>
    <p><a href="https://github.com/http-kit/chat-polling">chat-polling</a> is a realtime chat example of using polling</p>

{% highlight clojure %}
(def channel-hub (atom {}))

(defn handler [request]
  (with-channel request channel
    ;; Store the channel somewhere, and use it to send response to client when interesting event happens
    (swap! channel-hub assoc channel request)
    (on-close channel (fn [status]
                        ;; remove from hub when channel get closed
                        (swap! channel-hub dissoc channel)))))

(on-some-event                          ;; send data to client
 (doseq [channel (keys @channel-hub)]
   (send! channel {:status 200
                   :headers {"Content-Type" "application/json; charset=utf-8"}
                   :body data})))

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

<h3 id="websocket" class="anchor">WebSocket example</h3>

<ul>
  <li>Two-way communication between client and server</li>
  <li>Can easily degrade to HTTP long polling/streaming, due to the unified API</li>
  <li>
    <code>send!</code> with <code>java.lang.String</code>, a text frame assembled and sent to client
  </li>
  <li>
    <code>send!</code> with <code>java.io.InputStream</code> or <code>byte[]</code>, a binary frame assembled and sent to client
  </li>
  <li>For WebSocket Secure connection, one option is <a href="https://github.com/bumptech/stud">stud</a> (self-signed certificate may not work with websocket).
    <a href="http://nginx.com/news/nginx-websockets.html">Nginx</a> can do it, too.</li>
</ul>

{% highlight clojure %}
(defn handler [request]
  (with-channel request channel
    (on-close channel (fn [status] (println "channel closed: " status)))
    (on-receive channel (fn [data] ;; echo it back
                          (send! channel data)))))

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

<h3 id="handshake" class="anchor">Control WebSocket handshake</h3>
    <p>The <code>with-channel</code> does the WebSocket handshake automatically. In case if you want to control it, e.g., to support WebSocket subprotocol,
      <a href="https://github.com/http-kit/http-kit/issues/64">here</a> is a workaround. cgmartin's <a href="https://gist.github.com/cgmartin/5880732">gist</a> is a good place to get inspired.</p>

  <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.core :only [defroutes GET POST DELETE ANY context]]
      org.httpkit.server)

(defn show-landing-page [req] ;; ordinary clojure function, accepts a request map, returns a response map
  ;; return landing page's html string. Using template library is a good idea:
  ;; 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))
  (files "/static/") ;; static file url prefix /static, in `public` folder
  (not-found "<p>Page not found.</p>")) ;; all other, return 404

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

  <h3 class="anchor" id="deploy">Recommended server deployment</h3>
  <p>http-kit runs alone happily, handy for development and quick deployment.
    Use of a 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 can also be used to <a href="migration.html#https">add https support</a>.</p>
  <ul>
    <li>They are fast and 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
    # put more servers here for load balancing
    # 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 %}