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 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 // NewContext returns a context for an in-flight HTTP request. 64 // This function is cheap. 65 func NewContext(req *http.Request) context.Context { 66 return internal.ReqContext(req) 67 } 68 69 // WithContext returns a copy of the parent context 70 // and associates it with an in-flight HTTP request. 71 // This function is cheap. 72 func WithContext(parent context.Context, req *http.Request) context.Context { 73 return internal.WithContext(parent, req) 74 } 75 76 // TODO(dsymonds): Add a Call function here? Otherwise other packages can't access internal.Call. 77 78 // BlobKey is a key for a blobstore blob. 79 // 80 // Conceptually, this type belongs in the blobstore package, but it lives in 81 // the appengine package to avoid a circular dependency: blobstore depends on 82 // datastore, and datastore needs to refer to the BlobKey type. 83 type BlobKey string 84 85 // GeoPoint represents a location as latitude/longitude in degrees. 86 type GeoPoint struct { 87 Lat, Lng float64 88 } 89 90 // Valid returns whether a GeoPoint is within [-90, 90] latitude and [-180, 180] longitude. 91 func (g GeoPoint) Valid() bool { 92 return -90 <= g.Lat && g.Lat <= 90 && -180 <= g.Lng && g.Lng <= 180 93 } 94 95 // APICallFunc defines a function type for handling an API call. 96 // See WithCallOverride. 97 type APICallFunc func(ctx context.Context, service, method string, in, out proto.Message) error 98 99 // WithAPICallFunc returns a copy of the parent context 100 // that will cause API calls to invoke f instead of their normal operation. 101 // 102 // This is intended for advanced users only. 103 func WithAPICallFunc(ctx context.Context, f APICallFunc) context.Context { 104 return internal.WithCallOverride(ctx, internal.CallOverrideFunc(f)) 105 } 106 107 // APICall performs an API call. 108 // 109 // This is not intended for general use; it is exported for use in conjunction 110 // with WithAPICallFunc. 111 func APICall(ctx context.Context, service, method string, in, out proto.Message) error { 112 return internal.Call(ctx, service, method, in, out) 113 } 114