go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/appengine/gaemiddleware/doc.go (about)

     1  // Copyright 2015 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package gaemiddleware provides a standard middleware for first-gen Appengine
    16  // apps.
    17  //
    18  // The gaemiddleware package itself provides a generic Environment class and
    19  // common implementations of methods. An Environment matching your AppEngine
    20  // environment configuration (e.g., standard, flex) should be chosen from a
    21  // sub-package.
    22  //
    23  // Deprecated: many parts of this package don't work at all on the GAE
    24  // second-gen runtime. Instead use go.chromium.org/luci/server in combination
    25  // with go.chromium.org/luci/server/gaeemulation module to get Cloud Datastore
    26  // support.
    27  //
    28  // This middleware configures the request environment to use GAE-based services
    29  // (like datastore via luci/gae package, logging and many more).
    30  //
    31  // For full functionality, the "default" module of a GAE application must be
    32  // running on an AppEngine Standard instance, and must have handlers installed
    33  // (via "standard.InstallHandlers").
    34  //
    35  // The minimal usage example (from GAE standard):
    36  //
    37  //	import (
    38  //	  ...
    39  //
    40  //	  "go.chromium.org/luci/appengine/gaemiddleware/standard"
    41  //	  "go.chromium.org/luci/common/logging"
    42  //	  "go.chromium.org/luci/server/router"
    43  //	)
    44  //
    45  //	func init() {
    46  //	  r := router.New()
    47  //	  standard.InstallHandlers(r)
    48  //
    49  //	  r.GET("/", standard.Base(), indexPage)
    50  //
    51  //	  http.DefaultServeMux.Handle("/", r)
    52  //	}
    53  //
    54  //	func indexPage(c *router.Context) {
    55  //	  logging.Infof(c.Context, "Handling the page")
    56  //	  ...
    57  //	}
    58  //
    59  // It registers various routes required for LUCI framework functionality in the
    60  // router, and sets up an application route (indexPage) configured to use GAE
    61  // services.
    62  //
    63  // # Handlers setup
    64  //
    65  // Some default registered routes are intended for use only by administrators or
    66  // internally by GAE itself (crons, task queues). While LUCI framework does
    67  // authorization checks itself, it is still recommended that you protect such
    68  // routes on app.yaml level with "login: admin" check, to make GAE reject
    69  // unauthorized access earlier.
    70  //
    71  // In contrast, the rest of the routes (end-user facing HTML pages, API
    72  // handlers) usually use LUCI's authentication framework (to support OAuth2
    73  // tokens, among other things), and for that reason they must not use
    74  // "login: required" or "login: admin", since in that case GAE will enable its
    75  // own cookie-based authentication mechanism (that doesn't work with OAuth2).
    76  //
    77  // Thus the recommended handlers list is:
    78  //
    79  //	handlers:
    80  //	- url: /(internal|admin)/.*
    81  //	  script: _go_app
    82  //	  secure: always
    83  //	  login: admin
    84  //
    85  //	- url: /.*
    86  //	  script: _go_app
    87  //	  secure: always
    88  //
    89  // See https://cloud.google.com/appengine/docs/standard/go/config/appref for
    90  // more info about app.yaml.
    91  //
    92  // # Cron setup
    93  //
    94  // Some of the default LUCI services installed in BaseProd require cron jobs
    95  // for their operation.
    96  //
    97  // InstallHandlers call registers the cron handlers in the HTTP router, but GAE
    98  // still has to be instructed to actually call them.
    99  //
   100  // This can done by adding following jobs to cron.yaml file of your project:
   101  //
   102  //   - description: "tsmon housekeeping task"
   103  //     url: /internal/cron/ts_mon/housekeeping
   104  //     schedule: every 1 minutes
   105  //
   106  // See https://cloud.google.com/appengine/docs/standard/go/config/cronref for
   107  // more information about cron.yaml.
   108  package gaemiddleware