Middleware

class ehforwarderbot.Middleware(instance_id=None)

Middleware class.

middleware_id

Unique ID of the middleware. Convention of IDs is specified in Packaging and Publish. This ID will be appended with its instance ID when available.

Type

str

middleware_name

Human-readable name of the middleware.

Type

str

instance_id

The instance ID if available.

Type

str

__init__(instance_id=None)

Initialize the middleware. Inherited initializer MUST call the “super init” method at the beginning.

Parameters

instance_id (Optional[NewType()(InstanceID, str)]) – Instance ID of the middleware.

get_extra_functions()

Get a list of additional features

Returns

A dict of methods marked as additional features. Method can be called with get_extra_functions()["methodName"]().

Return type

Dict[str, Callable]

process_message(message)

Process a message with middleware

Parameters

message (Message) – Message object to process

Returns

Processed message or None if discarded.

Return type

Optional[Message]

process_status(status)

Process a status update with middleware

Parameters

status (Status) – Message object to process

Returns

Processed status or None if discarded.

Return type

Optional[Status]

About Middleware ID

With the introduction of instance IDs, it is required to use the self.middleware_id or equivalent instead of any hard-coded ID or constants while referring to the middleware ID (e.g. while retrieving the path to the configuration files, etc).

Accept commands from user through Master Channel

Despite we do not limit how the User interact with your middleware, there are 2 common ways to do it through a master channel.

Capture messages

If the action is chat-specific, you can capture messages with a specific pattern. Try to make the pattern easy to type but unique enough so that you don’t accidentally catch messages that were meant to sent to the chat.

You may also construct a virtual chat or chat member of type “System” to give responses to the User.

“Additional features”

If the action is not specific to any chat, but to the system as a whole, we have provided the same command line-like interface as in slave channels to middlewares as well. Details are available at Additional features.

Chat-specific interactions

Middlewares can have chat-specific interactions through capturing messages and reply to them with a chat member created by the middleware.

The following code is an example of a middleware that interact with the user by capturing messages.

When the master channel sends a message with a text starts with time`, the middleware captures this message and reply with the name of the chat and current time on the server. The message captured is not delivered to any following middlewares or the slave channel.

def process_message(self: Middleware, message: Message) -> Optional[Message]:
    if message.deliver_to != coordinator.master and \  # sent from master channel
        text.startswith('time`'):

        # Make a system chat object.
        # For difference between `make_system_member()` and `add_system_member()`,
        # see their descriptions above.
        author = message.chat.make_system_member(
            uid="__middleware_example_time_reporter__",
            name="Time reporter",
            middleware=self
        )

        # Make a reply message
        reply = Message(
            uid=f"__middleware_example_{uuid.uuid4()}__",
            text=f"Greetings from chat {message.chat.name} on {datetime.now().strftime('%c')}.",
            chat=chat,
            author=author,  # Using the new chat we created before
            type=MsgType.Text,
            target=message,  # Quoting the incoming message
            deliver_to=coordinator.master  # message is to be delivered to master
        )
        # Send the message back to master channel
        coordinator.send_message(reply)

        # Capture the message to prevent it from being delivered to following middlewares
        # and the slave channel.
        return None

    # Continue to deliver messages not matching the pattern above.
    return message