Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Clojure web application library: abstracts HTTP to allow modular and concise webapps.
branch: master

This branch is 383 commits behind mmcgrana:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src/ring
test
.gitignore
LICENSE
README.textile
SPEC
build.xml

README.textile

Ring

Ring is a Clojure web applications library inspired by Python’s WSGI and Ruby’s Rack. By abstracting the details of HTTP into a simple, unified API, Ring allows web applications to be constructed of modular components that can be shared among a variety of applications, web servers, and web frameworks.

The SPEC file at the root of this distribution for provides a complete description of the Ring interface.

Quick Setup

First clone the Ring source:

git clone git://github.com/mmcgrana/ring.git cd ring

Then download the needed dependencies:

ant deps

The deps ant target downloads all Ring dependencies and unpacks them to deps/. To see a live “Hello World” Ring app, run:

java -Djava.ext.dirs=deps clojure.main src/ring/examples/hello_world.clj

then visit http://localhost:8080/ in your browser; the Ring app will respond to your request with a simple HTML page indicating the time of day.

To see a more sophisticated Ring app, run:

java -Djava.ext.dirs=deps clojure.main src/ring/examples/wrapping.clj
  • If you request http://localhost:8080/ in your browser the ring.dump handler will respond with an HTML page representing the request map that it received (see the SPEC for details on the request map).
  • If you request http://localhost:8080/clojure.png, the ring.file middleware will detect that there is a clojure.png file in the app’s public directory and return that image as a response.
  • If you request http://localhost:8080/error, the app will produce an error that will be caught by the ring.show-exceptions middleware, which will in turn return a readable backtrace as the HTML response.

All Available Libs

  • ring.jetty: Adapter for the Jetty webserver.
  • ring.httpcore: Adapter for the Apache HttpCore webserver.
  • ring.file: Middleware that serves static files out of a public directory.
  • ring.file-info: Middleware that augments response headers with info about File responses.
  • ring.static: Middleware that serves static files with specified prefixes out of a public directory.
  • ring.dump: Handler that dumps request maps as HTML responses for debugging.
  • ring.show-exceptions: Middleware that catches exceptions and displays readable backtraces for debugging.
  • ring.reload: Middleware to automatically reload selected libs before each requests, minimizing server restarts.
  • ring.builder: Helpers for composing Ring apps from multiple handlers and middleware.
  • ring.lint: Linter for the Ring interface, ensures compliance with the Ring spec.
  • ring.examples.*: Various example Ring apps.

Development

Ring is being actively developed; you can track its progress and contribute at the project’s GitHub page.

To run all the Ring unit tests:

java -Djava.ext.dirs=deps clojure.main test/ring/run.clj

You can learn more about Ring’s dependencies at the following sites:

Thanks

This project borrows heavily from Ruby’s Rack and Python’s WSGI, and I thank the communities developing and supporting those projects.



     +--->HTTP Request--->[Adapter]--->Req1---->[Middleware]--->Req2----+
     |                                                                  |
 [Client]                                                           [Handler]
     |                                                                  |
     +----HTTP Response<--[Adapter]<---Resp2<---[Middleware]<---Resp1<--+

Copyright © 2009 Mark McGranaghan and released under an MIT license.
Clojure logo by Tom Hickey.

Something went wrong with that request. Please try again.