Review comments #2.

credentials/tls/certprovider/distributor.go

@@ -29,7 +29,7 @@ import (
 // materials by handling synchronization between the producer and consumers of
 // the key material.
 //
-// Provider implementations must embed this type into themselves and:
+// Provider implementations may choose to embed this type into themselves and:
 // - Whenever they have new key material, they should invoke the Set() method.
 // - When users of the provider call KeyMaterial(), it will be handled by the
 //   distributor which will return the most up-to-date key material furnished
@@ -56,6 +56,9 @@ func NewDistributor() *Distributor {
 }
 
 // Set updates the key material in the distributor with km.
+//
+// Provider implementations which use the distributor must not modify the
+// contents of the KeyMaterial struct pointed to by km.
 func (d *Distributor) Set(km *KeyMaterial) {
 	d.mu.Lock()
 	d.km = km

credentials/tls/certprovider/provider.go

@@ -86,6 +86,7 @@ type StableConfig interface {
 // instantiations as they deem fit.
 type Provider interface {
 	// KeyMaterial returns the key material sourced by the provider.
+	// Callers are expected to use the returned value as read-only.
 	//
 	// Implementations must honor the deadline specified in ctx.
 	KeyMaterial(ctx context.Context, opts KeyMaterialOptions) (*KeyMaterial, error)

credentials/tls/certprovider/store.go

@@ -33,17 +33,17 @@ func init() {
 	}
 }
 
-// Key contains data which uniquely identifies a provider instance.
-type Key struct {
+// StoreKey contains data which uniquely identifies a provider instance.
+type StoreKey struct {
 	// Name is the registered name of the provider.
 	Name string
 	// Config is the configuration used by the provider instance.
 	Config StableConfig
 }
 
 // storeKey acts the key to the map of providers maintained by the store. Go
-// maps need to be indexed by comparable types, so the above Key struct cannot
-// be used since it contains an interface.
+// maps need to be indexed by comparable types, so the above StoreKey struct
+// cannot be used since it contains an interface.
 type storeKey struct {
 	// name of the certificate provider.
 	name string
@@ -77,7 +77,7 @@ func GetStore() *Store {
 // exists for key, its reference count is incremented before returning. If no
 // provider exists for key, a new is created using the registered builder. If
 // no registered builder is found, a nil provider is returned.
-func (ps *Store) GetProvider(key Key) Provider {
+func (ps *Store) GetProvider(key StoreKey) Provider {
 	ps.mu.Lock()
 	defer ps.mu.Unlock()
 

credentials/tls/certprovider/store_test.go

@@ -148,7 +148,7 @@ func makeProvider(t *testing.T, name, config string) (Provider, *fakeProvider) {
 
 	// Pass the config to the store to fetch a provider.
 	store := GetStore()
-	key := Key{Name: name, Config: cfg}
+	key := StoreKey{Name: name, Config: cfg}
 	prov := store.GetProvider(key)
 	if prov == nil {
 		t.Fatalf("store.Get(%v) is nil", key)