net/http: document that Header.Set canonicalizes the header key

[githubsands]

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

1.10.3

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

darwin, amd64

What did you do?

https://play.golang.org/p/l-3GJBY-vWA

What did you expect to see?

Expected key to be the same string HeyHey when adding it to the http header rather then Heyhey.

What did you see instead?

Saw that after adding or setting a string to a header it does not keep the n+1 capital letter causing a check for the same key to fail.

Go normalizes header names (see net/http#CanonicalHeaderKey). Why does this matter though? HTTP header names are case-insensitive.

[katiehockman]

/cc @bradfitz

[bradfitz]

We can document this more but we can't (and shouldn't) change it.

Also it shouldn't matter, as @bontibon pointed out. (In HTTP/2 headers can't even have case.)

If you really need to talk to a broken HTTP/1 server that distinguish cases, you can set the map value directly without using the accessor methods.

[githubsands]

Ah I see "-" between capital letters is a common http header convention.

[bradfitz]

The hyphens are required for many HTTP/HTTP-using RFCs, but the case is not required. It's just a convention.

[gopherbot]

Change https://golang.org/cl/138677 mentions this issue: net/http: document Header.Set canonicalizes the header key