This is an automated email from the ASF dual-hosted git repository.
Alanxtl pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/dubbo-go.git
The following commit(s) were added to refs/heads/develop by this push:
new 6c49e65a0 docs(triple): document header and trailer usage (#3380)
6c49e65a0 is described below
commit 6c49e65a075cadbe74811d0dafd937fe919a014f
Author: 吴杨帆 <[email protected]>
AuthorDate: Tue Jun 9 10:24:34 2026 +0800
docs(triple): document header and trailer usage (#3380)
Co-authored-by: wuyangfan <[email protected]>
---
protocol/triple/triple_protocol/header.go | 102 ++++++++++++++++++++++++------
1 file changed, 84 insertions(+), 18 deletions(-)
diff --git a/protocol/triple/triple_protocol/header.go
b/protocol/triple/triple_protocol/header.go
index b23a5c279..adc9f7ecb 100644
--- a/protocol/triple/triple_protocol/header.go
+++ b/protocol/triple/triple_protocol/header.go
@@ -111,10 +111,19 @@ func newIncomingContext(ctx context.Context, data
http.Header) context.Context {
return context.WithValue(ctx, extraDataKey{}, extraData)
}
-// NewOutgoingContext sets headers entirely. If there are existing headers,
they would be replaced.
-// It is used for passing headers to server-side.
-// It is like grpc.NewOutgoingContext.
-// Please refer to
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#sending-metadata.
+// NewOutgoingContext sets outgoing request headers on ctx. If ctx already has
+// outgoing headers, they are replaced.
+//
+// For example:
+//
+// ctx := NewOutgoingContext(context.Background(), http.Header{
+// "hello": []string{"triple"},
+// })
+// resp, err := client.Greet(ctx, &greet.GreetRequest{})
+//
+// Use AppendToOutgoingContext to add more values without replacing existing
+// outgoing headers. These APIs follow the same pattern as grpc metadata:
+//
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#sending-metadata.
func NewOutgoingContext(ctx context.Context, data http.Header) context.Context
{
var header = http.Header{}
@@ -144,10 +153,20 @@ func cloneExtraData(data map[string]http.Header)
map[string]http.Header {
return cloned
}
-// AppendToOutgoingContext merges kv pairs from user and existing headers.
-// It is used for passing headers to server-side.
-// It is like grpc.AppendToOutgoingContext.
-// Please refer to
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#sending-metadata.
+// AppendToOutgoingContext appends key-value pairs to outgoing request headers.
+// It panics when kv contains an odd number of strings.
+//
+// For example:
+//
+// ctx := NewOutgoingContext(context.Background(), http.Header{
+// "hello": []string{"triple"},
+// })
+// ctx = AppendToOutgoingContext(ctx, "hello", "dubbo", "hey", "hessian")
+// resp, err := client.Greet(ctx, &greet.GreetRequest{})
+//
+// The example sends "hello: triple", "hello: dubbo", and "hey: hessian" to the
+// server. This API follows the same pattern as grpc metadata:
+//
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#sending-metadata.
func AppendToOutgoingContext(ctx context.Context, kv ...string)
context.Context {
if len(kv)%2 == 1 {
panic(fmt.Sprintf("AppendToOutgoingContext got an odd number of
input pairs for header: %d", len(kv)))
@@ -181,9 +200,21 @@ func ExtractFromOutgoingContext(ctx context.Context)
http.Header {
}
}
-// FromIncomingContext retrieves headers passed by client-side. It is like
grpc.FromIncomingContext.
-// it must call after append/setOutgoingContext to return current value
-// Please refer to
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#receiving-metadata-1.
+// FromIncomingContext retrieves request headers received by a server handler.
+//
+// For example:
+//
+// func (srv *Server) Greet(ctx context.Context, req *greet.GreetRequest)
(*greet.GreetResponse, error) {
+// headers, ok := FromIncomingContext(ctx)
+// if ok {
+// values := headers.Values("hello")
+// // Use values.
+// }
+// return &greet.GreetResponse{}, nil
+// }
+//
+// This API follows the same pattern as grpc metadata:
+//
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#receiving-metadata-1.
func FromIncomingContext(ctx context.Context) (http.Header, bool) {
data, ok := ctx.Value(extraDataKey{}).(map[string]http.Header)
if !ok {
@@ -195,9 +226,20 @@ func FromIncomingContext(ctx context.Context)
(http.Header, bool) {
}
}
-// SetHeader is used for setting response header in server-side. It is like
grpc.SendHeader(ctx, header) but
-// not send header.
-// Please refer to
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#unary-call-2.
+// SetHeader appends response headers from a server handler. The headers are
+// buffered and sent with the response instead of being sent immediately.
+//
+// For example:
+//
+// func (srv *Server) Greet(ctx context.Context, req *greet.GreetRequest)
(*greet.GreetResponse, error) {
+// if err := SetHeader(ctx, http.Header{"hi":
[]string{"triple"}}); err != nil {
+// return nil, err
+// }
+// return &greet.GreetResponse{}, nil
+// }
+//
+// This API follows the same pattern as grpc metadata:
+//
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#unary-call-2.
func SetHeader(ctx context.Context, header http.Header) error {
conn, ok := ctx.Value(handlerOutgoingKey{}).(StreamingHandlerConn)
if !ok {
@@ -208,8 +250,19 @@ func SetHeader(ctx context.Context, header http.Header)
error {
return nil
}
-// SetTrailer is used for setting response trailers in server-side. It is like
grpc.SetTrailer(ctx, header).
-// Please refer to
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#unary-call-2.
+// SetTrailer appends response trailers from a server handler.
+//
+// For example:
+//
+// func (srv *Server) Greet(ctx context.Context, req *greet.GreetRequest)
(*greet.GreetResponse, error) {
+// if err := SetTrailer(ctx, http.Header{"end": []string{"end"}});
err != nil {
+// return nil, err
+// }
+// return &greet.GreetResponse{}, nil
+// }
+//
+// This API follows the same pattern as grpc metadata:
+//
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#unary-call-2.
func SetTrailer(ctx context.Context, trailer http.Header) error {
conn, ok := ctx.Value(handlerOutgoingKey{}).(StreamingHandlerConn)
if !ok {
@@ -220,8 +273,21 @@ func SetTrailer(ctx context.Context, trailer http.Header)
error {
return nil
}
-// SendHeader is used for setting response headers in server-side and send
them directly. It is like grpc.SendHeader(ctx, header).
-// Please refer to
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#unary-call-2.
+// SendHeader appends response headers from a server handler and sends them
+// immediately. This is useful for streaming handlers that need to flush
headers
+// before the first message.
+//
+// For example:
+//
+// func (srv *Server) GreetStream(ctx context.Context, stream
greet.GreetService_GreetStreamServer) error {
+// if err := SendHeader(ctx, http.Header{"hi":
[]string{"triple"}}); err != nil {
+// return err
+// }
+// return stream.Send(&greet.GreetResponse{})
+// }
+//
+// This API follows the same pattern as grpc metadata:
+//
https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md#unary-call-2.
func SendHeader(ctx context.Context, header http.Header) error {
conn, ok := ctx.Value(handlerOutgoingKey{}).(StreamingHandlerConn)
if !ok {
