AGENTS.md

1# Common Transport Utilities (lib/transport)
2 
3*   This directory contains common implementation details, abstractions, and utilities shared across various gRPC transport implementations (such as CHTTP2, PH2, Inproc, and Chaotic Good).
4 
5See also: [gRPC Transports overview](../../transport/AGENTS.md)
6 
7## Overarching Purpose
8 
9Files in this directory provide essential abstractions and reusable components that transport implementations depend on. Rather than each transport reinventing basic networking, state tracking, or encoding primitives, they utilize the APIs exposed here.
10 
11**Core Responsibilities:**
12*   **Transport Abstraction Interfaces:** The core struct definitions for `grpc_transport` and `grpc_stream`.
13*   **Promise-Based Networking:** Providing the `PromiseEndpoint` API to wrap traditional EventEngine endpoints with modern C++ Coroutine/Promise interfaces.
14*   **Bandwidth Estimation:** Tracking bytes sent/received over time to dynamically compute Bandwidth-Delay Product (BDP) for flow control.
15*   **State & Error Tracking:** Tracking connectivity states and converting error namespaces/types (e.g., HTTP/2 status/errors to `absl::Status` or gRPC status codes).
16*   **Header Encoding & Parsing:** Encoding and decoding gRPC timeout headers securely and efficiently.
17 
18## Key Files and Components
19 
20*   **`transport.{h,cc}`**
21    *   Defines the underlying `grpc_transport` and `grpc_stream` structs.
22    *   Contains core serialization, statistic structures, and operational batching definitions (`grpc_transport_stream_op_batch`).
23*   **`promise_endpoint.{h,cc}`**
24    *   The `PromiseEndpoint` class provides a convenient API to run asynchronous read/write network streams using the gRPC Promise framework (`src/core/lib/promise`).
25*   **`bdp_estimator.{h,cc}`**
26    *   The `BdpEstimator` tracks traffic flow to adapt HTTP/2 window sizes (flow control) based on connection bandwidth and latency.
27*   **`connectivity_state.{h,cc}`**
28    *   Tracks `grpc_connectivity_state` transitions for channels/transports. Provides state change notifications.
29*   **`timeout_encoding.{h,cc}`**
30    *   Provides standard routines to encode and decode the `grpc-timeout` HTTP/2 header.
31*   **`status_conversion.{h,cc}`**
32    *   Utility functions converting between HTTP status codes, HTTP/2 errors (`grpc_chttp2_error_code`), and gRPC canonical status codes (`grpc_status_code`).
33*   **`error_utils.{h,cc}`**
34    *   Utilities for converting transit errors, raw `grpc_error_handle` objects, or `absl::Status` into status codes and error messages.
35*   **`call_final_info.{h,cc}`**
36    *   Struct definitions tracking transport-level metrics and statistics compiled when a call terminates.
37 
38## Dependencies and Guidelines
39 
40*   **Modern promise-based code:** New additions or modifications to `PromiseEndpoint` should strictly follow the conventions of the gRPC Promise framework located in `src/core/lib/promise/`.
41*   **Compatibility:** Changes in this directory affect all transport types. Extra caution should be taken to avoid breaking behavior across CHTTP2, PH2, and chaotic_good transports. Ensure their respective unit and end-to-end tests run after making any modifications here.
42