AGENTS.md

1# "Chaotic Good" Transport
2 
3This directory contains the implementation of a new, experimental gRPC transport called "Chaotic Good".
4 
5See also: [gRPC Transports overview](../transport/AGENTS.md)
6 
7## Overarching Purpose
8 
9The "Chaotic Good" transport is a new transport implementation for gRPC that is designed to be more performant and flexible than the existing CHTTP2 transport. It is based on a custom framing format and is heavily reliant on the gRPC Core Promise API.
10 
11See also: [gRPC Transports directory](../)
12## Core Concepts
13 
14The "Chaotic Good" transport is built around a few key concepts:
15 
16*   **Custom Framing Format**: The transport uses a custom framing format that is defined in the `chaotic_good_frame.proto` file. The framing format is designed to be simple and efficient, and it supports all of the features of gRPC, including headers, messages, and trailers.
17*   **Promise-Based Architecture**: The transport is heavily based on the [gRPC Core Promise API](../../lib/promise/AGENTS.md). This allows the transport to be implemented in a more asynchronous and non-blocking way, which can lead to better performance and scalability.
18*   **Separation of Control and Data Planes**: The transport separates the control plane (e.g., sending and receiving headers) from the data plane (e.g., sending and receiving messages). This allows the transport to be more flexible and to support a variety of different use cases.
19 
20## Files
21 
22*   **`chaotic_good.h`, `chaotic_good.cc`**: These files contain the main entry points for the Chaotic Good transport.
23*   **`client_transport.h`, `client_transport.cc`**: These files contain the implementation of the client-side transport.
24*   **`server_transport.h`, `server_transport.cc`**: These files contain the implementation of the server-side transport.
25*   **`frame.h`, `frame.cc`**: These files define the C++ classes that represent the different types of frames in the custom framing format.
26*   **`frame_header.h`, `frame_header.cc`**: These files define the header for each frame in the custom framing format.
27*   **`chaotic_good_frame.proto`**: This file contains the protobuf definition of the framing format.
28*   **`frame_transport.h`**: Defines the interface for a transport that can send and receive frames.
29*   **`control_endpoint.h`, `control_endpoint.cc`**: Implements the control plane for the transport.
30*   **`data_endpoints.h`, `data_endpoints.cc`**: Implements the data plane for the transport.
31*   **`scheduler.h`, `scheduler.cc`**: A simple scheduler for running promises.
32 
33## Major Classes
34 
35*   `grpc_core::chaotic_good::ChaoticGoodClientTransport`: The client-side transport implementation.
36*   `grpc_core::chaotic_good::ChaoticGoodServerTransport`: The server-side transport implementation.
37*   `grpc_core::chaotic_good::FrameInterface`: The base class for all frame types.
38*   `grpc_core::chaotic_good::FrameTransport`: The interface for a transport that can send and receive frames.
39 
40## Notes
41 
42*   This transport is still under development and is not yet recommended for production use.
43*   The name "Chaotic Good" is a reference to the Dungeons & Dragons alignment system. It originally reflected that Chaotic Good was a transport with an alignment story, as it guaranteed alignment for received messages.
44*   The transport is a good example of how the gRPC Core Promise API can be used to build high-performance, asynchronous network applications.
45*   The separation of the control and data planes is a key design feature of the transport. It allows the transport to be more flexible and to support a variety of different use cases. For example, the control plane could be implemented over a reliable transport like TCP, while the data plane could be implemented over a less reliable transport like UDP.
46