ociclient: best place to inject User-Agent?

[tianon]

I noticed today that nothing in my cuelabs.dev/go/oci/ociregistry/ociclient-using stack is setting User-Agent, so I'm hitting registries with Go-http-client/1.1, which is less than ideal.

To be clear, I'm not opposed to ociclient growing explicit User-Agent behavior of some kind, but I can totally understand why y'all might not want to do that! 😄

So the middle ground I'm proposing is an explicit reference somewhere in the godoc for ociclient for how to inject User-Agent correctly (and I'd even go so far as to make it a strong recommendation, at least for anyone connecting to registries they don't personally run).

I think the way to handle this given the existing API is a Transport/RoundTripper shim that injects it into every request, but I'm very open to being wrong. 🙇 ❤️

[tianon]

https://github.com/cue-lang/cue/blob/c29fd02c46f0c438148d1051489bf42122f59f19/internal/cueversion/transport.go#L8-L34 is validating to find 😄 ❤️

[mvdan]

We agree that most clients should be setting a user-agent string, just like we do. That's indeed why we expose a transport in the ociclient API.

We briefly discussed ways to provide a more user friendly API for the common case of setting a user agent string, such as exposing our userAgentTransport implementation in the ociclient API, but we couldn't agree on whether that's the right thing to do. It's a generic HTTP transport middleware, not anything specific to an OCI client or library, so it doesn't feel like an API that we ourselves should expose.

However, we can all agree that it's not obvious how to do this for a new user reading the docs. Do you want to send a patch to add an example or piece of documentation, for example showing what the CUE code does?

[tianon]

Yeah, totally fair! Honestly it seems like something net/http should have direct support for, since pretty much every use case ought to be setting a meaningful User-Agent of some kind, not relying on the default provided by net/http, but it's a non-trivial bit of code (albeit straightforward) to do so 😭

In a docs update, would you prefer that be copying minimal bits of the CUE implementation into the docs, or should it be linked to instead? (the former feels kind of funny because if we're copying the code into the docs, maybe we should copy it into a package instead so we can say "use X to set User-Agent" instead 😅)

[tianon]

I've been doing a lot with Cache-Control headers recently and realized that this issue is perhaps broader than just User-Agent -- there's not really a clean way (that I'm aware of) for a server or a client to specify extra request or response headers like Cache-Control short of replacing the round-tripper, which isn't super reasonable if the header needs to vary based on the request data (for example, a very long max-age for pull-by-digest but a short max-age or even no-cache for pull-by-tag). 🤔

This is slightly related to #2 too, but not exactly since that's really a different thing which just happens to also need an extra Location header, although it's possible a generic means of specifying additional headers could work for that use case as well.

[tianon]

As I (finally 😂😭😇) implement User-Agent in my code, I notice one bit of added complexity there is the way the wrappers compose for things like ociauth/authentication means that the order of composing the wrappers really matters to make sure that all requests to auth servers also get User-Agent set, and makes what I've posited above slightly more complicated because headers like Cache-Control are probably intended for the registry server, not the auth server. 🤔