AGENTS.md

1# gRPC Core Call
2 
3This directory is the heart of the gRPC C++ core, defining the fundamental data
4structures and mechanisms for representing and managing a single RPC.
5 
6See also: [gRPC Core overview](../AGENTS.md)
7 
8## Overarching Purpose
9 
10The code in this directory provides the client and server-side representations
11of a call, the central "spine" that connects them, and the various components
12needed to manage the lifecycle of an RPC, including metadata, messages, and
13status.
14 
15## Core Concepts
16 
17*   **`CallSpine`**: The `CallSpine` is the central component of a gRPC call. It
18    encapsulates the call's context, including the arena allocator, call
19    filters, and the pipes for message and metadata communication. The
20    `CallSpine` is shared between a `CallInitiator` (the client-side) and a
21    `CallHandler` (the server-side).
22*   **`CallInitiator`**: The `CallInitiator` is the client-side view of a call.
23    It is used for initiating requests and receiving responses.
24*   **`CallHandler`**: The `CallHandler` is the server-side view of a call. It
25    is used for handling incoming requests and sending responses.
26*   **`ClientCall`**: The `ClientCall` is the public client-side API for a call.
27    It wraps the `CallInitiator` and `CallSpine`.
28*   **`ServerCall`**: The `ServerCall` is the public server-side API for a call.
29    It wraps the `CallHandler` and `CallSpine`.
30 
31## Differentiating Call V1 and Call V3 Code
32 
33*   **Implementation Class**: The classes used to represent the call interface.
34    *   Call Interface (Common for V1 and V3) : [call.h](../lib/surface/call.h)
35    *   Call V1: `FilterStackCall`
36        ([filter_stack_call.h](../lib/surface/filter_stack_call.h))
37    *   Call V3:
38        *   `ClientCall`
39            ([client_call.h](client_call.h))
40        *   and `ServerCall`
41            ([server_call.h](server_call.h))
42*   **Concurrency Model**: Concurrency and thread safety mechanism.
43    *   Call V1: [Combiner](../lib/iomgr/combiner.h) and
44        [WorkSerializer](src/core/util/work_serializer.h)
45    *   Call V3: gRPC Promise library with [`Party`](../lib/promise/party.h)
46*   **Companion Transports**: Transport layers compatible with each stack.
47    *   Call V1: CHTTP2 transport, Legacy InProc
48    *   Call V3: PH2, Chaotic Good, InProc transports
49    *   For details about the transports see
50        [chttp2/AGENTS.md](../ext/transport/chttp2/AGENTS.md) and
51        [chaotic_good/AGENTS.md](../ext/transport/chaotic_good/AGENTS.md)
52*   **Creation Method**: The entry point used to instantiate new calls.
53    *   Call V1: `grpc_call_create`
54    *   Call V3: `MakeClientCall` and `MakeServerCall`
55*   **Exclusive Files**: C++ source files exclusive to each stack model.
56    *   Call V1:
57        *   `src/core/lib/surface/filter_stack_call.{h,cc}`
58        *   `src/core/lib/surface/legacy_channel.{h,cc}`
59        *   `src/core/lib/channel/channel_stack.{h,cc}`
60        *   `src/core/lib/channel/channel_stack_builder.{h,cc}`
61        *   `src/core/ext/filters/channel_idle/legacy_channel_idle_filter.cc`
62    *   Call V3:
63        *   `src/core/call/client_call.{h,cc}`
64        *   `src/core/call/server_call.{h,cc}`
65        *   `src/core/call/call_spine.{h,cc}`
66        *   `src/core/call/call_filters.{h,cc}`
67        *   `src/core/client_channel/direct_channel.{h,cc}`
68*   **Shared Files**: Source files used by both Call V1 and Call V3.
69    *   `src/core/lib/surface/call.{h,cc}`
70    *   `src/core/lib/surface/call_utils.{h,cc}`
71    *   `src/core/call/metadata.{h,cc}`
72    *   `src/core/call/metadata_batch.{h,cc}`
73 
74## Call V3 Stack
75 
76![Call V3 Stack](CallV3.png)
77<!--
78Can add a text based version of this diagram if needed. It will be more
79accessible to the AIs
80-->
81 
82*   **`src/core/call/call_spine.{h,cc}`**: The `CallSpine` is the key
83    abstraction to understand in this directory. It's the "glue" that holds a
84    call together.
85*   The use of `CallInitiator` and `CallHandler` provides a clean separation of
86    concerns between the client and server sides of a call.
87*   In a CallSpine we always have a `CallInitiator` and `CallHandler` pair.
88*   `CallInitiator` is always near/towards the client side.
89*   `CallHandler` is always near/towards the server side.
90*   When CallInitiator sends metadata, it flows into the spine. The spine
91    executes filter hooks before reaching CallHandler.
92*   Similarly, response metadata and messages from CallHandler pass through
93    filters and reach the CallInitiator.
94 
95## Files
96 
97*   **`src/core/call/client_call.{h,cc}`**: These files define the `ClientCall`
98    class.
99*   **`src/core/call/server_call.{h,cc}`**: These files define the `ServerCall`
100    class.
101*   **`src/core/call/metadata.{h,cc}`**,
102    **`src/core/call/metadata_batch.{h,cc}`**: These files provide the data
103    structures for representing and manipulating RPC metadata.
104*   **`src/core/call/message.{h,cc}`**: Defines the `Message` class, which is a
105    container for RPC messages.
106*   **`src/core/call/call_filters.{h,cc}`**: These files define the
107    `CallFilters` class, which is responsible for managing the filters for a
108    call.
109*   **`src/core/call/interception_chain.{h,cc}`**: These files define the
110    `InterceptionChain` class, which is used to manage the execution of a set of
111    interceptors.
112 
113## Notes
114 
115*   This directory is heavily based on the
116    [gRPC Core Promise API](../lib/promise/AGENTS.md). Familiarity with that API
117    is essential for understanding the code here.
118*   The `CallFilters` class is responsible for managing the filters for a call.
119    See the [channel documentation](../lib/channel/AGENTS.md) for more
120    information about filters.
121