Serverless WSGI

Warnings

• breaking Version 3.0.0 introduced breaking changes for Serverless Framework integration, requiring Serverless Framework versions 2.32.0 or newer. Ensure your `serverless` CLI is updated.
  Fix: Upgrade your Serverless Framework CLI: `npm install -g serverless` (or `npm install serverless@^2.32.0` if you need to pin to a specific 2.x version).
• breaking Version 2.0.0 dropped Python 2 support and requires Werkzeug 2 or later. It also removed deprecated WSGI environment variables (`API_GATEWAY_AUTHORIZER`, `event`, `context`); these should be accessed via `serverless.authorizer`, `serverless.event`, and `serverless.context` respectively.
  Fix: Ensure your Lambda runtime is Python 3.6+ and that Werkzeug 2.0+ is installed. Update your application code to use the new `serverless.*` variables.
• breaking With Werkzeug 3.0.0 (a dependency of `serverless-wsgi`), `werkzeug.urls.url_encode` is no longer available. If your application directly uses this Werkzeug function, you'll need to migrate to `urllib` counterparts.
  Fix: Replace `werkzeug.urls.url_encode` calls in your application with functions from Python's standard `urllib.parse` module, such as `urllib.parse.urlencode`.
• gotcha When deploying with the Serverless Framework plugin, the handler `wsgi.handler` was renamed to `wsgi_handler.handler` in version 1.7.0. While the old name is still supported, using `wsgi_handler.handler` is the recommended and up-to-date practice.
  Fix: Update your `serverless.yml` to specify `handler: wsgi_handler.handler` for your Lambda functions.
• gotcha Binary data (e.g., images, fonts) might be incorrectly base64 encoded by `serverless-wsgi` if the corresponding MIME types are not explicitly added to `binaryMimeTypes` in your API Gateway configuration (typically via `serverless.yml`).
  Fix: Configure API Gateway to include the necessary `binaryMimeTypes` in your `serverless.yml` to ensure proper decoding of binary responses. You can also extend `serverless_wsgi.TEXT_MIME_TYPES` if you have custom text types that should not be base64 encoded.
• gotcha AWS Lambda has a deployment package size limit (50MB compressed, 250MB uncompressed). Large applications or those with many dependencies might exceed this, especially if development artifacts or unnecessary files are included.
  Fix: Use a `.serverlessignore` file or the `package.exclude` options in `serverless.yml` to omit large or unnecessary files. Consider using `serverless-python-requirements` with `dockerizePip: true` for complex C-extension dependencies to reduce package size.

Install

• pip install serverless-wsgi Install Python package
• npm install serverless-wsgi Install Serverless Framework plugin (recommended for deployment)

Imports

• handle_request

  import serverless_wsgi
  
  def lambda_handler(event, context):
      from your_app_module import app # Your WSGI application instance
      return serverless_wsgi.handle_request(app, event, context)

  When using the serverless-wsgi Python package directly within a Lambda handler, import `serverless_wsgi` and call `serverless_wsgi.handle_request`. The `wsgi_handler.handler` is the entry point configured in `serverless.yml` for the plugin, which internally calls `serverless_wsgi.handle_request`.

Quickstart

This quickstart demonstrates how to integrate `serverless-wsgi` with a simple Flask application for direct use within an AWS Lambda function. The `lambda_handler` function serves as the entry point, passing the AWS event and context to `serverless_wsgi.handle_request`. For actual deployment, the `serverless-wsgi` plugin for the Serverless Framework is typically used, which abstracts away the manual `lambda_handler` setup by configuring `wsgi_handler.handler` in your `serverless.yml`.

import os
import serverless_wsgi
from flask import Flask, jsonify

# Your Flask (or any WSGI) application
app = Flask(__name__)

@app.route('/')
def hello():
    return jsonify(message='Hello from Serverless WSGI!')

@app.route('/env')
def show_env():
    return jsonify(environment=dict(os.environ))

# The AWS Lambda handler function
def lambda_handler(event, context):
    # This is the core function from the serverless-wsgi Python library
    # that maps API Gateway events to your WSGI application.
    return serverless_wsgi.handle_request(app, event, context)

# Example of how you would run it locally (for testing)
if __name__ == '__main__':
    # In a real setup, this is handled by `sls wsgi serve` or a WSGI server.
    # For a minimal local test, you could use Werkzeug's run_simple.
    from werkzeug.serving import run_simple
    print("Running local Flask app on http://127.0.0.1:5000/")
    run_simple('127.0.0.1', 5000, app, use_reloader=True, use_debugger=True)