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/ 9package appengine // import "google.golang.org/appengine" 10 11import ( 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. 53func Main() { 54 internal.Main() 55} 56 57// IsDevAppServer reports whether the App Engine app is running in the 58// development App Server. 59func 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). 66func IsStandard() bool { 67 return internal.IsStandard() 68} 69 70// IsFlex reports whether the App Engine app is running in the flexible environment. 71func 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. 77func 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). 83func IsSecondGen() bool { 84 return internal.IsSecondGen() 85} 86 87// NewContext returns a context for an in-flight HTTP request. 88// This function is cheap. 89func 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. 96func WithContext(parent context.Context, req *http.Request) context.Context { 97 return internal.WithContext(parent, req) 98} 99 100// BlobKey is a key for a blobstore blob. 101// 102// Conceptually, this type belongs in the blobstore package, but it lives in 103// the appengine package to avoid a circular dependency: blobstore depends on 104// datastore, and datastore needs to refer to the BlobKey type. 105type BlobKey string 106 107// GeoPoint represents a location as latitude/longitude in degrees. 108type GeoPoint struct { 109 Lat, Lng float64 110} 111 112// Valid returns whether a GeoPoint is within [-90, 90] latitude and [-180, 180] longitude. 113func (g GeoPoint) Valid() bool { 114 return -90 <= g.Lat && g.Lat <= 90 && -180 <= g.Lng && g.Lng <= 180 115} 116 117// APICallFunc defines a function type for handling an API call. 118// See WithCallOverride. 119type APICallFunc func(ctx context.Context, service, method string, in, out proto.Message) error 120 121// WithAPICallFunc returns a copy of the parent context 122// that will cause API calls to invoke f instead of their normal operation. 123// 124// This is intended for advanced users only. 125func WithAPICallFunc(ctx context.Context, f APICallFunc) context.Context { 126 return internal.WithCallOverride(ctx, internal.CallOverrideFunc(f)) 127} 128 129// APICall performs an API call. 130// 131// This is not intended for general use; it is exported for use in conjunction 132// with WithAPICallFunc. 133func APICall(ctx context.Context, service, method string, in, out proto.Message) error { 134 return internal.Call(ctx, service, method, in, out) 135} 136