vendor/google.golang.org/api/option/option.go

   1 // Copyright 2017 Google LLC
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //      http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 // Package option contains options for Google API clients.
  16 package option
  17
  18 import (
  19         "net/http"
  20
  21         "golang.org/x/oauth2"
  22         "google.golang.org/api/internal"
  23         "google.golang.org/grpc"
  24 )
  25
  26 // A ClientOption is an option for a Google API client.
  27 type ClientOption interface {
  28         Apply(*internal.DialSettings)
  29 }
  30
  31 // WithTokenSource returns a ClientOption that specifies an OAuth2 token
  32 // source to be used as the basis for authentication.
  33 func WithTokenSource(s oauth2.TokenSource) ClientOption {
  34         return withTokenSource{s}
  35 }
  36
  37 type withTokenSource struct{ ts oauth2.TokenSource }
  38
  39 func (w withTokenSource) Apply(o *internal.DialSettings) {
  40         o.TokenSource = w.ts
  41 }
  42
  43 type withCredFile string
  44
  45 func (w withCredFile) Apply(o *internal.DialSettings) {
  46         o.CredentialsFile = string(w)
  47 }
  48
  49 // WithCredentialsFile returns a ClientOption that authenticates
  50 // API calls with the given service account or refresh token JSON
  51 // credentials file.
  52 func WithCredentialsFile(filename string) ClientOption {
  53         return withCredFile(filename)
  54 }
  55
  56 // WithServiceAccountFile returns a ClientOption that uses a Google service
  57 // account credentials file to authenticate.
  58 //
  59 // Deprecated: Use WithCredentialsFile instead.
  60 func WithServiceAccountFile(filename string) ClientOption {
  61         return WithCredentialsFile(filename)
  62 }
  63
  64 // WithCredentialsJSON returns a ClientOption that authenticates
  65 // API calls with the given service account or refresh token JSON
  66 // credentials.
  67 func WithCredentialsJSON(p []byte) ClientOption {
  68         return withCredentialsJSON(p)
  69 }
  70
  71 type withCredentialsJSON []byte
  72
  73 func (w withCredentialsJSON) Apply(o *internal.DialSettings) {
  74         o.CredentialsJSON = make([]byte, len(w))
  75         copy(o.CredentialsJSON, w)
  76 }
  77
  78 // WithEndpoint returns a ClientOption that overrides the default endpoint
  79 // to be used for a service.
  80 func WithEndpoint(url string) ClientOption {
  81         return withEndpoint(url)
  82 }
  83
  84 type withEndpoint string
  85
  86 func (w withEndpoint) Apply(o *internal.DialSettings) {
  87         o.Endpoint = string(w)
  88 }
  89
  90 // WithScopes returns a ClientOption that overrides the default OAuth2 scopes
  91 // to be used for a service.
  92 func WithScopes(scope ...string) ClientOption {
  93         return withScopes(scope)
  94 }
  95
  96 type withScopes []string
  97
  98 func (w withScopes) Apply(o *internal.DialSettings) {
  99         o.Scopes = make([]string, len(w))
 100         copy(o.Scopes, w)
 101 }
 102
 103 // WithUserAgent returns a ClientOption that sets the User-Agent.
 104 func WithUserAgent(ua string) ClientOption {
 105         return withUA(ua)
 106 }
 107
 108 type withUA string
 109
 110 func (w withUA) Apply(o *internal.DialSettings) { o.UserAgent = string(w) }
 111
 112 // WithHTTPClient returns a ClientOption that specifies the HTTP client to use
 113 // as the basis of communications. This option may only be used with services
 114 // that support HTTP as their communication transport. When used, the
 115 // WithHTTPClient option takes precedent over all other supplied options.
 116 func WithHTTPClient(client *http.Client) ClientOption {
 117         return withHTTPClient{client}
 118 }
 119
 120 type withHTTPClient struct{ client *http.Client }
 121
 122 func (w withHTTPClient) Apply(o *internal.DialSettings) {
 123         o.HTTPClient = w.client
 124 }
 125
 126 // WithGRPCConn returns a ClientOption that specifies the gRPC client
 127 // connection to use as the basis of communications. This option many only be
 128 // used with services that support gRPC as their communication transport. When
 129 // used, the WithGRPCConn option takes precedent over all other supplied
 130 // options.
 131 func WithGRPCConn(conn *grpc.ClientConn) ClientOption {
 132         return withGRPCConn{conn}
 133 }
 134
 135 type withGRPCConn struct{ conn *grpc.ClientConn }
 136
 137 func (w withGRPCConn) Apply(o *internal.DialSettings) {
 138         o.GRPCConn = w.conn
 139 }
 140
 141 // WithGRPCDialOption returns a ClientOption that appends a new grpc.DialOption
 142 // to an underlying gRPC dial. It does not work with WithGRPCConn.
 143 func WithGRPCDialOption(opt grpc.DialOption) ClientOption {
 144         return withGRPCDialOption{opt}
 145 }
 146
 147 type withGRPCDialOption struct{ opt grpc.DialOption }
 148
 149 func (w withGRPCDialOption) Apply(o *internal.DialSettings) {
 150         o.GRPCDialOpts = append(o.GRPCDialOpts, w.opt)
 151 }
 152
 153 // WithGRPCConnectionPool returns a ClientOption that creates a pool of gRPC
 154 // connections that requests will be balanced between.
 155 // This is an EXPERIMENTAL API and may be changed or removed in the future.
 156 func WithGRPCConnectionPool(size int) ClientOption {
 157         return withGRPCConnectionPool(size)
 158 }
 159
 160 type withGRPCConnectionPool int
 161
 162 func (w withGRPCConnectionPool) Apply(o *internal.DialSettings) {
 163         balancer := grpc.RoundRobin(internal.NewPoolResolver(int(w), o))
 164         o.GRPCDialOpts = append(o.GRPCDialOpts, grpc.WithBalancer(balancer))
 165 }
 166
 167 // WithAPIKey returns a ClientOption that specifies an API key to be used
 168 // as the basis for authentication.
 169 //
 170 // API Keys can only be used for JSON-over-HTTP APIs, including those under
 171 // the import path google.golang.org/api/....
 172 func WithAPIKey(apiKey string) ClientOption {
 173         return withAPIKey(apiKey)
 174 }
 175
 176 type withAPIKey string
 177
 178 func (w withAPIKey) Apply(o *internal.DialSettings) { o.APIKey = string(w) }
 179
 180 // WithoutAuthentication returns a ClientOption that specifies that no
 181 // authentication should be used. It is suitable only for testing and for
 182 // accessing public resources, like public Google Cloud Storage buckets.
 183 // It is an error to provide both WithoutAuthentication and any of WithAPIKey,
 184 // WithTokenSource, WithCredentialsFile or WithServiceAccountFile.
 185 func WithoutAuthentication() ClientOption {
 186         return withoutAuthentication{}
 187 }
 188
 189 type withoutAuthentication struct{}
 190
 191 func (w withoutAuthentication) Apply(o *internal.DialSettings) { o.NoAuth = true }