gRPC-Go基础（4）metadata和超时设置

0. 简介

Go在多个go routine之间传递数据使用的是Go SDK提供的context包，而context的作用范围在进程内，而gRPC使用的是跨进程的网络传输，那如何实现跨进程的元数据传输呢？

1. metadata

1.1 metadata结构

metadata的简单理解，就是http 的 Header 中的 key-value 对

gRPC使用metadata在服务之间传输全局数据，metadata形式为键值对（k-v）列表，如下：

type MD map[string][]string

• k一般为字符串，v可以是字符串，也可以是二进制数据，当v是二进制数据时，k必须以-bin结尾，二进制数据会被base64编码然后传输；
• 同时，k不能以grpc-开头，因为这是为gRPC所保留；
• k中大写字符会被转化为小写；
• 如上，一个k可以对应多个v。

1.2 metadata创建

New方法

md := metadata.New(map[string]string{"k1":"v1","k2":"v2"})

Pair方法（相同的key自动合并）

md := metadata.Pairs(
   "k1", "v1",
   "k1", "v1.2",
   "k2-bin", string([]byte{1, 2}),
)

k1对应的值会被自动合并为map[string][]string{k1: {v1, v1.2}}。k2-bin对应的值会被进行base64编码。

1.3 客户端处理metadata

1.3.1 发送metadata

NewOutgoingContext

md := metadata.Pairs(
   "k1", "v1",
   "k1", "v1.2",
   "k2-bin", string([]byte{1, 2}),
)
ctx := metadata.NewOutgoingContext(context.Background(), md)

将新创建的 Metadata 添加到 context 中，这样会 覆盖 掉原来已有的 metadata。其实际上就是调用了context.WithValue 方法，生成了一个子context而已，这个子context中包含了传入的metadata。

// NewOutgoingContext creates a new context with outgoing md attached. If used
// in conjunction with AppendToOutgoingContext, NewOutgoingContext will
// overwrite any previously-appended metadata.
func NewOutgoingContext(ctx context.Context, md MD) context.Context {
   return context.WithValue(ctx, mdOutgoingKey{}, rawMD{md: md})
}

AppendToOutgoingContext

ctx = metadata.AppendToOutgoingContext(ctx, "k1", "v1", "k1", "v1.2", "k2-bin", string([]byte{1, 2}))

AppendToOutgoingContext方法将k-v对添加到已有的context中。如果对应的context没有metadata，那么就会创建一个；如果已有metadata了，那么就将数据添加到原来的metadata（推荐使用 AppendToOutgoingContext)。

1.3.2 接收metadata
目前，gRPC的客户端支持接收的metadata包括header和trailer。
一元RPC
header和trailer可以通过Header和Trailer方法，在调用gRPC方法的CallOption时传入，在函数调用结束后取出。

var header, trailer metadata.MD
res, err := grpcClient.SimpleRoute(ctx, &simplepb.SimpleRequest{Data: "I am iguochan"}, grpc.Header(&header), grpc.Trailer(&trailer))

值得注意的是，虽然流式RPC的方法调用中也有CallOption，但是这两个方法**明确仅用于一元RPC。

// Header returns a CallOptions that retrieves the header metadata
// for a unary RPC.
func Header(md *metadata.MD) CallOption {
   return HeaderCallOption{HeaderAddr: md}
}

// Trailer returns a CallOptions that retrieves the trailer metadata
// for a unary RPC.
func Trailer(md *metadata.MD) CallOption {
   return TrailerCallOption{TrailerAddr: md}
}

流式RPC
所有的流式RPC都将使用以下形式接收服务端发送的header和trailer。通过接口ClientStream的Header() (metadata.MD, error)和Trailer() metadata.MD方法取出。

stream, err := grpcClient.RouteList(context.Background())

// 从流中取header
header, err := stream.Header()

// 从流中取出trailer
trailer := stream.Trailer()

1.4 服务端处理metadata

1.4.1 发送metadata
和客户端接收metadata一样，服务端只能发送header和trailer这两类metadata。

一元RPC
有关这些方法的具体用法可以参考go文档。

func (r *Server) SimpleRoute(ctx context.Context, request *simplepb.SimpleRequest) (*simplepb.SimpleResponse, error) {
   // ...
   md := metadata.Pairs(/* ... */)
   err := grpc.SendHeader(ctx, md)
   // ...
   md := metadata.Pairs(/* ... */)
   err = grpc.SetTrailer(ctx, md)
}

流式RPC

func (r *Server) RouteList(server simplepb.Route_RouteListServer) error {
   // ...
   md := metadata.Pairs(/* ... */)
   err := server.SendHeader(md)
   // ...
   md := metadata.Pairs(/* ... */)
   server.SetTrailer(md)
   // ...
}

1.4.2 接收metadata
要读取客户端发送的元数据，服务器需要从 RPC 上下文中检索它。如果是一元调用，则可以使用 RPC 处理程序的上下文。对于流式调用，服务器需要从流中获取上下文。

一元RPC

func (r *Server) SimpleRoute(ctx context.Context, request *simplepb.SimpleRequest) (*simplepb.SimpleResponse, error) {
   md, ok := metadata.FromIncomingContext(ctx)
   if ok {
      // do something with metadata
   }
   // ...
}

流式RPC

func (r *Server) ListValue(request *simplepb.SimpleRequest, server simplepb.Route_ListValueServer) error {
   md, ok := metadata.FromIncomingContext(server.Context())
   if ok {
      // do something with metadata
   }
   // ...
}

1.5 metadata的传输

以上介绍了metadata的用法，本节将介绍一下metadata在gRPC各端之间的传输机制。上面说过，在Go中，metadata就是实际上就是调用了context.WithValue 方法，生成了一个子context，那其实不管是在客户端还是服务端，都属于context的上下文传递。
1.5.1 客户端输出metadata
根据前面的文章，我们知道，用户定义好protobuf后通过protoc生成服务端的interface和客户端的桩代码（stub），在桩代码中，已经包含了客户端的实现：

func (c *routeClient) SimpleRoute(ctx context.Context, in *SimpleRequest, opts ...grpc.CallOption) (*SimpleResponse, error) {
   out := new(SimpleResponse)
   err := c.cc.Invoke(ctx, "/simplepb.Route/SimpleRoute", in, out, opts...)
   if err != nil {
      return nil, err
   }
   return out, nil
}

当发起gRPC请求后，会调用Invoke方法，最终会调用invoke方法：

func invoke(ctx context.Context, method string, req, reply interface{}, cc *ClientConn, opts ...CallOption) error {
    cs, err := newClientStream(ctx, unaryStreamDesc, cc, method, opts...)
    if err != nil {
        return err
    }
    if err := cs.SendMsg(req); err != nil {
        return err
    }
    return cs.RecvMsg(reply)
}

invoke方法会调用newClientStream，newClientStream方法比较长，在里面会生成一个函数newStream，并调用newClientStreamWithParams：

func newClientStream(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, opts ...CallOption) (_ ClientStream, err error) {
    // ...
    var newStream = func(ctx context.Context, done func()) (iresolver.ClientStream, error) {
        return newClientStreamWithParams(ctx, desc, cc, method, mc, onCommit, done, opts...)
    }
    // ...
}

newClientStreamWithParams最红会选择一个transport去传输：

func newClientStreamWithParams(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, mc serviceconfig.MethodConfig, onCommit, doneFunc func(), opts ...CallOption) (_ iresolver.ClientStream, err error) {
    // ...
    // Pick the transport to use and create a new stream on the transport.
    // Assign cs.attempt upon success.
    op := func(a *csAttempt) error {
        if err := a.getTransport(); err != nil {
                return err
        }
        if err := a.newStream(); err != nil {
                return err
        }
        // Because this operation is always called either here (while creating
        // the clientStream) or by the retry code while locked when replaying
        // the operation, it is safe to access cs.attempt directly.
        cs.attempt = a
        return nil
    }
    // ...
}

而gRPC选择的是HTTP2作为传输协议，所以最终a.newStream()会最终调用到HTTP2的NewStream：

// NewStream creates a stream and registers it into the transport as "active"
// streams.  All non-nil errors returned will be *NewStreamError.
func (t *http2Client) NewStream(ctx context.Context, callHdr *CallHdr) (*Stream, error) {
    ctx = peer.NewContext(ctx, t.getPeer())
    headerFields, err := t.createHeaderFields(ctx, callHdr)
    if err != nil {
        return nil, &NewStreamError{Err: err, AllowTransparentRetry: false}
    }
}

createHeaderFields，顾名思义，就是构建HTTP请求时的头（HEADERS Frame），其有关metadata从context到HTTP Header的转换实现如下：

func (t *http2Client) createHeaderFields(ctx context.Context, callHdr *CallHdr) ([]hpack.HeaderField, error) {
    // ...
    if md, added, ok := metadata.FromOutgoingContextRaw(ctx); ok {
        var k string
        for k, vv := range md {
            // HTTP doesn't allow you to set pseudoheaders after non pseudoheaders were set.
            if isReservedHeader(k) {
                continue
            }
            for _, v := range vv {
                headerFields = append(headerFields, hpack.HeaderField{Name: k, Value: encodeMetadataHeader(k, v)})
            }
        }
        for _, vv := range added {
            for i, v := range vv {
                if i%2 == 0 {
                        k = strings.ToLower(v)
                        continue
                }
                // HTTP doesn't allow you to set pseudoheaders after non pseudoheaders were set.
                if isReservedHeader(k) {
                        continue
                }
                headerFields = append(headerFields, hpack.HeaderField{Name: k, Value: encodeMetadataHeader(k, v)})
            }
        }
    }
    // ...
}

可以看到，所谓metadata，其实最终是通过HTTP2协议的头帧带入到网络的，主要存储在Binary-Header和ASCII-Header，感兴趣的同学可以参考gRPC over HTTP2。
1.5.2 服务端接收metadata
服务端通过Serve方法来启动，监听来自客户端的连接：

err = grpcServer.Serve(listener)
if err != nil {
    log.Fatalf("grpcServer.Serve err: %v", err)
}

Serve方法最终会调用到handleRawConn，handleRawConn会通过HTTP2去接收消息。

func (s *Server) handleRawConn(lisAddr string, rawConn net.Conn) {
    // ...
    st := s.newHTTP2Transport(rawConn)
    // ...
    go func() {
        s.serveStreams(st)
        s.removeConn(lisAddr, st)
    }()
}

接下来的调用流程涉及的方法是：serveStreams——>HandleStreams——>operateHeaders，最终在operateHeaders，会将所有的头文件中的传入的Header（除去默认的一些字段等）读入到mdata中，这就是服务端拿到的metadata。

func (t *http2Server) operateHeaders(frame *http2.MetaHeadersFrame, handle func(*Stream), traceCtx func(context.Context, string) context.Context) (fatal bool) {
    // ...
    for _, hf := range frame.Fields {
        switch hf.Name {
        // ...
        default:
            if isReservedHeader(hf.Name) && !isWhitelistedHeader(hf.Name) {
                break
            }
            v, err := decodeMetadataHeader(hf.Name, hf.Value)
            if err != nil {
                headerError = true
                logger.Warningf("Failed to decode metadata header (%q, %q): %v", hf.Name, hf.Value, err)
                break
            }
            mdata[hf.Name] = append(mdata[hf.Name], v)
        }
    }
    // ...
}

2. 超时设置

除了一些元数据的传输，在gRPC中，我们还支持将context中的超时传递到接下来的每个服务中，甚至可以跨语言，而这是怎么做到的呢？首先我们想到是通过metadata传输，实际上并不是的。

2.1 客户端输出超时信息

其实从前面1.5.1 客户端输出metadata的最后一步，createHeaderFields方法中，就有如下处理，超时的数值会被作为key是grpc-timeout的值放在HTTP2的头中（正如备注中所言，其实在网络上的传输时间是没有被计入的，会有一定误差）。

func (t *http2Client) createHeaderFields(ctx context.Context, callHdr *CallHdr) ([]hpack.HeaderField, error) {
    // ...
    if dl, ok := ctx.Deadline(); ok {
        // Send out timeout regardless its value. The server can detect timeout context by itself.
        // TODO(mmukhi): Perhaps this field should be updated when actually writing out to the wire.
        timeout := time.Until(dl)
        headerFields = append(headerFields, hpack.HeaderField{Name: "grpc-timeout", Value: grpcutil.EncodeDuration(timeout)})
    }
    // ...
}

2.2 服务端端接收超时信息

同理，在HTTP2的server端的头处理函数operateHeaders中，也会对grpc-timeout对应的值进行处理，将其值读入到timeout中，并置上timeoutSet标志，用于后续处理。

func (t *http2Server) operateHeaders(frame *http2.MetaHeadersFrame, handle func(*Stream), traceCtx func(context.Context, string) context.Context) (fatal bool) {
    // ...
    var (
        // ...
        timeoutSet bool
        timeout    time.Duration
    )
    // ...
    for _, hf := range frame.Fields {
        switch hf.Name {
        // ...
        case "grpc-timeout":
            timeoutSet = true
            var err error
            if timeout, err = decodeTimeout(hf.Value); err != nil {
                headerError = true
            }
        }
    }
    // ...
    if timeoutSet {
        s.ctx, s.cancel = context.WithTimeout(t.ctx, timeout)
    } else {
        s.ctx, s.cancel = context.WithCancel(t.ctx)
    }
    // ...
}

3. 小结

根据以上分析，我们可以发现，不管是metadata还是超时，都是通过HTTP2的头帧传入到对侧的。