cron

Documentation

Overview

Package cron allows to register handlers called by Cloud Scheduler.

The HTTP endpoints exposed by this module perform necessary authorization checks and route requests to registered handlers, collecting monitoring metrics from them.

Note that you still need to configure Cloud Scheduler jobs (or cron.yaml when running on Appengine). By default registered handlers are exposed as "/internal/cron/<handler-id>" endpoints. This URL path should be used when configuring Cloud Scheduler jobs or in cron.yaml when running on Appengine.

Index

• Variables
• func NewModule(opts *ModuleOptions) module.Module
• func NewModuleFromFlags() module.Module
• func RegisterHandler(id string, h Handler)
• type Dispatcher
  • func (d *Dispatcher) InstallCronRoutes(r *router.Router, prefix string)
  • func (d *Dispatcher) RegisterHandler(id string, h Handler)
• type Handler
• type ModuleOptions
  • func (o *ModuleOptions) Register(f *flag.FlagSet)

Variables

var ModuleName = module.RegisterName("go.chromium.org/luci/server/cron")

ModuleName can be used to refer to this module when declaring dependencies.

Functions

func NewModule

func NewModule(opts *ModuleOptions) module.Module

NewModule returns a server module that sets up a cron dispatcher.

func NewModuleFromFlags

func NewModuleFromFlags() module.Module

NewModuleFromFlags is a variant of NewModule that initializes options through command line flags.

Calling this function registers flags in flag.CommandLine. They are usually parsed in server.Main(...).

func RegisterHandler

func RegisterHandler(id string, h Handler)

RegisterHandler is a shortcut for Default.RegisterHandler.

Types

type Dispatcher

type Dispatcher struct {
	// AuthorizedCallers is a list of service accounts Cloud Scheduler may use to
	// call cron HTTP endpoints.
	//
	// See https://cloud.google.com/scheduler/docs/http-target-auth for details.
	//
	// Can be empty on Appengine, since there calls are authenticated using
	// "X-Appengine-Cron" header.
	AuthorizedCallers []string

	// GAE is true when running on Appengine.
	//
	// It alters how incoming HTTP requests are authenticated.
	GAE bool

	// DisableAuth can be used to disable authentication on HTTP endpoints.
	//
	// This is useful when running in development mode on localhost or in tests.
	DisableAuth bool
	// contains filtered or unexported fields
}

Dispatcher routes requests from Cloud Scheduler to registered handlers.

var Default Dispatcher

Default is a dispatcher installed into the server when using NewModule or NewModuleFromFlags.

The module takes care of configuring this dispatcher based on the server environment and module's options.

You still need to register your handlers in it using RegisterHandler and configure Cloud Scheduler jobs (or cron.yaml when running on Appengine) to actually invoke them.

func (*Dispatcher) InstallCronRoutes

func (d *Dispatcher) InstallCronRoutes(r *router.Router, prefix string)

InstallCronRoutes installs routes that handle requests from Cloud Scheduler.

func (*Dispatcher) RegisterHandler

func (d *Dispatcher) RegisterHandler(id string, h Handler)

RegisterHandler registers a callback called to handle a cron job invocation.

The handler can be invoked via GET requests to "<serving-prefix>/<id>", (usually "/internal/cron/<id>"). This URL path should be used when configuring Cloud Scheduler jobs or in cron.yaml when running on Appengine.

The ID must match `[a-zA-Z0-9_\-.]{1,100}`. Panics otherwise. Panics if a handler with such ID is already registered.

type Handler

type Handler func(ctx context.Context) error

Handler is called to handle a cron job invocation.

Transient errors are transformed into HTTP 500 replies to Cloud Scheduler, which may trigger a retry based on the job's retry configuration. Returning a non-transient error results in a error-level logging message and HTTP 202 reply, which does not trigger a retry.

type ModuleOptions

type ModuleOptions struct {
	// Dispatcher is a dispatcher to use.
	//
	// Default is the global Default instance.
	Dispatcher *Dispatcher

	// ServingPrefix is a URL path prefix to serve registered cron handlers from.
	//
	// GETs to a URL under this prefix (regardless which one) will be treated
	// as Cloud Scheduler calls.
	//
	// Must start with "/internal/". Default is "/internal/cron".
	ServingPrefix string

	// AuthorizedCallers is a list of service accounts Cloud Scheduler may use to
	// call cron HTTP endpoints.
	//
	// See https://cloud.google.com/scheduler/docs/http-target-auth for details.
	//
	// Can be empty on Appengine, since there calls are authenticated using
	// "X-Appengine-Cron" header.
	//
	// Default is an empty list.
	AuthorizedCallers []string
}

ModuleOptions contain configuration of the cron server module.

It will be used to initialize Default dispatcher.

func (*ModuleOptions) Register

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

Register registers the command line flags.

Mutates `o` by populating defaults.