servenv

package
v0.20.0-rc2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 20, 2024 License: Apache-2.0 Imports: 63 Imported by: 32

Documentation

Overview

Package servenv contains functionality that is common for all Vitess server programs. It defines and initializes command line flags that control the runtime environment.

After a server program has called flag.Parse, it needs to call env.Init to make env use the command line variables to initialize the environment. It also needs to call env.Close before exiting.

Note: If you need to plug in any custom initialization/cleanup for a vitess distribution, register them using OnInit and onClose. A clean way of achieving that is adding to this package a file with an init() function that registers the hooks.

Index

Constants

View Source 
const Name = "proto"

Name is the name registered for the proto compressor.

Variables

View Source 
var (
	// TruncateUILen truncate queries in debug UIs to the given length. 0 means unlimited.
	TruncateUILen = 512

	// TruncateErrLen truncate queries in error logs to the given length. 0 means unlimited.
	TruncateErrLen = 0
)
View Source 
var AppVersion versionInfo

AppVersion is the struct to store build info.

View Source 
var (

	// ExitChan waits for a signal that tells the process to terminate
	ExitChan chan os.Signal
)
View Source 
var (

	// GRPCServer is the global server to serve gRPC.
	GRPCServer *grpc.Server
)

This file handles gRPC server, on its own port. Clients register servers, based on service map:

servenv.RegisterGRPCFlags() 

servenv.OnRun(func() {
  if servenv.GRPCCheckServiceMap("XXX") {
    pb.RegisterXXX(servenv.GRPCServer, XXX)
  }
}

Note servenv.GRPCServer can only be used in servenv.OnRun, and not before, as it is initialized right before calling OnRun.

View Source 
var (

	// ListeningURL is filled in when calling Run, contains the server URL.
	ListeningURL url.URL
)
View Source 
var TestingEndtoend = false

TestingEndtoend is true when this Vitess binary is being ran as part of an endtoend test suite

Functions

func AddStatusFuncs 

func AddStatusFuncs(fmap template.FuncMap)

AddStatusFuncs merges the provided functions into the set of functions used to render /debug/status. Call this before AddStatusPart if your template requires custom functions.

func AddStatusPart 

func AddStatusPart(banner, fragment string, f func() any)

AddStatusPart adds a new section to status. fragment is used as a subtemplate of the template used to render /debug/status, and will be executed using the value of invoking f at the time of the /debug/status request. fragment is parsed and executed with the html/template package. Functions registered with AddStatusFuncs may be used in the template.

func AddStatusSection 

func AddStatusSection(banner string, f func() string)

AddStatusSection registers a function that generates extra information for the global status page, it will be used as a header before the information. If more complex output than a simple string is required use AddStatusPart instead.

func ClientCertSubstrings 

func ClientCertSubstrings() string

ClientCertSubstrings returns the value of the `--grpc_auth_mtls_allowed_substrings` flag.

func CobraPreRunE added in v0.18.0 

func CobraPreRunE(cmd *cobra.Command, args []string) error

CobraPreRunE returns the common function that commands will need to load viper infrastructure. It matches the signature of cobra's (Pre|Post)RunE-type functions.

func FakeAuthStreamInterceptor 

func FakeAuthStreamInterceptor(srv any, stream grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error

FakeAuthStreamInterceptor fake interceptor to test plugin

func FakeAuthUnaryInterceptor 

func FakeAuthUnaryInterceptor(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error)

FakeAuthUnaryInterceptor fake interceptor to test plugin

func FireRunHooks 

func FireRunHooks()

FireRunHooks fires the hooks registered by OnHook. Use this in a non-server to run the hooks registered by servenv.OnRun().

func GRPCAuth 

func GRPCAuth() string

GRPCAuth returns the value of the `--grpc_auth_mode` flag.

func GRPCCert 

func GRPCCert() string

GRPCCert returns the value of the `--grpc_cert` flag.

func GRPCCertificateAuthority added in v0.15.0 

func GRPCCertificateAuthority() string

GRPCCertificateAuthority returns the value of the `--grpc_ca` flag.

func GRPCCheckServiceMap 

func GRPCCheckServiceMap(name string) bool

GRPCCheckServiceMap returns if we should register a gRPC service (and also logs how to enable / disable it)

func GRPCKey 

func GRPCKey() string

GRPCKey returns the value of the `--grpc_key` flag.

func GRPCPort 

func GRPCPort() int

GRPCPort returns the value of the `--grpc_port` flag.

func GetAuthenticator 

func GetAuthenticator(name string) func() (Authenticator, error)

GetAuthenticator returns an AuthPlugin by name, or log.Fatalf.

func GetFlagSetFor added in v0.15.0 

func GetFlagSetFor(cmd string) *pflag.FlagSet

GetFlagSetFor returns the flag set for a given command. This has to exported for the Vitess-operator to use

func GetInitStartTime added in v0.16.0 

func GetInitStartTime() time.Time

func HTTPHandle added in v0.17.0 

func HTTPHandle(pattern string, handler http.Handler)

HTTPHandle registers the given handler for the internal servenv mux.

func HTTPHandleFunc added in v0.17.0 

func HTTPHandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))

HTTPHandleFunc registers the given handler func for the internal servenv mux.

func HTTPRegisterProfile added in v0.17.0 

func HTTPRegisterProfile()

HTTPRegisterProfile registers the default pprof HTTP endpoints with the internal servenv mux.

func HTTPServe added in v0.17.0 

func HTTPServe(l net.Listener) error

HTTPServe starts the HTTP server for the internal servenv mux on the listener.

func HandlePanic 

func HandlePanic(component string, err *error)

HandlePanic should be called using 'defer' in the RPC code that executes the command.

func Init 

func Init()

Init is the first phase of the server startup.

func InitServiceMap 

func InitServiceMap(protocol, name string)

InitServiceMap will set the default value for a protocol/name to be served.

func MoveFlagsToCobraCommand added in v0.18.0 

func MoveFlagsToCobraCommand(cmd *cobra.Command)

MoveFlagsToCobraCommand moves the servenv-registered flags to the flagset of the given cobra command, then copies over the glog flags that otherwise require manual transferring.

func MovePersistentFlagsToCobraCommand added in v0.18.0 

func MovePersistentFlagsToCobraCommand(cmd *cobra.Command)

MovePersistentFlagsToCobraCommand functions exactly like MoveFlagsToCobraCommand, but moves the servenv-registered flags to the persistent flagset of the given cobra command, then copies over the glog flags that otherwise require manual transferring.

Useful for transferring flags to a parent command whose subcommands should inherit the servenv-registered flags.

func MySQLServerVersion added in v0.10.0 

func MySQLServerVersion() string

MySQLServerVersion returns the value of the `--mysql_server_version` flag.

func OnClose 

func OnClose(f func())

OnClose registers f to be run at the end of the app lifecycle. This happens after the lameduck period just before the program exits. All hooks are run in parallel.

func OnInit 

func OnInit(f func())

OnInit registers f to be run at the beginning of the app lifecycle. It should be called in an init() function.

func OnParse added in v0.15.0 

func OnParse(f func(fs *pflag.FlagSet))

OnParse registers a callback function to register flags on the flagset that are used by any caller of servenv.Parse or servenv.ParseWithArgs.

func OnParseFor added in v0.15.0 

func OnParseFor(cmd string, f func(fs *pflag.FlagSet))

OnParseFor registers a callback function to register flags on the flagset used by servenv.Parse or servenv.ParseWithArgs. The provided callback will only be called if the `cmd` argument passed to either Parse or ParseWithArgs exactly matches the `cmd` argument passed to OnParseFor.

To register for flags for multiple commands, for example if a package's flags should be used for only vtgate and vttablet but no other binaries, call this multiple times with the same callback function. To register flags for all commands globally, use OnParse instead.

func OnRun 

func OnRun(f func())

OnRun registers f to be run right at the beginning of Run. All hooks are run in parallel.

func OnTerm 

func OnTerm(f func())

OnTerm registers a function to be run when the process receives a SIGTERM. This allows the program to change its behavior during the lameduck period.

All hooks are run in parallel, and there is no guarantee that the process will wait for them to finish before dying when the lameduck period expires.

See also: OnTermSync

func OnTermSync 

func OnTermSync(f func())

OnTermSync registers a function to be run when the process receives SIGTERM. This allows the program to change its behavior during the lameduck period.

All hooks are run in parallel, and the process will do its best to wait (up to -onterm_timeout) for all of them to finish before dying.

See also: OnTerm

func ParseFlags 

func ParseFlags(cmd string)

ParseFlags initializes flags and handles the common case when no positional arguments are expected.

func ParseFlagsForTests added in v0.18.0 

func ParseFlagsForTests(cmd string)

ParseFlagsForTests initializes flags but skips the version, filesystem args and go flag related work. Note: this should not be used outside of unit tests.

func ParseFlagsWithArgs 

func ParseFlagsWithArgs(cmd string) []string

ParseFlagsWithArgs initializes flags and returns the positional arguments

func Port 

func Port() int

Port returns the value of the `--port` flag.

func RegisterAuthPlugin 

func RegisterAuthPlugin(name string, authPlugin func() (Authenticator, error))

RegisterAuthPlugin registers an implementation of AuthServer.

func RegisterDefaultFlags 

func RegisterDefaultFlags()

RegisterDefaultFlags registers the default flags for listening to a given port for standard connections. If calling this, then call RunDefault()

func RegisterDefaultSocketFileFlags 

func RegisterDefaultSocketFileFlags()

RegisterDefaultSocketFileFlags registers the default flags for listening to a socket. This needs to be called before flags are parsed.

func RegisterFlags added in v0.15.0 

func RegisterFlags()

RegisterFlags installs the flags used by Init, Run, and RunDefault.

This must be called before servenv.ParseFlags if using any of those functions.

func RegisterFlagsForTopoBinaries added in v0.15.0 

func RegisterFlagsForTopoBinaries(registerFlags func(fs *pflag.FlagSet))

func RegisterFlagsWithTimeouts added in v0.20.0 

func RegisterFlagsWithTimeouts(tf *TimeoutFlags)

func RegisterGRPCServerAuthFlags added in v0.15.0 

func RegisterGRPCServerAuthFlags()

RegisterGRPCServerAuthFlags registers flags required to enable server-side authentication in vitess gRPC services.

`go/cmd/*` entrypoints should call this function before ParseFlags(WithArgs)? if they wish to expose Authenticator functionality.

func RegisterGRPCServerFlags added in v0.15.0 

func RegisterGRPCServerFlags()

RegisterGRPCServerFlags registers flags required to run a gRPC server via Run or RunDefault.

`go/cmd/*` entrypoints should call this function before ParseFlags(WithArgs)? if they wish to run a gRPC server.

func RegisterMySQLServerFlags added in v0.15.0 

func RegisterMySQLServerFlags(fs *pflag.FlagSet)

RegisterMySQLServerFlags installs the flags needed to specify or expose a particular MySQL server version from Vitess.

func RegisterServiceMapFlag added in v0.15.0 

func RegisterServiceMapFlag()

RegisterServiceMapFlag registers an OnParse hook to install the `--service_map` flag for a given cmd. It must be called before ParseFlags or ParseFlagsWithArgs.

func Run 

func Run(bindAddress string, port int)

Run starts listening for RPC and HTTP requests, and blocks until it the process gets a signal.

func RunDefault 

func RunDefault()

RunDefault calls Run() with the parameters from the flags.

func StaticAuthUsernameFromContext added in v0.16.0 

func StaticAuthUsernameFromContext(ctx context.Context) string

StaticAuthUsernameFromContext returns the username authenticated by the static auth plugin and stored in the Context, if any

func StatusURLPath 

func StatusURLPath() string

StatusURLPath returns the path to the status page.

Types

type Authenticator 

type Authenticator interface {
	Authenticate(ctx context.Context, fullMethod string) (context.Context, error)
}

Authenticator provides an interface to implement auth in Vitess in grpc server

type Exporter 

type Exporter struct {
	// contains filtered or unexported fields
}

Exporter remaps http and stats end-points to distinct namespaces.

Unnamed exporters are treated as unscoped, and requests are passed through to the underlying functions.

For named exporters, http handle requests of the form /path will be remapped to /name/path. In the case of stats variables, a new dimension will be added. For example, a Counter of value 1 will be changed to a map {"name": 1}. A multi-counter like { "a.b": 1, "c.d": 2} will be mapped to {"name.a.b": 1, "name.c.d": 2}. Stats vars of the same name are merged onto a single map. For example, if exporters name1 and name2 independently create a stats Counter named foo and export values 1 and 2, the result is a merged stats var named foo with the following content: {"name1": 1, "name2": 2}.

The functions that create the stat vars don't always return the actual exported variable. Instead they return a variable that only affects the dimension that was assigned to the exporter. The exported variables are named evar, and the variables returned to the caller are named lvar (local var).

If there are duplicates, "Func" vars will be changed to invoke the latest callback function. Non-Func vars will be reused. For counters, the adds will continue to add on top of existing values. For gauges, this is less material because a new "Set" will overwrite the previous value. This behavior of reusing counters is necessary because we build derived variables like Rates, which need to continue referencing the original variable that was created.

func NewExporter 

func NewExporter(name, label string) *Exporter

NewExporter creates a new Exporter with name as namespace. label is the name of the additional dimension for the stats vars.

func (*Exporter) AddStatusPart 

func (e *Exporter) AddStatusPart(banner, frag string, f func() any)

AddStatusPart adds a status part to the status page. If Exporter has a name, the part is added to a url named /name/debug/status. Otherwise, it's /debug/status.

func (*Exporter) HandleFunc 

func (e *Exporter) HandleFunc(url string, f func(w http.ResponseWriter, r *http.Request))

HandleFunc sets or overwrites the handler for url. If Exporter has a name, url remapped from /path to /name/path. If name is empty, the request is passed through to HTTPHandleFunc.

func (*Exporter) Name 

func (e *Exporter) Name() string

Name returns the name of the exporter.

func (*Exporter) NewCounter 

func (e *Exporter) NewCounter(name string, help string) *stats.Counter

NewCounter creates a name-spaced equivalent for stats.NewCounter.

func (*Exporter) NewCounterDurationFunc 

func (e *Exporter) NewCounterDurationFunc(name string, help string, f func() time.Duration) *stats.CounterDurationFunc

NewCounterDurationFunc creates a name-spaced equivalent for stats.NewCounterDurationFunc.

func (*Exporter) NewCounterFunc 

func (e *Exporter) NewCounterFunc(name string, help string, f func() int64) *stats.CounterFunc

NewCounterFunc creates a name-spaced equivalent for stats.NewCounterFunc.

func (*Exporter) NewCountersFuncWithMultiLabels 

func (e *Exporter) NewCountersFuncWithMultiLabels(name, help string, labels []string, f func() map[string]int64) *stats.CountersFuncWithMultiLabels

NewCountersFuncWithMultiLabels creates a name-spaced equivalent for stats.NewCountersFuncWithMultiLabels.

func (*Exporter) NewCountersWithMultiLabels 

func (e *Exporter) NewCountersWithMultiLabels(name, help string, labels []string) *stats.CountersWithMultiLabels

NewCountersWithMultiLabels creates a name-spaced equivalent for stats.NewCountersWithMultiLabels.

func (*Exporter) NewCountersWithSingleLabel 

func (e *Exporter) NewCountersWithSingleLabel(name, help string, label string, tags ...string) *stats.CountersWithSingleLabel

NewCountersWithSingleLabel creates a name-spaced equivalent for stats.NewCountersWithSingleLabel. Tags are ignored if the exporter is named.

func (*Exporter) NewGauge 

func (e *Exporter) NewGauge(name string, help string) *stats.Gauge

NewGauge creates a name-spaced equivalent for stats.NewGauge.

func (*Exporter) NewGaugeDurationFunc 

func (e *Exporter) NewGaugeDurationFunc(name string, help string, f func() time.Duration) *stats.GaugeDurationFunc

NewGaugeDurationFunc creates a name-spaced equivalent for stats.NewGaugeDurationFunc.

func (*Exporter) NewGaugeFloat64 added in v0.15.0 

func (e *Exporter) NewGaugeFloat64(name string, help string) *stats.GaugeFloat64

NewGaugeFloat64 exporter assumes all counters/gauges are int64 based; I haven't found a good solution for exporting a float64 gauge yet. (Shlomi)

func (*Exporter) NewGaugeFunc 

func (e *Exporter) NewGaugeFunc(name string, help string, f func() int64) *stats.GaugeFunc

NewGaugeFunc creates a name-spaced equivalent for stats.NewGaugeFunc.

func (*Exporter) NewGaugesFuncWithMultiLabels 

func (e *Exporter) NewGaugesFuncWithMultiLabels(name, help string, labels []string, f func() map[string]int64) *stats.GaugesFuncWithMultiLabels

NewGaugesFuncWithMultiLabels creates a name-spaced equivalent for stats.NewGaugesFuncWithMultiLabels.

func (*Exporter) NewGaugesWithMultiLabels 

func (e *Exporter) NewGaugesWithMultiLabels(name, help string, labels []string) *stats.GaugesWithMultiLabels

NewGaugesWithMultiLabels creates a name-spaced equivalent for stats.NewGaugesWithMultiLabels.

func (*Exporter) NewGaugesWithSingleLabel 

func (e *Exporter) NewGaugesWithSingleLabel(name, help string, label string, tags ...string) *stats.GaugesWithSingleLabel

NewGaugesWithSingleLabel creates a name-spaced equivalent for stats.NewGaugesWithSingleLabel. Tags are ignored if the exporter is named.

func (*Exporter) NewHistogram 

func (e *Exporter) NewHistogram(name, help string, cutoffs []int64) *stats.Histogram

NewHistogram creates a name-spaced equivalent for stats.NewHistogram. The function currently just returns an unexported variable.

func (*Exporter) NewMultiTimings 

func (e *Exporter) NewMultiTimings(name string, help string, labels []string) *MultiTimingsWrapper

NewMultiTimings creates a name-spaced equivalent for stats.NewMultiTimings. The function currently just returns an unexported variable.

func (*Exporter) NewRates 

func (e *Exporter) NewRates(name string, singleCountVar multiCountVar, samples int, interval time.Duration) *stats.Rates

NewRates creates a name-spaced equivalent for stats.NewRates. The function currently just returns an unexported variable.

func (*Exporter) NewTimings 

func (e *Exporter) NewTimings(name string, help string, label string) *TimingsWrapper

NewTimings creates a name-spaced equivalent for stats.NewTimings. The function currently just returns an unexported variable.

func (*Exporter) Publish 

func (e *Exporter) Publish(name string, v expvar.Var)

Publish creates a name-spaced equivalent for stats.Publish. The function just passes through if the Exporter name is empty.

func (*Exporter) URLPrefix 

func (e *Exporter) URLPrefix() string

URLPrefix returns the URL prefix for the exporter.

type MtlsAuthPlugin 

type MtlsAuthPlugin struct {
	// contains filtered or unexported fields
}

MtlsAuthPlugin implements static username/password authentication for grpc. It contains an array of username/passwords that will be authorized to connect to the grpc server.

func (*MtlsAuthPlugin) Authenticate 

func (ma *MtlsAuthPlugin) Authenticate(ctx context.Context, fullMethod string) (context.Context, error)

Authenticate implements Authenticator interface. This method will be used inside a middleware in grpc_server to authenticate incoming requests.

type MultiTimingsWrapper 

type MultiTimingsWrapper struct {
	// contains filtered or unexported fields
}

MultiTimingsWrapper provides a namespaced version of stats.MultiTimings.

func (*MultiTimingsWrapper) Add 

func (tw *MultiTimingsWrapper) Add(names []string, elapsed time.Duration)

Add behaves like MultiTimings.Add.

func (*MultiTimingsWrapper) Counts 

func (tw *MultiTimingsWrapper) Counts() map[string]int64

Counts behaves lie MultiTimings.Counts.

func (*MultiTimingsWrapper) Record 

func (tw *MultiTimingsWrapper) Record(names []string, startTime time.Time)

Record behaves like MultiTimings.Record.

func (*MultiTimingsWrapper) Reset added in v0.8.0 

func (tw *MultiTimingsWrapper) Reset()

Reset will clear histograms: used during testing

type StaticAuthConfigEntry 

type StaticAuthConfigEntry struct {
	Username string
	Password string
}

StaticAuthConfigEntry is the container for server side credentials. Current implementation matches the the one from the client but this will change in the future as we hooked this pluging into ACL features.

type StaticAuthPlugin 

type StaticAuthPlugin struct {
	// contains filtered or unexported fields
}

StaticAuthPlugin implements static username/password authentication for grpc. It contains an array of username/passwords that will be authorized to connect to the grpc server.

func (*StaticAuthPlugin) Authenticate 

func (sa *StaticAuthPlugin) Authenticate(ctx context.Context, fullMethod string) (context.Context, error)

Authenticate implements AuthPlugin interface. This method will be used inside a middleware in grpc_server to authenticate incoming requests.

type TimeoutFlags added in v0.20.0 

type TimeoutFlags struct {
	LameduckPeriod time.Duration
	OnTermTimeout  time.Duration
	OnCloseTimeout time.Duration
}

type TimingsWrapper 

type TimingsWrapper struct {
	// contains filtered or unexported fields
}

TimingsWrapper provides a namespaced version of stats.Timings.

func (*TimingsWrapper) Add 

func (tw *TimingsWrapper) Add(name string, elapsed time.Duration)

Add behaves like Timings.Add.

func (*TimingsWrapper) Counts 

func (tw *TimingsWrapper) Counts() map[string]int64

Counts behaves like Timings.Counts.

func (*TimingsWrapper) Record 

func (tw *TimingsWrapper) Record(name string, startTime time.Time)

Record behaves like Timings.Record.

func (*TimingsWrapper) Reset added in v0.8.0 

func (tw *TimingsWrapper) Reset()

Reset will clear histograms: used during testing

type WrappedServerStream 

type WrappedServerStream struct {
	grpc.ServerStream
	WrappedContext context.Context
}

WrappedServerStream is based on the service stream wrapper from: https://github.com/grpc-ecosystem/go-grpc-middleware

func WrapServerStream 

func WrapServerStream(stream grpc.ServerStream) *WrappedServerStream

WrapServerStream returns a ServerStream that has the ability to overwrite context.

func (*WrappedServerStream) Context 

func (w *WrappedServerStream) Context() context.Context

Context returns the wrapper's WrappedContext, overwriting the nested grpc.ServerStream.Context()

Source Files

View all Source files

Directories

Path Synopsis
internal
mux

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.