Merge pull request #25 from http-interop/fix/import-meta-as-readme

Update README

Author: shadowhand

README.md

@@ -1,49 +1,56 @@
-HTTP Middleware
-===============
+HTTP Server Middleware
+======================
 
 1. Summary
 ----------
 
 The purpose of this PSR is to provide an interface that defines the formal
-method signature for HTTP Middleware that is compatible with HTTP Messages,
-as defined in PSR-7.
+method signature for HTTP Server Middleware that is compatible with HTTP
+Messages, as defined in [PSR-7][psr7].
+
+[psr7]: http://www.php-fig.org/psr/psr-7/
 
 2. Why Bother?
 --------------
 
-The general concept of reusable middleware was popularized by [StackPHP][stackphp].
-Since the release of the HTTP Messages standard, a number of frameworks have
-adopted middleware that uses HTTP Message interfaces.
+The HTTP Messages specification does not contain any reference to HTTP Middleware.
+
+The design pattern used by middleware has existed for many years as the
+[pipeline pattern][pipeline], or more specifically, "linear pipeline processing".
+The general concept of reusable middleware was popularized within PHP by
+[StackPHP][stackphp]. Since the release of the HTTP Messages standard, a number
+of frameworks have adopted middleware that use HTTP Message interfaces.
 
-Agreeing on a formal middleware interface eliminates several problems and
+Agreeing on a formal server middleware interface eliminates several problems and
 provides a number of benefits:
 
 * Provides a formal standard for middleware developers to commit to.
 * Eliminates duplication of similar interfaces defined by various frameworks.
 * Avoids minor discrepancies in method signatures.
 * Enables any middleware component to run in any compatible framework.
 
+[pipeline]: https://en.wikipedia.org/wiki/Pipeline_(computing)
 [stackphp]: http://stackphp.com/
-[express]: http://expressjs.com/en/guide/writing-middleware.html
 
 3. Scope
 --------
 
-## 3.1 Goals
+### 3.1 Goals
 
 * Create a middleware interface that uses HTTP Messages.
-* Provide a suggested interface for middleware stack containers.
-* Ensure that middleware will not be tied to a specific implementation of HTTP Messages.
+* Ensure that middleware will not be coupled to a specific implementation of HTTP Messages.
 * Implement a middleware signature that is based on best practices.
 
-## 3.2 Non-Goals
+### 3.2 Non-Goals
 
+* Attempting to define how middleware is dispatched.
+* Attempting to define interfaces for client/asynchronous middleware.
 * Attempting to define the mechanism by which HTTP responses are created.
 
 4. Approaches
 -------------
 
-There are currently two common approaches to middleware that use HTTP Messages.
+There are currently two common approaches to server middleware that use HTTP Messages.
 
 ### 4.1 Double Pass
 
@@ -54,6 +61,8 @@ and is based on [Express middleware][express], which is defined as:
 fn(request, response, next): response
 ```
 
+[express]: http://expressjs.com/en/guide/writing-middleware.html
+
 Based on the middleware implementations already used by frameworks that have
 adopted this signature, the following commonalities are observed:
 
@@ -110,19 +119,17 @@ This may be resolved in the future with [functional interfaces][php-functional].
 The other approach to middleware is much closer to [StackPHP][stackphp] style
 and is defined as:
 
-
 ```
-fn(request, next): response
+fn(request, frame): response
 ```
 
 Middleware taking this approach generally has the following commonalities:
 
-* The middleware is defined as a [callable][php-callable] using a [closure][php-closure]
- or a class with an `__invoke` method.
+* The middleware is defined with a specific interface with a method that takes
+ the request for processing.
 * The middleware is passed 2 arguments during invocation:
- 1. A `RequestInterface` implementation.
- 3. A `callable` that receives the request to dispatch next middleware.
-
+ 1. An object that represents an HTTP request.
+ 2. A delegate that receives the request to dispatch next middleware in the pipeline.
 
 In this form, middleware has no access to a response until one is generated by
 innermost middleware. Middleware can then modify the response before returning
@@ -136,59 +143,142 @@ only the request being passed to the middleware.
 #### 4.2.1 Projects Using Single Pass
 
 There are fewer examples of this approach within projects using HTTP Messages,
-with a couple of notable exceptions.
+with one notable exception.
 
-[Guzzle middleware](http://docs.guzzlephp.org/en/latest/handlers-and-middleware.html)
-uses a rather unique approach to middleware that is based around generators and
-promises. Ignoring the generator portion, Guzzle middleware has the signature:
+[Guzzle middleware][guzzle-middleware] is focused on outgoing (client) requests
+and uses this signature:
 
 ```
 function(RequestInterface $request, array $options): ResponseInterface
 ```
 
-[Laravel middleware](https://laravel.com/docs/master/middleware) does make use
-of HTTP Messages but supports middleware with the signature:
+#### 4.2.2 Additional Projects Using Single Pass
+
+There are also significant projects that predate HTTP Messages using this approach.
+
+[StackPHP][stackphp] is based on [Symfony HttpKernel][httpkernel] and supports
+middleware with this signature:
 
 ```
-function handle(Request $request, callable $next): Response
+handle(Request $request, $type, $catch): Response
 ```
 
-[StackPHP][stackphp] is based specifically around [Symfony HttpKernel][httpkernel]
-and not HTTP Messages but does use a single pass approach:
+*__Note__: While Stack has multiple arguments, a response object is not included.*
 
-```php
-handle(Request $request, $type, $catch): Response
+[Laravel middleware][laravel-middleware] uses Symfony components and supports
+middleware with this signature:
+
+```
+function handle(Request $request, callable $next): Response
 ```
 
+[guzzle-middleware]: http://docs.guzzlephp.org/en/latest/handlers-and-middleware.html
 [httpkernel]: https://symfony.com/doc/2.0/components/http_kernel/introduction.html
+[laravel-middleware]: https://laravel.com/docs/master/middleware
 
 ### 4.3 Comparison of Approaches
 
 The single pass approach to middleware has been well established in the PHP
 community for many years. This is most evident with the large number of packages
 that are based around StackPHP.
 
-The double pass approach is much newer but has already been widely adopted by
+The double pass approach is much newer but has been almost universally used by
 early adopters of HTTP Messages.
 
-5. `DelegateInterface`
+### 4.4 Chosen Approach
+
+Despite the nearly universal adoption of the double-pass approach there are
+significant issues regarding implementation.
+
+The most severe is that passing an empty response has no guarantees that the
+response is in a usable state. This is further exacerbated by the fact that a
+middleware may modify the response before passing it for further dispatching.
+
+Further compounding the problem is that there is no way to ensure that the
+response body has not been written to, which can lead to incomplete output or
+error responses being sent with cache headers attached. It is also possible
+to end up with [corrupted body content][rob-allen-filtering] when writing over
+existing body content if the new content is shorter than the original. The most
+effective way to resolve these issues is to always provide a fresh stream when
+modifying the body of a message.
+
+[rob-allen-filtering]: https://akrabat.com/filtering-the-psr-7-body-in-middleware/
+
+Some have argued that passing the response helps ensure dependency inversion.
+While it is true that it helps avoid depending on a specific implementation of
+HTTP messages, the problem can also be resolved by injecting factories into the
+middleware to create HTTP message objects, or by injecting empty message instances.
+With the creation of HTTP Factories in [PSR-17][psr17], a standard approach to
+handling dependency inversion is possible.
+
+[psr17]: https://github.com/php-fig/fig-standards/blob/master/proposed/http-factory/http-factory-meta.md
+
+A more subjective, but also important, concern is that existing double-pass
+middleware typically uses the `callable` type hint to refer to middleware.
+This makes strict typing impossible, as there is no assurance that the `callable`
+being passed implements a middleware signature, which reduces runtime safety.
+
+**Due to these significant issues the lambda approach has been choosen for this proposal.**
+
+5. Design Decisions
 -------------------
 
-The `$next` argument is a callable in most existing middleware systems. However using
-an interface allows to improve type safety and IDE support.
+### 5.1 Middleware Design
+
+The `ServerMiddlewareInterface` defines a single method that accepts a server
+request and a delegate and must return a response. The middleware may:
+
+- Evolve the request before passing it to the delegate to execute the next
+ available middleware.
+- Evolve the response received from the delegate before returning it.
+- Create and return a response without passing it to the delegate, thereby
+ preventing any further middleware from executing.
+
+#### Why doesn't middleware use `__invoke`?
+
+Doing so would conflict with existing middleware that implements the double-pass
+approach and may want to implement the middleware interface.
+
+In addition, classes that define `__invoke` can be type hinted as `callable`,
+which results in less strict typing. This is generally undesirable, especially
+when the `__invoke` method uses strict typing.
+
+#### Why is a server request required?
+
+To make it clear that the middleware can only be used in a synchronous, server
+side context.
+
+While not all middleware will need to use the additional methods defined by the
+server request interface, external requests are typically handled asynchronously
+and would need to return a [promise][promises] of a response. (This is primarily
+due to the fact that multiple requests can be made in parallel and processed as
+they are returned.) It is outside the scope of this proposal to address the needs
+of asynchronous request/response life cycle.
+
+Attempting to define client middleware would be premature at this point. Any future
+proposal that is focused on client side request processing should have the opportunity
+to define a standard that is specific to the nature of asynchronous middleware.
+
+_See "client vs server side middleware" in [relevant links](#relevant-links) for
+additional information._
+
+[promises]: https://promisesaplus.com/
+
+### 5.2 Delegate Design
+
+The `DelegateInterface` defines a single method that accepts a request and
+returns a response. The delegate interface must be implemented by any middleware
+dispatcher that uses middleware implementing `ServerMiddlewareInterface`.
+
+#### Why isn't the delegate a `callable`?
 
-Using `__invoke()` as the method name was considered but was not kept. That solution
-would have had the benefit of keeping the existing practice of invoking `$next`
-directly (`$response = $next($request)`). However many existing middleware systems
-already use a class that implements `__invoke()` for the `$next` argument with
-a different signature: `$request` *and* `$response`. By selecting a different method,
-PSR-15 may be implemented within existing systems in parallel with existing features,
-providing a migration path for these libraries and their consumers. In some cases,
-existing `__invoke()` implementations could even proxy to the method defined by
-PSR-15, or vice versa.
+Using an interface type hint improves runtime safety and IDE support.
 
-You can read [the relevant discussion in the mailing list](https://groups.google.com/d/topic/php-fig/V12AAcT_SxE/discussion).
+In addition, it allows compatibility with existing middleware that already defines
+an `__invoke` method.
 
+_See "discussion of FrameInterface" in [relevant links](#relevant-links) for
+additional information._
 
 6. People
 ---------
@@ -205,11 +295,12 @@ You can read [the relevant discussion in the mailing list](https://groups.google
 ### 6.3 Contributors
 
 * Rasmus Schultz, <rasmus@mindplay.dk>
+* Matthew Weier O'Phinney, <mweierophinney@gmail.com>
 
 7. Votes
 --------
 
-* [Entrance Vote](https://groups.google.com/forum/#!topic/php-fig/v9AijALWJhI)
+* [Entrance Vote](https://groups.google.com/d/msg/php-fig/v9AijALWJhI/04XCwqgIEAAJ)
 * **Acceptance Vote:** _(not yet taken)_
 
 8. Relevant Links
@@ -219,6 +310,8 @@ _**Note:** Order descending chronologically._
 
 * [PHP-FIG mailing list thread](https://groups.google.com/d/msg/php-fig/vTtGxdIuBX8/NXKieN9vDQAJ)
 * [The PHP League middleware proposal](https://groups.google.com/d/msg/thephpleague/jyztj-Nz_rw/I4lHVFigAAAJ)
+* [PHP-FIG discussion of FrameInterface](https://groups.google.com/d/msg/php-fig/V12AAcT_SxE/aRXmNnIVCwAJ)
+* [PHP-FIG discussion about client vs server side middleware](https://groups.google.com/d/msg/php-fig/vBk0BRgDe2s/GTaT0yKNBgAJ)
 
 9. Errata
 ---------