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 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// NewContext returns a context for an in-flight HTTP request. 64// This function is cheap. 65func 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. 72func 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. 83type BlobKey string 84 85// GeoPoint represents a location as latitude/longitude in degrees. 86type GeoPoint struct { 87 Lat, Lng float64 88} 89 90// Valid returns whether a GeoPoint is within [-90, 90] latitude and [-180, 180] longitude. 91func (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. 97type 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. 103func 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. 111func APICall(ctx context.Context, service, method string, in, out proto.Message) error { 112 return internal.Call(ctx, service, method, in, out) 113} 114