net/http: document that SetCookie can quote the value

[gazerro]

The SetCookie function quotes the value if it contains spaces or commas but this behavior is not documented in SetCookie documentation:

SetCookie adds a Set-Cookie header to the provided ResponseWriter's headers. The provided cookie must have a valid Name. Invalid cookies may be silently dropped.

[odeke-em]

Thank you for the report @gazerro! Kindly cc-ing @vdobler for Cookies.

[gopherbot]

Change https://golang.org/cl/221677 mentions this issue: net/http: document that SetCookie can quote the value

[vdobler]

The quotes are allowed by RFC 6265. We could quote every value on Mondays and be compliant to the spec. The fact that the cookie value might be quoted is implicit in "a Set-Cookie header". The whole idea of providing dedicated cookie handling functions in net/http is to free the user from parsing Cookie and Set-Cookie headers himself. The value might be quoted or not but net/http, all relevant browsers and all cookie handling libraries in other languages transparently handle quoted and unquoted values. I do not see why the user needs to be informed about this particular detail of the generated Set-Cookie header. Other details are also not mentioned as they are regulated by the relevant spec (e.g. time zone of the expires field).

I do not think that this behaviour should be documented: Once documented it cannot be changed anymore.
The quoting was introduced to provide compatibility with other languages and common browsers to allow formally (according to RFC 6265) invalid cookie-values to be used because they are common in the wild.

The documentation states

Invalid cookies may be silently dropped.

but does not specify what exactly is considered "invalid", simply because this is a moving target: If every browser properly handles some character X and most other HTTP libraries allow X then net/http has tried to also allow X.

What values are considered valid/invalid and which one need quoting has changed several times. These changes have allowed users to use Go with existing browsers and existing legacy systems. If we fix what is quoted we loos the ability to accommodate for future changes.

I don't think this should be documented:

• documenting it specifies it and makes it unchangable
• the more interesting fact which values are invalid is undocumented for exactly this reason
• the fact that quotes might or might not be used is part of the relevant RFC 6265 already

[gazerro]

Now that the proposal #46370, to add a Cookie.Valid method, has been accepted, I think this issue is not that important anymore, so I close it.