Custom Protocols ⚙️

Dementor is not limited to a predefined set of protocols and can be extended with custom implementations. Each protocol extension is defined as a Python module that implements specific functions recognized by the core engine.

Required Functions

Custom protocol modules may define the following functions:

apply_config(session: SessionConfig) → None

Optional

Applies custom configuration logic to the current SessionConfig object. This function is called during setup, using global definitions from dementor.config.

create_server_threads(session: SessionConfig) → List[Thread]

Optional, but recommended

Creates and returns server thread objects for this protocol. Threads must not be started here — they will be started automatically.

To enable a custom protocol, its Python module must be placed in a directory listed under the Dementor.ExtraModules setting in your configuration file, the protocols package within Dementor or within the protocols directory under ~/.dementor/protocols.

Example: POP3 Protocol Extension

Below is an example implementation of a POP3 protocol handler with plain-text authentication:

pop3.py

from dementor.config import TomlConfig, Attribute as A

# Define the custom config section for POP3
class POP3Config(TomlConfig):
    _section_ = "POP3"
    _fields_ = [
        # Attribute(name, config_key, default_value)
        A("pop3_enabled", "Dementor.POP3", True),  # defined in [Dementor]
        A("pop3_port", "Port", 110),               # defined in [POP3]
    ]

def apply_config(session: SessionConfig):
    # Populate values from the configuration file
    session.pop3_config = TomlConfig.build_config(POP3Config)

def create_server_threads(session: SessionConfig):
    is_enabled = session.pop3_config.pop3_enabled
    return [POP3Server(session.pop3_config)] if is_enabled else []

class POP3Server(Thread):
    def __init__(self, config):
        super().__init__()
        self.config = config
        # Additional setup here

    def run(self):
        # Start listening on self.config.pop3_port
        ...