docker / docker/docker-credential-helpers
`StoreExample` in client package uses full URL, which seems to disagree with other implementations
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 1.3k
- Forks
- 195
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 5
Description
The client package includes an example of how to use client.Store:
The ServerURL field is set to a URL including a scheme here, which on the surface seems correct for a field named ServerURL. However, in practice it seems like existing callers like docker login set this field to include just a hostname instead, such as "registry.example.com".
I notice that at least some of the actual credential helper implementations in this repository use registryurl.Parse, which normalizes this difference away a little by turning a bare hostname into a schemeless URL:
...but others, such as the pass helper, just take whatever they are given and use it without any normalization:
...so in order to interop with other implementations I presumably need to exactly match the way they would populate this field.
My main hope in opening this issue is to confirm that I've correctly understood that the code example for Store and the documentation in the main README of this repository are both incorrect and that the actual credential helper protocol (as expected by existing real implementations) is to send just a plain hostname wherever a "server URL" is expected.
Is that correct, or is the situation more subtle than that? 🤔
Given that many implementations just take "ServerURL" verbatim and use it as a key, I assume the caller is also responsible for normalizing the hostname for case-insensitive comparison, such as by using idna.Profile.ToUnicode on one of the four IDNA profiles. Is there any established convention for exactly what normalization is to be used here?
Thanks!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare the Store example in client/client_test.go with the README, registryurl/parse.go, and pass/pass.go. Trace how ServerURL is populated and consumed across the referenced implementations, then document the established URL and hostname normalization convention and identify which example or README statements need correction.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- authentication, security
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100