grpc-go Code Map: From ClientConn to http2Client, and from Serve to Handler

Status: Draft (2026-10-17), Code Reading. Baseline version: grpc/grpc-go v1.83.2 (commit 030ee8becb20, read from local Go module cache). Since the latest release is v1.84.0, line numbers may differ slightly. The 파일:줄 in the text refers to the function declaration line in v1.83.2. There are no new measurements in this part, only comparisons with the numbers from Part 6.

Table of Contents

• 1. One-line Summary: Company Org Chart
• 2. Architecture Diagram
• 3. Code Map
• 4. Following the Core Path
  • 4.1 Creating a Channel: Not connecting anything yet
  • 4.2 When an Address Arrives: Resolver → Balancer → Subchannel → Picker
  • 4.3 A Single Call: From Invoke to Stream
  • 4.4 Picker: Wait or Fail Fast
  • 4.5 Server: From Serve to Handler
• 5. Comparison with Part 6 Measurements
• 6. Where to Start Reading
• 7. Good Places for Your First Contribution
• 8. Limitations
• References

1. One-line Summary: Company Organizational Chart

The channel is a team leader. When a task (call) is received, instead of doing it directly, the address book manager (resolver) hands over the given list to the assignment manager (balancer), and the assignment manager picks employees (subchannels) in advance and selects one using the daily assignment sheet (picker) whenever a task arrives. Each employee has their own telephone line (HTTP/2 connection). Since the assignment sheet is replaced entirely as a single paper, it does not contend for locks with anyone at the moment of picking a task.

2. Architecture Diagram

3. Code Map

4. Following the Core Path

4.1 Creating a Channel: Nothing is Connected Yet

NewClient applies options, parses the target string, selects the resolver builder, and (initParsedTargetAndResolverBuilder, default scheme dns), prepares the idle state, and finishes. Preparing the idle state (initIdleStateLocked) creates a resolver wrapper (newCCResolverWrapper) and a balancer wrapper (newCCBalancerWrapper), but the resolver does not run yet. When the first call arrives, exitIdleMode changes the channel to CONNECTING and starts the resolver. If there are no calls for 30 minutes, enterIdleMode tears down the connections with the resolver and balancer and returns to idle.

4.2 When addresses arrive: Resolver → Balancer → Subchannel → Picker

1. When the resolver finds addresses, it calls ccResolverWrapper.UpdateState , and the channel's updateResolverStateAndUnlock applies the service config and passes it to (applyServiceConfigAndBalancer) the balancer (updateClientConnState).
2. The balancer (e.g., round_robin) calls NewSubConn for each address, which creates newAddrConnLocked with addrConn . This addrConn is the actual entity of the subchannel.
3. addrConn connects in the order of resetTransportAndUnlock → tryAllAddrs → createTransport , and if it fails, retries after a backoff. If it fails or gets disconnected, it requests ResolveNow from the resolver (Part 5, Section 4.1).
4. Whenever the subchannel state changes, the balancer creates a new picker, sends it to ccBalancerWrapper.UpdateState , and pickerWrapper.updatePicker updates the picker and swaps it atomically. Calls that were waiting are awakened as the channel attached to the previous picker closes.

Why was it divided like this? By keeping address resolution (DNS, xDS, Kubernetes APIs, etc.) and selection (round-robin, weighted, hash, etc.) completely decoupled, any resolver can be combined with any balancer. Balancer updates are processed sequentially by a serializer (see the comment ingrpcsync.CallbackSerializer, balancer_wrapper.go ), and the hot path where calls pass through (pick) only reads a single atomic value, ensuring that the two worlds never wait for each other's locks.

4.3 Single Call: From Invoke to Stream

1. The generated stub calls ClientConn.Invoke , passes through the interceptor, and invoke goes to newClientStream → newClientStreamWithParams . Even unary calls are internally implemented as a "stream of sending one message and receiving one."
2. Creating a single attempt (newAttemptLocked), getTransport selects a subchannel from the picker. For the transport of the chosen subchannel, it sends HEADERS via csAttempt.newStream → http2Client.NewStream (Part 3's createHeaderFields).
3. SendMsg serializes, compresses, adds a 5-byte prefix, writes to csAttempt.sendMsg , and reads the response through RecvMsg → recv → parser.recvMsg ). If it fails, withRetry looks at Part 4's shouldRetry to create a new attempt and replays the buffered sent messages.

4.4 Picker: To Wait or Fail Fast

What happens if a call arrives but there are no READY subchannels? A branch in pickerWrapper.pick provides the answer.

pickResult, err := p.Pick(info)
if err != nil {
	if err == balancer.ErrNoSubConnAvailable {
		continue
	}
	if st, ok := status.FromError(err); ok {
		...
		return pick{}, dropError{error: err}
	}
	// For all other errors, wait for ready RPCs should block and other
	// RPCs should fail with unavailable.
	if !failfast {
		lastPickErr = err
		continue
	}
	return pick{}, status.Error(codes.Unavailable, err.Error())
}

Source: grpc/grpc-go v1.83.2 picker_wrapper.go Excerpt from lines 157-176, Apache-2.0

• If still connecting (ErrNoSubConnAvailable), wait until a new picker arrives is waited for. This is why calls do not fail on a connecting channel.
• If all subchannels are TRANSIENT_FAILURE, the picker returns an error, and the default (fail fast) is immediately UNAVAILABLE . grpc.WaitForReady(true) Only calls with wait for the deadline (wait-for-ready.md as defined in).
• If it returns a status error (drop), it does not even retry. This is the path used when the control plane says "discard this call."

In production, this difference looks like this: for a few seconds while restarting the server, fail fast clients spew UNAVAILABLE (like logs 10-13 of Collector in Part 6), and wait-for-ready clients quietly wait and succeed if the server comes back within the deadline.

4.5 Server: From Serve to Handler

1. Server.Serve When Accept does handleRawConn , it spawns
2. as a goroutine. After the credential handshake, NewServerTransport exchanges HTTP/2 settings, and serveStreams reads frames. The default maximum concurrent streams is unlimited (math.MaxUint32, server.go:189).
3. When HEADERS arrive, operateHeaders reads :path, content-type, grpc-timeout to create a stream (invalid content-type is 415), and handleStream splits the path into service name and method name to look up in the table registered as RegisterService ( ServiceDescfrom Part 1). If not found, UNIMPLEMENTED.
4. If unary, processUnaryRPC, if stream, processStreamingRPC reads messages, calls interceptors and handlers, and then writes trailers with writeStatus .
5. GracefulStop sends GOAWAY to block new streams and waits for ongoing ones to finish. MaxConnectionAge in Part 5 uses the same GOAWAY.

5. Comparison with Part 6 Measurements

Even with the same grpc-go, how many channels are created and how they are usedis determined by the client code, and that choice dictates the connection count, memory usage, and load balancing.

6. Where to Read First

1. Documentation/ of keepalive.md·concurrency.md·anti-patterns.md is read first. anti-patterns.md explains why the old Dial·WithBlock should be avoided.
2. call.go → stream.go of newClientStreamWithParams·csAttempt is used to follow a single call.
3. picker_wrapper.go → balancer_wrapper.go → balancer/roundrobin is used for the selection side, and resolver_wrapper.go → internal/resolver/dns for the lookup side.
4. internal/transport/http2_client.go of NewStream·reader·keepalive, controlbuf.go leads down to the write loop.
5. For the server, reading only server.go of handleStream → processUnaryRPC reveals the dispatch structure.

7. Good First Contribution Areas

• grpc-go recommends "Status: Help Wanted" issues with no assignee for first-time contributors (11 open as of 2026-10-17, CONTRIBUTING). Changing behavior or APIs requires prior agreement via an issue, and features involving multiple languages must start with a gRFC.
• Generative AI Policyis in place. All repository communication (issues, PR bodies, and comments) must be written directly by humans (with translation and phrasing assistance as exceptions), automated agents must not post directly to GitHub, and AI-generated code must be fully understood and taken responsibility for by the submitter (CONTRIBUTING under master).
• Three TODOs found while reading: stream.go:634 hedging, clientconn.go line 1364 "Move re-interpretation request into pick_first" (#7534), and createHeaderFields benchmark for pre-counting header counts. All three require design discussions and are too large for a first PR, but serve as great entry points for reading the issues.
• Documentation candidates are gathered in Part 8, Section 7.

8. Limitations

• xDS(xds/·internal/xds/) and advanced balancers like ringhash, weightedroundrobin, and RLS were not read.
• controlbuf.go write scheduling and memory pools(mem/), and stats handlers (OpenTelemetry integration) were not covered.
• Line numbers are based on v1.83.2. Differences with v1.84.0 were not verified (unverified).

Titi's note. Since the assignment table (picker) is swapped out entirely, there is no need to fight with the assignment manager for a spot even when customers rush in. Instead, if all employees fall ill, whether to wait (WaitForReady) or turn them away (fail fast) is decided by the customer!

References

All materials were accessed on 2026-10-17.

• grpc/grpc-go v1.83.2: clientconn.go, call.go, stream.go, picker_wrapper.go, balancer_wrapper.go, resolver_wrapper.go, server.go, internal/transport/http2_client.go, internal/transport/http2_server.go, rpc_util.go, Documentation/, CONTRIBUTING.md(master)
• grpc/grpc v1.84.0: doc/wait-for-ready.md, doc/load-balancing.md
• Cited code: grpc-go v1.83.2, Apache License 2.0.