Permalink
Browse files

rework SPEC and README to reflect new terminology

  • Loading branch information...
mmcgrana committed May 5, 2009
1 parent 203cbbd commit 37ff2680fe544e614904c030626123e116386957
Showing with 38 additions and 37 deletions.
  1. +8 −8 README.textile
  2. +30 −29 SPEC
View
@@ -25,21 +25,21 @@ 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@ endpoint will respond with an HTML page representing the Ring request that it received (see the @SPEC@ for details on the Ring request).
+ * 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.
h2. All Available Libs
- * @ring.jetty@: Handler for the Jetty webserver.
- * @ring.httpcore@: Handler for the Apache HttpCore webserver.
+ * @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@: Endpoint that dumps the Ring requests as HTML responses for debugging.
+ * @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 combining Ring endpoints and middleware into Ring apps.
+ * @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.
@@ -66,11 +66,11 @@ This project borrows heavily from Ruby's Rack and Python's WSGI, and I thank the
---
<pre><code>
- +--->HTTP Request--->[Handler]--->Req1---->[Middleware]--->Req2----+
+ +--->HTTP Request--->[Adapter]--->Req1---->[Middleware]--->Req2----+
| |
- [Client] [Endpoint]
+ [Client] [Handler]
| |
- +----HTTP Response<--[Handler]<---Resp2<---[Middleware]<---Resp1<--+
+ +----HTTP Response<--[Adapter]<---Resp2<---[Middleware]<---Resp1<--+
</code></pre>
Copyright (c) 2009 Mark McGranaghan and released under an MIT license.
View
59 SPEC
@@ -1,37 +1,38 @@
=== Ring Spec (Draft Version)
-Ring is defined in terms of Components, Handlers, Requests, and Responses,
-each of which are described below.
+Ring is defined in terms of Handlers, Middleware, Adapters, Requests Maps, and
+Response Maps, each of which are described below.
-== Components
-Ring components constitute the logic of the web application and are abstracted
-form the details of the HTTP protocol. They are implemented as Clojure
-functions that process a given request to generate and return a response.
+== Handlers
+Ring handlers constitute the core logic of the web application and are
+abstracted from the details of the HTTP protocol. Handlers are implemented as
+Clojure functions that process a given request map to generate and return a
+response map.
-A component is either an 'endpoint' or 'middleware'. An endpoint component is
-used at the leaf of a component tree, i.e. it does not call any other components
-to generate it's response. A 'middleware' component in contrast may invoke
-other components to generate its response. We can combine 1 or more endpoints
-with 0 or more middleware components to build a complete Ring 'app'. Such an
-app can then be run by a Ring handler.
-== Handlers
-A Ring handler is a server implementation than can 'run' apps. Handlers are
-responsible for implementing the HTTP protocol and abstracting the apps that
-they run from the details of the protocol.
+== Middleware
+Ring middleware augments the functionality of handlers by invoking them in the
+process of generating responses. Typically middleware will be implemented as a higher-order function that takes one or more handlers and configuration options
+as arguments and returns a new handler with the desired compound behavior.
+
+
+== Adapters
+Handlers are run via Ring adapters, which are in turn responsible for
+implementing the HTTP protocol and abstracting the handlers that they run from
+the details of the protocol.
-Handlers are implemented as functions of two arguments, an options map and a
-Ring app. The options map provides any needed configuration to the handler, such
+Adapters are implemented as functions of two arguments: an options map and a
+handler. The options map provides any needed configuration to the adapter, such
as the port on which to run.
-Once initialized, handlers receive HTTP requests, parse them to construct an
-Ring request, and then invoke their Ring app with this request as an
-argument. Once the app returns a Ring response, the handler uses it to construct
-and send an HTTP response to the client.
+Once initialized, adapters receive HTTP requests, parse them to construct an
+request map, and then invoke their handler with this request map as an
+argument. Once the handler returns a response map, the adapter uses it to
+construct and send an HTTP response to the client.
-== Ring Requests
-A Ring request is a Clojure map containing at least the following keys and
+== Request Map
+A request map is a Clojure map containing at least the following keys and
corresponding values:
:server-port
@@ -84,13 +85,13 @@ corresponding values:
(Optional, InputStream)
An InputStream for the request body, if present.
-If a component invokes another component with an environment containing
+If a component invokes another component with a request map containing
additional keys, these keys must be namespaced using the Clojure
:name.space/key-name convention. The ring.* namespaces are reserved.
-== Ring Responses
-A Ring response is a Clojure map containing at least the following keys and corresponding values:
+== Response Map
+A response map is a Clojure map containing at least the following keys and corresponding values:
:status
(Required, Integer)
@@ -118,5 +119,5 @@ A Ring response is a Clojure map containing at least the following keys and corr
Contents are consumed from the stream and sent to the client. When the
stream is exhausted, it is .close'd.
-As with environments, keys other than those listed above should be appropriately
-namespaced.
+As with request maps, keys in response maps other than those listed above should
+be appropriately namespaced.

0 comments on commit 37ff268

Please sign in to comment.