API¶
Middleware¶
EPDBServe¶
-
class
falcon_epdb.
EPDBServe
(backend, exempt_methods=('OPTIONS', ), serve_options=None)[source]¶ 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)[source]¶ 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
.
- backend (EPDBBackend) – An instance of the class that will validate and decode the
Backends¶
Base64Backend¶
FernetBackend¶
-
class
falcon_epdb.
FernetBackend
(key)[source]¶ 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 thefalcon-epdb
dependency to your project.falcon-epdb[fernet]
-
decode_header_value
(epdb_header)[source]¶ 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 theFernet
prefix.
-
JWTBackend¶
-
class
falcon_epdb.
JWTBackend
(key)[source]¶ 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 thefalcon-epdb
dependency to your project.falcon-epdb[jwt]
-
decode_header_value
(epdb_header)[source]¶ 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 theJWT
prefix.
-
EPDBBackend¶
-
class
falcon_epdb.
EPDBBackend
[source]¶ 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)[source]¶ Process the
X-EPDB
header content.Parameters: epdb_header (string) – The content of the X-EPDB
headerReturns: 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)[source]¶ 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)[source]¶ Ensure that the decoded
X-EPDB
header content is well-formed.Parameters: header_content (dictionary) – The decoded X-EPDB
header contentReturns: The value of the epdb key Return type: dictionary Raises: EPDBException header_content
must be of the form:{ "epdb": {} }
-