unitelabs-cdk 0.2.4__py3-none-any.whl

unitelabs/cdk/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import version
+
+from .compose_app import AppFactory, compose_app
+from .config import Config
+from .connector import Connector
+from .logging import create_logger
+
+__version__ = version("unitelabs_cdk")
+__all__ = ["__version__", "Connector", "Config", "create_logger", "compose_app", "AppFactory"]

unitelabs/cdk/cli/__init__.py

@@ -0,0 +1,4 @@
+from .certificate import certificate
+from .connector import connector
+
+__all__ = ["certificate", "connector"]

unitelabs/cdk/cli/certificate.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import pathlib
+
+import click
+from sila import server
+
+from unitelabs.cdk import Config
+
+config = Config()
+
+
+@click.group()
+def certificate() -> None:
+    """Utility tool to handle certificates for TLS encryption."""
+
+
+@certificate.command()
+@click.option(
+    "--uuid",
+    type=str,
+    default=config.sila_server.get("uuid", None),
+    required=True,
+    help="The SiLA server's uuid.",
+)
+@click.option(
+    "--host",
+    type=str,
+    default=lambda: config.sila_server.get("host", "0.0.0.0"),
+    help="The SiLA server's host address.",
+)
+@click.option(
+    "--target",
+    "-t",
+    type=str,
+    default=".",
+    help="The output directory in which to store the certificate files.",
+)
+def generate(uuid: str, host: str, target: str):
+    """Generates a new self-signed certificate according to the SiLA 2 specification."""
+    key, cert = server.generate_certificate(uuid, host)
+
+    directory = pathlib.Path(target)
+    directory.mkdir(parents=True, exist_ok=True)
+    (directory / "cert.pem").write_bytes(cert)
+    (directory / "key.pem").write_bytes(key)
+
+
+if __name__ == "__main__":
+    certificate()

unitelabs/cdk/cli/connector.py

@@ -0,0 +1,59 @@
+import importlib
+import importlib.machinery
+import importlib.metadata
+import importlib.util
+import logging
+
+import click
+
+from unitelabs.cdk import AppFactory, compose_app, utils
+
+
+@click.group()
+def connector() -> None:
+    """Base cli"""
+
+
+@connector.command()
+@click.option(
+    "--app",
+    type=str,
+    metavar="IMPORT",
+    default=utils.find_factory,
+    help="The application factory function to load, in the form 'module:name'.",
+)
+@click.option(
+    "-v",
+    "--verbose",
+    count=True,
+    help="Increase the verbosity of to debug.",
+)
+@utils.coroutine
+async def start(app, verbose: int):
+    """Application Entrypoint"""
+    log_level = logging.DEBUG if verbose > 0 else logging.INFO
+
+    create_app = await load_create_app(app)
+    app = await compose_app(create_app, log_level=log_level)
+
+    await app.start()
+
+
+async def load_create_app(location: str) -> AppFactory:
+    """
+    Dynamically import the application factory from the given location.
+
+    Args:
+      location: Where to find the app factory formatted as "module:name".
+    """
+
+    module_name, _, factory_name = location.partition(":")
+
+    module = importlib.import_module(module_name)
+    create_app = getattr(module, factory_name)
+
+    return create_app
+
+
+if __name__ == "__main__":
+    connector()

unitelabs/cdk/compose_app.py

@@ -0,0 +1,147 @@
+import collections.abc
+import functools
+import inspect
+import logging
+import signal
+import sys
+import types
+import typing
+
+from .connector import Connector
+from .logging import create_logger
+
+T = typing.TypeVar("T")
+
+
+Generator = typing.Union[
+    collections.abc.Generator[T, None, None],
+    collections.abc.AsyncGenerator[T, None],
+]
+
+
+AppFactory = collections.abc.Callable[
+    ...,
+    typing.Union[
+        Connector,
+        collections.abc.Awaitable[Connector],
+        Generator,
+    ],
+]
+
+
+async def compose_app(create_app: AppFactory, log_level: int = logging.INFO) -> Connector:
+    """
+    Creates and configures a ready to use Connector.
+
+    Args:
+      create_app: The factory method used to create the Connector instance.
+
+    Returns:
+      The newly created Connector.
+
+    Raises:
+      ValueError: If create_app does not follow the required interface.
+    """
+
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+
+    create_logger("sila", log_level)
+    create_logger("unitelabs", log_level)
+
+    app = await init_app(app_factory=create_app)
+
+    return app
+
+
+# pylint: disable-next=unused-argument
+def signal_handler(signum: int, frame: typing.Optional[types.FrameType]) -> None:
+    """
+    Gracefully handle received signals.
+
+    Args:
+      signum: The signal number.
+      frame: The current stack frame.
+    """
+
+    sys.exit(signum)
+
+
+async def init_app(app_factory: AppFactory) -> Connector:
+    """
+    Uses the provided factory method to init a new Connector.
+
+    Args:
+      app_factory: The factory method to call.
+
+    Returns:
+      The initialized Connector.
+
+    Raises:
+      ValueError: If app_factory does not follow the required interface.
+    """
+
+    if inspect.isasyncgenfunction(app_factory) or inspect.isgeneratorfunction(app_factory):
+        generator: Generator[Connector] = app_factory()
+        generator = _sync_to_async_gen(generator)
+
+        try:
+            app = await generator.__anext__()
+        except (StopAsyncIteration, StopIteration):
+            raise ValueError("Unable to create app: `create_app` did not yield a value.") from None
+
+        shutdown_handler = functools.partial(_shutdown_yield, generator)
+        app.on_shutdown(handler=shutdown_handler)
+
+        return app
+
+    if inspect.iscoroutinefunction(app_factory):
+        return await app_factory()
+
+    if inspect.isfunction(app_factory):
+        return app_factory()
+
+    raise ValueError(f"Invalid `create_app`: '{app_factory}'. Provide a callable function that returns a Connector.")
+
+
+async def _shutdown_yield(generator: collections.abc.AsyncGenerator[T, None]) -> None:
+    """
+    Execute the shutdown of a factory function by advancing the iterator
+    after the yield and ensure the iteration ends (if not it means there is
+    more than one yield in the function).
+
+    Args:
+      generator: The factory function to create the app.
+    """
+
+    try:
+        await generator.__anext__()
+    except (StopAsyncIteration, StopIteration):
+        pass
+    else:
+        await _shutdown_yield(generator)
+
+
+async def _sync_to_async_gen(generator: Generator[T]) -> collections.abc.AsyncGenerator[T, None]:
+    """
+    Wraps any generator into an async generator.
+
+    Args:
+      generator: The generator to wrap as async.
+
+    Returns:
+      The async generator.
+    """
+
+    if inspect.isasyncgen(generator):
+        async for item in generator:
+            yield item
+
+        return
+
+    if inspect.isgenerator(generator):
+        while True:
+            try:
+                yield next(generator)
+            except StopIteration:
+                return

unitelabs/cdk/config.py

@@ -0,0 +1,12 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from sila import cloud_connector, server
+
+
+class Config(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env", env_file_encoding="utf-8", env_nested_delimiter="__", extra="ignore"
+    )
+
+    environment: str = "development"
+    sila_server: server.ServerConfig = server.ServerConfig()
+    cloud_server_endpoint: cloud_connector.CloudServerEndpointConfig = cloud_connector.CloudServerEndpointConfig()

unitelabs/cdk/connector.py

@@ -0,0 +1,126 @@
+import asyncio
+import contextlib
+import logging
+import typing
+
+from sila import cloud_connector, discovery, server
+from unitelabs.cdk.features.core.sila_service import SiLAService
+
+from .config import Config
+
+Handler = typing.Callable[..., typing.Union[typing.Any, typing.Awaitable[typing.Any]]]
+
+
+class Connector:
+    """Main app"""
+
+    def __init__(self, config: typing.Optional[dict] = None):
+        self.__config = Config.parse_obj(config or {})
+
+        self._shutdown_handlers: list[Handler] = []
+
+        self._sila_server = server.Server(config=self.config.sila_server)
+        self.logger.debug(self._sila_server)
+        self._broadcaster = discovery.Broadcaster(self._sila_server)
+
+        self.config.cloud_server_endpoint["options"] = {
+            # The period (in milliseconds) after which a keepalive ping is sent on the transport.
+            "grpc.keepalive_time_ms": 60 * 1000,
+            # The amount of time (in milliseconds) the sender of the keepalive ping waits for an
+            # acknowledgement. If it does not receive an acknowledgment within this time, it will
+            # close the connection.
+            "grpc.keepalive_timeout_ms": 3 * 60 * 1000,
+            # If set to 1 (0 : false; 1 : true), allows keepalive pings to be sent even if there
+            # are no calls in flight.
+            "grpc.keepalive_permit_without_calls": 0,
+            # How many pings can the client send before needing to send a data/header frame.
+            "grpc.http2.max_pings_without_data": 0,
+        } | self.config.cloud_server_endpoint.get("options", {})
+
+        self._cloud_server_endpoint = cloud_connector.CloudServerEndpoint(
+            self._sila_server, self.config.cloud_server_endpoint
+        )
+
+        self.register(SiLAService())
+
+    def register(self, feature: server.Feature):
+        """Register a new feature to this driver"""
+        self.logger.debug("Added feature: %s", feature)
+        self._sila_server.add_feature(feature)
+
+    async def start(self):
+        """
+        Start the connector and all related services.
+        """
+
+        try:
+            await asyncio.gather(
+                asyncio.create_task(self._sila_server.start()),
+                asyncio.create_task(self._broadcaster.start()),
+                asyncio.create_task(self._cloud_server_endpoint.start()),
+            )
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await self.close()
+
+    async def close(self):
+        """
+        Close the connector and all related services.
+        """
+
+        for shutdown_handler in self._shutdown_handlers:
+            with contextlib.suppress(Exception):
+                if asyncio.iscoroutinefunction(shutdown_handler):
+                    await shutdown_handler()
+                else:
+                    shutdown_handler()
+
+    @property
+    def config(self) -> Config:
+        return self.__config
+
+    @property
+    def sila_server(self) -> server.Server:
+        return self._sila_server
+
+    @property
+    def logger(self) -> logging.Logger:
+        """A standard Python :class:`~logging.Logger` for the app."""
+        return logging.getLogger(__package__)
+
+    @property
+    def debug(self) -> bool:
+        """Whether debug mode is enabled."""
+        return True
+
+    def on_shutdown(self, handler: Handler) -> None:
+        """
+        Add a shutdown hook to be called in the terminating phase (in response
+        to an explicit call to `app.close()` or upon receipt of system signals
+        such as SIGINT or SIGTERM).
+
+        Args:
+          handler: The method to be called on shutdown.
+
+        Raises:
+          TypeError: If the `handler` argument is not callable.
+        """
+
+        if not callable(handler):
+            raise TypeError("The `handler` argument must be callable.")
+
+        self._shutdown_handlers.append(handler)
+
+    def off_shutdown(self, handler: Handler) -> None:
+        """
+        Remove a previously added shutdown hook.
+
+        Args:
+          handler: The handler to be removed from the shutdown hooks.
+        """
+
+        try:
+            self._shutdown_handlers.remove(handler)
+        except ValueError:
+            pass

unitelabs/cdk/features/core/lock_controller/LockController-v2_0.proto

@@ -0,0 +1,67 @@
+syntax = "proto3";
+
+import "SiLAFramework.proto";
+
+package sila2.org.silastandard.core.lockcontroller.v2;
+
+/* This Feature allows a SiLA Client to lock a SiLA Server for exclusive use, preventing other SiLA Clients from using the SiLA Server while it is locked. To lock a SiLA Server a Lock Identifier has to be set, using the 'LockServer' command. This Lock Identifier has to be sent along with every (lock protected) request to the SiLA Server in order to use its functionality. To send the lock identifier the SiLA Client Meta Data 'LockIdentifier' has to be used. When locking a SiLA Server a timeout can be specified that defines the time after which the SiLA Server will be automatically unlocked if no request with a valid lock identifier has been received meanwhile. After the timeout has expired or after explicit unlock no lock identifier has to be sent any more. */
+service LockController {
+  /* Locks a SiLA Server for exclusive use by setting a lock identifier that has to be sent along with any following (lock protected) request as long as the SiLA Server is locked. The lock can be reset by issuing the 'Unlock Server' command. */
+  rpc LockServer (sila2.org.silastandard.core.lockcontroller.v2.LockServer_Parameters) returns (sila2.org.silastandard.core.lockcontroller.v2.LockServer_Responses) {}
+  /* Unlocks a locked SiLA Server. No lock identifier has to be sent for any following calls until the server is locked again via the 'Lock Server' command. */
+  rpc UnlockServer (sila2.org.silastandard.core.lockcontroller.v2.UnlockServer_Parameters) returns (sila2.org.silastandard.core.lockcontroller.v2.UnlockServer_Responses) {}
+  /* 
+      Returns true if the SiLA Server is currently locked or false else.
+
+      This property MUST NOT be lock protected, so that any SiLA Client can query the current lock state
+      of a SiLA Server.
+     */
+  rpc Subscribe_IsLocked (sila2.org.silastandard.core.lockcontroller.v2.Subscribe_IsLocked_Parameters) returns (stream sila2.org.silastandard.core.lockcontroller.v2.Subscribe_IsLocked_Responses) {}
+  /* Get fully qualified identifiers of all features, commands and properties affected by LockIdentifier */
+  rpc Get_FCPAffectedByMetadata_LockIdentifier (sila2.org.silastandard.core.lockcontroller.v2.Get_FCPAffectedByMetadata_LockIdentifier_Parameters) returns (sila2.org.silastandard.core.lockcontroller.v2.Get_FCPAffectedByMetadata_LockIdentifier_Responses) {}
+}
+
+/* Parameters for LockServer */
+message LockServer_Parameters {
+  sila2.org.silastandard.String LockIdentifier = 1;  /* The lock identifier that has to be sent along with every (lock protected) request to use the server's functionality. */
+  sila2.org.silastandard.Integer Timeout = 2;  /* The time (in seconds) after a SiLA Server is automatically unlocked when no request with a valid lock identifier has been received meanwhile. A timeout of zero seconds specifies an infinite time (no timeout). */
+}
+
+/* Responses of LockServer */
+message LockServer_Responses {
+}
+
+/* Parameters for UnlockServer */
+message UnlockServer_Parameters {
+  sila2.org.silastandard.String LockIdentifier = 1;  /* The lock identifier that has been used to lock the SiLA Server. */
+}
+
+/* Responses of UnlockServer */
+message UnlockServer_Responses {
+}
+
+/* Parameters for IsLocked */
+message Subscribe_IsLocked_Parameters {
+}
+
+/* Responses of IsLocked */
+message Subscribe_IsLocked_Responses {
+  sila2.org.silastandard.Boolean IsLocked = 1;  /* Returns true if the SiLA Server is currently locked or false else. This property MUST NOT be lock protected, so that any SiLA Client can query the current lock state of a SiLA Server. */
+}
+
+/* Parameters for Get_FCPAffectedByMetadata_LockIdentifier */
+message Get_FCPAffectedByMetadata_LockIdentifier_Parameters {
+}
+
+/* Responses of Get_FCPAffectedByMetadata_LockIdentifier */
+message Get_FCPAffectedByMetadata_LockIdentifier_Responses {
+  repeated sila2.org.silastandard.String AffectedCalls = 1;  /* Fully qualified identifiers of all features, commands and properties affected by LockIdentifier */
+}
+
+/* 
+      The lock identifier has to be sent with every (lock protected) call in order to use the functionality
+      of a locked SiLA Server.
+     */
+message Metadata_LockIdentifier {
+  sila2.org.silastandard.String LockIdentifier = 1;  /* The lock identifier has to be sent with every (lock protected) call in order to use the functionality of a locked SiLA Server. */
+}

unitelabs/cdk/features/core/lock_controller/LockController-v2_0.sila.xml

@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<Feature SiLA2Version="1.0" FeatureVersion="2.0" MaturityLevel="Draft" Originator="org.silastandard" Category="core"
+         xmlns="http://www.sila-standard.org"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://www.sila-standard.org https://gitlab.com/SiLA2/sila_base/raw/master/schema/FeatureDefinition.xsd">
+  <Identifier>LockController</Identifier>
+  <DisplayName>Lock Controller</DisplayName>
+  <Description>
+    This Feature allows a SiLA Client to lock a SiLA Server for exclusive use, preventing other SiLA Clients
+    from using the SiLA Server while it is locked. To lock a SiLA Server a Lock Identifier has to be set, using the
+    'LockServer' command. This Lock Identifier has to be sent along with every (lock protected)
+    request to the SiLA Server in order to use its functionality.
+
+    To send the lock identifier the SiLA Client Meta Data 'LockIdentifier' has to be used.
+
+    When locking a SiLA Server a timeout can be specified that defines the time after which the SiLA Server will
+    be automatically unlocked if no request with a valid lock identifier has been received meanwhile.
+    After the timeout has expired or after explicit unlock no lock identifier has to be sent any more.
+  </Description>
+  <Command>
+    <Identifier>LockServer</Identifier>
+    <DisplayName>Lock Server</DisplayName>
+    <Description>
+      Locks a SiLA Server for exclusive use by setting a lock identifier that has to be sent along with
+      any following (lock protected) request as long as the SiLA Server is locked.
+      The lock can be reset by issuing the 'Unlock Server' command.
+    </Description>
+    <Observable>No</Observable>
+    <Parameter>
+      <Identifier>LockIdentifier</Identifier>
+      <DisplayName>Lock Identifier</DisplayName>
+      <Description>
+        The lock identifier that has to be sent along with every (lock protected) request to use the server's
+        functionality.
+      </Description>
+      <DataType>
+        <Basic>String</Basic>
+      </DataType>
+    </Parameter>
+    <Parameter>
+      <Identifier>Timeout</Identifier>
+      <DisplayName>Timeout</DisplayName>
+      <Description>
+        The time (in seconds) after a SiLA Server is automatically unlocked when no request with a valid lock identifier
+        has been received meanwhile. A timeout of zero seconds specifies an infinite time (no timeout).
+      </Description>
+      <DataType>
+        <Constrained>
+          <DataType>
+            <Basic>Integer</Basic>
+          </DataType>
+          <Constraints>
+            <Unit>
+              <Label>s</Label>
+              <Factor>1</Factor>
+              <Offset>0</Offset>
+              <UnitComponent>
+                <SIUnit>Second</SIUnit>
+                <Exponent>1</Exponent>
+              </UnitComponent>
+            </Unit>
+          </Constraints>
+        </Constrained>
+      </DataType>
+    </Parameter>
+    <DefinedExecutionErrors>
+      <Identifier>ServerAlreadyLocked</Identifier>
+    </DefinedExecutionErrors>
+  </Command>
+  <Command>
+    <Identifier>UnlockServer</Identifier>
+    <DisplayName>Unlock Server</DisplayName>
+    <Description>
+      Unlocks a locked SiLA Server. No lock identifier has to be sent for any following calls until
+      the server is locked again via the 'Lock Server' command.
+    </Description>
+    <Observable>No</Observable>
+    <Parameter>
+      <Identifier>LockIdentifier</Identifier>
+      <DisplayName>Lock Identifier</DisplayName>
+      <Description>The lock identifier that has been used to lock the SiLA Server.</Description>
+      <DataType>
+        <Basic>String</Basic>
+      </DataType>
+    </Parameter>
+    <DefinedExecutionErrors>
+      <Identifier>ServerNotLocked</Identifier>
+      <Identifier>InvalidLockIdentifier</Identifier>
+    </DefinedExecutionErrors>
+  </Command>
+  <Property>
+    <Identifier>IsLocked</Identifier>
+    <DisplayName>Is Locked</DisplayName>
+    <Description>
+      Returns true if the SiLA Server is currently locked or false else.
+
+      This property MUST NOT be lock protected, so that any SiLA Client can query the current lock state
+      of a SiLA Server.
+    </Description>
+    <Observable>Yes</Observable>
+    <DataType>
+      <Basic>Boolean</Basic>
+    </DataType>
+  </Property>
+  <Metadata>
+    <Identifier>LockIdentifier</Identifier>
+    <DisplayName>Lock Identifier</DisplayName>
+    <Description>
+      The lock identifier has to be sent with every (lock protected) call in order to use the functionality
+      of a locked SiLA Server.
+    </Description>
+    <DataType>
+      <Basic>String</Basic>
+    </DataType>
+    <DefinedExecutionErrors>
+      <Identifier>InvalidLockIdentifier</Identifier>
+    </DefinedExecutionErrors>
+  </Metadata>
+  <DefinedExecutionError>
+    <Identifier>InvalidLockIdentifier</Identifier>
+    <DisplayName>Invalid Lock Identifier</DisplayName>
+    <Description>The sent lock identifier is not valid.</Description>
+  </DefinedExecutionError>
+  <DefinedExecutionError>
+    <Identifier>ServerAlreadyLocked</Identifier>
+    <DisplayName>Server Already Locked</DisplayName>
+    <Description>The SiLA Server can not be locked because it is already locked.</Description>
+  </DefinedExecutionError>
+  <DefinedExecutionError>
+    <Identifier>ServerNotLocked</Identifier>
+    <DisplayName>Server Not Locked</DisplayName>
+    <Description>The SiLA Server can not be unlocked because it is not locked.</Description>
+  </DefinedExecutionError>
+</Feature>

unitelabs/cdk/features/core/lock_controller/__init__.py

@@ -0,0 +1,15 @@
+from .lock_controller import LockController
+from .lock_controller_base import (
+    InvalidLockIdentifier,
+    LockControllerBase,
+    ServerAlreadyLocked,
+    ServerNotLocked,
+)
+
+__all__ = [
+    "LockController",
+    "LockControllerBase",
+    "InvalidLockIdentifier",
+    "ServerAlreadyLocked",
+    "ServerNotLocked",
+]