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 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
56 | 56 |
57 [middleware]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shel
f/shelf@id_Middleware | 57 [middleware]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shel
f/shelf@id_Middleware |
58 | 58 |
59 [shelf.Pipeline]: http://www.dartdocs.org/documentation/shelf/latest/index.html
#shelf/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 Middleware that routes requests between handlers should be sure to update each |
| 67 request's [`handlerPath`][handlerPath] and [`url`][url]. This allows inner |
| 68 handlers to know where they are in the application so they can do their own |
| 69 routing correctly. This can be easily accomplished using |
| 70 [`Request.change()`][change]: |
| 71 |
| 72 [handlerPath]: http://www.dartdocs.org/documentation/shelf/latest/index.html#she
lf/shelf.Request@id_handlerPath |
| 73 [url]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/shelf
.Request@id_url |
| 74 [change]: http://www.dartdocs.org/documentation/shelf/latest/index.html#shelf/sh
elf.Request@id_change |
| 75 |
| 76 ```dart |
| 77 // In an imaginary routing middleware... |
| 78 var component = request.url.pathComponents.first; |
| 79 var handler = _handlers[component]; |
| 80 if (handler == null) return new Response.notFound(null); |
| 81 |
| 82 // Create a new request just like this one but with whatever URL comes after |
| 83 // [component] instead. |
| 84 return handler(request.change(script: component)); |
| 85 ``` |
| 86 |
66 ## Adapters | 87 ## Adapters |
67 | 88 |
68 An adapter is any code that creates [shelf.Request][] objects, passes them to a | 89 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, | 90 handler, and deals with the resulting [shelf.Response][]. For the most part, |
70 adapters forward requests from and responses to an underlying HTTP server; | 91 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 | 92 [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`, | 93 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. | 94 or it might pipe requests directly from an HTTP client to a Shelf handler. |
74 | 95 |
75 [shelf_io.serve]: http://www.dartdocs.org/documentation/shelf/latest/index.html#
shelf/shelf-io@id_serve | 96 [shelf_io.serve]: http://www.dartdocs.org/documentation/shelf/latest/index.html#
shelf/shelf-io@id_serve |
76 | 97 |
77 When implementing an adapter, some rules must be followed. The adapter must not | 98 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 | 99 pass the `url` or `handlerPath` parameters to [new shelf.Request][]; it should |
79 only pass `requestedUri`. If it passes the `context` parameter, all keys must | 100 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 | 101 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 | 102 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][]. | 103 header separated by commas as per [RFC 2616 section 4.2][]. |
83 | 104 |
84 [new shelf.Request]: http://www.dartdocs.org/documentation/shelf/latest/index.ht
ml#shelf/shelf.Request@id_Request- | 105 [new shelf.Request]: http://www.dartdocs.org/documentation/shelf/latest/index.ht
ml#shelf/shelf.Request@id_Request- |
85 | 106 |
86 [RFC 2616 section 4.2]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html | 107 [RFC 2616 section 4.2]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html |
87 | 108 |
88 An adapter must handle all errors from the handler, including the handler | 109 An adapter must handle all errors from the handler, including the handler |
(...skipping 35 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
124 } | 145 } |
125 ``` | 146 ``` |
126 | 147 |
127 ## Inspiration | 148 ## Inspiration |
128 | 149 |
129 * [Connect](http://www.senchalabs.org/connect/) for NodeJS. | 150 * [Connect](http://www.senchalabs.org/connect/) for NodeJS. |
130 * Read [this great write-up](http://howtonode.org/connect-it) to understand | 151 * Read [this great write-up](http://howtonode.org/connect-it) to understand |
131 the overall philosophy of all of these models. | 152 the overall philosophy of all of these models. |
132 * [Rack](http://rack.github.io/) for Ruby. | 153 * [Rack](http://rack.github.io/) for Ruby. |
133 * [WSGI](http://legacy.python.org/dev/peps/pep-3333/) for Python. | 154 * [WSGI](http://legacy.python.org/dev/peps/pep-3333/) for Python. |
OLD | NEW |