vendor/google.golang.org/appengine/appengine.go

   1 // Copyright 2011 Google Inc. All rights reserved.
   2 // Use of this source code is governed by the Apache 2.0
   3 // license that can be found in the LICENSE file.
   4
   5 // Package appengine provides basic functionality for Google App Engine.
   6 //
   7 // For more information on how to write Go apps for Google App Engine, see:
   8 // https://cloud.google.com/appengine/docs/go/
   9 package appengine // import "google.golang.org/appengine"
  10
  11 import (
  12         "net/http"
  13
  14         "github.com/golang/protobuf/proto"
  15         "golang.org/x/net/context"
  16
  17         "google.golang.org/appengine/internal"
  18 )
  19
  20 // The gophers party all night; the rabbits provide the beats.
  21
  22 // Main is the principal entry point for an app running in App Engine.
  23 //
  24 // On App Engine Flexible it installs a trivial health checker if one isn't
  25 // already registered, and starts listening on port 8080 (overridden by the
  26 // $PORT environment variable).
  27 //
  28 // See https://cloud.google.com/appengine/docs/flexible/custom-runtimes#health_check_requests
  29 // for details on how to do your own health checking.
  30 //
  31 // On App Engine Standard it ensures the server has started and is prepared to
  32 // receive requests.
  33 //
  34 // Main never returns.
  35 //
  36 // Main is designed so that the app's main package looks like this:
  37 //
  38 //      package main
  39 //
  40 //      import (
  41 //              "google.golang.org/appengine"
  42 //
  43 //              _ "myapp/package0"
  44 //              _ "myapp/package1"
  45 //      )
  46 //
  47 //      func main() {
  48 //              appengine.Main()
  49 //      }
  50 //
  51 // The "myapp/packageX" packages are expected to register HTTP handlers
  52 // in their init functions.
  53 func Main() {
  54         internal.Main()
  55 }
  56
  57 // IsDevAppServer reports whether the App Engine app is running in the
  58 // development App Server.
  59 func IsDevAppServer() bool {
  60         return internal.IsDevAppServer()
  61 }
  62
  63 // IsStandard reports whether the App Engine app is running in the standard
  64 // environment. This includes both the first generation runtimes (<= Go 1.9)
  65 // and the second generation runtimes (>= Go 1.11).
  66 func IsStandard() bool {
  67         return internal.IsStandard()
  68 }
  69
  70 // IsFlex reports whether the App Engine app is running in the flexible environment.
  71 func IsFlex() bool {
  72         return internal.IsFlex()
  73 }
  74
  75 // IsAppEngine reports whether the App Engine app is running on App Engine, in either
  76 // the standard or flexible environment.
  77 func IsAppEngine() bool {
  78         return internal.IsAppEngine()
  79 }
  80
  81 // IsSecondGen reports whether the App Engine app is running on the second generation
  82 // runtimes (>= Go 1.11).
  83 func IsSecondGen() bool {
  84         return internal.IsSecondGen()
  85 }
  86
  87 // NewContext returns a context for an in-flight HTTP request.
  88 // This function is cheap.
  89 func NewContext(req *http.Request) context.Context {
  90         return internal.ReqContext(req)
  91 }
  92
  93 // WithContext returns a copy of the parent context
  94 // and associates it with an in-flight HTTP request.
  95 // This function is cheap.
  96 func WithContext(parent context.Context, req *http.Request) context.Context {
  97         return internal.WithContext(parent, req)
  98 }
  99
 100 // TODO(dsymonds): Add a Call function here? Otherwise other packages can't access internal.Call.
 101
 102 // BlobKey is a key for a blobstore blob.
 103 //
 104 // Conceptually, this type belongs in the blobstore package, but it lives in
 105 // the appengine package to avoid a circular dependency: blobstore depends on
 106 // datastore, and datastore needs to refer to the BlobKey type.
 107 type BlobKey string
 108
 109 // GeoPoint represents a location as latitude/longitude in degrees.
 110 type GeoPoint struct {
 111         Lat, Lng float64
 112 }
 113
 114 // Valid returns whether a GeoPoint is within [-90, 90] latitude and [-180, 180] longitude.
 115 func (g GeoPoint) Valid() bool {
 116         return -90 <= g.Lat && g.Lat <= 90 && -180 <= g.Lng && g.Lng <= 180
 117 }
 118
 119 // APICallFunc defines a function type for handling an API call.
 120 // See WithCallOverride.
 121 type APICallFunc func(ctx context.Context, service, method string, in, out proto.Message) error
 122
 123 // WithAPICallFunc returns a copy of the parent context
 124 // that will cause API calls to invoke f instead of their normal operation.
 125 //
 126 // This is intended for advanced users only.
 127 func WithAPICallFunc(ctx context.Context, f APICallFunc) context.Context {
 128         return internal.WithCallOverride(ctx, internal.CallOverrideFunc(f))
 129 }
 130
 131 // APICall performs an API call.
 132 //
 133 // This is not intended for general use; it is exported for use in conjunction
 134 // with WithAPICallFunc.
 135 func APICall(ctx context.Context, service, method string, in, out proto.Message) error {
 136         return internal.Call(ctx, service, method, in, out)
 137 }