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

    Constants

    This section is empty.

    Variables

    View Source
    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.