diff --git a/README.md b/README.md index 0dee32f0..2b1c5ea0 100644 --- a/README.md +++ b/README.md @@ -8,57 +8,53 @@ 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][1] file at the root of this distribution provides a -complete description of the Ring interface. +The [SPEC.md][1] file at the root of this distribution provides a +complete description of the Ring interface. The [Wiki][2] contains +more in-depth documentation on how to use Ring. -[1]: https://github.com/ring-clojure/ring/blob/master/SPEC - -## Upgrade Notice - -From version 1.2.1 onward, the ring/ring-core package no longer comes -with the `javax.servlet/servlet-api` package as a dependency (see -issue [#89][2]). - -If you are using the `ring/ring-core` namespace on its own, you may -run into errors when executing tests or running alternative adapters. -To resolve this, include the following dependency in your dev profile: - - [javax.servlet/servlet-api "2.5"] - -[2]: https://github.com/ring-clojure/ring/pull/89 +[1]: https://github.com/ring-clojure/ring/blob/master/SPEC.md +[2]: https://github.com/ring-clojure/ring/wiki ## Libraries -* ring-core - essential functions for handling parameters, cookies and more -* ring-devel - functions for developing and debugging Ring applications -* ring-servlet - construct Java servlets from Ring handlers -* ring-jetty-adapter - a Ring adapter that uses the Jetty webserver +* `ring/ring` - meta-package containing all relevant dependencies +* `ring/ring-core` - core functions and middleware for Ring handlers, + requests and responses +* `org.clojure/ring-websocket-protocols` - contains only the protocols + necessary for the WebSocket API +* `ring/ring-devel` - functions for developing and debugging Ring + applications +* `ring/ring-servlet` - construct legacy Java Servlets (≤ 4.0) from Ring + handlers +* `org.ring-clojure/ring-jakarta-servlet` construct + [Jakarta Servlets][3] (≥ 5.0) from Ring handlers +* `ring/ring-jetty-adapter` - a Ring adapter that uses an embedded + [Jetty][4] web server + +[3]: https://projects.eclipse.org/projects/ee4j.servlet +[4]: https://eclipse.dev/jetty/ ## Installation -To include one of the above libraries, for example `ring-core`, add -the following to your `:dependencies`: +To include one of the above libraries, for instance `ring-core`, add +the following dependency to your `deps.edn` file: - [ring/ring-core "1.10.0"] + ring/ring-core {:mvn/version "1.10.0"} -To include all of them: +Or to your Leiningen project file: - [ring "1.10.0"] + [ring/ring-core "1.10.0"] ## Documentation * [Wiki](https://github.com/ring-clojure/ring/wiki) * [API docs](https://ring-clojure.github.io/ring/) -## Community - -* [Google group](http://groups.google.com/group/ring-clojure) - ## Contributing -Please see [CONTRIBUTING.md][3]. +Please read [CONTRIBUTING.md][5] before submitting a pull request. -[3]: https://github.com/ring-clojure/ring/blob/master/CONTRIBUTING.md +[5]: https://github.com/ring-clojure/ring/blob/master/CONTRIBUTING.md ## Thanks diff --git a/SPEC b/SPEC deleted file mode 100644 index 3778c117..00000000 --- a/SPEC +++ /dev/null @@ -1,141 +0,0 @@ -=== Ring Spec (1.4) -Ring is defined in terms of handlers, middleware, adapters, requests maps, and -response maps, each of which are described below. - - -== Handlers -Ring handlers constitute the core logic of the web application. Handlers are -implemented as Clojure functions. - -A synchronous handler takes 1 argument, a request map, and returns a response -map. - -An asynchronous handler takes 3 arguments: a request map, a callback function -for sending a response and a callback function for raising an exception. The -response callback takes a response map as its argument. The exception callback -takes an exception as its argument. - -A handler function may simultaneously support synchronous and asynchronous -behavior by accepting both arities. - - -== 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. - -Adapters are implemented as functions of two arguments: a handler and an options -map. The options map provides any needed configuration to the adapter, such as -the port on which to run. - -Once initialized, adapters receive HTTP requests, parse them to construct a -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. - - -== Request Map -A request map is a Clojure map containing at least the following keys and -corresponding values: - -:server-port - (Required, Integer) - The port on which the request is being handled. - -:server-name - (Required, String) - The resolved server name, or the server IP address. - -:remote-addr - (Required, String) - The IP address of the client or the last proxy that sent the request. - -:uri - (Required, String) - The request URI, excluding the query string and the "?" separator. - Must start with "/". - -:query-string - (Optional, String) - The query string, if present. - -:scheme - (Required, clojure.lang.Keyword) - The transport protocol, must be one of :http or :https. - -:request-method - (Required, clojure.lang.Keyword) - The HTTP request method, must be a lowercase keyword corresponding to a HTTP - request method, such as :get or :post. - -:protocol - (Required, String) - The protocol the request was made with, e.g. "HTTP/1.1". - -:content-type [DEPRECATED] - (Optional, String) - The MIME type of the request body, if known. - -:content-length [DEPRECATED] - (Optional, Integer) - The number of bytes in the request body, if known. - -:character-encoding [DEPRECATED] - (Optional, String) - The name of the character encoding used in the request body, if known. - -:ssl-client-cert - (Optional, java.security.cert.X509Certificate) - The SSL client certificate, if supplied. - -:headers - (Required, clojure.lang.IPersistentMap) - A Clojure map of downcased header name Strings to corresponding header value - Strings. When there are multiple headers with the same name, the header - values are concatenated together, separated by the "," character. - -:body - (Optional, java.io.InputStream) - An InputStream for the request body, if present. - - -== Response Map -A response map is a Clojure map containing at least the following keys and -corresponding values: - -:status - (Required, Integer) - The HTTP status code, must be greater than or equal to 100. - -:headers - (Required, clojure.lang.IPersistentMap) - A Clojure map of HTTP header names to header values. These values may be - either Strings, in which case one name/value header will be sent in the - HTTP response, or a seq of Strings, in which case a name/value header will be - sent for each such String value. - -:body - (Optional, ring.core.protocols/StreamableResponseBody) - A representation of the response body, if a response body is appropriate for - the response's status code. The response body must satisfy the - StreamableResponseBody protocol located in the ring.core.protocols namespace. - - By default the protocol is satisfied by the following types: - - String: - Contents are sent to the client as-is. - ISeq: - Each element of the seq is sent to the client as a string. - File: - Contents at the specified location are sent to the client. The server may - use an optimized method to send the file if such a method is available. - InputStream: - Contents are consumed from the stream and sent to the client. When the - stream is exhausted, it is .close'd. diff --git a/SPEC-alpha.md b/SPEC.md similarity index 100% rename from SPEC-alpha.md rename to SPEC.md