feat(jsonrpc): add CustomHeader http.Header for multi-value headers

RPCClientOpts.CustomHeaders is a map[string]string applied via
http.Header.Set, which can only carry one value per name. Callers
that need to forward multi-value headers (Cookie, X-Forwarded-For,
or any other RFC 7230 list-form header) currently have to either
drop values or comma-join them — and comma-joining is wrong for
Cookie, whose RFC 6265 separator is "; ", not ", ".

Add a sibling CustomHeader field of type http.Header. Values are
copied verbatim into request.Header so multiple values per name
become multiple header lines on the wire.

Application order in newRequest is: library defaults
(Content-Type, Accept), then CustomHeaders (legacy), then
CustomHeader. CustomHeader therefore takes precedence for any
name present in both, and CustomHeaders behavior is unchanged
for callers that don't set CustomHeader, preserving backward
compatibility.

CustomHeaders is marked Deprecated in its godoc, pointing callers
to CustomHeader for new code.

Author: ananthb

rpc/jsonrpc/jsonrpc.go

@@ -271,15 +271,40 @@ type rpcClient struct {
 	endpoint      string
 	httpClient    HTTPClient
 	customHeaders map[string]string
+	customHeader  http.Header
 }
 
-// RPCClientOpts can be provided to NewClientWithOpts() to change configuration of RPCClient.
+// RPCClientOpts can be provided to NewClientWithOpts() to change configuration
+// of RPCClient.
 //
-// HTTPClient: provide a custom http.Client (e.g. to set a proxy, or tls options)
+// HTTPClient: provide a custom http.Client (e.g. to set a proxy, or tls
+// options).
 //
-// CustomHeaders: provide custom headers, e.g. to set BasicAuth
+// CustomHeader: provide custom request headers as an http.Header. Use this for
+// any new code: it preserves multi-value semantics so headers like Cookie,
+// X-Forwarded-For, or other RFC 7230 list-form headers are sent as separate
+// header lines verbatim instead of being collapsed to a single value.
+//
+// CustomHeaders is the legacy map[string]string equivalent and is kept for
+// backward compatibility. When a name is present in both CustomHeader and
+// CustomHeaders, CustomHeader wins.
 type RPCClientOpts struct {
-	HTTPClient    HTTPClient
+	HTTPClient HTTPClient
+
+	// CustomHeader applies request headers as an http.Header, preserving
+	// multi-value entries (each value becomes its own header line on the
+	// wire). Prefer this over CustomHeaders.
+	CustomHeader http.Header
+
+	// CustomHeaders applies request headers from a name->value map. Each
+	// entry is applied via http.Header.Set, so only a single value per
+	// name survives — multiple inbound values for the same header are
+	// silently dropped and Cookie / X-Forwarded-For style headers cannot
+	// be forwarded faithfully.
+	//
+	// Deprecated: use CustomHeader instead. CustomHeaders is retained for
+	// backward compatibility; new code should use the http.Header field
+	// which supports multi-value headers correctly.
 	CustomHeaders map[string]string
 }
 
@@ -364,6 +389,10 @@ func NewClientWithOpts(endpoint string, opts *RPCClientOpts) RPCClient {
 		}
 	}
 
+	if len(opts.CustomHeader) > 0 {
+		rpcClient.customHeader = opts.CustomHeader.Clone()
+	}
+
 	return rpcClient
 }
 
@@ -485,11 +514,19 @@ func (client *rpcClient) newRequest(ctx context.Context, req any) (*http.Request
 	request.Header.Set("Content-Type", "application/json")
 	request.Header.Set("Accept", "application/json")
 
-	// set default headers first, so that even content type and accept can be overwritten
+	// CustomHeaders (legacy, single-value) is applied first so that even
+	// Content-Type and Accept can be overwritten by callers that need to.
 	for k, v := range client.customHeaders {
 		request.Header.Set(k, v)
 	}
 
+	// CustomHeader (http.Header) is applied last so it takes precedence
+	// over CustomHeaders for any name present in both, and so multi-value
+	// entries land verbatim as separate header lines on the wire.
+	for k, vs := range client.customHeader {
+		request.Header[http.CanonicalHeaderKey(k)] = append([]string(nil), vs...)
+	}
+
 	return request, nil
 }
 

rpc/jsonrpc/jsonrpc_test.go

@@ -57,6 +57,59 @@ func TestSimpleRpcCallHeaderCorrect(t *testing.T) {
 	Expect(req.Header.Get("Accept")).To(Equal("application/json"))
 }
 
+func TestCustomHeader_PreservesMultiValue(t *testing.T) {
+	RegisterTestingT(t)
+
+	hdr := http.Header{}
+	hdr.Add("X-Forwarded-For", "1.1.1.1")
+	hdr.Add("X-Forwarded-For", "2.2.2.2")
+	hdr.Add("Cookie", "a=1")
+	hdr.Add("Cookie", "b=2")
+	hdr.Set("Authorization", "Bearer t")
+
+	rpcClient := NewClientWithOpts(httpServer.URL, &RPCClientOpts{
+		CustomHeader: hdr,
+	})
+	rpcClient.Call(context.Background(), "noop")
+
+	req := (<-requestChan).request
+
+	Expect(req.Header.Values("X-Forwarded-For")).To(Equal([]string{"1.1.1.1", "2.2.2.2"}))
+	Expect(req.Header.Values("Cookie")).To(Equal([]string{"a=1", "b=2"}))
+	Expect(req.Header.Get("Authorization")).To(Equal("Bearer t"))
+}
+
+func TestCustomHeader_TakesPrecedenceOverCustomHeaders(t *testing.T) {
+	RegisterTestingT(t)
+
+	rpcClient := NewClientWithOpts(httpServer.URL, &RPCClientOpts{
+		CustomHeaders: map[string]string{
+			"X-Test": "from-map",
+		},
+		CustomHeader: http.Header{
+			"X-Test": []string{"from-header-a", "from-header-b"},
+		},
+	})
+	rpcClient.Call(context.Background(), "noop")
+
+	req := (<-requestChan).request
+	Expect(req.Header.Values("X-Test")).To(Equal([]string{"from-header-a", "from-header-b"}))
+}
+
+func TestCustomHeaders_StillWorks(t *testing.T) {
+	RegisterTestingT(t)
+
+	rpcClient := NewClientWithOpts(httpServer.URL, &RPCClientOpts{
+		CustomHeaders: map[string]string{
+			"X-Backcompat": "yes",
+		},
+	})
+	rpcClient.Call(context.Background(), "noop")
+
+	req := (<-requestChan).request
+	Expect(req.Header.Get("X-Backcompat")).To(Equal("yes"))
+}
+
 // test if the structure of an rpc request is built correctly by validating the data that arrived on the test server
 func TestRpcClient_Call(t *testing.T) {
 	RegisterTestingT(t)