How Requests are Handled

Requests and domains

App Engine determines that an incoming request is intended for your application
using the domain name of the request. A request whose domain name is
http://your_app_id.appspot.com is routed to the application whose ID is
your_app_id. Every application gets an appspot.com domain name for free.

appspot.com domains also support subdomains of the form subdomain-dot-
your_app_id.appspot.com, where subdomain can be any string allowed in one
part of a domain name (not .). Requests sent to any subdomain in this way are
routed to your application.

You can set up a custom top-level domain using the Google Cloud Platform Console
custom domains page. You can assign
subdomains of your business's domain to various applications, such as Google
Mail or Sites. You can also associate an App Engine application with a
subdomain. You can set up a custom domain after you create a new project. See
Using Custom Domains and
SSL
for more information.

Requests for these URLs all go to the versions of your application that you have
configured to receive
traffic. Each version
of your application also has its own URL, so you can deploy and test a new
version before configuring traffic to the version. The version-specific URL uses
the version identifier from your app's configuration file in addition to the
appspot.com domain name, in this pattern:
http://[VERSION_ID]-dot-latest-dot-[PROJECT_ID].appspot.com You can also use
subdomains with the version-specific URL:
http://[SUBDOMAIN]-dot-[VERSION_ID]-dot-latest-dot-[PROJECT_ID].appspot.com

Warning: When writing Python code to get the application ID, you must use the
get_application_id()
method instead of the environment variable. App Engine might prefix a
string to the application ID in the environment variable such as dev~ in the
development web server and s~ in production. Functions that rely on the
application ID set in app.yaml will fail if called with the application ID
from the environment variable.

The domain name used for the request is included in the request data passed to
the application. If you want your app to respond differently depending on the
domain name used to access it (such as to restrict access to certain domains, or
redirect to an official domain), you can check the request data, such as the
Host request header, for the domain from within the application code and
respond accordingly.

If your app uses services,
you can address requests to a specific service and optionally a specific version
of that service. For more information about service addressability, see
How Requests are
Routed.

Note: Google recommends
using the HTTPS protocol to send requests to your app. Google does not issue SSL
certificates for double-wildcard domains hosted at appspot.com. Therefore with HTTPS
you must use the string "-dot-" instead of "." to separate subdomains, as shown in the examples
below. You can use a simple "." with your own custom domain or with HTTP addresses.

Request handlers

When App Engine receives a web request for your application, it
calls the handler script
that corresponds to the URL, as described in the application's
app.yaml configuration
file
.
The Python 2.7 runtime supports the WSGI
standard and the CGI
standard for
backwards compatibility. WSGI is preferred, and some features of Python 2.7 do
not work without it. The configuration of your application's script
handlers
determines whether a request is handled using WSGI or CGI.

App Engine runs multiple instances of your application, each instance has
its own web server for handling requests. Any request can be routed to any
instance, so consecutive requests from the same user are not necessarily sent
to the same instance. The number of instances can be adjusted automatically as
traffic changes.

If you mark your application as thread-safe, concurrent requests will be
enabled, which means that App Engine can dispatch multiple requests to each web
server in parallel. To do so, set
threadsafe: true
in app.yaml. Concurrent requests are not available if any script handler uses
CGI.

Requests and WSGI

The server determines which Python application object to call by comparing the
URL of the request to the URL patterns in the app's configuration file. It then
calls the application object using the arguments as defined in the
WSGI standard. The application object performs actions
appropriate to the request, then prepares a response and returns it as a list of
strings.

Most applications use a framework, such as
webapp2, to handle WSGI requests.
webapp2 is included as part of the Python 2.7 runtime.

Requests and CGI

Warning: CGI is included for backwards compatibility and its use is discouraged.
Use WSGI if possible.

The server determines which Python handler script to run by comparing the URL of
the request to the URL patterns in the app's configuration file. It then runs
the script in a environment populated with the request data. As described in
the CGI standard, the server puts the request data in
environment variables and the standard input stream. The script performs actions
appropriate to the request, then prepares a response and puts it on the standard
output stream.

Most applications use a library to parse CGI requests and return CGI responses,
such as the cgi module
from the Python standard library, or a web framework that knows the CGI protocol
(such as webapp). You can refer
to the CGI documentation for details about the environment variables and the
format of the input stream data.

Request headers

An incoming HTTP request includes the HTTP headers sent by the client. For
security purposes, some headers are sanitized or amended by intermediate proxies
before they reach the application.

The following headers are removed from the request:

Accept-Encoding

Connection

Keep-Alive

Proxy-Authorization

TE

Trailer

Transfer-Encoding

In addition, the header Strict-Transport-Security is removed from requests
served to any domains other than appspot.com or *.appspot.com.

These headers relate to the transfer of the HTTP data between the client and
server, and are transparent to the application. For example, the server may
automatically send a gzipped response, depending on the value of the Accept-
Encoding request header. The application itself does not need to know which
content encodings the client can accept.

Note: Entity headers (headers relating to the request body) are not sanitized or
checked, so applications should not rely on them. In particular, the Content-
MD5 request header is sent unmodified to the application, so may not match the
MD5 hash of the content. Also, the Content-Encoding request header is not
checked by the server, so if the client sends a gzipped request body, it will be
sent in compressed form to the application.

App Engine specific headers

As a service to the app, App Engine adds the following headers to all requests:

X-AppEngine-Country

Country from which the request originated, as an ISO 3166-1
alpha-2 country code. App
Engine determines this code from the client's IP address. Note that the country
information is not derived from the WHOIS database; it's possible that an IP
address with country information in the WHOIS database will not have country
information in the X-AppEngine-Country header. Your application should handle
the special country code ZZ (unknown country).

X-AppEngine-Region

Name of region from which the request originated. This value only makes
sense in the context of the country in X -AppEngine-Country. For example, if
the country is "US" and the region is "ca", that "ca" means "California", not
Canada. The complete list of valid region values is found in the
ISO-3166-2 standard.

X-AppEngine-City

Name of the city from which the request originated. For example, a request
from the city of Mountain View might have the header value mountain view.
There is no canonical list of valid values for this header.

X-AppEngine-CityLatLong

Latitude and longitude of the city from which the request originated. This
string might look like "37.386051,-122.083851" for a request from Mountain View.

Responses

App Engine calls the handler script with a Request and waits for the script to
return; all data written to the standard output stream is sent as the HTTP
response.

As explained below, there are limits that apply to the response you generate,
and the response may be modified before it is returned to the client.

Note: This HTTP header documentation only applies to responses to inbound HTTP
requests. For HTTP headers related to outbound requests originated by your App
Engine code, see the header documentation for
URLFetch.

Response size limits

Dynamic responses are limited to 32MB. If a script handler generates a response
larger than this limit, the server sends back an empty response with a 500
Internal Server Error status code. This limitation does not apply to responses
that serve data from
the Blobstore or
Google Cloud Storage
.

Streaming Responses

App Engine does not support streaming responses where data is sent in
incremental chunks to the client while a request is being processed. All data
from your code is collected as described above and sent as a single HTTP
response.

Response compression

If the client sends HTTP headers with the original request indicating that the
client can accept compressed (gzipped) content, App Engine compresses the
handler response data automatically and attaches the appropriate response
headers. It uses both the Accept-Encoding and User-Agent request headers to
determine if the client can reliably receive compressed responses.

Custom clients can indicate that they are able to receive compressed responses
by specifying both Accept-Encoding and User-Agent headers with a value of
gzip. The Content-Type of the response is also used to determine whether
compression is appropriate; in general, text-based content types are compressed,
whereas binary content types are not.

Note: In the absence of a Content-Type header provided by your application, a
default Content-Type: text/html header will be set, but the automatic gzip
compression will not be applied.

When responses are compressed automatically by App Engine, the Content-
Encoding header is added to the response.

Headers removed

The following headers are ignored and removed from the response:

Connection

Content-Encoding*

Content-Length

Date

Keep-Alive

Proxy-Authenticate

Server

Trailer

Transfer-Encoding

Upgrade

* May be re-added if the response is compressed by App Engine.

In addition, the header Strict-Transport-Security is removed from responses
served from any domains other than *.appspot.com.

Headers with non-ASCII characters in either the name or value are also removed.

Headers added or replaced

The following headers are added or replaced in the response:

Cache-Control, Expires and Vary

These headers specify caching policy to intermediate web proxies (such as
Internet Service Providers) and browsers. If your script sets these headers,
they will usually be unmodified, unless the response has a Set-Cookie header, or
is generated for a user who is signed in using an administrator account. Static
handlers will set these headers as directed by the configuration
file.
If you do not specify a Cache-Control, the server may set it to private, and
add a Vary: Accept-Encoding header.

If you have a Set-Cookie response header, the Cache-Control header will be
set to private (if it is not already more restrictive) and the Expires
header will be set to the current date (if it is not already in the past).
Generally, this will allow browsers to cache the response, but not
intermediate proxy servers. This is for security reasons, since if the
response was cached publicly, another user could subsequently request the
same resource, and retrieve the first user's cookie.

Note: The development server disables caching by default (for both script
and static content), so that if you do not specify caching headers, you will
not have cached content while developing your app.Note: If you use a webob-based framework (such as webapp or webapp2), the
Cache-Control header is set to no-cache by default, so you must override
it if you want caching in your script handlers.

Content-Encoding

Depending upon the request headers and response Content-Type, the server
may automatically compress the response body, as described above. In this case,
it adds a Content-Encoding: gzip header to indicate that the body is
compressed. See the section on response compression for
more detail.

Content-Length or Transfer-Encoding

The server always ignores the Content-Length header returned by the
application. It will either set Content-Length to the length of the body
(after compression, if compression is applied), or delete Content-Length, and
use chunked transfer encoding (adding a Transfer-Encoding: chunked header).

Content-Type

If not specified by the application, the server will set a default
Content-Type: text/html header.

Note: If you use a webob-based framework (such as webapp or webapp2), the
Content-Type header is set to text/html; charset=utf-8 by default, so
this default (without a charset property) does not apply.

Date

Set to the current date and time.

Server

Set to Google Frontend.
The development server sets this to Development/x, where x is the version
number.

If you access your site while signed in using an administrator account, App
Engine includes per-request statistics in the response headers:

X-AppEngine-Estimated-CPM-US-Dollars

An estimate of what 1,000 requests similar to this request would cost in US
dollars.

X-AppEngine-Resource-Usage

The resources used by the request, including server-side time as a number of
milliseconds.

Responses with resource usage statistics will be made uncacheable.

If the X-AppEngine-BlobKey header is in the application's response, it and the
optional X-AppEngine-BlobRange header will be used to replace the body with
all or part of a blobstore blob's content. If Content-Type is not specified by
the application, it will be set to the blob's MIME type. If a range is
requested, the response status will be changed to 206 Partial Content, and a
Content-Range header will be added. The X-AppEngine-BlobKey and X
-AppEngine-BlobRange headers will be removed from the response. You do not
normally need to set these headers yourself, as the
blobstore_handlers.BlobstoreDownloadHandler class sets them. See Serving a
Blob
for details.

Response headers set in the application configuration

Custom HTTP Response headers can be set per URL for dynamic and static paths in
your application's configuration file. See the http_headers sections in the
configuration
documentation
for more details.

The request timer

A request handler has a limited amount of time to generate and return a response
to a request, typically around 60 seconds. Once the deadline has been reached,
the request handler is interrupted.

The Python runtime environment interrupts the request handler by raising a
DeadlineExceededError, from the package google.appengine.runtime. If the
request handler does not catch this exception, as with all uncaught exceptions,
the runtime environment will return an HTTP 500 server error to the client.

The request handler can catch this error to customize the response. The runtime
environment gives the request handler a little bit more time (less than a
second) after raising the exception to prepare a custom response.

If the handler hasn't returned a response or raised an exception by the second
deadline, the handler is terminated and a default error response is returned.

While a request can take as long as 60 seconds to respond, App Engine is
optimized for applications with short-lived requests, typically those that take
a few hundred milliseconds. An efficient app responds quickly for the majority
of requests. An app that doesn't will not scale well with App Engine's
infrastructure.

Warning: The DeadlineExceededError can potentially be raised from anywhere in
your program, including finally blocks, so it could leave your program in an
invalid state. This can cause deadlocks or unexpected errors in threaded code
(including the built-in threading library), because locks may not be released.
Note that (unlike in Java) the runtime may not terminate the process, so this
could cause problems for future requests to the same instance. To be safe, you
should not rely on the DeadlineExceededError, and instead ensure that your
requests complete well before the time limit.

Logging

The App Engine web server captures everything the handler script writes to the
standard output stream for the response to the web request. It also captures
everything the handler script writes to the standard error stream, and stores
it as log data. Each request is assigned a request_id, a
globally unique identifier based on the request's start time. Log data for your
application can be viewed in the Cloud Platform Console
Logs page, or downloaded using
the gcloud app logs read command:

gcloud app logs read --logs=request_log

The App Engine Python runtime environment includes special support for the
logging module from
the Python standard library to understand logging concepts such as log levels
("debug", "info", "warning", "error", "critical").

The environment

The execution environment automatically sets several environment variables; you
can set more in app.yaml. Of the automatically-set variables, some are special
to App Engine, while others are part of the WSGI or CGI standards. Python code
can access these variables using the os.environ dictionary.

The following environment variables are specific to App Engine:

CURRENT_VERSION_ID: The major and minor version of the currently running
application, as "X.Y". The major version number ("X") is specified in the app's
app.yaml file. The minor version number ("Y") is set automatically when each
version of the app is uploaded to App Engine. On the development web server, the
minor version is always "1".

AUTH_DOMAIN: The domain used for authenticating users with the Users API.
Apps hosted on appspot.com have an AUTH_DOMAIN of gmail.com, and accept any
Google account. Apps hosted on a custom domain have an AUTH_DOMAIN equal to
the custom domain.

INSTANCE_ID: Contains the instance ID of the frontend instance handling a
request. The ID is a hex string (for example,
00c61b117c7f7fd0ce9e1325a04b8f0df30deaaf). A logged-in admin can use the id in
a url: http://[INSTANCE_ID].myApp.appspot.com/. The request will be routed to
that specific frontend instance. If the instance cannot handle the request it
returns an immediate 503.

The following environment variables are part of the WSGI and CGI standards, with
special behavior in App Engine:

SERVER_SOFTWARE: In the development web server, this value is
"Development/X.Y" where "X.Y" is the version of the runtime. When running on App
Engine, this value is "Google App Engine/X.Y.Z".

Additional environment variables are set according to the WSGI or CGI standard.
For more information on these variables, see the WSGI
standard or the CGI
standard, as appropriate.

Request IDs

At the time of the request, you can save the request ID, which is unique to that
request. The request ID can be used later to look up the logs for that request,
using the fetch() function's
request_ids parameter.

The following sample code shows how to get the request ID in the context of a
request:

App caching

The Python runtime environment caches imported modules between requests on a
single web server, similar to how a standalone Python application loads a module
only once even if the module is imported by multiple files. Since WSGI handlers
are modules, they are cached between requests. CGI handler scripts are only
cached if they provide a main() routine; otherwise, the CGI handler script is
loaded for every request. See Requests for more
information about the differences between WSGI and CGI.

App caching provides a significant benefit in response time. We recommend that
all CGI handler scripts use a main() routine, as described below.

Imports are cached

For efficiency, the web server keeps imported modules in memory and does not re-
load or re-evaluate them on subsequent requests to the same application on the
same server. Most modules do not initialize any global data or have other side
effects when they are imported, so caching them does not change the behavior of
the application.

If your application imports a module that depends on the module being evaluated
for every request, the application must accommodate this caching behavior.

CGI handler scripts can also be cached

You can tell App Engine to cache the CGI handler script itself, in addition to
imported modules. If the handler script defines a function named main(), then
the script and its global environment will be cached like an imported module.
The first request for the script on a given web server evaluates the script
normally. For subsequent requests, App Engine calls the main() function in the
cached environment.

To cache a handler script, App Engine must be able to call main() with no
arguments. If the handler script does not define a main() function, or the
main() function requires arguments (that don't have defaults), then App Engine
loads and evaluates the entire script for every request.

Keeping the parsed Python code in memory saves time and allows for faster
responses. Caching the global environment has other potential uses as well:

Compiled regular expressions. All regular expressions are parsed and stored in
a compiled form. You can store compiled regular expressions in global variables,
then use app caching to re-use the compiled objects between requests.

GqlQuery objects.
The GQL query string is parsed when the GqlQuery object is created. Re-using a
GqlQuery object with parameter binding and the
bind()
method is faster than re-constructing the object each time. You can store a
GqlQuery object with parameter binding for the values in a global variable, then
re-use it by binding new parameter values for each request.

Configuration and data files. If your application loads and parses
configuration data from a file, it can retain the parsed data in memory to avoid
having to re-load the file with each request.

The handler script should call main() when imported. App Engine expects that
importing the script calls main(), so App Engine does not call it when loading
the request handler for the first time on a server.

App caching with main() provides a significant improvement in your CGI
handler's response time. We recommend it for all applications that use CGI.

Quotas and limits

Google App Engine automatically allocates resources to your application as
traffic increases. However, this is bound by the following restrictions:

App Engine reserves automatic scaling capacity for applications with
low latency, where the application responds to requests in less than one second.
Applications with very high latency (over one second per request for many
requests) and high throughput require Silver, Gold, or Platinum support.
Customers with this level of support can request higher throughput limits by
contacting their support representative.

Applications that are heavily
CPU-bound may also incur some additional latency in order to efficiently share
resources with other applications on the same servers. Requests for static files
are exempt from these latency limits.

Each incoming request to the application counts toward the Requests limit.
Data sent in response to a request counts toward the
Outgoing Bandwidth (billable) limit.