Why isn't broker a handler?

[XedinUnknown]

Upon reading the readme, I noticed that one way to dispatch the middleware pipe is with Broker::handle(). Given that a common use of handlers is as middleware dispatchers, shouldn't Broker implement RequestHandlerInterface istead of MiddlewareInterface? This would look great to the consuming code, as the entry point would just need to do the same thing it would do if it were not using Broker:

/* @var $handler Northwoods\Broker\Broker /*
$handler->handle($request);

Given that Broker would probably be the top-most item of the stack that processes a request, it would make more sense for it to be a handler, rather than middleware, IMO.

[XedinUnknown]

It appears that there is in fact a separate handler implementation that does this, which is not apparent from the readme. Still, given that this handler implementation is not what the consumer of Broker will interact with, it seems more natural for Broker itself to be a handler.

[shadowhand]

Broker can already be used as a handler, it just needs a callable $default to generate a response when none is generated by a middleware.

[XedinUnknown]

If broker could be used as a handler, then I could use it in a method that accepts RequestHandlerInterface, and in the exact same way. But Broker does not implement RequestHandlerInterface (both formally, and because its handle() method requires a second parameter), and therefore cannot be used as a PSR-15 handler. Sorry if it was not clear that I am referring to formal PSR definitions, not simply usage.

[shadowhand]

@XedinUnknown what would the benefit of that be? I tried implementing RequestHandlerInterface and it didn't really seem to offer any value. Broker doesn't know what response should be given when it no longer has middleware to process, so all it can do is generate an empty HTTP 500.

[XedinUnknown]

Sorry, perhaps I wasn't clear from the beginning.

The consumers of Broker will most likely use it as an entry point to the application. They will probably marshal some environment values, such as those coming from a SAPI, into a server request object, give it to Broker, and emit the response. So, Broker is the main handler of the request, and therefore conceptually it looks more like a handler: they would want to "handle" the request in some familiar and interoperable way. Whereas if it is a middleware, they would have to have a stack implementation, and a handler, and a router/dispatcher. But Broker is already all that, so it looks more like a handler to me from this point too.

I must admit that, although the concept of a middleware pipe in general (as opposed to HTTP specific middleware) was something that I had separately come up with a few years ago, I'm finding it hard to understand the separation between Middleware and Handler. Middleware is usually dispatched as part of a stack; each middleware can be capable of producing a response; and it should have the ability to "forward" the request to the next middleware somehow. So, not sure how the concept of "handler", especially as a second parameter to process(), fits into the middleware paradigm. That said, you don't directly dispatch a middleware or a stack, and to be conceptually correct there needs to be a "handler" that simply gets a request and produces a response, without exposing detail of how that happens (perhaps via a middleware stack). This is especially confusing given that there doesn't appear to be consensus on how exactly middleware stacks are dispatched, and what is their relation to middleware. Some handlers dispatch stacks, others produce a response, some do both, and some do more than that. But I prefer to operate within a field of concepts, rather than standards or implementations, and IMO the current docs on the standard don't really give a clear description of this.

[shadowhand]

@XedinUnknown this is fixed in version 3.0.0, see #13.