actinia-cloudevent-plugin 0.1.0__py3-none-any.whl

actinia_cloudevent_plugin/__init__.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+"""Copyright (c) 2018-2025 mundialis GmbH & Co. KG.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+actinia plugin initalization
+"""
+
+__license__ = "GPLv3"
+__author__ = "Carmen Tawalika, Anika Weinmann"
+__copyright__ = "Copyright 2022 mundialis GmbH & Co. KG"
+__maintainer__ = "mundialis GmbH & Co. KG"
+
+
+import importlib.metadata
+
+try:
+    # Change here if project is renamed and does not equal the package name
+    DIST_NAME = __name__
+    __version__ = importlib.metadata.version(DIST_NAME)
+except Exception():
+    __version__ = "unknown"

actinia_cloudevent_plugin/api/__init__.py

@@ -0,0 +1,4 @@
+"""actinia-cloudevent-plugin API part of package.
+
+This part provides the API part of the actinia-cloudevent-plugin.
+"""

actinia_cloudevent_plugin/api/cloudevent.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python
+"""Copyright (c) 2025 mundialis GmbH & Co. KG.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Hello World class
+"""
+
+__license__ = "GPLv3"
+__author__ = "Lina Krisztian"
+__copyright__ = "Copyright 2025 mundialis GmbH & Co. KG"
+__maintainer__ = "mundialis GmbH & Co. KG"
+
+from flask import jsonify, make_response
+from flask_restful_swagger_2 import Resource, swagger
+from requests.exceptions import ConnectionError  # noqa: A004
+
+from actinia_cloudevent_plugin.apidocs import cloudevent
+from actinia_cloudevent_plugin.core.processing import (
+    cloud_event_to_process_chain,
+    receive_cloud_event,
+    send_binary_cloud_event,
+    # send_structured_cloud_event,
+)
+from actinia_cloudevent_plugin.model.response_models import (
+    SimpleStatusCodeResponseModel,
+)
+from actinia_cloudevent_plugin.resources.config import EVENTRECEIVER
+
+
+class Cloudevent(Resource):
+    """Cloudevent handling."""
+
+    def __init__(self) -> None:
+        """Cloudevent class initialisation."""
+        self.msg = (
+            "Received event <EVENT1> and returned event <EVENT2>"
+            " with actinia-job <ACTINIA_JOB>."
+        )
+
+    def get(self):
+        """Cloudevent get method: not allowed response."""
+        res = jsonify(
+            SimpleStatusCodeResponseModel(
+                status=405,
+                message="Method Not Allowed",
+            ),
+        )
+        return make_response(res, 405)
+
+    @swagger.doc(cloudevent.describe_cloudevent_post_docs)
+    def post(self) -> SimpleStatusCodeResponseModel:
+        """Cloudevent post method with cloudevent from postbody.
+
+        Receives cloudevent, transforms to process chain (pc),
+        sends pc to actinia + start process,
+        and returns cloudevent with queue name.
+        """
+        # Transform postbody to cloudevent
+        event_received = receive_cloud_event()
+        # With received process chain start actinia process + return cloudevent
+        actinia_job = cloud_event_to_process_chain(event_received)
+        # URL to which the generated cloudevent is sent
+        url = EVENTRECEIVER.url
+        # TODO: binary or structured cloud event?
+        # From https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#message
+        # A "structured-mode message" is one where the entire event (attributes and data)
+        # are encoded in the message body, according to a specific event format.
+        # A "binary-mode message" is one where the event data is stored in the message body,
+        # and event attributes are stored as part of message metadata.
+        # Often, binary mode is used when the producer of the CloudEvent wishes to add the
+        # CloudEvent's metadata to an existing event without impacting the message's body.
+        # In most cases a CloudEvent encoded as a binary-mode message will not break an
+        # existing receiver's processing of the event because the message's metadata
+        # typically allows for extension attributes.
+        # In other words, a binary formatted CloudEvent would work for both
+        # a CloudEvents enabled receiver as well as one that is unaware of CloudEvents.
+        try:
+            event_returned = send_binary_cloud_event(
+                event_received,
+                actinia_job,
+                url,
+            )
+            return SimpleStatusCodeResponseModel(
+                status=204,
+                message=self.msg.replace("<EVENT1>", event_received["id"])
+                .replace("<EVENT2>", event_returned["id"])
+                .replace("<ACTINIA_JOB>", actinia_job),
+            )
+        except ConnectionError as e:
+            return f"Connection ERROR when returning cloudevent: {e}"
+        except Exception() as e:
+            return f"ERROR when returning cloudevent: {e}"

actinia_cloudevent_plugin/apidocs/__init__.py

@@ -0,0 +1,4 @@
+"""actinia-cloudevent-plugin API DOCs part of package.
+
+This part provides the API DOCs part of the actinia-cloudevent-plugin.
+"""

actinia_cloudevent_plugin/apidocs/cloudevent.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python
+"""Copyright (c) 2025 mundialis GmbH & Co. KG.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Hello World class
+"""
+
+__license__ = "GPLv3"
+__author__ = "Lina Krisztian"
+__copyright__ = "Copyright 2025 mundialis GmbH & Co. KG"
+__maintainer__ = "mundialis GmbH & Co. KG"
+
+
+from actinia_cloudevent_plugin.model.response_models import (
+    SimpleStatusCodeResponseModel,
+)
+
+describe_cloudevent_post_docs = {
+    # "summary" is taken from the description of the get method
+    "tags": ["cloudevent"],
+    "description": (
+        "Receives cloudevent, transforms and starts pc and returns cloudevent."
+    ),
+    "responses": {
+        "200": {
+            "description": (
+                "This response returns received, and returned events, "
+                "generated queue name and the status"
+            ),
+            "schema": SimpleStatusCodeResponseModel,
+        },
+        "400": {
+            "description": "This response returns an error message",
+            "schema": SimpleStatusCodeResponseModel,
+        },
+    },
+}

actinia_cloudevent_plugin/core/__init__.py

@@ -0,0 +1,4 @@
+"""actinia-cloudevent-plugin core part of package.
+
+This part provides the core part of the actinia-cloudevent-plugin.
+"""

actinia_cloudevent_plugin/core/processing.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+"""Copyright (c) 2025 mundialis GmbH & Co. KG.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Example core functionality
+"""
+
+__license__ = "GPLv3"
+__author__ = "Lina Krisztian"
+__copyright__ = "Copyright 2025 mundialis GmbH & Co. KG"
+__maintainer__ = "mundialis GmbH & Co. KG"
+
+
+import requests
+from cloudevents.conversion import to_binary, to_structured
+from cloudevents.http import CloudEvent, from_http
+from flask import request
+
+
+def receive_cloud_event():
+    """Return cloudevent from postpody."""
+    # Parses CloudEvent 'data' and 'headers' into a CloudEvent.
+    event = from_http(request.headers, request.get_data())
+
+    # ? TODO
+    # eventually Filter the event (see example below)
+    event_type = event["type"]
+    if event_type == "com.example.object.created":
+        print("Object created event received!")
+
+    return event
+
+
+def cloud_event_to_process_chain(event) -> str:
+    """Return queue name for process chain of event."""
+    # (Remove ruff-exception, when pc variable used)
+    pc = event.get_data()["list"][0]  # noqa: F841
+    # !! TODO !!: pc to job
+    # NOTE: as standalone app -> consider for queue name creation
+    # HTTP POST pc to actinia-module plugin processing endpoint
+    # # # include an identifier for grouping cloudevents of same actinia process (?)
+    # # # (e.g. new metadata field "queue_name", or within data, or use existign id)
+    # -> actinia core returns resource-url, including resource_id  (and queue name)
+    #   (queuename = xx_<resource_id>; if configured accordingly within actinia -> each job own queue)
+    # via knative jobsink: start actinia worker (with queue name)
+    # (https://knative.dev/docs/eventing/sinks/job-sink/#usage)
+    # e.g. HTTP POST with queue name
+    # kubectl run curl --image=curlimages/curl --rm=true --restart=Never -ti -- -X POST -v \
+    #    -H "content-type: application/json"  \
+    #    -H "ce-specversion: 1.0" \
+    #    -H "ce-source: my/curl/command" \
+    #    -H "ce-type: my.demo.event" \
+    #    -H "ce-id: 123" \
+    #    -d '{"details":"queuename"}' \
+    #    http://job-sink.knative-eventing.svc.cluster.local/default/job-sink-logger
+    return "<queue_name>_<resource_id>"  # queue name and resource id
+
+
+def send_binary_cloud_event(event, actinia_job, url):
+    """Return posted binary event with actinia_job."""
+    attributes = {
+        "specversion": event["specversion"],
+        "source": "/actinia-cloudevent-plugin",
+        "type": "com.mundialis.actinia.process.started",
+        "subject": event["subject"],
+        "datacontenttype": "application/json",
+    }
+    data = {"actinia_job": actinia_job}
+
+    event = CloudEvent(attributes, data)
+    headers, body = to_binary(event)
+    # send event
+    requests.post(url, headers=headers, data=body)
+
+    return event
+
+
+def send_structured_cloud_event(event, actinia_job, url):
+    """Return posted structured event with actinia_job."""
+    attributes = {
+        "specversion": event["specversion"],
+        "source": "/actinia-cloudevent-plugin",
+        "type": "com.mundialis.actinia.process.started",
+        "subject": event["subject"],
+        "datacontenttype": "application/json",
+    }
+    data = {"actinia_job": actinia_job}
+
+    event = CloudEvent(attributes, data)
+    headers, body = to_structured(event)
+    # send event
+    requests.post(url, headers=headers, data=body)
+
+    return event

actinia_cloudevent_plugin/endpoints.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+"""Copyright (c) 2018-2025 mundialis GmbH & Co. KG.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Add endpoints to flask app with endpoint definitions and routes
+"""
+
+__license__ = "GPLv3"
+__author__ = "Carmen Tawalika, Anika Weinmann, Lina Krisztian"
+__copyright__ = "Copyright 2022-2024 mundialis GmbH & Co. KG"
+__maintainer__ = "mundialis GmbH & Co. KG"
+
+
+import sys
+
+import werkzeug
+from flask import current_app, send_from_directory
+from flask_restful_swagger_2 import Api
+
+from actinia_cloudevent_plugin.api.cloudevent import Cloudevent
+from actinia_cloudevent_plugin.resources.logging import log
+
+
+# endpoints loaded if run as actinia-core plugin as well as standalone app
+def create_endpoints(flask_api: Api) -> None:
+    """Create plugin endpoints."""
+    app = flask_api.app
+    apidoc = flask_api
+
+    package = sys._getframe().f_back.f_globals["__package__"]  # noqa: SLF001
+    if package != "actinia_core":
+
+        @app.route("/")
+        def index():
+            try:
+                return current_app.send_static_file("index.html")
+            except werkzeug.exceptions.NotFound:
+                log.debug("No index.html found. Serving backup.")
+                # when actinia-cloudevent-plugin is installed in single mode,
+                # the swagger endpoint would be "latest/api/swagger.json".
+                # As api docs exist in single mode,
+                # use this fallback for plugin mode.
+                return """<h1 style='color:red'>actinia-metadata-plugin</h1>
+                    <a href="api/v1/swagger.json">API docs</a>"""
+
+        @app.route("/<path:filename>")
+        def static_content(filename):
+            # WARNING: all content from folder "static" will be accessible!
+            return send_from_directory(app.static_folder, filename)
+
+    apidoc.add_resource(Cloudevent, "/")

actinia_cloudevent_plugin/main.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+"""Copyright (c) 2025 mundialis GmbH & Co. KG.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+Application entrypoint. Creates Flask app and swagger docs, adds endpoints
+"""
+
+__author__ = "Carmen Tawalika, Lina Krisztian"
+__copyright__ = "2025-present mundialis GmbH & Co. KG"
+__license__ = "Apache-2.0"
+
+
+from flask import Flask
+from flask_cors import CORS
+from flask_restful_swagger_2 import Api
+
+from actinia_cloudevent_plugin.endpoints import create_endpoints
+from actinia_cloudevent_plugin.resources.logging import log
+
+flask_app = Flask(__name__)
+# allows endpoints with and without trailing slashes
+flask_app.url_map.strict_slashes = False
+CORS(flask_app)
+
+
+API_VERSION = "v1"
+
+URL_PREFIX = f"/api/{API_VERSION}"
+
+apidoc = Api(
+    flask_app,
+    title="actinia-cloudevent-plugin",
+    prefix=URL_PREFIX,
+    api_version=API_VERSION,
+    api_spec_url=f"{URL_PREFIX}/swagger",
+    schemes=["https", "http"],
+    consumes=["application/json"],
+    description="""Receives cloudevent,
+                   transforms it to an actinia process chain
+                   and returns cloudevent back.
+                   """,
+)
+
+create_endpoints(apidoc)
+
+
+if __name__ == "__main__":
+    # call this for development only with:
+    # `python3 -m actinia_cloudevent_plugin.main`
+    log.debug("starting app in development mode...")
+    # ruff: S201 :Use of `debug=True` in Flask app detected
+    flask_app.run(debug=True, use_reloader=False)  # noqa: S201
+    # for production environent use application in wsgi.py

actinia_cloudevent_plugin/model/__init__.py

@@ -0,0 +1,4 @@
+"""actinia-cloudevent-plugin model part of package.
+
+This part provides the model part of the actinia-cloudevent-plugin.
+"""

actinia_cloudevent_plugin/model/response_models.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python
+"""Copyright (c) 2018-2024 mundialis GmbH & Co. KG.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Response models
+"""
+
+__license__ = "GPLv3"
+__author__ = "Anika Weinmann"
+__copyright__ = "Copyright 2022 mundialis GmbH & Co. KG"
+__maintainer__ = "mundialis GmbH & Co. KG"
+
+
+from typing import ClassVar
+
+from flask_restful_swagger_2 import Schema
+
+
+class SimpleStatusCodeResponseModel(Schema):
+    """Simple response schema to inform about status."""
+
+    type: str = "object"
+    properties: ClassVar[dict] = {
+        "status": {
+            "type": "number",
+            "description": "The status code of the request.",
+        },
+        "message": {
+            "type": "string",
+            "description": "A short message to describes the status",
+        },
+    }
+    required: ClassVar[list[str]] = ["status", "message"]
+
+
+simple_response_example = SimpleStatusCodeResponseModel(
+    status=200,
+    message="success",
+)
+SimpleStatusCodeResponseModel.example = simple_response_example

actinia_cloudevent_plugin/resources/__init__.py

@@ -0,0 +1,4 @@
+"""actinia-cloudevent-plugin resources part of package.
+
+This part provides the Resources part of the actinia-cloudevent-plugin.
+"""

actinia_cloudevent_plugin/resources/config.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+"""Copyright (c) 2018-2025 mundialis GmbH & Co. KG.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+Configuration file
+"""
+
+__author__ = "Carmen Tawalika, Lina Krisztian"
+__copyright__ = "2018-2025 mundialis GmbH & Co. KG"
+__license__ = "Apache-2.0"
+
+
+import configparser
+from pathlib import Path
+
+# config can be overwritten by mounting *.ini files into folders inside
+# the config folder.
+DEFAULT_CONFIG_PATH = "config"
+CONFIG_FILES = [
+    str(f) for f in Path(DEFAULT_CONFIG_PATH).glob("**/*.ini") if f.is_file()
+]
+GENERATED_CONFIG = DEFAULT_CONFIG_PATH + "/actinia-cloudevent-plugin.cfg"
+
+
+class EVENTRECEIVER:
+    """Default config for cloudevent receiver."""
+
+    url = "http://localhost:3000/"
+
+
+class LOGCONFIG:
+    """Default config for logging."""
+
+    logfile = "actinia-cloudevent-plugin.log"
+    level = "INFO"
+    type = "stdout"
+
+
+class Configfile:
+    """Configuration file."""
+
+    def __init__(self) -> None:
+        """Overwrite config classes.
+
+        Will overwrite the config classes above when config files
+        named DEFAULT_CONFIG_PATH/**/*.ini exist.
+        On first import of the module it is initialized.
+        """
+        config = configparser.ConfigParser()
+        config.read(CONFIG_FILES)
+        if len(config) <= 1:
+            print("Could not find any config file, using default values.")
+            return
+        print("Loading config files: " + str(CONFIG_FILES) + " ...")
+
+        with open(  # noqa: PTH123
+            GENERATED_CONFIG,
+            "w",
+            encoding="utf-8",
+        ) as configfile:
+            config.write(configfile)
+        print("Configuration written to " + GENERATED_CONFIG)
+
+        # LOGGING
+        if config.has_section("LOGCONFIG"):
+            if config.has_option("LOGCONFIG", "logfile"):
+                LOGCONFIG.logfile = config.get("LOGCONFIG", "logfile")
+            if config.has_option("LOGCONFIG", "level"):
+                LOGCONFIG.level = config.get("LOGCONFIG", "level")
+            if config.has_option("LOGCONFIG", "type"):
+                LOGCONFIG.type = config.get("LOGCONFIG", "type")
+
+        # EVENTRECEIVER
+        if config.has_section("EVENTRECEIVER"):
+            if config.has_option("EVENTRECEIVER", "url"):
+                EVENTRECEIVER.url = config.get("EVENTRECEIVER", "url")
+
+
+init = Configfile()