server

Documentation

Overview

Package server implements an environment for running LUCI servers.

Index

• Variables
• type Options
  • func (o *Options) Register(f *flag.FlagSet)
• type Server
  • func New(opts Options) *Server
  • func (s *Server) Fatal(err error)
  • func (s *Server) ListenAndServe() error
  • func (s *Server) RegisterHTTP(addr string) *router.Router
  • func (s *Server) RunInBackground(activity string, f func(context.Context))
  • func (s *Server) Shutdown()

Variables

var DefaultOAuthScopes = []string{
	"https://www.googleapis.com/auth/cloud-platform",
	"https://www.googleapis.com/auth/userinfo.email",
}

DefaultOAuthScopes is a list of OAuth scopes we want a local user to grant us when running the server locally.

Types

type Options

type Options struct {
	Prod             bool               // must be set when running in production
	HTTPAddr         string             // address to bind the main listening socket to
	AdminAddr        string             // address to bind the admin socket to
	RootSecretPath   string             // path to a JSON file with the root secret key
	SettingsPath     string             // path to a JSON file with app settings
	ClientAuth       clientauth.Options // base settings for client auth options
	TokenCacheDir    string             // where to cache auth tokens (optional)
	AuthDBPath       string             // if set, load AuthDB from a file
	CloudProject     string             // name of hosting Google Cloud Project
	TsMonAccount     string             // service account to flush metrics as
	TsMonServiceName string             // service name of tsmon target
	TsMonJobName     string             // job name of tsmon target
	// contains filtered or unexported fields
}

Options are exposed as command line flags.

func (*Options) Register

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

Register registers the command line flags.

type Server

type Server struct {
	Routes *router.Router // HTTP routes exposed via opts.HTTPAddr
	// contains filtered or unexported fields
}

Server is responsible for initializing and launching the serving environment.

Doesn't do TLS. Should be sitting behind a load balancer that terminates TLS.

func New

func New(opts Options) *Server

New constructs a new server instance.

It hosts one or more HTTP servers and starts and stops them in unison. It is also responsible for preparing contexts for incoming requests.

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) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe 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) RegisterHTTP

func (s *Server) RegisterHTTP(addr string) *router.Router

RegisterHTTP prepares an additional HTTP server.

Can be used to open more listening HTTP ports (in addition to opts.HTTPAddr and opts.AdminAddr). Returns a router that should be populated with routes exposed through the added server.

Should be called before ListenAndServe (panics otherwise).

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 callback receives a context with following services available:

• go.chromium.org/luci/common/logging: Logging.
• go.chromium.org/luci/server/caching: Process cache.
• go.chromium.org/luci/server/secrets: Secrets.
• go.chromium.org/luci/server/settings: Access to app settings.
• go.chromium.org/luci/server/auth: Making authenticated calls.

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) 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.