Cowboy 用户指南 (二十二) - Streams

流

流是一组形成HTTP请求/响应对的消息。

术语流来自HTTP/2。在Cowboy中，它也用于谈论HTTP/1.1或HTTP/1.0。它不应该与流请求或响应主体相混淆。

所有版本的HTTP都允许客户端发起流。HTTP/2是唯一一个允许服务器的协议，通过其服务器推送功能。客户端和服务器发起的流在Cowboy中都经过相同的过程。

流处理程序

流处理器必须实现五个不同的回调。其中4个是直接相关的;一个是特别的。

所有回调函数都会接收流ID作为第一个参数。

它们中的大多数都可以返回要由Cowboy执行的命令列表。当回调连接起来时，可以拦截和修改这些命令。例如，这对于修改响应很有用。

当一个新的请求进来时，init/3回调函数被调用。它接收这个监听器的Req对象和协议选项。

当接收到来自请求主体的数据时，将调用data/4回调。它同时接收这个数据和一个指示是否需要更多数据的标志。

当接收到这个流的Erlang消息时，会调用info/3回调函数。它们通常是请求流程发送的消息。

最后，使用terminate/3回调函数调用流的终止原因。返回值将被忽略。请注意，与Erlang中的所有terminate回调一样，并不能保证它会被调用。

特殊的回调函数early_error/5在请求报头被完全接收之前发生错误，并且Cowboy正在发送响应时被调用。它接收部分请求对象、错误原因、协议选项和Cowboy将发送的响应。必须返回此响应，可能已修改。

内置的处理程序

Cowboy有四个处理程序。

cowboy_stream_h是默认的流处理程序。它是Cowboy大部分功能的核心。所有的流处理程序链都应该最后调用它。

cowboy_compress_h将在可能时自动压缩响应。默认情况下不启用。这是一个编写自己的处理程序来修改响应的好例子。

cowboy_metrics_h 收集关于流的指标，然后将它们传递给一个可配置的函数。默认情况下不启用。

cowboy_tracer_h可用于根据请求的内容或其来源有条件地跟踪流。跟踪事件被传递给可配置的函数。默认情况下不启用。