From 304d28ba9e71ed200d9e9051fe3b1f8ef696bd19 Mon Sep 17 00:00:00 2001
From: Patrick Jones <ithuriel@google.com>
Date: Tue, 22 Jun 2021 09:25:17 -0700
Subject: [PATCH] downscope: further updates and nits

---
 google/downscope/downscoping.go      | 25 +++++++++++++++----------
 google/downscope/downscoping_test.go |  6 +-----
 google/downscope/example_test.go     | 10 +++++++---
 3 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/google/downscope/downscoping.go b/google/downscope/downscoping.go
index 87ea3ef..1995428 100644
--- a/google/downscope/downscoping.go
+++ b/google/downscope/downscoping.go
@@ -56,7 +56,7 @@ type AccessBoundaryRule struct {
 	// An Condition restricts the availability of permissions
 	// to specific Cloud Storage objects. Optional.
 	//
-	// Use this field if you want to make permissions available for specific objects,
+	// A Condition can be used  to make permissions available for specific objects,
 	// rather than all objects in a Cloud Storage bucket.
 	Condition *AvailabilityCondition `json:"availabilityCondition,omitempty"`
 }
@@ -82,13 +82,18 @@ type DownscopingConfig struct {
 	Rules []AccessBoundaryRule
 }
 
-// A DownscopingTokenSource is used to retrieve a downscoped token with restricted
+// A downscopingTokenSource is used to retrieve a downscoped token with restricted
 // permissions compared to the root Token that is used to generate it.
-type DownscopingTokenSource struct {
-	// Ctx is the context used to query the API to retrieve a downscoped Token.
-	Ctx context.Context
-	// Config holds the information necessary to generate a downscoped Token.
-	Config DownscopingConfig
+type downscopingTokenSource struct {
+	// ctx is the context used to query the API to retrieve a downscoped Token.
+	ctx context.Context
+	// config holds the information necessary to generate a downscoped Token.
+	config DownscopingConfig
+}
+
+// NewTokenSource returns an empty downscopingTokenSource.
+func NewTokenSource(ctx context.Context, conf DownscopingConfig) downscopingTokenSource {
+	return downscopingTokenSource{ctx: ctx, config: conf}
 }
 
 // downscopedTokenWithEndpoint is a helper function used for unit testing
@@ -176,11 +181,11 @@ func downscopedTokenWithEndpoint(ctx context.Context, config DownscopingConfig,
 	return newToken, nil
 }
 
-// Token() uses a DownscopingTokenSource to generate an oauth2 Token.
+// Token() uses a downscopingTokenSource to generate an oauth2 Token.
 // Do note that the returned TokenSource is an oauth2.StaticTokenSource. If you wish
 // to refresh this token automatically, then initialize a locally defined
 // TokenSource struct with the Token held by the StaticTokenSource and wrap
 // that TokenSource in an oauth2.ReuseTokenSource.
-func (dts DownscopingTokenSource) Token() (*oauth2.Token, error) {
-	return downscopedTokenWithEndpoint(dts.Ctx, dts.Config, identityBindingEndpoint)
+func (dts downscopingTokenSource) Token() (*oauth2.Token, error) {
+	return downscopedTokenWithEndpoint(dts.ctx, dts.config, identityBindingEndpoint)
 }
diff --git a/google/downscope/downscoping_test.go b/google/downscope/downscoping_test.go
index fe59ce3..e79edc8 100644
--- a/google/downscope/downscoping_test.go
+++ b/google/downscope/downscoping_test.go
@@ -46,12 +46,8 @@ func Test_DownscopedTokenSource(t *testing.T) {
 	}
 	myTok := oauth2.Token{AccessToken: "Mellon"}
 	tmpSrc := oauth2.StaticTokenSource(&myTok)
-	out, err := downscopedTokenWithEndpoint(context.Background(), DownscopingConfig{tmpSrc, new}, ts.URL)
+	_, err := downscopedTokenWithEndpoint(context.Background(), DownscopingConfig{tmpSrc, new}, ts.URL)
 	if err != nil {
 		t.Fatalf("NewDownscopedTokenSource failed with error: %v", err)
 	}
-	_, err = out.Token()
-	if err != nil {
-		t.Fatalf("Token() call failed with error %v", err)
-	}
 }
diff --git a/google/downscope/example_test.go b/google/downscope/example_test.go
index 35d3d83..cffd4ff 100644
--- a/google/downscope/example_test.go
+++ b/google/downscope/example_test.go
@@ -1,3 +1,7 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package downscope_test
 
 import (
@@ -9,9 +13,9 @@ import (
 
 func ExampleNewTokenSource() {
 	ctx := context.Background()
-	// Initializes an accessBoundary with one Rule
+	// Initializes an accessBoundary with one Rule.
 	accessBoundary := []downscope.AccessBoundaryRule{
-		downscope.AccessBoundaryRule{
+		{
 			AvailableResource:    "//storage.googleapis.com/projects/_/buckets/foo",
 			AvailablePermissions: []string{"inRole:roles/storage.objectViewer"},
 		},
@@ -23,7 +27,7 @@ func ExampleNewTokenSource() {
 
 	// rootSource, err := google.DefaultTokenSource(ctx, "https://www.googleapis.com/auth/cloud-platform")
 
-	dts := downscope.DownscopingTokenSource{ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary}}
+	dts := downscope.NewTokenSource(ctx, downscope.DownscopingConfig{RootSource: rootSource, Rules: accessBoundary})
 	_ = dts
 	// You can now use the token held in myTokenSource to make
 	// Google Cloud Storage calls, as follows: