Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Interactive debugging for your Falco apps

Project description

Build version Build status Coverage status Source code Documentation status Supported Python versions Build version Black code formatter

A Falcon middleware that wraps the excellent epdb tool and allows one to connect to a running Falcon app and use interactive debugging to step through the code.

Better documentation can be found at readthedocs.

Source code can be found on GitHub at jcwilson/falcon-epdb.


If you are only planning on debugging in a development environment where access to your service is restricted to you or trusted partners, you may find the Base64 backend sufficient to your purposes. You can just install the library as you would any Python library.




pip install falcon-epdb


poetry add falcon-epdb

However, if you need a little more security, you can use one of the other authenticated backends (Fernet, JWT). Choose the one that best fits your use case and install it as a Python extra.




pip install falcon-epdb[fernet, jwt]


poetry add falcon-epdb[jwt]


This library adds a middleware to your Falcon API stack, and as such will run for all requests, save those excluded by exempt_methods provided to the EPDBServer constructor. If it detects a well-formed (and possibly authenticated) X-EPDB header on the request it will start the epdb server on the configured port and block until it establishes a connection from an epdb client, at which point processing continues but under the control of the remote debugging session.

Subsequent requests with an acceptable header will reuse the client connection and automatically drop into the remote debugging session again.

Configuring the middleware

The EPDBServe<falcon_epdb.EPDBServe> middleware accepts a handful of parameters. The most important are the backend and serve_options parameters. The backend determines how a request is examined for the “secret knock” to start the remote debugging server. The included implementations assume a well-formed X-EPDB header, but nothing precludes you from sub-classing EPDBBackend<falcon_epdb.EPDBBackend> and implementing your own.

The serve_options are options that are passed through to the epdb.serve() call. See Backends for details on how to add this middleware to your API.

Constructing the X-EPDB header

The content of the header is as follows:

  "epdb": {}

Depending on the backend in use, one should encode this content into the appropriate header-safe value. Then append this value to the name of the backend.

X-EPDB: Base64 eyJlcGRiIjoge319

Connecting the client

Example code for connecting to the waiting port:

import epdb

edpb.connect(host=<host>, port=9000)



Server side configuration

epdb_middleware = EPDBServe(
    serve_options={'port': 9000})
api = falcon.API(middleware=[epdb_middleware])

Crafting an appropriate header

import base64
import json

header_content = base64.b64encode(json.dumps({'epdb': {}}).encode()).decode()
header_value = 'Base64 {}'.format(header_content)


Server side configuration

fernet_key = Fernet.generate_key()  # The shared key
epdb_middleware = EPDBServe(
    serve_options={'port': 9000})
api = falcon.API(middleware=[epdb_middleware])

Crafting an appropriate header

import json
from cryptography.fernet import Fernet

f = Fernet(<fernet_key>)  # Key configured on the server
header_content = f.encrypt(json.dumps({'epdb': {}}).encode()).decode()
header_value = 'Fernet {}'.format(header_content)


Server side configuration

jwt_key = uuid.uuid4().hex  # The shared key
epdb_middleware = EPDBServe(
    serve_options={'port': 9000})
api = falcon.API(middleware=[epdb_middleware])

Crafting an appropriate header

import jwt

header_content = jwt.encode({'epdb': {}}, <jwt_key>, algorithm='HS256').decode()
header_value = 'JWT {}'.format(header_content)


You must be sure to allow access to the configured port on your host. Be sure to check your security groups and firewall rules.

Configure your web app to only run one worker process. If you have multiple workers, only the first one will be able to serve on the configured port. If this is not possible you will have to take steps to ensure that all requests that wish to use the remote debugging port are routed to the same worker. This will depend heavily on your HTTP stack and is beyond the scope of this documentation.

Be sure to up your request timeout limit to something on the order of minutes so that the HTTP server doesn’t close your request connection or kill your worker process while you’re debugging.

You may need to provide the HTTP- prefix on your X-EPDB header for it to be handled correctly. So instead of sending X-EPDB, you would send HTTP-X-EPDB.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for falcon-epdb, version 1.1.2
Filename, size File type Python version Upload date Hashes
Filename, size falcon_epdb-1.1.2-py2.py3-none-any.whl (15.6 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size falcon-epdb-1.1.2.tar.gz (7.8 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page