AGENTS.md

1# HTTP Server Filter
2 
3This directory contains a server-side filter for processing HTTP/2 headers.
4 
5See also: [gRPC HTTP Filters overview](../AGENTS.md)
6 
7## Overarching Purpose
8 
9The HTTP server filter is a critical component of the gRPC server-side channel stack. It is responsible for processing incoming HTTP/2 headers to ensure that they are valid for a gRPC request, as defined by the [gRPC-over-HTTP/2 specification](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md).
10 
11## Files
12 
13*   `http_server_filter.h`, `http_server_filter.cc`: These files define the `HttpServerFilter` class, a server-side filter that validates incoming HTTP/2 headers and manipulates metadata.
14 
15## Header Validation
16 
17The filter performs the following validation checks on the incoming headers:
18 
19*   It ensures that the `:scheme` header is `http` or `https`.
20*   It ensures that the `:method` header is `POST`. It can be configured to allow `PUT` requests for testing purposes, but this is not recommended for production use.
21*   It ensures that the `content-type` header is `application/grpc` or a variation thereof.
22*   It ensures that the `te` header is `trailers`.
23 
24If any of these checks fail, the filter will send an error to the client.
25 
26## Header Manipulation
27 
28The filter also performs the following header manipulations:
29 
30*   It can be configured to surface the `user-agent` header to the application.
31 
32## Major Classes
33 
34*   `grpc_core::HttpServerFilter`: The channel filter implementation.
35 
36## Notes
37 
38*   This filter is an essential part of the gRPC server-side channel stack. It ensures that incoming requests are compliant with the gRPC-over-HTTP/2 specification.
39*   The `GRPC_ARG_DO_NOT_USE_UNLESS_YOU_HAVE_PERMISSION_FROM_GRPC_TEAM_ALLOW_BROKEN_PUT_REQUESTS` channel argument can be used to allow `PUT` requests. This is intended for testing purposes only, and should not be used in production. `PUT` requests are not compliant with the gRPC specification, and can cause problems with some gRPC features, such as retries.
40*   The filter also has an option to surface the `user-agent` header to the application, which can be useful for analytics or other purposes. This is controlled by the `GRPC_ARG_SURFACE_USER_AGENT` channel argument.
41