Dog Fort

Quick Start

Install node.

  lein new dogfort my-project
  cd my-project
  lein npm install
  lein build

then in another terminal

  cd my-project
  node main.js

For easy development install supervisor

  npm install supervisor -g

  cd my-project
  supervisor main.js

Supervisor will restart the node.process whenever you make changes.

Usage

Dog Fort uses Ring's concept of handlers and adapters, the only difference being that the handler should return a promise of a response structure, not the response itself, due to the asynchronous nature of Node. See Red Lobster for documentation on promises.

    (ns user
      (:use [dogfort.http :only [run-http]])
      (:require [redlobster.promise :as p]))

    (defn handler [request]
      (p/promise {:status 200
                  :headers {:content-type "text/html"}
                  :body "<h1>This is Dog Fort</h1>"}))

    (run-http handler {:port 1337})

The body of a response can also be a Node stream. Here's an example that serves a file directly from the file system using a Node Stream object.

    (ns user
      (:use [dogfort.http :only [run-http]])
      (:require [redlobster.stream :as stream]
                [redlobster.promise :as p])


    (defn handler [request]
      (p/promise {:status 200
                :headers {:content-type "text/plain"}
                :body (stream/slurp "README.md")}))

    (run-http handler {:port 1337})

Routing

Dog Fort includes a request routing mechanism heavily inspired by Compojure. It introduces the defroutes macro for building handlers with routing.

    (ns user
      (:use [dogfort.http :only [run-http]])
      (:require [dogfort.middleware.routing])
      (:use-macros [dogfort.middleware.routing-macros :only [defroutes GET]]))

    (defroutes app
      (GET "/hello/:name" [name]
        ["<h1>Hello " name "!</h1>"]))

    (run-http app {:port 1337})

The defroutes macro takes a symbol name, and a series of sub-handler definitions, which are created using the GET macro and its corresponding macros for other request methods: POST, HEAD, etc.

This macro takes a path expression in the Rails style, a vector of variable bindings that should match the variables used in the path expression, and a series of forms constituting the handler's body, and should return a response as usual.

Notice, however, that routing sub-handlers don't need to return a promise. For convenience, you can also return a response map directly, or dispense with the map altogether and just return the response body, either as a string, a sequence or a Node Stream object. The routing middleware will automatically wrap it as appropriate, defaulting to a Content-Type of text/html if you only provide the body. Note that if you need to perform asynchronous calls, you will still have to return a promise and realise it to a response map as usual.

License

Copyright 2012 Bodil Stokke and Matthew Molloy

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.