API

Middleware

EPDBServe

class falcon_epdb.EPDBServe(backend, exempt_methods=('OPTIONS', ), serve_options=None)

A middleware to enable remote debuging via an epdb server.

Parameters:

• backend (EPDBBackend) – An instance of the class that will validate and decode the X-EPDB header
• exempt_methods (iterable of strings) – HTTP methods which will be ignored by this middleware
• serve_options (dictionary) – Parameters passed-through to epdb.serve()

A client may include a special X-EPDB header containing an appropriately formed payload. If they do, the header will be passed to the configured backend for processing. If the payload passes authentication and meets the content requirements, the app will be begin listening for epdb client connections.

A well-formed header has content simply of the form:

{
    "epdb": {}
}

The encoding and encryption of this payload is determined by the EPDBBackend provided to the middleware.

process_request(req, resp)

Check for a well-formed X-EPDB header and if present activate the epdb server.

Parameters:

• req – The Falcon request object
• resp – The Falcon response object (unused)

This will block, waiting for an epdb client connection, the first time a valid header is received. Once the client is connected, subsequent passes will simply activate the connected client and drop it into the epdb shell.

The header processing is delegated to the configured EPDBBackend.

Backends

Base64Backend

class falcon_epdb.Base64Backend

A simple unauthenticated backend for local development.

decode_header_value(epdb_header)

Pull the encrypted data out of the header, if present.

Parameters:epdb_header (string) – The content of the X-EPDB header. Returns:The decoded header payload Return type:dictionary Raises:EPDBException

It expects epdb_header to have the Base64 prefix.

FernetBackend

class falcon_epdb.FernetBackend(key)

A Python cryptography-based backend that supports a pre-shared key (ie. password) protocol.

Parameters:key (bytes) – The fernet key used to encrypt the header content

Note

To use this backend, one must install the cryptography package. The easiest way to do this is to specify the [fernet] extra when adding the falcon-epdb dependency to your project.

requirements.txt

falcon-epdb[fernet]

decode_header_value(epdb_header)

Pull the encrypted data out of the header, if present.

Parameters:epdb_header (string) – The content of the X-EPDB header. Returns:The decoded and decrypted header payload Return type:dictionary Raises:EPDBException

It expects epdb_header to have the Fernet prefix.

JWTBackend

class falcon_epdb.JWTBackend(key)

A JWT-based backend that supports a pre-shared key (ie. password) protocol.

Parameters:key (bytes) – The JWT key used to encrypt the header content

Note

To use this backend, one must install the PyJWT package. The easiest way to do this is to specify the [jwt] extra when adding the falcon-epdb dependency to your project.

requirements.txt

falcon-epdb[jwt]

decode_header_value(epdb_header)

Pull the encrypted data out of the header, if present.

Parameters:epdb_header (string) – The content of the X-EPDB header. Returns:The decoded and decrypted header payload Return type:dictionary Raises:EPDBException

It expects epdb_header to have the JWT prefix.

EPDBBackend

class falcon_epdb.EPDBBackend

The abstract base class defining the header-processing backend interface.

An inheriting subclass must define decode_header_value(), but may define other methods if necessary. This class is structured to provide a balance of convenience and flexibility.

decode_header_value(epdb_header)

Process the X-EPDB header content.

Parameters:epdb_header (string) – The content of the X-EPDB header Returns:The decoded and decrypted header payload Return type:dictionary

This does not need to do any content validation, as that is handled in validate_header_content().

get_header_data(req)

Process a request and return the contents of a conforming payload.

Parameters:req (Request) – The Falcon request object Returns:The paylod content or None Return type:dictionary or None

This implementation assumes that the payload is present on the X-EPDB header, but subclasses may override this method if their use-case demands it.

If the request does not appear to be attempting begin a debugging session, this will return None.

static validate_header_content(header_content)

Ensure that the decoded X-EPDB header content is well-formed.

Parameters:header_content (dictionary) – The decoded X-EPDB header content Returns:The value of the epdb key Return type:dictionary Raises:EPDBException

header_content must be of the form:

{
    "epdb": {}
}

Exceptions

EPDBException

exception falcon_epdb.EPDBException

Raised when an error occurs during the processing of an X-EPDB header.