A zio.http.ProtocolStack represents a linear stack of protocol layers, each of which can statefully transform incoming and outgoing values of some handler.

Protocol stacks can be thought of as a formal model of the process of transforming one handler into another handler.

Protocol stacks are designed to support precise semantics around error handling. In particular, if a layer successfully processes an incoming value of a handler, then that same layer will also have a chance to process the outgoing value of the handler. This requirement constrains the ways in which layers can fail, and the types of handlers they may be applied to.

In particular, protocol stacks can be applied to handlers that fail with the same type as their output type. This guarantees that should a handler fail, it will still produce an outgoing value that can be processed by all the layers that successfully transformed the incoming value.

Further, a layer may only fail while it processes an incoming value, and it may only value with the same type as its outgoing value. This guarantees that should a layer fail, it will still produce an outgoing value that can be processed by all the earlier layers that successfully transformed the incoming value.

In a way, the entire design of protocol stacks is geared at ensuring layers that successfully process incoming values will also have a chance to process outgoing values.

The only composition operator on protocol stacks is ++, which simply chains two stacks together. This operator is associative and has an identity (which is the protocol stack that neither transforms incoming nor outgoing values, and which acts as an identity when used to transform handlers).