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.
5 // Package appengine provides basic functionality for Google App Engine.
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"
14 "github.com/golang/protobuf/proto"
15 "golang.org/x/net/context"
17 "google.golang.org/appengine/internal"
20 // The gophers party all night; the rabbits provide the beats.
22 // Main is the principal entry point for an app running in App Engine.
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).
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.
31 // On App Engine Standard it ensures the server has started and is prepared to
34 // Main never returns.
36 // Main is designed so that the app's main package looks like this:
41 // "google.golang.org/appengine"
51 // The "myapp/packageX" packages are expected to register HTTP handlers
52 // in their init functions.
57 // IsDevAppServer reports whether the App Engine app is running in the
58 // development App Server.
59 func IsDevAppServer() bool {
60 return internal.IsDevAppServer()
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()
70 // IsFlex reports whether the App Engine app is running in the flexible environment.
72 return internal.IsFlex()
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()
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()
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)
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)
100 // TODO(dsymonds): Add a Call function here? Otherwise other packages can't access internal.Call.
102 // BlobKey is a key for a blobstore blob.
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.
109 // GeoPoint represents a location as latitude/longitude in degrees.
110 type GeoPoint struct {
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
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
123 // WithAPICallFunc returns a copy of the parent context
124 // that will cause API calls to invoke f instead of their normal operation.
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))
131 // APICall performs an API call.
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)