2. Proxy-Status HTTP 字段

Proxy-Status HTTP 响应字段允许中介传达关于其处理某个响应及其关联请求的附加信息.

该字段的值是一个 List (参见 [STRUCTURED-FIELDS] 第 3.1 节). List 中的每个成员表示一个处理过该响应的中介. 第一个成员表示最接近源服务器的中介, 最后一个成员表示最接近用户代理的中介.

例如:

Proxy-Status: revproxy1.example.net, ExampleCDN

这表示该响应首先由 revproxy1.example.net (靠近源服务器的反向代理) 处理, 然后由 ExampleCDN 处理.

中介自行判断何时适合向响应添加 Proxy-Status 字段. 有些中介可能决定把它附加到所有响应, 另一些则可能只在显式配置时, 或在请求包含激活调试模式的头部字段时才添加.

List 的每个成员标识插入该值的中介, 并且其类型必须是 String 或 Token. 根据部署方式不同, 它可能是服务名称 (但不是软件或硬件产品名称; 例如 "ExampleCDN" 合适, 但 "ExampleProxy" 不合适, 因为它不能标识部署), 主机名 ("proxy-3.example.com"), IP 地址, 或生成的字符串.

每个成员的参数 (按照 [STRUCTURED-FIELDS] 第 3.1.2 节) 传达该中介处理响应及其关联请求时的附加信息; 参见第 2.1 节. 虽然这些参数都是可选的 (OPTIONAL), 但鼓励中介提供尽可能多的信息, 不过这样做时需要注意第 4 节中的安全考量.

向 Proxy-Status 字段添加值时, 中介应当保留字段中已有的成员, 以便调试处理请求的整个中介链, 除非它被显式配置为移除这些成员, 例如防止内部网络细节泄露, 参见第 4 节.

源服务器禁止生成 Proxy-Status 字段.

Proxy-Status 可以作为 HTTP trailer 字段发送. 例如, 如果中介正在流式传输响应, 而入站连接突然终止, 由于头部区段已经发送, Proxy-Status 只能附加到出站消息的 trailer 区段. 然而, 因为它可能在通往用户代理的路径上被静默丢弃 (所有 trailer 字段都是如此; 参见 [HTTP] 第 6.5 节), 除非无法在头部区段发送, 否则不应将 Proxy-Status 作为 trailer 字段发送.

为了允许接收方重建 trailer 字段中传达的 Proxy-Status 成员与头部字段中成员之间的相对顺序, 中介禁止将 Proxy-Status 作为 trailer 字段发送, 除非它也在同一消息中生成了带有相同成员 (但参数可能不同) 的 Proxy-Status 头部字段.

例如, 一个标识为 'ThisProxy' 的代理收到带有如下头部字段的响应:

Proxy-Status: SomeOtherProxy

它会把自己的条目添加到头部字段:

Proxy-Status: SomeOtherProxy, ThisProxy

因此它可以附加一个 trailer 字段:

Proxy-Status: ThisProxy; error=read_timeout

这样下游接收方即可理解, 'SomeOtherProxy' 的处理发生在 'ThisProxy' 之前.

客户端可以为了调试或其它目的, 将 Proxy-Status trailer 字段值提升到头部区段中, 例如使其更容易访问.

2.1. Proxy-Status 参数

Proxy-Status List 的每个成员都可以带有描述代理如何处理响应的参数. 本节详细说明这些参数.

2.1.1. error

"error" 参数的值类型为 Token, 表示一个代理错误类型 (Proxy Error Type, 第 2.3 节); 它的存在表示中介在为请求获取响应时遇到了问题.

2.1.2. next-hop

"next-hop" 参数的值类型为 String 或 Byte Sequence; 它的存在表示中介用于转发请求的下一跳. 这可以是 IP 地址和端口号, 主机名, 或其它形式的标识符.

2.1.3. next-protocol

"next-protocol" 参数的值类型为 Token 或 Byte Sequence; 它的存在表示中介连接到下一跳时使用的 ALPN 协议标识符 [RFC7301].

2.1.4. received-status

"received-status" 参数的值类型为 Integer; 它的存在表示中介从下一跳服务器收到的 HTTP 状态码. 参数值必须在 100 到 999 (含) 的范围内.

该参数仅在不存在 error 参数时适用. 它用于中介基于从下一跳收到的响应生成自己的响应, 但并未生成错误的情况.

2.1.5. details

"details" 参数的值类型为 String; 它允许代理传达特定于该响应且没有更适合参数承载的附加信息. 这可能包括特定于实现或特定于部署的信息.

2.2. 定义新的 Proxy-Status 参数

可以通过在 "HTTP Proxy-Status Parameters" 注册表中注册来定义新的 Proxy-Status 参数.

注册请求按照 [RFC8126] 第 4.5 节由专家审查 (Expert Review) 评审和批准. 推荐提供规范文档, 但并非必需.

专家在评估请求时应考虑以下因素:

社区反馈.
该值是否定义得足够明确.
通用参数优先于特定于厂商, 应用或部署的值. 如果社区无法就通用值达成一致, 参数名称应相应地更具体, 例如带有标识厂商, 应用或部署的前缀.
参数名称是否与其它 Proxy-Status 参数, 新的或既有的错误类型冲突, 造成混淆, 或未来可能如此.

注册请求应使用以下模板:

Name: [Proxy-Status 参数名称, 类型为 Token]

Description: [参数语义说明]

Reference: [定义该参数的规范; 可选]

Notes: [可选]

有关发送注册请求的位置, 参见注册表 https://www.iana.org/assignments/http-proxy-status.