How Requests are Handled

Region ID

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn more about region IDs.

OK

This document describes how your App Engine application receives requests and sends responses.

For more details, see the Request Headers and Responses reference.

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

Handling requests

Your application is responsible for starting a webserver and handling requests. You can use any web framework that is available for your development language.

App Engine runs multiple instances of your application, and 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. An instance can handle multiple requests concurrently. The number of instances can be adjusted automatically as traffic changes. You can also change the number of concurrent requests an instance can handle by setting the max_concurrent_requests element in your app.yaml file.

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.

The following Python script responds to a request with an HTTP header and the message Hello, World!.

import webapp2


class MainPage(webapp2.RequestHandler):
    def get(self):
        self.response.headers["Content-Type"] = "text/plain"
        self.response.write("Hello, World!")


app = webapp2.WSGIApplication(
    [
        ("/", MainPage),
    ],
    debug=True,
)

To dispatch multiple requests to each web server in parallel, mark your application as threadsafe by adding a threadsafe: true to your app.yaml file. Concurrent requests are not available if any script handler uses CGI.

Quotas and limits

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 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.

Both HTTP and HTTPS (secure) requests count toward the Requests, Incoming Bandwidth (billable), and Outgoing Bandwidth (billable) limits. The Google Cloud console Quota Details page also reports Secure Requests, Secure Incoming Bandwidth, and Secure Outgoing Bandwidth as separate values for informational purposes. Only HTTPS requests count toward these values. For more information, see the Quotas page.

The following limits apply specifically to the use of request handlers:

Limit	Amount
Request size	32 megabytes
Response size	32 megabytes
Request timeout	Depends on the type of scaling your app uses
Maximum total number of files (app files and static files)	10,000 total 1,000 per directory
Maximum size of an application file	32 megabytes
Maximum size of a static file	32 megabytes
Maximum total size of all application and static files	First 1 gigabyte is free $ 0.026 per gigabyte per month after first 1 gigabyte
Pending request timeout	10 seconds
Maximum size of a single request header field	8 kilobytes for second-generation runtimes in the standard environment. Requests to these runtimes with header fields exceeding 8 kilobytes will return HTTP 400 errors.

Request limits

All HTTP/2 requests will be translated into HTTP/1.1 requests when forwarded to the application server.

Response limits

• Dynamic responses are limited to 32 MB. 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 legacy Blobstore or Cloud Storage.

• The response header limit is 8 KB for second-generation runtimes. Response headers that exceed this limit will return HTTP 502 errors, with logs showing upstream sent too big header while reading response header from upstream.

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.

For more information, see the Request headers reference.

Handling request timeouts

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. To ensure this level of performance, there is a system-imposed maximum request timeout that every app must respond by.

If your app exceeds this deadline, App Engine interrupts the request handler. The Python runtime environment accomplishes this by raising a DeadlineExceededError exception from 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.

class TimerHandler(webapp2.RequestHandler):
    def get(self):
        from google.appengine.runtime import DeadlineExceededError

        try:
            time.sleep(70)
            self.response.write("Completed.")
        except DeadlineExceededError:
            self.response.clear()
            self.response.set_status(500)
            self.response.out.write("The request did not complete in time.")

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

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 stop 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.

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.

There are size limits that apply to the response you generate, and the response may be modified before it is returned to the client.

For more information, see the Request responses reference.

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

App Engine does its best to serve compressed (gzipped) content to clients that support it. To determine if content should be compressed, App Engine does the following when it receives a request:

1. Confirms if the client can reliably receive compressed responses by viewing both the Accept-Encoding and User-Agent headers in the request. This approach avoids some well-known bugs with gzipped content in popular browsers.

2. Confirms if compressing the content is appropriate by viewing the Content-Type header that you have configured for the response handler. In general, compression is appropriate for text-based content types, and not for binary content types.

Note the following:

• A client can force text-based content types to be compressed by setting both of the Accept-Encoding and User-Agent request headers to gzip.

• If a request doesn't specify gzip in the Accept-Encoding header, App Engine will not compress the response data.

• The Google Frontend caches responses from App Engine static file and directory handlers. Depending on a variety of factors, such as which type of response data is cached first, which Vary headers you have specified in the response, and which headers are included in the request, a client could request compressed data but receive uncompressed data, and the other way around. For more information, see Response caching.

Response caching

The Google Frontend, and potentially the user's browser and other intermediate caching proxy servers, will cache your app's responses as instructed by standard caching headers that you specify in the response. You can specify these response headers either through your framework, directly in your code, or through App Engine static file and directory handlers.

In the Google Frontend, the cache key is the full URL of the request.

Caching static content

To ensure that clients always receive updated static content as soon as it is published, we recommend that you serve static content from versioned directories, such as css/v1/styles.css. The Google Frontend will not validate the cache (check for updated content) until the cache expires. Even after the cache expires, the cache will not be updated until the content at the request URL changes.

The following response headers that you can set in app.yaml influence how and when the Google Frontend caches content:

• Cache-Control should be set to public for the Google Frontend to cache content; it may also be cached by the Google Frontend unless you specify a Cache-Control private or no-store directive. If you don't set this header in app.yaml , App Engine automatically adds it for all responses handled by a static file or directory handler. For more information, see Headers added or replaced.

• Vary: To enable the cache to return different responses for a URL based on headers that are sent in the request, set one or more of the following values in the Vary response header: Accept, Accept-Encoding, Origin, or X-Origin

  Due to the potential for high cardinality, data will not be cached for other Vary values.

  For example:

  1. You specify the following response header:

     Vary: Accept-Encoding

  2. You app receives a request that contains the Accept-Encoding: gzip header. App Engine returns a compressed response and the Google Frontend caches the gzipped version of the response data. All subsequent requests for this URL that contain the Accept-Encoding: gzip header will receive the gzipped data from the cache until the cache becomes invalidated (due to the content changing after the cache expires).

  3. Your app receives a request that does not contain the Accept-Encoding header. App Engine returns an uncompressed response and Google Frontend caches the uncompressed version of the response data. All subsequent requests for this URL that do not contain the Accept-Encoding header will receive the compressed data from the cache until the cache becomes invalidated.

  If you do not specify a Vary response header, the Google Frontend creates a single cache entry for the URL and will use it for all requests regardless of the headers in the request. For example:

  1. You do not specify the Vary: Accept-Encoding response header.
  2. A request contains the Accept-Encoding: gzip header, and the gzipped version of the response data will be cached.
  3. A second request does not contain the Accept-Encoding: gzip header. However, because the cache contains a gzipped version of the response data, the response will be gzipped even though the client requested uncompressed data.

The headers in the request also influence caching:

• If the request contains an Authorization header, the content will not be cached by the Google Frontend.

Cache expiration

By default, the caching headers that App Engine static file and directory handlers add to responses instruct clients and web proxies such as the Google Frontend to expire the cache after 10 minutes.

After a file is transmitted with a given expiration time, there is generally no way to clear it out of web-proxy caches, even if the user clears their own browser cache. Re-deploying a new version of the app will not reset any caches. Therefore, if you ever plan to modify a static file, it should have a short (less than one hour) expiration time. In most cases, the default 10-minute expiration time is appropriate.

You can change the default expiration for all static file and directory handlers by specifying the default_expiration element in your app.yaml file. To set specific expiration times for individiual handlers, specify the expiration element within the handler element in your app.yaml file.

The value you specify in the expiration elements time will be used to set the Cache-Control and Expires HTTP response headers.

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.

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.

Caching CGI handlers

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.

Note: Be careful to not "leak" user-specific information between requests. Avoid global variables unless caching is desired, and always initialize request- specific data inside the main() routine.

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

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 Google Cloud console using Cloud Logging.

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").

import logging

import webapp2


class MainPage(webapp2.RequestHandler):
    def get(self):
        logging.debug("This is a debug message")
        logging.info("This is an info message")
        logging.warning("This is a warning message")
        logging.error("This is an error message")
        logging.critical("This is a critical message")

        try:
            raise ValueError("This is a sample value error.")
        except ValueError:
            logging.exception("A example exception log.")

        self.response.out.write("Logging example.")


app = webapp2.WSGIApplication([("/", MainPage)], debug=True)

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: https://INSTANCE_ID-dot-VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.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.

You can also set environment variables in the app.yaml file:

env_variables:
  DJANGO_SETTINGS_MODULE: 'myapp.settings'

The following webapp2 request handler displays every environment variable visible to the application in the browser:

class PrintEnvironmentHandler(webapp2.RequestHandler):
    def get(self):
        self.response.headers["Content-Type"] = "text/plain"
        for key, value in os.environ.iteritems():
            self.response.out.write("{} = {}\n".format(key, value))

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 in Cloud Logging.

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

class RequestIdHandler(webapp2.RequestHandler):
    def get(self):
        self.response.headers["Content-Type"] = "text/plain"
        request_id = os.environ.get("REQUEST_LOG_ID")
        self.response.write("REQUEST_LOG_ID={}".format(request_id))

Forcing HTTPS connections

For security reasons, all applications should encourage clients to connect over https. To instruct the browser to prefer https over http for a given page or entire domain, set the Strict-Transport-Security header in your responses. For example:

Strict-Transport-Security: max-age=31536000; includeSubDomains

To set this header for any static content that is served by your app, add the header to your app's static file and directory handlers.

To set this header for responses that are generated from your code, use the flask-talisman library.

Caution: Clients that have received the header in the past will refuse to connect if https becomes non-functional or is disabled for any reason. To learn more, see this Cheat Sheet on HTTP Strict Transport Security.

Handling asynchronous background work

Background work is any work that your app performs for a request after you have delivered your HTTP response. Avoid performing background work in your app, and review your code to make sure all asynchronous operations finish before you deliver your response.

For long-running jobs, we recommend using Cloud Tasks. With Cloud Tasks, HTTP requests are long-lived and return a response only after any asynchronous work ends.

Warning: Performing asynchronous background work can result in higher billing. App Engine might scale up additional instances due to high CPU load, even if there are no active requests. Users may also experience increased latency because of requests waiting in the pending queue for available instances.