Plugins

The service supports the system of plugins. Plugins must be written in the Python programming language.

Plugin types

There are three sorts of plugins:

  • On event plugin. The plugin is triggered when an event occurs. The plugin should implement a callback function. This function is called on each event of the corresponding type. The set of event types is defined by the service developers.

    Supported event types:

    event type

    description

    monitoring_event

    Event contains monitoring points for sending to a custom monitoring system

    Plugin example:

    """
    Module request monitoring plugin example
    """
    import asyncio
    from abc import abstractmethod
    
    from aiohttp import ClientSession
    from luna_plugins.base.plugins_meta.base_plugins import BaseEventPlugin
    
    
    class BaseRequestMonitoringPlugin(BaseEventPlugin):
        """
        Base class for requests monitoring.
        """
    
        # event name for triggering callback
        eventName = "monitoring_event"
    
        @abstractmethod
        async def flushPointToMonitoring(self, point: "MonitoringPoint", logger) -> None:
            """
            All plugins must realize this method.
    
            This function call after end of request
    
            Args:
                point: point for monitoring
                logger: logger
            """
    
        async def handleEvent(self, points: list["MonitoringPoint"], logger):
            await asyncio.gather(*[self.flushPointToMonitoring(point, logger) for point in points])
    
    
    class RequestMonitoringPlugin(BaseRequestMonitoringPlugin):
        """
        Example plugin sends a request data for monitoring to third-party source.
        Only one instance of this class exist during the program execution.
        """
    
        def __init__(self, app: "LunaApplication"):
            super().__init__(app)
            self.url = "http://127.0.0.1:5020/1/buckets"
            self.session: ClientSession | None = None
            self.bucket = "plugin_test_bucket"
    
        async def close(self):
            """
            Stop plugin.
    
            Close all open connections and ect
            """
            if self.session:
                await self.session.close()
    
        async def initialize(self):
            """
            Initialize plugin.
    
            Close all open connections and ect
            """
            self.session = ClientSession()
            async with self.session.post(f"{self.url}?bucket={self.bucket}") as resp:
                if resp.status not in (201, 409):
                    response = await resp.json()
                    raise RuntimeError(f"failed create bucket, {self.bucket}, response: {response}")
    
        async def flushPointToMonitoring(self, point: "MonitoringPoint", logger) -> None:
            """
            Callback for sending a request monitoring data.
    
            Args:
                point: point for monitoring
                logger: logger
            """
            logger.debug(f"Plugin 'flushPointToMonitoring' get point, series: {point.series}, time: {point.eventTime}")
            msg = {"tags": point.tags, "fields": point.fields}
            async with self.session.post(f"{self.url}/{self.bucket}/objects", json=msg) as resp:
                logger.info(resp.status)
                logger.info(await resp.text())
    

    This plugin demonstrates the sending of a request monitoring data to another service. All monitoring plugins must implement the BaseRequestMonitoringPlugin abstract class.

  • Background plugin. This sort of plugin is intended for background work.

    The background plugin can implement:

    • custom route

    • background monitoring of service resources

    • collaboration of an event plugin and a background plugin (batching monitoring points)

    • connection to other data sources (Redis, RabbitMQ) and their data processing

    Plugin example:

    """
    Module realizes background plugin example
    """
    import asyncio
    from asyncio import Task
    
    from luna_plugins.base.plugins_meta.base_plugins import BaseBackgroundHandler, BaseBackgroundPlugin, pluginHTTPResponse
    
    
    class HandlerExample(BaseBackgroundHandler):
        """
        Handler example
        """
    
        async def get(self, request):  # pylint: disable=unused-argument
            """
            Method get example.
    
            Returns:
                response
            """
            return self.response(body="I am teapot", headers={"Content-Type": "text/plain"}, statusCode=418)
    
    
    def anotherHandlerExample(request):  # pylint: disable=unused-argument
        """Standalone handler example"""
        return pluginHTTPResponse(statusCode=200, body="T800", headers={"Content-Type": "text/plain"})
    
    
    class BackgroundPluginExample(BaseBackgroundPlugin):
        """
        Background plugin example.
    
        Create background task and add a route.
        """
    
        def __init__(self, app: "LunaApplication"):
            super().__init__(app)
            self.task: Task | None = None
            self.temperature = 0
    
        async def initialize(self):
            """
            Initialize plugin
            """
            self.addRoute("/teapot", HandlerExample)
            self.addRoute("/teapot/version", anotherHandlerExample, methods={"get"})
    
        async def close(self):
            """
            Stop background process
            Returns:
    
            """
            if self.task:
                self.task.cancel()
    
        async def usefulJob(self):
            """
            Some useful  async work
            """
            while True:
                await asyncio.sleep(1)
                self.temperature = min(100, self.temperature + 1)
                if self.temperature < 100:
                    self.app.ctx.logger.info(f"I boil water, temperature: {self.temperature}")
                else:
                    self.app.ctx.logger.info("boiling water is ready, would you care for a cup of tea?")
    
        async def start(self):
            """
            Run background process
    
            .. warning::
                The function suppose that the process is handle in this coroutine. The coroutine must start
                the process only without awaiting a end of the process
            """
            self.task = asyncio.create_task(self.usefulJob())
    

    This plugin demonstrates background work and implements a route. All background plugins must implement the BaseRequestMonitoringPlugin abstract class.

  • Builtin plugin. This sort of plugin is provided only by VL and allow to get access to external VL services which not included to luna-platform. Each plugin provides access to part or whole resources of external service.

    At this moment available plugins are:
    • luna-streams

    The plugin also check authorization parameters for access to several resources. It is possible to use Luna-Account-Id/Basic/Bearer authorization to make requests just like for all other endpoint of luna-api.

    It is also possible to delimit access permissions using token permission. To make it possible, it needs to create new or update existing token passing custom token permission keys, for example {“permissions”: {“streams”: [“creation”, “view”, “modification”, “deletion”]}}

    These parameters will works the same way as for all other luna-api resources.

    Luna-Streams builtin plugin

    Requirements:
    • properly executed Luna-Streams service

    • properly specified plugin settings. For example:

      "LUNA_API_PLUGINS_SETTINGS": {
              "luna-streams": {
                  "luna-streams-address": {"origin": "http://127.0.0.1:5160/1", "api_version": 1},
                  "luna-streams-timeouts": {"request": 42, "connect": 42}
              }
          }
      }
      

    * prefix is /6/plugins/luna-streams

    luna-api route

    luna-streams route

    description

    permission key

    prefix/version

    /version

    get luna-streams api version

    prefix/docs/spec

    /1/docs/spec

    get luna-streams spec documentation

    prefix/streams

    /1/streams

    create new/get/delete existing streams

    streams

    prefix/streams/count

    /1/streams/count

    get streams count

    streams

    prefix/streams/<stream-id>

    /1/streams/<stream-id>

    replace/get/delete stream

    streams

    prefix/plugins

    /1/plugins

    get list of active plugins

    prefix/streams/logs

    /1/streams/logs

    get/delete streams logs

    streams

    prefix/streams/<stream-id> /preview/handler/live

    /1/streams/<stream-id> /preview/handler/live

    get stream live preview

    streams streams

    prefix/streams/<stream-id> /preview/handler/frame

    /1/streams/logs /preview/handler/frame

    get stream frame preview

    streams streams

Enable plugin

If the user implements a plugin, the file with the plugin should be added to the luna_api/plugins directory of the service. The plugin filename should be added to the LUNA_API_ACTIVE_PLUGINS configuration setting.