SFTPPlus Documentation

Start Page 7. Developer Documentation 7.1.4. Python API Event Handler

7.1.4. Python API Event Handler

7.1.4.1. Introduction

SFTPPlus allows developers to write custom event handlers using the Python programming language.

The handlers are execute in separate independent processes / CPU cores, without shared memory. This is why the handle() method of the extension needs to be a @staticmethod and always received the configuration.

The handler is initialized multiple time. One instance is created in the main process and extra instances are created for each CPU.

A single extension instance can have the onStart(configuration) / onStop() method called multiple times during its lifetime. onStart(configuration) and onStop() methods are only called for the instance running in the main process.

The code for the event handler needs to be placed in a Python file (module) inside the extension/ folder from the SFTPPlus installation folder.

You can find an extensive example inside the extension/demo_event_handler.py folder of the default SFTPPlus installation. Below is a brief example:

class DemoEventHandler(object):
    """
    An event handler which just prints to standard output the ID of the
    received events.
    """

    def __init__(self):
        """
        Called when the event handler is started in each worker and
        in the main process.
        """

    def onStart(self, parent):
        """
        Called in the main process when the event handler starts.

        `parent.configuration` is the Unicode string defined in the
        extension configuration option.

        Any exception raised here will stop the event handler from
        starting.
        """
        self._configuration = parent.configuration

    def onStop(self):
        """
        Called in the main process when the event handler stops.
        """
        self._configuration = None

    def getConfiguration(self, event):
        """
        Called in the main process before dispatching the event to
        the worker process.

        Return the configuration for the event as Unicode.

        It can be used as validation for the event,
        before handling the event in a separate CPU core    .

        Any exception raised here will stop the handling of this
        specific event instance by the extension.
        """
        return self._configuration

    @staticmethod
    def handle(event, configuration):
        """
        Called in a separate process when it should handle the event.

        This function should work even when onStart and onStop were not
        called.

        `configuration` is the Unicode value returned by
        getConfiguration(event).
        """
        print(b'Configuration %s' % (configuration,))
        print(b'Received %s' % (event.id,))

This event handler can be configured as:

[event-handlers/56df1d0a-78c6-11e9-a2ff-137be4dbb9a8]
enabled = yes
type = extension
name = python-extension

entry_point = python:extensions.demo_event_handler.DemoEventHandler

configuration = some-free-text-configuration

7.1.4.2. Execution queue

SFTPPlus will only handle in parallel N events, where N is based on the number of CPUs available to the OS.

All the other events required to be handled by the extensions are placed into a queue.

The extension is called to handle the event only when there are free CPUs.

To prevent misconfiguration, there is a hard limit of 10 minutes for how long an event can stay in the queue and for processing the event.

7.1.4.3. Event data members

The event object received in the handler has the following structure.

The overall structure of the event object is:

id
message
timestamp:
    cwa_14051
    iso_8601
    iso_8601_local
    iso_8601_fractional
    iso_8601_basic
    iso_8601_compact
    timestamp
account:
    name
    uuid
    peer:
        address
        port
        protocol
        family
component:
    name
    uuid
    type
server:
    uuid
    name
data_json
data

The members of data are specific to each event. See Events page for more details regarding the data available for each event.

Many events have data.path and data.real_path, together with the associated data.file_name, data.directory_name, data.real_file_name, and data.real_directory_name.

Below is the description for the main members of the event object.


name:id
type:string
optional:No
description:ID of this event. See Events page for the list of all available events.

name:message
type:string
optional:No
description:A human readable description of this event.

The timestmap contains the following attributes:


name:timestamp
type:string
optional:No
description:Date and time at which this event was created, as Unix timestamp with milliseconds.

name:cwa_14051
type:string
optional:No
description:Date and time in CWA 14051 at which this event was emitted.

The account contains the following attributes:


name:uuid
type:string
optional:No
description:UUID of the account emitting this event. In case no account is associated with the event, this will be the special process account. In case the associated account is not yet authenticated this will be the special peer account.

name:name
type:string
optional:No
description:Name of the account emitting this event.

name:peer
type:JSON Object
optional:No
description:Address of the peer attached to this account. This might be a local or remote address, depending on whether the account is used for client side or server side interaction.

The peer contains the following attributes:


name:address
type:string
optional:No
description:IP address of this connection.

name:port
type:integer
optional:No
description:Port number of this connection.

name:protocol
type:string
optional:No
description:OSI Layer 4 transport layer protocol used for this connection in the form of either TCP or UDP.

The component contains the following attributes:


name:uuid
type:string
optional:No
description:UUID of the component (service or transfer) emitting this event.

name:type
type:string
optional:No
description:Type of the component emitting this event.

The server contains the following attributes:


name:uuid
type:string
optional:No
description:UUID of the server emitting this event.

name:type
type:string
optional:No
description:Type of the server emitting this event.