gaemiddleware

Documentation

Overview

Package gaemiddleware provides a standard middleware for Appengine apps.

This middleware configures the request environment to use GAE-based services (like datastore via luci/gae package, logging and many more).

The minimal usage example (from GAE standard):

import (
  ...

  "github.com/luci/luci-go/appengine/gaemiddleware"
  "github.com/luci/luci-go/common/logging"
  "github.com/luci/luci-go/server/router"
)

func init() {
  r := router.New()
  gaemiddleware.InstallHandlers(r)

  r.GET("/", gaemiddleware.BaseProd(), indexPage)

  http.DefaultServeMux.Handle("/", r)
}

func indexPage(c *router.Context) {
  logging.Infof(c.Context, "Handling the page")
  ...
}

It registers various routes required for LUCI framework functionality in the router, and sets up an application route (indexPage) configured to use GAE services.

Handlers setup

Some default registered routes are intended for use only by administrators or internally by GAE itself (crons, task queues). While LUCI framework does authorization checks itself, it is still recommended that you protect such routes on app.yaml level with "login: admin" check, to make GAE reject unauthorized access earlier.

In contrast, the rest of the routes (end-user facing HTML pages, API handlers) usually use LUCI's authentication framework (to support OAuth2 tokens, among other things), and for that reason they must not use "login: required" or "login: admin", since in that case GAE will enable its own cookie-based authentication mechanism (that doesn't work with OAuth2).

Thus the recommended handlers list is:

handlers:
- url: /(internal|admin)/.*
  script: _go_app
  secure: always
  login: admin

- url: /.*
  script: _go_app
  secure: always

See https://cloud.google.com/appengine/docs/standard/go/config/appref for more info about app.yaml.

Cron setup

Some of the default LUCI services installed in BaseProd require cron jobs for their operation.

InstallHandlers call registers the cron handlers in the HTTP router, but GAE still has to be instructed to actually call them.

This can done by adding following jobs to cron.yaml file of your project:

• description: "tsmon housekeeping task" url: /internal/cron/ts_mon/housekeeping schedule: every 1 minutes

• description: "LUCI Config datastore cache periodic refresh" url: /admin/config/cache/manager schedule: every 10 mins

See https://cloud.google.com/appengine/docs/standard/go/config/cronref for more information about cron.yaml.

Index

• Constants
• func BaseProd() router.MiddlewareChain
• func InstallHandlers(r *router.Router)
• func InstallHandlersWithMiddleware(r *router.Router, base router.MiddlewareChain)
• func RequireCron(c *router.Context, next router.Handler)
• func RequireTaskQueue(queue string) router.Middleware
• func WithProd(c context.Context, req *http.Request) context.Context

Constants

const Version = "1.0.0"

Version is a semantic version of base luci-go GAE library.

It is bumped whenever we add new features or fix important bugs. It is reported to monitoring as 'luci/components/version' string metric with 'component' field set to 'github.com/luci/luci-go/appengine/gaemiddleware'.

It allows to track what GAE apps use what version of the library, so it's easier to detect stale code running in production.

Functions

func BaseProd

func BaseProd() router.MiddlewareChain

BaseProd returns a middleware chain to use for all GAE requests.

This middleware chain installs prod GAE services into the request context (via WithProd), and wraps the request with a panic catcher and monitoring hooks.

func InstallHandlers

func InstallHandlers(r *router.Router)

InstallHandlers installs handlers for framework routes.

These routes are needed for various services provided in BaseProd context to work:

• Authentication related routes
• Settings pages
• Various housekeeping crons
• Warmup

They must be installed into a default module, but it is also safe to install them into a non-default module. This may be handy if you want to move cron handlers into a non-default module.

func InstallHandlersWithMiddleware

func InstallHandlersWithMiddleware(r *router.Router, base router.MiddlewareChain)

InstallHandlersWithMiddleware installs handlers for framework routes.

It is same as 'InstallHandlers', but allows caller to customize the middleware chain used for the routes. This may be needed if application callbacks invoked through the default routes (settings pages, monitoring callbacks) need some additional state in the context.

'base' is expected to be BaseProd() or its derivative. It must NOT do any interception of requests (e.g. checking and rejecting unauthenticated requests).

func RequireCron

func RequireCron(c *router.Context, next router.Handler)

RequireCron ensures that the request is from the appengine 'cron' service.

It checks the presence of a magical header that can be set only by GAE. If the header is not there, it aborts the request with StatusForbidden.

This middleware has no effect when using 'BaseTest' or when running under dev_appserver.py

func RequireTaskQueue

func RequireTaskQueue(queue string) router.Middleware

RequireTaskQueue ensures that the request is from the specified task queue.

It checks the presence of a magical header that can be set only by GAE. If the header is not there, it aborts the request with StatusForbidden.

if 'queue' is the empty string, than this simply checks that this handler was run from ANY appengine taskqueue.

This middleware has no effect when using 'BaseTest' or when running under dev_appserver.py

func WithProd

func WithProd(c context.Context, req *http.Request) context.Context

WithProd adds various production GAE LUCI services to the context.

Basically, it installs GAE-specific backends and caches for various subsystems to make them work in GAE environment.

One example is a backend for Logging: github.com/luci/luci-go/common/logging. Logs emitted through a WithProd() context go to GAE logs.

'Production' here means the services will use real GAE APIs (not mocks or stubs), so WithProd should never be used from unit tests.