From 666ee08931041b7fed56bed7132649785b2d3dfe Mon Sep 17 00:00:00 2001
From: Noah Dietz <noahdietz@users.noreply.github.com>
Date: Tue, 6 Feb 2024 09:57:03 -0800
Subject: [PATCH] fix: add XGoogFieldMaskHeader constant (#321)

---
 v2/callctx/callctx.go              |  8 ++++++++
 v2/callctx/callctx_example_test.go | 22 ++++++++++++++++++++++
 v2/header.go                       | 11 ++++++++---
 3 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/v2/callctx/callctx.go b/v2/callctx/callctx.go
index af15fb58..9aab3d91 100644
--- a/v2/callctx/callctx.go
+++ b/v2/callctx/callctx.go
@@ -38,6 +38,14 @@ import (
 )
 
 const (
+	// XGoogFieldMaskHeader is the canonical header key for the [System Parameter]
+	// that specifies the response read mask. The value(s) for this header
+	// must adhere to format described in [fieldmaskpb].
+	//
+	// [System Parameter]: https://cloud.google.com/apis/docs/system-parameters
+	// [fieldmaskpb]: https://google.golang.org/protobuf/types/known/fieldmaskpb
+	XGoogFieldMaskHeader = "x-goog-fieldmask"
+
 	headerKey = contextKey("header")
 )
 
diff --git a/v2/callctx/callctx_example_test.go b/v2/callctx/callctx_example_test.go
index c46c6f42..e34bc097 100644
--- a/v2/callctx/callctx_example_test.go
+++ b/v2/callctx/callctx_example_test.go
@@ -34,6 +34,8 @@ import (
 	"fmt"
 
 	"github.com/googleapis/gax-go/v2/callctx"
+	"google.golang.org/genproto/googleapis/api/metric"
+	"google.golang.org/protobuf/types/known/fieldmaskpb"
 )
 
 func ExampleSetHeaders() {
@@ -47,3 +49,23 @@ func ExampleSetHeaders() {
 	fmt.Println(headers["key"][0])
 	// Output: value
 }
+
+func ExampleXGoogFieldMaskHeader() {
+	ctx := context.Background()
+	ctx = callctx.SetHeaders(ctx, callctx.XGoogFieldMaskHeader, "field_one,field.two")
+
+	// Send the returned context to the request you are making.
+}
+
+func ExampleXGoogFieldMaskHeader_fieldmaskpb() {
+	// Build a mask using the expected response protobuf message.
+	mask, err := fieldmaskpb.New(&metric.MetricDescriptor{}, "display_name", "metadata.launch_stage")
+	if err != nil {
+		// handle error
+	}
+
+	ctx := context.Background()
+	ctx = callctx.SetHeaders(ctx, callctx.XGoogFieldMaskHeader, mask.String())
+
+	// Send the returned context to the request you are making.
+}
diff --git a/v2/header.go b/v2/header.go
index 453fab7e..3e53729e 100644
--- a/v2/header.go
+++ b/v2/header.go
@@ -103,7 +103,9 @@ func goVersion() string {
 	return "UNKNOWN"
 }
 
-// XGoogHeader is for use by the Google Cloud Libraries only.
+// XGoogHeader is for use by the Google Cloud Libraries only. See package
+// [github.com/googleapis/gax-go/v2/callctx] for help setting/retrieving
+// request/response headers.
 //
 // XGoogHeader formats key-value pairs.
 // The resulting string is suitable for x-goog-api-client header.
@@ -125,7 +127,8 @@ func XGoogHeader(keyval ...string) string {
 }
 
 // InsertMetadataIntoOutgoingContext is for use by the Google Cloud Libraries
-// only.
+// only. See package [github.com/googleapis/gax-go/v2/callctx] for help
+// setting/retrieving request/response headers.
 //
 // InsertMetadataIntoOutgoingContext returns a new context that merges the
 // provided keyvals metadata pairs with any existing metadata/headers in the
@@ -137,7 +140,9 @@ func InsertMetadataIntoOutgoingContext(ctx context.Context, keyvals ...string) c
 	return metadata.NewOutgoingContext(ctx, insertMetadata(ctx, keyvals...))
 }
 
-// BuildHeaders is for use by the Google Cloud Libraries only.
+// BuildHeaders is for use by the Google Cloud Libraries only. See package
+// [github.com/googleapis/gax-go/v2/callctx] for help setting/retrieving
+// request/response headers.
 //
 // BuildHeaders returns a new http.Header that merges the provided
 // keyvals header pairs with any existing metadata/headers in the provided