Documentation

Overview

Package module defines a framework for extending server.Server with optional reusable bundles of functionality (called "modules", naturally).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Host

type Host interface {
	// Routes returns a router that servers HTTP requests hitting the main port.
	//
	// The module can use it to register additional request handlers.
	//
	// Note that users of server.Server can register more routers through
	// server.AddPort(...) and server.VirtualHost(...). Such application-specific
	// routers are not accessible to modules.
	Routes() *router.Router

	// RunInBackground launches the given callback in a separate goroutine right
	// before starting the serving loop.
	//
	// 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 derived from the global server
	// context and it is canceled when the server is shutting down. It is expected
	// the goroutine will exit soon after the context is canceled.
	RunInBackground(activity string, f func(context.Context))

	// RegisterCleanup registers a callback that is run in server's ListenAndServe
	// after the server exits the serving loop.
	//
	// It receives the global server context.
	RegisterCleanup(cb func(context.Context))

	// RegisterUnaryServerInterceptor registers an grpc.UnaryServerInterceptor
	// applied to all unary RPCs that hit the server.
	//
	// Interceptors are chained in order they are registered, which matches
	// the order of modules in the list of modules. The first registered
	// interceptor becomes the outermost.
	RegisterUnaryServerInterceptor(intr grpc.UnaryServerInterceptor)
}

Host is part of server.Server API that modules are allowed to use during their initialization to inject useful functionality into the server.

TODO(vadimsh):

* Allow adding a middleware to the default middleware chain.
* Allow registering pRPC servers.

type HostOptions

type HostOptions struct {
	Prod         bool   // set when running in production (not on a dev workstation)
	GAE          bool   // set when running on Appengine, implies Prod
	CloudProject string // name of hosting Google Cloud Project if running in GCP
	CloudRegion  string // name of a hosting region (e.g. 'us-central1') if known
}

HostOptions are options the server was started with.

It is a subset of global server.Options that modules are allowed to use to tweak their behavior.

type Module

type Module interface {
	// Name is a name of this module for logs and internal maps.
	//
	// Usually it is a full name of the go package that implements the module, but
	// it can be arbitrary as long as it is unique within a server. Attempting to
	// register two identically named modules results in a fatal error during
	// the server startup.
	Name() string

	// Initialize is called during the server startup after the core functionality
	// is initialized, but before the server enters the serving loop.
	//
	// The method receives the global server context and can return a derived
	// context which will become the new global server context. That way the
	// module may inject additional state into the context inherited by all
	// requests. If it returns nil, the server context won't be changed.
	//
	// The module may use the context (with all values available there) and the
	// given Host interface to register itself in various server systems. It must
	// not retain 'host': the object it points to becomes invalid after Initialize
	// finishes and using it causes panics. This is intentional.
	//
	// Modules are initialized sequentially in order they are registered. A module
	// observes effects of initialization of all prior modules, e.g. via
	// context.Context.
	//
	// An error causes the process to crash with the corresponding message.
	Initialize(ctx context.Context, host Host, opts HostOptions) (context.Context, error)
}

Module represents some optional part of a server.

It is generally a stateful object constructed from some configuration. It can be hooked to the server in server.New(...) or server.Main(...).

Source Files