options.go raw

   1  package options
   2  
   3  import (
   4  	"crypto/tls"
   5  
   6  	"go.uber.org/zap"
   7  	"google.golang.org/grpc"
   8  
   9  	"github.com/yandex-cloud/go-sdk/v2/credentials"
  10  	"github.com/yandex-cloud/go-sdk/v2/pkg/authentication"
  11  	"github.com/yandex-cloud/go-sdk/v2/pkg/endpoints"
  12  	"github.com/yandex-cloud/go-sdk/v2/pkg/options/retry"
  13  )
  14  
  15  // defaultEndpoint specifies the default gRPC endpoint for connecting to the Yandex Cloud API.
  16  const defaultEndpoint = "api.cloud.yandex.net:443"
  17  
  18  // Option defines a function that modifies the configuration of an Options instance.
  19  type Option func(*Options)
  20  
  21  // Options defines a configuration structure for customizing SDK behavior and connections.
  22  type Options struct {
  23  	// Credentials is used to sign and authenticate API requests.
  24  	Credentials credentials.Credentials
  25  	// EndpointsResolver provides or overrides service endpoints.
  26  	// By default, the SDK uses built-in endpoints, but you can
  27  	// supply a custom resolver to target pre-release or private APIs.
  28  	EndpointsResolver endpoints.EndpointsResolver
  29  	// DiscoveryEndpoint specifies a custom URL to retrieve default
  30  	// service endpoints. If unset, the SDK uses its default discovery service.
  31  	DiscoveryEndpoint string
  32  	// Authenticator signs requests and injects auth headers.
  33  	Authenticator authentication.Authenticator
  34  	// TLSConfig allows customizing TLS settings for gRPC connections.
  35  	// If nil, the SDK uses the system default configuration.
  36  	TlsConfig *tls.Config
  37  	// Plaintext, when true, disables TLS and connects over Plaintext.
  38  	// This is useful for local testing or when an external proxy handles TLS.
  39  	Plaintext bool
  40  	// Logger provides structured logging functionality using zap Logger.
  41  	// If not set, no logging will be performed.
  42  	Logger *zap.Logger
  43  
  44  	CustomDialOpts      []grpc.DialOption
  45  	RetryOptions        []retry.RetryOption
  46  	DefaultRetryOptions bool
  47  }
  48  
  49  // DefaultOptions initializes and returns an Options struct with default configuration for endpoint and connection timeout.
  50  func DefaultOptions() *Options {
  51  	return &Options{
  52  		DiscoveryEndpoint: defaultEndpoint,
  53  	}
  54  }
  55  
  56  // WithCredentials sets the provided Credentials to the Options, used for signing and authenticating API requests.
  57  func WithCredentials(creds credentials.Credentials) Option {
  58  	return func(o *Options) {
  59  		o.Credentials = creds
  60  	}
  61  }
  62  
  63  // WithEndpointsResolver configures a custom EndpointsResolver to dynamically resolve gRPC service endpoints for the SDK.
  64  func WithEndpointsResolver(resolver endpoints.EndpointsResolver) Option {
  65  	return func(o *Options) {
  66  		o.EndpointsResolver = resolver
  67  	}
  68  }
  69  
  70  // WithDiscoveryEndpoint sets a custom discovery endpoint URL for resolving service endpoints in the SDK configuration.
  71  func WithDiscoveryEndpoint(endpoint string) Option {
  72  	return func(o *Options) {
  73  		o.DiscoveryEndpoint = endpoint
  74  	}
  75  }
  76  
  77  // WithAuthenticator sets the provided Authenticator for authentication in the Options configuration.
  78  func WithAuthenticator(auth authentication.Authenticator) Option {
  79  	return func(o *Options) {
  80  		o.Authenticator = auth
  81  	}
  82  }
  83  
  84  // WithTLSConfig sets a custom TLS configuration for gRPC connections by assigning it to the Options struct.
  85  func WithTLSConfig(config *tls.Config) Option {
  86  	return func(o *Options) {
  87  		o.TlsConfig = config
  88  	}
  89  }
  90  
  91  // WithPlaintext is an Option that configures the SDK to use Plaintext communication, disabling TLS for gRPC connections.
  92  func WithPlaintext() Option {
  93  	return func(o *Options) {
  94  		o.Plaintext = true
  95  	}
  96  }
  97  
  98  // WithDefaultRetryOptions enables default retry handling by setting the `DefaultRetryOptions` field to true in Options.
  99  // it could be used in combination with WithRetryOptions to override default retry options.
 100  func WithDefaultRetryOptions() Option {
 101  	return func(o *Options) {
 102  		o.DefaultRetryOptions = true
 103  	}
 104  }
 105  
 106  // WithRetryOptions applies retry options to the SDK's configuration.
 107  func WithRetryOptions(opts ...retry.RetryOption) Option {
 108  	return func(o *Options) {
 109  		o.RetryOptions = opts
 110  	}
 111  }
 112  
 113  // WithCustomDialOptions injects custom gRPC dial options into the SDK's configuration.
 114  // It ovverides any other dial options that may have been set by other Options.
 115  func WithCustomDialOptions(opts ...grpc.DialOption) Option {
 116  	return func(o *Options) {
 117  		o.CustomDialOpts = opts
 118  	}
 119  }
 120