| OLD | NEW |
| 1 ## Web Server Middleware for Dart | 1 ## Web Server Middleware for Dart |
| 2 | 2 |
| 3 ## Introduction | 3 ## Introduction |
| 4 | 4 |
| 5 **Shelf** makes it easy to create and compose **web servers** and **parts of web | 5 **Shelf** makes it easy to create and compose **web servers** and **parts of web |
| 6 servers**. How? | 6 servers**. How? |
| 7 | 7 |
| 8 * Expose a small set of simple types. | 8 * Expose a small set of simple types. |
| 9 * Map server logic into a simple function: a single argument for the request, | 9 * Map server logic into a simple function: a single argument for the request, |
| 10 the response is the return value. | 10 the response is the return value. |
| (...skipping 23 matching lines...) Expand all Loading... |
| 34 ``` | 34 ``` |
| 35 | 35 |
| 36 ## Handlers and Middleware | 36 ## Handlers and Middleware |
| 37 | 37 |
| 38 A [handler][] is any function that handles a [shelf.Request][] and returns a | 38 A [handler][] is any function that handles a [shelf.Request][] and returns a |
| 39 [shelf.Response][]. It can either handle the request itself--for example, a | 39 [shelf.Response][]. It can either handle the request itself--for example, a |
| 40 static file server that looks up the requested URI on the filesystem--or it can | 40 static file server that looks up the requested URI on the filesystem--or it can |
| 41 do some processing and forward it to another handler--for example, a logger that | 41 do some processing and forward it to another handler--for example, a logger that |
| 42 prints information about requests and responses to the command line. | 42 prints information about requests and responses to the command line. |
| 43 | 43 |
| 44 [handler]: https://api.dartlang.org/apidocs/channels/be/dartdoc-viewer/shelf/she
lf.Handler | 44 [handler]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/s
helf@id_Handler |
| 45 | 45 |
| 46 [shelf.Request]: https://api.dartlang.org/apidocs/channels/be/dartdoc-viewer/she
lf/shelf.Request | 46 [shelf.Request]: http://www.dartdocs.org/documentation/shelf/latest/index.html#s
helf/shelf.Request |
| 47 | 47 |
| 48 [shelf.Response]: https://api.dartlang.org/apidocs/channels/be/dartdoc-viewer/s
helf/shelf.Response | 48 [shelf.Response]: http://www.dartdocs.org/documentation/shelf/latest/index.html
#shelf/shelf.Response |
| 49 | 49 |
| 50 The latter kind of handler is called "[middleware][]", since it sits in the | 50 The latter kind of handler is called "[middleware][]", since it sits in the |
| 51 middle of the server stack. Middleware can be thought of as a function that | 51 middle of the server stack. Middleware can be thought of as a function that |
| 52 takes a handler and wraps it in another handler to provide additional | 52 takes a handler and wraps it in another handler to provide additional |
| 53 functionality. A Shelf application is usually composed of many layers of | 53 functionality. A Shelf application is usually composed of many layers of |
| 54 middleware with one or more handlers at the very center; the [shelf.Pipeline][] | 54 middleware with one or more handlers at the very center; the [shelf.Pipeline][] |
| 55 class makes this sort of application easy to construct. | 55 class makes this sort of application easy to construct. |
| 56 | 56 |
| 57 [middleware]: https://api.dartlang.org/apidocs/channels/be/dartdoc-viewer/shelf/
shelf.Middleware | 57 [middleware]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shel
f/shelf@id_Middleware |
| 58 | 58 |
| 59 [shelf.Pipeline]: https://api.dartlang.org/apidocs/channels/be/dartdoc-viewer/s
helf/shelf.Pipeline | 59 [shelf.Pipeline]: http://www.dartdocs.org/documentation/shelf/latest/index.html
#shelf/shelf.Pipeline |
| 60 | 60 |
| 61 Some middleware can also take multiple handlers and call one or more of them for | 61 Some middleware can also take multiple handlers and call one or more of them for |
| 62 each request. For example, a routing middleware might choose which handler to | 62 each request. For example, a routing middleware might choose which handler to |
| 63 call based on the request's URI or HTTP method, while a cascading middleware | 63 call based on the request's URI or HTTP method, while a cascading middleware |
| 64 might call each one in sequence until one returns a successful response. | 64 might call each one in sequence until one returns a successful response. |
| 65 | 65 |
| 66 ## Adapters | 66 ## Adapters |
| 67 | 67 |
| 68 An adapter is any code that creates [shelf.Request][] objects, passes them to a | 68 An adapter is any code that creates [shelf.Request][] objects, passes them to a |
| 69 handler, and deals with the resulting [shelf.Response][]. For the most part, | 69 handler, and deals with the resulting [shelf.Response][]. For the most part, |
| 70 adapters forward requests from and responses to an underlying HTTP server; | 70 adapters forward requests from and responses to an underlying HTTP server; |
| 71 [shelf_io.serve][] is this sort of adapter. An adapter might also synthesize | 71 [shelf_io.serve][] is this sort of adapter. An adapter might also synthesize |
| 72 HTTP requests within the browser using `window.location` and `window.history`, | 72 HTTP requests within the browser using `window.location` and `window.history`, |
| 73 or it might pipe requests directly from an HTTP client to a Shelf handler. | 73 or it might pipe requests directly from an HTTP client to a Shelf handler. |
| 74 | 74 |
| 75 [shelf_io.serve]: https://api.dartlang.org/apidocs/channels/be/dartdoc-viewer/sh
elf/shelf-io#id_serve | 75 [shelf_io.serve]: http://www.dartdocs.org/documentation/shelf/latest/index.html#
shelf/shelf-io@id_serve |
| 76 | 76 |
| 77 When implementing an adapter, some rules must be followed. The adapter must not | 77 When implementing an adapter, some rules must be followed. The adapter must not |
| 78 pass the `url` or `scriptName` parameters to [new shelf.Request][]; it should | 78 pass the `url` or `scriptName` parameters to [new shelf.Request][]; it should |
| 79 only pass `requestedUri`. If it passes the `context` parameter, all keys must | 79 only pass `requestedUri`. If it passes the `context` parameter, all keys must |
| 80 begin with the adapter's package name followed by a period. If multiple headers | 80 begin with the adapter's package name followed by a period. If multiple headers |
| 81 with the same name are received, the adapter must collapse them into a single | 81 with the same name are received, the adapter must collapse them into a single |
| 82 header separated by commas as per [RFC 2616 section 4.2][]. | 82 header separated by commas as per [RFC 2616 section 4.2][]. |
| 83 | 83 |
| 84 [new shelf.Request]: https://api.dartlang.org/apidocs/channels/be/dartdoc-viewer
/shelf/shelf.Request#id_Request- | 84 [new shelf.Request]: http://www.dartdocs.org/documentation/shelf/latest/index.ht
ml#shelf/shelf.Request@id_Request- |
| 85 | 85 |
| 86 [RFC 2616 section 4.2]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html | 86 [RFC 2616 section 4.2]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html |
| 87 | 87 |
| 88 An adapter must handle all errors from the handler, including the handler | 88 An adapter must handle all errors from the handler, including the handler |
| 89 returning a `null` response. It should print each error to the console if | 89 returning a `null` response. It should print each error to the console if |
| 90 possible, then act as though the handler returned a 500 response. The adapter | 90 possible, then act as though the handler returned a 500 response. The adapter |
| 91 may include body data for the 500 response, but this body data must not include | 91 may include body data for the 500 response, but this body data must not include |
| 92 information about the error that occurred. This ensures that unexpected errors | 92 information about the error that occurred. This ensures that unexpected errors |
| 93 don't result in exposing internal information in production by default; if the | 93 don't result in exposing internal information in production by default; if the |
| 94 user wants to return detailed error descriptions, they should explicitly include | 94 user wants to return detailed error descriptions, they should explicitly include |
| (...skipping 29 matching lines...) Expand all Loading... |
| 124 } | 124 } |
| 125 ``` | 125 ``` |
| 126 | 126 |
| 127 ## Inspiration | 127 ## Inspiration |
| 128 | 128 |
| 129 * [Connect](http://www.senchalabs.org/connect/) for NodeJS. | 129 * [Connect](http://www.senchalabs.org/connect/) for NodeJS. |
| 130 * Read [this great write-up](http://howtonode.org/connect-it) to understand | 130 * Read [this great write-up](http://howtonode.org/connect-it) to understand |
| 131 the overall philosophy of all of these models. | 131 the overall philosophy of all of these models. |
| 132 * [Rack](http://rack.github.io/) for Ruby. | 132 * [Rack](http://rack.github.io/) for Ruby. |
| 133 * [WSGI](http://legacy.python.org/dev/peps/pep-3333/) for Python. | 133 * [WSGI](http://legacy.python.org/dev/peps/pep-3333/) for Python. |
| OLD | NEW |