luci-go: github.com/luci/luci-go/server Index | Files | Directories

package server

import "github.com/luci/luci-go/server"

Package server implements an environment for running LUCI servers.

It interprets command line flags and initializes the serving environment with following services available via context.Context:

* go.chromium.org/luci/common/logging: Logging.
* go.chromium.org/luci/common/trace: Tracing.
* go.chromium.org/luci/server/caching: Process cache.
* go.chromium.org/luci/server/secrets: Secrets (optional).
* go.chromium.org/luci/server/settings: Access to app settings (optional).
* go.chromium.org/luci/server/auth: Making authenticated calls.
* go.chromium.org/luci/server/redisconn: Redis connection pool (optional).
* go.chromium.org/gae: Datastore (optional).

Usage example:

func main() {
  server.Main(nil, func(srv *server.Server) error {
    // Initialize global state, change root context.
    if err := initializeGlobalStuff(srv.Context); err != nil {
      return err
    }
    srv.Context = injectGlobalStuff(srv.Context)

    // Install regular HTTP routes.
    srv.Routes.GET("/", router.MiddlewareChain{}, func(c *router.Context) {
      // ...
    })

    // Install pRPC services.
    servicepb.RegisterSomeServer(srv.PRPC, &SomeServer{})
    return nil
  })
}

Index

Package Files

server.go

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.

func Main Uses

func Main(opts *Options, init func(srv *Server) error)

Main initializes the server and runs its serving loop until SIGTERM.

Registers all options in the default flag set and uses `flag.Parse` to parse them. If 'opts' is nil, the default options will be used.

On errors, logs them and aborts the process with non-zero exit code.

type Options Uses

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
    AuthServiceHost  string             // hostname of an Auth Service to use
    AuthDBDump       string             // Google Storage path to fetch AuthDB dumps from
    AuthDBSigner     string             // service account that signs AuthDB dumps
    RedisAddr        string             // Redis server to connect to as "host:port" (optional)
    RedisDB          int                // index of a logical Redis DB to use by default (optional)
    CloudProject     string             // name of hosting Google Cloud Project
    TraceSampling    string             // what portion of traces to upload to StackDriver
    TsMonAccount     string             // service account to flush metrics as
    TsMonServiceName string             // service name of tsmon target
    TsMonJobName     string             // job name of tsmon target
    ContainerImageID string             // ID of the container image with this binary, for logs (optional)
    // contains filtered or unexported fields
}

Options are exposed as command line flags.

func (*Options) Register Uses

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

Register registers the command line flags.

type Server Uses

type Server struct {
    // Context is the root context used by all requests and background activities.
    //
    // Can be replaced (by a derived context) before ListenAndServe call, for
    // example to inject values accessible to all request handlers.
    Context context.Context

    // Routes is HTTP routes exposed via HTTPAddr port.
    //
    // Should be populated before ListenAndServe call.
    Routes *router.Router

    // PRPC is pRPC service with APIs exposed via HTTPAddr port.
    //
    // Should be populated before ListenAndServe call.
    PRPC *prpc.Server

    // Options is a copy of options passed to New.
    Options Options
    // contains filtered or unexported fields
}

Server is responsible for initializing and launching the serving environment.

Generally assumed to be a singleton: do not launch multiple Server instances within the same process, use RegisterHTTP instead if you want to expose multiple ports.

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

func New Uses

func New(opts Options) (srv *Server, err error)

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.

On errors returns partially initialized server (always non-nil). At least its logging will be configured and can be used to report the error. Trying to use such partially initialized server for anything else is undefined behavior.

func (*Server) Fatal Uses

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 Uses

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) RegisterCleanup Uses

func (s *Server) RegisterCleanup(cb func())

RegisterCleanup registers a callback that is run in ListenAndServe 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) RegisterHTTP Uses

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 Uses

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) Shutdown Uses

func (s *Server) Shutdown()

Shutdown gracefully stops the server if it was running.

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

Directories

PathSynopsis
analyticsPackage analytics provides a standard way to store the Google Analytics tracking ID.
authPackage auth implements authentication and authorization framework for HTTP servers.
auth/authdbPackage authdb contains definition of Authentication Database (aka AuthDB).
auth/authdb/dumpPackage dump implements loading AuthDB from dumps in Google Storage.
auth/authtestPackage authtest implements some interfaces used by auth package to simplify unit testing.
auth/delegationPackage delegation contains low-level API for working with delegation tokens.
auth/delegation/messages
auth/internal
auth/openidPackage openid implements OpenID Connect Login protocol (client side).
auth/servicePackage service implements a wrapper around API exposed by auth_service: https://github.com/luci/luci-py/tree/master/appengine/auth_service
auth/service/protocol
auth/signingPackage signing provides interfaces to sign arbitrary small blobs with RSA-SHA256 signature (PKCS1v15) and verify such signatures.
auth/signing/signingtestPackage signingtest implements signing.Signer interface using small random keys.
auth/xsrfPackage xsrf provides Cross Site Request Forgery prevention middleware.
cachingPackage caching implements common server object caches.
caching/cachingtestPackage cachingtest contains helpers for testing code that uses caching package.
caching/layeredPackage layered provides a two-layer cache for serializable objects.
internalPackage internal is supporting code used by server.go.
middlewarePackage middleware defines base type for context-aware HTTP request handler.
portalPackage portal implements HTTP routes for portal pages.
pprofPackage pprof is similar to net/http/pprof, except it supports auth.
pprof/internal
redisconnPackage redisconn is a facade for Redis connection pool.
routerPackage router provides an HTTP router with support for middleware and subrouters.
secretsPackage secrets provides an interface for a simple secret store: you ask it for a secret (a byte blob, identifies by some key), and it returns it to you (current version, as well as a bunch of previous versions).
secrets/testsecretsPackage testsecrets provides a dumb in-memory secret store to use in unit tests.
settingsPackage settings implements storage for infrequently changing global settings.
templatesPackage templates implements wrapper around html/template to provide lazy loading of templates and better integration with HTTP middleware framework.
tokensPackage tokens provides means to generate and validate base64 encoded tokens compatible with luci-py's components.auth implementation.
tsmonPackage tsmon adapts common/tsmon library to a server-side environment.
warmupPackage warmup allows to register hooks executed during the server warmup.

Package server imports 56 packages (graph). Updated 2019-12-11. Refresh now. Tools for package owners.