server

func (*Options) FromCloudRunEnv ¶

func (o *Options) FromCloudRunEnv() error

FromCloudRunEnv recognized K_SERVICE environment variable and configures some options based on what it discovers in the environment.

Does nothing if K_SERVICE is not set.

Equivalent to passing the following flags:

-prod
-http-addr -
-grpc-addr -
-admin-addr -
-allow-h2c
-shutdown-delay 1s
-cloud-project <cloud project Cloud Run container is running in>
-cloud-region <cloud region Cloud Run container is running in>
-service-account-json :gce
-open-id-rpc-auth-enable
-ts-mon-service-name <cloud project Cloud Run container is running in>
-ts-mon-job-name ${K_SERVICE}

Flags passed via the actual command line in the Cloud Run manifest override these prefilled defaults. In particular pass either `-http-addr` or `-grpc-addr` (or both) to enable corresponding ports.

Additionally the hostname (used in metric and trace fields) is derived from environment to be semantically similar to what it looks like in the GKE environment.

func (*Options) FromGAEEnv ¶

func (o *Options) FromGAEEnv()

FromGAEEnv uses the GAE_* env vars to configure the server for the GAE environment.

Does nothing if GAE_VERSION is not set.

Equivalent to passing the following flags:

-prod
-http-addr 0.0.0.0:${PORT}
-admin-addr -
-shutdown-delay 1s
-cloud-project ${GOOGLE_CLOUD_PROJECT}
-cloud-region <derived from the region code in GAE_APPLICATION>
-service-account-json :gce
-ts-mon-service-name ${GOOGLE_CLOUD_PROJECT}
-ts-mon-job-name ${GAE_SERVICE}

Additionally the hostname and -container-image-id (used in metric and trace fields) are derived from available GAE_* env vars to be semantically similar to what they represent in the GKE environment.

Note that a mapping between a region code in GAE_APPLICATION and the corresponding cloud region is not documented anywhere, so if you see warnings when your app starts up either update the code to recognize your region code or pass '-cloud-region' argument explicitly in app.yaml.

See https://cloud.google.com/appengine/docs/standard/go/runtime.

func (*Options) ImageName ¶

func (o *Options) ImageName() string

ImageName extracts image name from ContainerImageID.

This is the part of ContainerImageID before ':' or '@'.

func (*Options) ImageVersion ¶

func (o *Options) ImageVersion() string

ImageVersion extracts image tag or digest from ContainerImageID.

This is eventually reported as a value of 'server/version' metric.

On GAE it would return the service version name based on GAE_VERSION env var, since ContainerImageID is artificially constructed to look like "appengine/${CLOUD_PROJECT}/${GAE_SERVICE}:${GAE_VERSION}".

On Cloud Run it is responsibility of the deployment layer to correctly populate -container-image-id command line flag.

Returns "unknown" if ContainerImageID is empty or malformed.

func (*Options) Register ¶

func (o *Options) Register(f *flag.FlagSet)

Register registers the command line flags.

func (*Port) VirtualHost ¶

func (p *Port) VirtualHost(host string) *router.Router

VirtualHost returns a router (registering it if necessary) used for requests that have the given Host header.

Note that requests that match some registered virtual host router won't reach the default router (port.Routes), even if the virtual host router doesn't have a route for them. Such requests finish with HTTP 404.

Should be called before Server's Serve loop (panics otherwise).

func (*Server) AddPort ¶

func (s *Server) AddPort(opts PortOptions) (*Port, error)

AddPort prepares and binds an additional serving HTTP port.

Can be used to open more listening HTTP ports (in addition to opts.HTTPAddr and opts.AdminAddr). The returned Port object can be used to populate the router that serves requests hitting the added port.

If opts.ListenAddr is '-', a dummy port will be added: it is a valid *Port object, but it is not actually exposed as a listening TCP socket. This is useful to disable listening ports without changing any code.

Must be called before Serve (panics otherwise).

func (*Server) ConfigurePRPC ¶

func (s *Server) ConfigurePRPC(cb func(srv *prpc.Server))

ConfigurePRPC allows tweaking pRPC-specific server configuration.

Use it only for changing pRPC-specific options (usually ones that are related to HTTP protocol in some way). This method **must not be used** for registering interceptors or setting authentication options (changes to them done here will cause a panic). Instead use RegisterUnaryServerInterceptors to register interceptors or SetRPCAuthMethods to change how the server authenticates RPC requests. Changes done through these methods will apply to both gRPC and pRPC servers.

Must be called before Serve (panics otherwise).

func (*Server) Fatal ¶

func (s *Server) Fatal(err error)

Fatal logs the error and immediately shuts down the process with exit code 3.

No cleanup is performed. Deferred statements are not run. Not recoverable.

func (*Server) RegisterCleanup ¶

func (s *Server) RegisterCleanup(cb func(context.Context))

RegisterCleanup registers a callback that is run in Serve after the server has exited the serving loop.

Registering a new cleanup callback from within a cleanup causes a deadlock, don't do that.

func (*Server) RegisterService ¶

func (s *Server) RegisterService(desc *grpc.ServiceDesc, impl any)

RegisterService is part of grpc.ServiceRegistrar interface.

The registered service will be exposed through both gRPC and pRPC protocols on corresponding ports. See Server doc.

Must be called before Serve (panics otherwise).

func (*Server) RegisterStreamServerInterceptors ¶

func (s *Server) RegisterStreamServerInterceptors(intr ...grpc.StreamServerInterceptor)

RegisterStreamServerInterceptors registers grpc.StreamServerInterceptor's applied to all streaming RPCs that hit the server.

Interceptors are chained in order they are registered, i.e. the first registered interceptor becomes the outermost. The initial chain already contains some base interceptors (e.g. for monitoring) and all interceptors registered by server modules. RegisterStreamServerInterceptors extends this chain. Subsequent calls to RegisterStreamServerInterceptors adds more interceptors into the chain.

Must be called before Serve (panics otherwise).

func (*Server) RegisterUnaryServerInterceptors ¶

func (s *Server) RegisterUnaryServerInterceptors(intr ...grpc.UnaryServerInterceptor)

RegisterUnaryServerInterceptors registers grpc.UnaryServerInterceptor's applied to all unary RPCs that hit the server.

Interceptors are chained in order they are registered, i.e. the first registered interceptor becomes the outermost. The initial chain already contains some base interceptors (e.g. for monitoring) and all interceptors registered by server modules. RegisterUnaryServerInterceptors extends this chain. Subsequent calls to RegisterUnaryServerInterceptors adds more interceptors into the chain.

Must be called before Serve (panics otherwise).

func (*Server) RegisterUnifiedServerInterceptors ¶

func (s *Server) RegisterUnifiedServerInterceptors(intr ...grpcutil.UnifiedServerInterceptor)

RegisterUnifiedServerInterceptors registers given interceptors into both unary and stream interceptor chains.

It is just a convenience helper for UnifiedServerInterceptor's that usually need to be registered in both unary and stream interceptor chains. This method is equivalent to calling RegisterUnaryServerInterceptors and RegisterStreamServerInterceptors, passing corresponding flavors of interceptors to them.

Must be called before Serve (panics otherwise).

func (*Server) RegisterWarmup ¶

func (s *Server) RegisterWarmup(cb func(context.Context))

RegisterWarmup registers a callback that is run in server's Serve right before the serving loop.

It receives the global server context (including all customizations made by the user code in server.Main). Intended for best-effort warmups: there's no way to gracefully abort the server startup from a warmup callback.

Registering a new warmup callback from within a warmup causes a deadlock, don't do that.

func (*Server) RunInBackground ¶

func (s *Server) RunInBackground(activity string, f func(context.Context))

RunInBackground launches the given callback in a separate goroutine right before starting the serving loop.

If the server is already running, launches it right away. If the server fails to start, the goroutines will never be launched.

Should be used for background asynchronous activities like reloading configs.

All logs lines emitted by the callback are annotated with "activity" field which can be arbitrary, but by convention has format "<namespace>.<name>", where "luci" namespace is reserved for internal activities.

The context passed to the callback is canceled when the server is shutting down. It is expected the goroutine will exit soon after the context is canceled.

func (*Server) Serve ¶

func (s *Server) Serve() error

Serve launches the serving loop.

Blocks forever or until the server is stopped via Shutdown (from another goroutine or from a SIGTERM handler). Returns nil if the server was shutdown correctly or an error if it failed to start or unexpectedly died. The error is logged inside.

Should be called only once. Panics otherwise.

func (*Server) SetRPCAuthMethods ¶

func (s *Server) SetRPCAuthMethods(methods []auth.Method)

SetRPCAuthMethods overrides how the server authenticates incoming gRPC and pRPC requests.

It receives a list of auth.Method implementations which will be applied one after another to try to authenticate the request until the first successful hit. If all methods end up to be non-applicable (i.e. none of the methods notice any headers they recognize), the request will be passed through to the handler as anonymous (coming from an "anonymous identity"). Rejecting anonymous requests (if necessary) is the job of an authorization layer, often implemented as a gRPC interceptor. For simple cases use go.chromium.org/luci/server/auth/rpcacl interceptor.

By default (if SetRPCAuthMethods is never called) the server will check incoming requests have an `Authorization` header with a Google OAuth2 access token that has `https://www.googleapis.com/auth/userinfo.email` scope (see auth.GoogleOAuth2Method). Requests without `Authorization` header will be considered anonymous.

If OpenIDRPCAuthEnable option is set (matching `-open-id-rpc-auth-enable` flag), the service will recognize ID tokens as well. This is important for e.g. Cloud Run where this is the only authentication method supported natively by the platform. ID tokens are also generally faster to check than access tokens.

Note that this call completely overrides the previously configured list of methods instead of appending to it, since chaining auth methods is often tricky and it is safer to just always provide the whole list at once.

Passing an empty list of methods is allowed. All requests will be considered anonymous in that case.

Note that this call **doesn't affect** how plain HTTP requests (hitting the main HTTP port and routed through s.Router) are authenticated. Very often RPC requests and plain HTTP requests need different authentication methods and using an RPC authentication for everything is incorrect. To authenticate plain HTTP requests use auth.Authenticate(...) HTTP router middleware, perhaps in combination with s.CookieAuth (which is non-nil if there is a server module installed that provides a cookie-based authentication scheme).

Must be called before Serve (panics otherwise).

func (*Server) Shutdown ¶

func (s *Server) Shutdown()

Shutdown gracefully stops the server if it was running.

Blocks until the server is stopped. Can be called multiple times.

func (*Server) VirtualHost ¶

func (s *Server) VirtualHost(host string) *router.Router

VirtualHost returns a router (registering it if necessary) used for requests that hit the main port (opts.HTTPAddr) and have the given Host header.

Should be used in rare cases when the server is exposed through multiple domain names and requests should be routed differently based on what domain was used. If your server is serving only one domain name, or you don't care what domain name is used to access it, do not use VirtualHost.

Note that requests that match some registered virtual host router won't reach the default router (server.Routes), even if the virtual host router doesn't have a route for them. Such requests finish with HTTP 404.

Also the router created by VirtualHost is initially completely empty: the server and its modules don't install anything into it (there's intentionally no mechanism to do this). For that reason VirtualHost should never by used to register a router for the "main" domain name: it will make the default server.Routes (and all handlers installed there by server modules) useless, probably breaking the server. Put routes for the main server functionality directly into server.Routes instead, using VirtualHost only for routes that critically depend on Host header.

Must be called before Serve (panics otherwise).