Ghi chú phạm vi: single-repo (grpc-go); seeds là xương sống unary Invoke path (Invoke, newClientStream, clientStream, csAttempt, pickerWrapper, http2Client). Edge sang server-side/wire không có trong graph — xem sequence diagram (section 03) cho ranh giới HTTP/2.

Mermaid — nguồn đầy đủ

sequenceDiagram
    autonumber
    participant GC as generated code
    participant IV as ClientConn.Invoke (call.go)
    participant CS as clientStream (stream.go)
    participant PW as pickerWrapper
    participant AT as csAttempt
    participant T as http2Client
    participant W as HTTP/2 wire

    GC->>IV: Invoke(ctx, method, req, reply, opts)
    Note over IV: combine(callOptions) :32<br/>unaryInt chain? :34-36
    IV->>CS: newClientStream (unaryStreamDesc)
    Note over CS: OnCallBegin :227 · metadata validate :233-246<br/>waitForResolvedAddrs :249<br/>configSelector → methodConfig :263-297<br/>timeout ctx :313-318 · codec/compressor :330-364
    CS->>AT: op = getTransport + newStream (withRetry :399-412)
    AT->>PW: pick(ctx, failfast, method) :519
    Note over PW: block trên blockingCh tới khi<br/>picker sẵn sàng :111-140
    PW-->>AT: pick{transport, result}
    AT->>T: NewStream(callHdr) :756
    Note over T: createHeaderFields :542<br/>grpc-timeout từ deadline :613
    IV->>CS: SendMsg(req)
    Note over CS: prepareMsg (marshal+nén) :973<br/>size guard :990 · bufferForRetry :1007
    CS->>AT: sendMsg :1138
    AT->>T: transportStream.Write (Last=true) :1147
    alt write lỗi (unary)
        AT-->>CS: return nil :1148-1153 (lỗi hoãn sang RecvMsg)
    end
    T-)W: loopyWriter ghi frame (goroutine :476-479)
    W-)T: reader nhận frame (goroutine :420)
    IV->>CS: RecvMsg(reply)
    CS->>AT: recvMsg (withRetry + commitAttempt :1035-1037)
    Note over AT: decompressor từ RecvCompress :1169-1187<br/>recv :1189 · recv lần 2 bắt EOF :1227-1232
    AT-->>IV: reply hoặc status error (từ trailer :1191)
    alt lỗi retryable
        CS->>CS: shouldRetry :701-789 (transparent :717 / policy+throttle :757-767<br/>pushback :734-747 · backoff jitter :776-782)
        CS->>AT: newAttemptLocked → replay buffered ops :807-850
    end

sequenceDiagram
    autonumber
    participant GC as generated code
    participant IV as ClientConn.Invoke (call.go)
    participant CS as clientStream (stream.go)
    participant PW as pickerWrapper
    participant AT as csAttempt
    participant T as http2Client
    participant W as HTTP/2 wire

    GC->>IV: Invoke(ctx, method, req, reply, opts)
    Note over IV: combine(callOptions) :32<br/>unaryInt chain? :34-36
    IV->>CS: newClientStream (unaryStreamDesc)
    Note over CS: OnCallBegin :227 · metadata validate :233-246<br/>waitForResolvedAddrs :249<br/>configSelector → methodConfig :263-297<br/>timeout ctx :313-318 · codec/compressor :330-364
    CS->>AT: op = getTransport + newStream (withRetry :399-412)
    AT->>PW: pick(ctx, failfast, method) :519
    Note over PW: block trên blockingCh tới khi<br/>picker sẵn sàng :111-140
    PW-->>AT: pick{transport, result}
    AT->>T: NewStream(callHdr) :756
    Note over T: createHeaderFields :542<br/>grpc-timeout từ deadline :613
    IV->>CS: SendMsg(req)
    Note over CS: prepareMsg (marshal+nén) :973<br/>size guard :990 · bufferForRetry :1007
    CS->>AT: sendMsg :1138
    AT->>T: transportStream.Write (Last=true) :1147
    alt write lỗi (unary)
        AT-->>CS: return nil :1148-1153 (lỗi hoãn sang RecvMsg)
    end
    T-)W: loopyWriter ghi frame (goroutine :476-479)
    W-)T: reader nhận frame (goroutine :420)
    IV->>CS: RecvMsg(reply)
    CS->>AT: recvMsg (withRetry + commitAttempt :1035-1037)
    Note over AT: decompressor từ RecvCompress :1169-1187<br/>recv :1189 · recv lần 2 bắt EOF :1227-1232
    AT-->>IV: reply hoặc status error (từ trailer :1191)
    alt lỗi retryable
        CS->>CS: shouldRetry :701-789 (transparent :717 / policy+throttle :757-767<br/>pushback :734-747 · backoff jitter :776-782)
        CS->>AT: newAttemptLocked → replay buffered ops :807-850
    end

Chặng 1 — Entry & stream setup

Chặng 2 — Attempt: pick transport & mở stream HTTP/2

Chặng 3 — Send / Recv / Retry

Mermaid — nguồn đầy đủ

flowchart LR
    subgraph public_api["call.go — public API"]
        IV["ClientConn.Invoke :29<br/>unaryInt chain :34"] --> INV["invoke :65"]
    end
    subgraph engine["stream.go — stream engine"]
        NCS["newClientStream :213"] --> NCSP["newClientStreamWithParams :302"]
        NCSP --> CSTR["clientStream<br/>withRetry :831 · SendMsg :954 · RecvMsg :1025"]
        CSTR --> ATT["csAttempt :454<br/>getTransport :515 · sendMsg :1138 · recvMsg :1162"]
        CSTR -.retry.-> SR["shouldRetry :701<br/>throttle :764 · pushback :734 · jitter :776"]
    end
    subgraph indirection["registry / config"]
        CFG["configSelector → MethodConfig<br/>stream.go:263-297"]
        ENC["encoding registry<br/>GetCompressor/Codec"]
    end
    subgraph transport["internal/transport"]
        PW["pickerWrapper.pick :105<br/>blockingCh"]
        H2["http2Client.NewStream :756<br/>grpc-timeout :613"]
        WR["transportStream.Write ← write :1106"]
        GOR["goroutine loopyWriter :476 · reader :420"]
    end
    WIRE[("HTTP/2 wire — node lá")]

    INV --> NCS
    NCS --> CFG
    NCSP --> ENC
    ATT --> PW
    ATT --> H2
    ATT --> WR
    WR --> GOR --> WIRE

flowchart LR
    subgraph public_api["call.go — public API"]
        IV["ClientConn.Invoke :29<br/>unaryInt chain :34"] --> INV["invoke :65"]
    end
    subgraph engine["stream.go — stream engine"]
        NCS["newClientStream :213"] --> NCSP["newClientStreamWithParams :302"]
        NCSP --> CSTR["clientStream<br/>withRetry :831 · SendMsg :954 · RecvMsg :1025"]
        CSTR --> ATT["csAttempt :454<br/>getTransport :515 · sendMsg :1138 · recvMsg :1162"]
        CSTR -.retry.-> SR["shouldRetry :701<br/>throttle :764 · pushback :734 · jitter :776"]
    end
    subgraph indirection["registry / config"]
        CFG["configSelector → MethodConfig<br/>stream.go:263-297"]
        ENC["encoding registry<br/>GetCompressor/Codec"]
    end
    subgraph transport["internal/transport"]
        PW["pickerWrapper.pick :105<br/>blockingCh"]
        H2["http2Client.NewStream :756<br/>grpc-timeout :613"]
        WR["transportStream.Write ← write :1106"]
        GOR["goroutine loopyWriter :476 · reader :420"]
    end
    WIRE[("HTTP/2 wire — node lá")]

    INV --> NCS
    NCS --> CFG
    NCSP --> ENC
    ATT --> PW
    ATT --> H2
    ATT --> WR
    WR --> GOR --> WIRE

• Capability: cho phép application code thực hiện một unary RPC đồng bộ với semantics đầy đủ: per-method config từ service config (timeout/retry/size — stream.go:263-297), interceptor chain (call.go:34-36), nén tùy chọn (stream.go:347-364), retry an toàn (chỉ khi stream chưa được server xử lý hoặc code retryable — stream.go:708-719,757-759).
• Semantics chờ: RPC đầu tiên chờ resolver (stream.go:249), pick block khi chưa có subchannel READY trừ khi failfast (picker_wrapper.go:100-104) — nghĩa là "gọi RPC" ngầm bao gồm "chờ hạ tầng sẵn sàng", không fail ngay.
• Chuyển trạng thái attempt: tạo attempt → committed (khi RecvMsg bắt đầu — stream.go:1037) hoặc retry (transparent/policy) → finished; onCommit báo cho config selector (stream.go:281).
• Ngưỡng/config chi phối: service config per-method (MethodConfig), disableRetry DialOption (stream.go:721), retry throttler per-ClientConn (stream.go:386), env/DialOption về compressor và message size mặc định (stream.go:330-331).
• Điểm cần xác nhận với spec: (1) hành vi trả nil của SendMsg unary khi write lỗi có được document ở API contract không (comment nói "generated code requires it" — stream.go:1148-1151); (2) cardinality violation trả codes.Internal — gRFC nào quy định code này thay vì Unimplemented?

• Credentials: per-call creds gắn qua CallOption vào callHdr.Creds (stream.go:365-367); transport-level creds nằm ngoài phạm vi trace này (thuộc Dial path). Không thấy creds bị log trong nhánh đã trace.
• Dữ liệu nhạy cảm: khi binarylog bật, toàn bộ header + message (materialized) được log (stream.go:416-427,1013-1021,1038-1046) — môi trường có PII phải kiểm soát sink của binarylog. Stats handlers cũng nhận nguyên payload (stream.go:1156-1158,1211-1220) — plugin observability tự viết là điểm rò rỉ tiềm năng.
• Retry/timeout: timeout per-method từ service config ép vào ctx (stream.go:313-318) và truyền xuống wire qua header grpc-timeout (internal/transport/http2_client.go:613) — server biết deadline của client. Retry có throttling per-ClientConn + server pushback + jitter 0.8-1.2 (stream.go:764,772-782) — thiết kế chống retry storm sẵn.
• Idempotency: transparent retry chỉ khi stream Unprocessed (server chưa chạy handler — stream.go:712-719) nên an toàn; policy retry theo RetryableStatusCodes do người vận hành khai trong service config — khai code không idempotent (ví dụ retry trên UNKNOWN) là tự chuốc double-execution, thư viện không chặn hộ.

• combine() kèm comment giải thích race — mẫu tốt về "comment nói lý do, không nói cái gì" (call.go:40-53).
• TODO còn treo: check size theo len(data) thay vì payload (stream.go:989); API merge metadata.MD vào outgoing context chưa có (stream.go:546-553).
• Top-level Invoke deprecated vẫn export cho tương thích (call.go:55-61).
• Semantics SendMsg unary (trả nil khi write lỗi) chỉ được giải thích bằng comment nội bộ (stream.go:1148-1151) — đáng được nêu trong doc comment public của SendMsg.
• Cardinality violation checks (stream.go:1195-1197,1225-1232) là hardening tương đối mới — message lỗi rõ ràng, dễ grep.
• newClientStreamWithParams dài (~120 dòng setup) nhưng tuyến tính, mỗi block có comment — đọc được; phần retry (withRetry/shouldRetry/buffer replay) là vùng phức tạp nhất, xứng đáng có diagram riêng nếu trace sâu (v2).

• Server-side leg (server.go processUnaryRPC, nối bằng full method name): ngoài phạm vi trace này (client-side only theo golden flow user chọn).
• Resolver/balancer nội bộ (ccResolverWrapper, balancer_wrapper.go, quá trình sinh picker): chỉ trace đến điểm nối pickerWrapper.pick; đường resolver→balancer→picker update là nhánh riêng.
• Transport flow control (controlBuf, loopyWriter internals, BDP, window update): node lá v1 — đã ghi nhận goroutine :420/:476 nhưng không mở hộp.
• prepareMsg/recv internals (rpc_util.go framing, header 5-byte): dùng như hộp đen qua call site stream.go:973,1189; chưa Read file.
• Dial path (NewClient, resolver build lần đầu, idle manager exit-idle): điểm chạm duy nhất đã trace là waitForResolvedAddrs (stream.go:249 → clientconn.go:759 — chưa Read thân hàm).
• Nhánh streaming RPC (client/server streams, CloseSend :1054-1067): khác semantics unary đáng kể — flow riêng.