chore: migrate to gitea

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

@@ -0,0 +1,537 @@
+// Copyright 2017 Google LLC.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package option contains options for Google API clients.
+package option
+
+import (
+	"crypto/tls"
+	"log/slog"
+	"net/http"
+
+	"cloud.google.com/go/auth"
+	"golang.org/x/oauth2"
+	"golang.org/x/oauth2/google"
+	"google.golang.org/api/internal"
+	"google.golang.org/api/internal/credentialstype"
+	"google.golang.org/api/internal/impersonate"
+	"google.golang.org/grpc"
+)
+
+// CredentialsType specifies the type of JSON credentials being provided
+// to a loading function such as [WithAuthCredentialsFile] or
+// [WithAuthCredentialsJSON].
+type CredentialsType = credentialstype.CredType
+
+const (
+	// ServiceAccount represents a service account file type.
+	ServiceAccount = credentialstype.ServiceAccount
+	// AuthorizedUser represents an authorized user credentials file type.
+	AuthorizedUser = credentialstype.AuthorizedUser
+	// ImpersonatedServiceAccount represents an impersonated service account file type.
+	//
+	// IMPORTANT:
+	// This credential type does not validate the credential configuration. A security
+	// risk occurs when a credential configuration configured with malicious urls
+	// is used.
+	// You should validate credential configurations provided by untrusted sources.
+	// See [Security requirements when using credential configurations from an external
+	// source] https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
+	// for more details.
+	ImpersonatedServiceAccount = credentialstype.ImpersonatedServiceAccount
+	// ExternalAccount represents an external account file type.
+	//
+	// IMPORTANT:
+	// This credential type does not validate the credential configuration. A security
+	// risk occurs when a credential configuration configured with malicious urls
+	// is used.
+	// You should validate credential configurations provided by untrusted sources.
+	// See [Security requirements when using credential configurations from an external
+	// source] https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
+	// for more details.
+	ExternalAccount = credentialstype.ExternalAccount
+)
+
+// A ClientOption is an option for a Google API client.
+type ClientOption interface {
+	Apply(*internal.DialSettings)
+}
+
+// WithTokenSource returns a ClientOption that specifies an OAuth2 token
+// source to be used as the basis for authentication.
+func WithTokenSource(s oauth2.TokenSource) ClientOption {
+	return withTokenSource{s}
+}
+
+type withTokenSource struct{ ts oauth2.TokenSource }
+
+func (w withTokenSource) Apply(o *internal.DialSettings) {
+	o.TokenSource = w.ts
+}
+
+type withCredFile string
+
+func (w withCredFile) Apply(o *internal.DialSettings) {
+	o.CredentialsFile = string(w)
+}
+
+// WithCredentialsFile returns a ClientOption that authenticates
+// API calls with the given service account or refresh token JSON
+// credentials file.
+//
+// Deprecated: This function is being deprecated because of a potential security risk.
+//
+// This function does not validate the credential configuration. The security
+// risk occurs when a credential configuration is accepted from a source that
+// is not under your control and used without validation on your side.
+//
+// If you know that you will be loading credential configurations of a
+// specific type, it is recommended to use a credential-type-specific
+// option function.
+// This will ensure that an unexpected credential type with potential for
+// malicious intent is not loaded unintentionally. You might still have to do
+// validation for certain credential types. Please follow the recommendation
+// for that function. For example, if you want to load only service accounts,
+// you can use [WithAuthCredentialsFile] with [ServiceAccount]:
+//
+//	option.WithAuthCredentialsFile(option.ServiceAccount, "/path/to/file.json")
+//
+// If you are loading your credential configuration from an untrusted source and have
+// not mitigated the risks (e.g. by validating the configuration yourself), make
+// these changes as soon as possible to prevent security risks to your environment.
+//
+// Regardless of the function used, it is always your responsibility to validate
+// configurations received from external sources.
+func WithCredentialsFile(filename string) ClientOption {
+	return withCredFile(filename)
+}
+
+// WithAuthCredentialsFile returns a ClientOption that authenticates API calls
+// with the given JSON credentials file and credential type.
+//
+// Important: If you accept a credential configuration (credential
+// JSON/File/Stream) from an external source for authentication to Google
+// Cloud Platform, you must validate it before providing it to any Google
+// API or library. Providing an unvalidated credential configuration to
+// Google APIs can compromise the security of your systems and data. For
+// more information, refer to [Validate credential configurations from
+// external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+func WithAuthCredentialsFile(credType CredentialsType, filename string) ClientOption {
+	return withAuthCredentialsFile{
+		credsType: credType,
+		filename:  filename,
+	}
+}
+
+type withAuthCredentialsFile struct {
+	credsType CredentialsType
+	filename  string
+}
+
+func (w withAuthCredentialsFile) Apply(o *internal.DialSettings) {
+	o.AuthCredentialsFile = w.filename
+	o.AuthCredentialsType = w.credsType
+}
+
+// WithServiceAccountFile returns a ClientOption that uses a Google service
+// account credentials file to authenticate.
+//
+// Important: If you accept a credential configuration (credential
+// JSON/File/Stream) from an external source for authentication to Google
+// Cloud Platform, you must validate it before providing it to any Google
+// API or library. Providing an unvalidated credential configuration to
+// Google APIs can compromise the security of your systems and data. For
+// more information, refer to [Validate credential configurations from
+// external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+//
+// Deprecated: Use WithAuthCredentialsFile instead.
+func WithServiceAccountFile(filename string) ClientOption {
+	return WithAuthCredentialsFile(ServiceAccount, filename)
+}
+
+// WithCredentialsJSON returns a ClientOption that authenticates
+// API calls with the given service account or refresh token JSON
+// credentials.
+//
+// Deprecated: This function is being deprecated because of a potential security risk.
+//
+// This function does not validate the credential configuration. The security
+// risk occurs when a credential configuration is accepted from a source that
+// is not under your control and used without validation on your side.
+//
+// If you know that you will be loading credential configurations of a
+// specific type, it is recommended to use a credential-type-specific
+// option function.
+// This will ensure that an unexpected credential type with potential for
+// malicious intent is not loaded unintentionally. You might still have to do
+// validation for certain credential types. Please follow the recommendation
+// for that function. For example, if you want to load only service accounts,
+// you can use [WithAuthCredentialsJSON] with [ServiceAccount]:
+//
+//	option.WithAuthCredentialsJSON(option.ServiceAccount, json)
+//
+// If you are loading your credential configuration from an untrusted source and have
+// not mitigated the risks (e.g. by validating the configuration yourself), make
+// these changes as soon as possible to prevent security risks to your environment.
+//
+// Regardless of the function used, it is always your responsibility to validate
+// configurations received from external sources.
+func WithCredentialsJSON(p []byte) ClientOption {
+	return withCredentialsJSON(p)
+}
+
+type withCredentialsJSON []byte
+
+func (w withCredentialsJSON) Apply(o *internal.DialSettings) {
+	o.CredentialsJSON = make([]byte, len(w))
+	copy(o.CredentialsJSON, w)
+}
+
+// WithAuthCredentialsJSON returns a ClientOption that authenticates API calls
+// with the given JSON credentials and credential type.
+//
+// Important: If you accept a credential configuration (credential
+// JSON/File/Stream) from an external source for authentication to Google
+// Cloud Platform, you must validate it before providing it to any Google
+// API or library. Providing an unvalidated credential configuration to
+// Google APIs can compromise the security of your systems and data. For
+// more information, refer to [Validate credential configurations from
+// external sources](https://cloud.google.com/docs/authentication/external/externally-sourced-credentials).
+func WithAuthCredentialsJSON(credType CredentialsType, json []byte) ClientOption {
+	return withAuthCredentialsJSON{
+		credsType: credType,
+		json:      json,
+	}
+}
+
+type withAuthCredentialsJSON struct {
+	credsType CredentialsType
+	json      []byte
+}
+
+func (w withAuthCredentialsJSON) Apply(o *internal.DialSettings) {
+	o.AuthCredentialsJSON = w.json
+	o.AuthCredentialsType = w.credsType
+}
+
+// WithEndpoint returns a ClientOption that overrides the default endpoint
+// to be used for a service. Please note that by default Google APIs only
+// accept HTTPS traffic.
+//
+// For a gRPC client, the port number is typically included in the endpoint.
+// Example: "us-central1-speech.googleapis.com:443".
+//
+// For a REST client, the port number is typically not included. Example:
+// "https://speech.googleapis.com".
+func WithEndpoint(url string) ClientOption {
+	return withEndpoint(url)
+}
+
+type withEndpoint string
+
+func (w withEndpoint) Apply(o *internal.DialSettings) {
+	o.Endpoint = string(w)
+}
+
+// WithScopes returns a ClientOption that overrides the default OAuth2 scopes
+// to be used for a service.
+//
+// If both WithScopes and WithTokenSource are used, scope settings from the
+// token source will be used instead.
+func WithScopes(scope ...string) ClientOption {
+	return withScopes(scope)
+}
+
+type withScopes []string
+
+func (w withScopes) Apply(o *internal.DialSettings) {
+	o.Scopes = make([]string, len(w))
+	copy(o.Scopes, w)
+}
+
+// WithUserAgent returns a ClientOption that sets the User-Agent. This option
+// is incompatible with the [WithHTTPClient] option. If you wish to provide a
+// custom client you will need to add this header via RoundTripper middleware.
+func WithUserAgent(ua string) ClientOption {
+	return withUA(ua)
+}
+
+type withUA string
+
+func (w withUA) Apply(o *internal.DialSettings) { o.UserAgent = string(w) }
+
+// WithHTTPClient returns a ClientOption that specifies the HTTP client to use
+// as the basis of communications. This option may only be used with services
+// that support HTTP as their communication transport. When used, the
+// WithHTTPClient option takes precedent over all other supplied options.
+func WithHTTPClient(client *http.Client) ClientOption {
+	return withHTTPClient{client}
+}
+
+type withHTTPClient struct{ client *http.Client }
+
+func (w withHTTPClient) Apply(o *internal.DialSettings) {
+	o.HTTPClient = w.client
+}
+
+// WithGRPCConn returns a ClientOption that specifies the gRPC client
+// connection to use as the basis of communications. This option may only be
+// used with services that support gRPC as their communication transport. When
+// used, the WithGRPCConn option takes precedent over all other supplied
+// options.
+func WithGRPCConn(conn *grpc.ClientConn) ClientOption {
+	return withGRPCConn{conn}
+}
+
+type withGRPCConn struct{ conn *grpc.ClientConn }
+
+func (w withGRPCConn) Apply(o *internal.DialSettings) {
+	o.GRPCConn = w.conn
+}
+
+// WithGRPCDialOption returns a ClientOption that appends a new grpc.DialOption
+// to an underlying gRPC dial. It does not work with WithGRPCConn.
+func WithGRPCDialOption(opt grpc.DialOption) ClientOption {
+	return withGRPCDialOption{opt}
+}
+
+type withGRPCDialOption struct{ opt grpc.DialOption }
+
+func (w withGRPCDialOption) Apply(o *internal.DialSettings) {
+	o.GRPCDialOpts = append(o.GRPCDialOpts, w.opt)
+}
+
+// WithGRPCConnectionPool returns a ClientOption that creates a pool of gRPC
+// connections that requests will be balanced between.
+func WithGRPCConnectionPool(size int) ClientOption {
+	return withGRPCConnectionPool(size)
+}
+
+type withGRPCConnectionPool int
+
+func (w withGRPCConnectionPool) Apply(o *internal.DialSettings) {
+	o.GRPCConnPoolSize = int(w)
+}
+
+// WithAPIKey returns a ClientOption that specifies an API key to be used
+// as the basis for authentication.
+//
+// API Keys can only be used for JSON-over-HTTP APIs, including those under
+// the import path google.golang.org/api/....
+func WithAPIKey(apiKey string) ClientOption {
+	return withAPIKey(apiKey)
+}
+
+type withAPIKey string
+
+func (w withAPIKey) Apply(o *internal.DialSettings) { o.APIKey = string(w) }
+
+// WithAudiences returns a ClientOption that specifies an audience to be used
+// as the audience field ("aud") for the JWT token authentication.
+func WithAudiences(audience ...string) ClientOption {
+	return withAudiences(audience)
+}
+
+type withAudiences []string
+
+func (w withAudiences) Apply(o *internal.DialSettings) {
+	o.Audiences = make([]string, len(w))
+	copy(o.Audiences, w)
+}
+
+// WithoutAuthentication returns a ClientOption that specifies that no
+// authentication should be used. It is suitable only for testing and for
+// accessing public resources, like public Google Cloud Storage buckets.
+// It is an error to provide both WithoutAuthentication and any of WithAPIKey,
+// WithTokenSource, WithCredentialsFile or WithServiceAccountFile.
+func WithoutAuthentication() ClientOption {
+	return withoutAuthentication{}
+}
+
+type withoutAuthentication struct{}
+
+func (w withoutAuthentication) Apply(o *internal.DialSettings) { o.NoAuth = true }
+
+// WithQuotaProject returns a ClientOption that specifies the project used
+// for quota and billing purposes.
+//
+// For more information please read:
+// https://cloud.google.com/apis/docs/system-parameters
+func WithQuotaProject(quotaProject string) ClientOption {
+	return withQuotaProject(quotaProject)
+}
+
+type withQuotaProject string
+
+func (w withQuotaProject) Apply(o *internal.DialSettings) {
+	o.QuotaProject = string(w)
+}
+
+// WithRequestReason returns a ClientOption that specifies a reason for
+// making the request, which is intended to be recorded in audit logging.
+// An example reason would be a support-case ticket number.
+//
+// For more information please read:
+// https://cloud.google.com/apis/docs/system-parameters
+func WithRequestReason(requestReason string) ClientOption {
+	return withRequestReason(requestReason)
+}
+
+type withRequestReason string
+
+func (w withRequestReason) Apply(o *internal.DialSettings) {
+	o.RequestReason = string(w)
+}
+
+// WithTelemetryDisabled returns a ClientOption that disables default telemetry (OpenCensus)
+// settings on gRPC and HTTP clients.
+// An example reason would be to bind custom telemetry that overrides the defaults.
+func WithTelemetryDisabled() ClientOption {
+	return withTelemetryDisabled{}
+}
+
+type withTelemetryDisabled struct{}
+
+func (w withTelemetryDisabled) Apply(o *internal.DialSettings) {
+	o.TelemetryDisabled = true
+}
+
+// ClientCertSource is a function that returns a TLS client certificate to be used
+// when opening TLS connections.
+//
+// It follows the same semantics as crypto/tls.Config.GetClientCertificate.
+//
+// This is an EXPERIMENTAL API and may be changed or removed in the future.
+type ClientCertSource = func(*tls.CertificateRequestInfo) (*tls.Certificate, error)
+
+// WithClientCertSource returns a ClientOption that specifies a
+// callback function for obtaining a TLS client certificate.
+//
+// This option is used for supporting mTLS authentication, where the
+// server validates the client certifcate when establishing a connection.
+//
+// The callback function will be invoked whenever the server requests a
+// certificate from the client. Implementations of the callback function
+// should try to ensure that a valid certificate can be repeatedly returned
+// on demand for the entire life cycle of the transport client. If a nil
+// Certificate is returned (i.e. no Certificate can be obtained), an error
+// should be returned.
+//
+// This is an EXPERIMENTAL API and may be changed or removed in the future.
+func WithClientCertSource(s ClientCertSource) ClientOption {
+	return withClientCertSource{s}
+}
+
+type withClientCertSource struct{ s ClientCertSource }
+
+func (w withClientCertSource) Apply(o *internal.DialSettings) {
+	o.ClientCertSource = w.s
+}
+
+// ImpersonateCredentials returns a ClientOption that will impersonate the
+// target service account.
+//
+// In order to impersonate the target service account
+// the base service account must have the Service Account Token Creator role,
+// roles/iam.serviceAccountTokenCreator, on the target service account.
+// See https://cloud.google.com/iam/docs/understanding-service-accounts.
+//
+// Optionally, delegates can be used during impersonation if the base service
+// account lacks the token creator role on the target. When using delegates,
+// each service account must be granted roles/iam.serviceAccountTokenCreator
+// on the next service account in the chain.
+//
+// For example, if a base service account of SA1 is trying to impersonate target
+// service account SA2 while using delegate service accounts DSA1 and DSA2,
+// the following must be true:
+//
+//  1. Base service account SA1 has roles/iam.serviceAccountTokenCreator on
+//     DSA1.
+//  2. DSA1 has roles/iam.serviceAccountTokenCreator on DSA2.
+//  3. DSA2 has roles/iam.serviceAccountTokenCreator on target SA2.
+//
+// The resulting impersonated credential will either have the default scopes of
+// the client being instantiating or the scopes from WithScopes if provided.
+// Scopes are required for creating impersonated credentials, so if this option
+// is used while not using a NewClient/NewService function, WithScopes must also
+// be explicitly passed in as well.
+//
+// If the base credential is an authorized user and not a service account, or if
+// the option WithQuotaProject is set, the target service account must have a
+// role that grants the serviceusage.services.use permission such as
+// roles/serviceusage.serviceUsageConsumer.
+//
+// This is an EXPERIMENTAL API and may be changed or removed in the future.
+//
+// Deprecated: This option has been replaced by `impersonate` package:
+// `google.golang.org/api/impersonate`. Please use the `impersonate` package
+// instead with the WithTokenSource option.
+func ImpersonateCredentials(target string, delegates ...string) ClientOption {
+	return impersonateServiceAccount{
+		target:    target,
+		delegates: delegates,
+	}
+}
+
+type impersonateServiceAccount struct {
+	target    string
+	delegates []string
+}
+
+func (i impersonateServiceAccount) Apply(o *internal.DialSettings) {
+	o.ImpersonationConfig = &impersonate.Config{
+		Target: i.target,
+	}
+	o.ImpersonationConfig.Delegates = make([]string, len(i.delegates))
+	copy(o.ImpersonationConfig.Delegates, i.delegates)
+}
+
+type withCreds google.Credentials
+
+func (w *withCreds) Apply(o *internal.DialSettings) {
+	o.Credentials = (*google.Credentials)(w)
+}
+
+// WithCredentials returns a ClientOption that authenticates API calls.
+func WithCredentials(creds *google.Credentials) ClientOption {
+	return (*withCreds)(creds)
+}
+
+// WithAuthCredentials returns a ClientOption that specifies an
+// [cloud.google.com/go/auth.Credentials] to be used as the basis for
+// authentication.
+func WithAuthCredentials(creds *auth.Credentials) ClientOption {
+	return withAuthCredentials{creds}
+}
+
+type withAuthCredentials struct{ creds *auth.Credentials }
+
+func (w withAuthCredentials) Apply(o *internal.DialSettings) {
+	o.AuthCredentials = w.creds
+}
+
+// WithUniverseDomain returns a ClientOption that sets the universe domain.
+func WithUniverseDomain(ud string) ClientOption {
+	return withUniverseDomain(ud)
+}
+
+type withUniverseDomain string
+
+func (w withUniverseDomain) Apply(o *internal.DialSettings) {
+	o.UniverseDomain = string(w)
+}
+
+// WithLogger returns a ClientOption that sets the logger used throughout the
+// client library call stack. If this option is provided it takes precedence
+// over the value set in GOOGLE_SDK_GO_LOGGING_LEVEL. Specifying this option
+// enables logging at the provided logger's configured level.
+func WithLogger(l *slog.Logger) ClientOption {
+	return withLogger{l}
+}
+
+type withLogger struct{ l *slog.Logger }
+
+func (w withLogger) Apply(o *internal.DialSettings) {
+	o.Logger = w.l
+}