@camera.ui/server 0.0.1

package/dist/server/src/polyglot/python/plugins/schema.py

@@ -0,0 +1,392 @@
+import re
+from typing import Any, Union
+
+from camera_ui_types import (
+    JsonSchema,
+    JsonSchemaArray,
+    JsonSchemaBoolean,
+    JsonSchemaEnum,
+    JsonSchemaNumber,
+    JsonSchemaObject,
+    JsonSchemaObjectWithButtons,
+    JsonSchemaString,
+    PluginJsonSchema,
+    PluginJsonSchemaForm,
+    PluginRootSchema,
+    RootSchema,
+)
+
+
+def config_path_to_schema_path(config_path: str) -> str:
+    """
+    Converts a configuration path to a schema path by handling array indices and nested properties.
+
+    This function transforms the config path to match the structure expected by a JSON schema. For instance, converting array
+    indices and adding 'properties' keywords as needed to represent the hierarchical structure of the schema.
+
+    :param config_path: A dot-separated path string representing the location of a configuration item.
+    :return: A dot-separated path string adjusted to align with JSON schema structure.
+    """
+    path_parts = config_path.split(".")
+    schema_path_parts: list[str] = []
+
+    for index, part in enumerate(path_parts):
+        is_numeric_index = bool(re.match(r"^\d+$", part))
+        is_last_part = index == len(path_parts) - 1
+
+        if is_numeric_index:
+            schema_path_parts.extend(["items", "properties"])
+        else:
+            schema_path_parts.append(part)
+            if not is_last_part and not re.match(r"^\d+$", path_parts[index + 1]):
+                schema_path_parts.append("properties")
+
+    return ".".join(schema_path_parts)
+
+
+def generate_json_from_root_schema(
+    root_schema: Union[RootSchema, PluginRootSchema],
+) -> dict[str, Any]:
+    """
+    Generates a default JSON object based on the provided root schema. This function iterates through the schema's properties,
+    creating a nested JSON object that matches the structure of the schema with default values where specified.
+
+    :param root_schema: The root schema object which defines the structure and default values for the JSON object.
+    :return: A JSON object that conforms to the provided schema.
+    """
+    json_object: dict[str, Any] = {}
+
+    for key, json_schema in root_schema["schema"].items():
+        schema: Any = json_schema
+        json_object[key] = generate_json_from_schema(schema)
+
+    return json_object
+
+
+def generate_json_from_schema(
+    json_schema: Union[JsonSchema, PluginJsonSchema],
+) -> Any:
+    """
+    Generates JSON data based on a single schema definition. Depending on the schema type, this may generate a string, number,
+    boolean, object, or array, incorporating default values and nested structures as defined in the schema.
+
+    :param json_schema: The JSON schema from which to generate data.
+    :return: Generated JSON data that conforms to the specified schema.
+    """
+    schema_type = json_schema.get("type")
+
+    if schema_type in ["string", "number", "boolean"]:
+        if "enum" in json_schema:
+            if json_schema.get("multiple"):
+                return [json_schema.get("defaultValue")] if "defaultValue" in json_schema else []
+            else:
+                return json_schema.get(
+                    "defaultValue",
+                    json_schema["enum"][0] if json_schema.get("required", False) else None,
+                )
+        else:
+            return json_schema.get("defaultValue")
+    elif schema_type == "object":
+        properties: Any = json_schema.get("properties")
+        if properties:
+            return {k: generate_json_from_schema(v) for k, v in properties.items()}
+        return {}
+    elif schema_type == "array":
+        items = json_schema.get("items")
+        if items:
+            return [generate_json_from_schema(items)]
+        return []
+    else:
+        return None
+
+
+def get_value_by_path(obj: dict[Any, Any], path: str) -> Any:
+    """
+    Retrieves a value from a nested object or a list based on a dot-separated path. If the path includes indices for accessing
+    array elements, these are handled accordingly. If any part of the path is not found, None is returned.
+
+    :param obj: The object or list from which to retrieve the value.
+    :param path: A dot-separated path string representing the location of the item.
+    :return: The value at the specified path, or None if the path is not found.
+    """
+
+    keys: list[str] = []
+    for key in path.split("."):
+        if "[" in key:
+            path_key, index = key.split("[")
+            keys.append(path_key)
+            keys.append(index[:-1])
+        else:
+            keys.append(key)
+
+    current = obj
+    for key in keys:
+        if current is None:
+            return None
+        current = current.get(key)
+
+    return current
+
+
+def remove_functions_from_schema_form(
+    schema_form: PluginJsonSchemaForm,
+) -> PluginJsonSchemaForm:
+    """
+    Removes 'onSet' and 'onGet' functions from a schema form, making it suitable for serialization or scenarios where these
+    executable functions should not be included. This is particularly useful for preparing a schema for transmission over a
+    network or storing in a format that does not support functions.
+
+    :param schema_form: The schema form from which to remove functions.
+    :return: A new schema form with the functions removed.
+    """
+    filtered_schema_form: PluginJsonSchemaForm = {}
+
+    for key, value in schema_form.items():
+        json_schema: Any = value
+        filtered_schema_form[key] = remove_functions_from_schema(json_schema)
+
+    return filtered_schema_form
+
+
+def remove_functions_from_schema(
+    json_schema: PluginJsonSchema,
+) -> Any:
+    """
+    Similar to 'remove_functions_from_schema_form', but operates on a single schema object. It removes 'onSet' and 'onGet'
+    functions if present.
+
+    :param json_schema: The individual schema from which to remove functions.
+    :return: A new schema with the functions removed.
+    """
+    filtered_schema = {k: v for k, v in json_schema.items() if k not in ["onSet", "onGet"]}
+
+    if is_object_type(filtered_schema) and "properties" in filtered_schema:
+        filtered_schema["properties"] = remove_functions_from_schema_form(
+            filtered_schema["properties"]  # type: ignore
+        )
+
+    return filtered_schema
+
+
+def schema_path_to_config_path(schema_path: str) -> str:
+    """
+    Converts a schema path back to a configuration path by removing 'properties' and 'items' keywords, effectively reversing
+    the operation performed by 'config_path_to_schema_path'. This is useful for mapping a location within a schema to a
+    corresponding location in a configuration object or file.
+
+    :param schema_path: A dot-separated path string representing the location within a schema.
+    :return: A dot-separated path string representing the corresponding location within a configuration.
+    """
+    path_parts = schema_path.split(".")
+    config_path_parts: list[str] = []
+
+    for part in path_parts:
+        if part != "properties" and part != "items":
+            is_numeric_index = bool(re.match(r"^\d+$", part))
+            if is_numeric_index:
+                config_path_parts.append(f"[{part}]")
+            else:
+                config_path_parts.append(part)
+
+    return ".".join(config_path_parts)
+
+
+def generate_number_schema(value: float) -> JsonSchemaNumber:
+    """
+    Generates a JSON schema definition for a number.
+
+    :param value: The default number value to include in the schema (unused in this function but can be utilized for default values or examples).
+    :return: A JSON schema dictionary for a number type.
+    """
+    schema: JsonSchemaNumber = {"type": "number"}
+    return schema
+
+
+def generate_boolean_schema(value: bool) -> JsonSchemaBoolean:
+    """
+    Generates a JSON schema definition for a boolean.
+
+    :param value: The default boolean value to include in the schema (unused in this function but can be utilized for default values or examples).
+    :return: A JSON schema dictionary for a boolean type.
+    """
+    schema: JsonSchemaBoolean = {"type": "boolean"}
+    return schema
+
+
+def generate_string_schema(value: str) -> JsonSchemaString:
+    """
+    Generates a JSON schema definition for a string, including format detection for known formats such as date-time, email, UUID, and IP addresses based on the provided value.
+
+    :param value: A string example used to infer the format of the string in the schema.
+    :return: A JSON schema dictionary for a string type, possibly including a specific format.
+    """
+    string_object: JsonSchemaString = {"type": "string"}
+
+    iso8601_date_time = re.compile(r"^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(.\d+)?(Z|[+-]\d{2}:\d{2})?)?$")
+
+    time_with_seconds = re.match(r"^([01]?[0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])$", value)
+    time_without_seconds = re.match(r"^([01]?[0-9]|2[0-3]):([0-5][0-9])$", value)
+
+    if iso8601_date_time.match(value):
+        string_object["format"] = "date-time"
+    elif time_with_seconds or time_without_seconds:
+        string_object["format"] = "time"
+
+    if re.match(r"^\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,7}\b$", value):
+        string_object["format"] = "email"
+
+    if re.match(
+        r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
+        value,
+    ):
+        string_object["format"] = "uuid"
+
+    if re.match(r"^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$", value):
+        string_object["format"] = "ipv4"
+
+    if re.match(r"^\s*([0-9a-fA-F]{1,4}:){7}([0-9a-fA-F]{1,4})\s*$", value):
+        string_object["format"] = "ipv6"
+
+    return string_object
+
+
+def generate_enum_schema(value: list[str]) -> JsonSchemaEnum:
+    """
+    Generates a JSON schema definition for an enumeration, containing a set of predefined options.
+
+    :param value: A list of strings representing the possible values for the enumeration.
+    :return: A JSON schema dictionary for an enum type.
+    """
+    schema: JsonSchemaEnum = {"type": "string", "enum": value}
+    return schema
+
+
+def generate_object_schema(value: dict[str, Any]) -> JsonSchemaObject:
+    """
+    Generates a JSON schema definition for an object, including properties based on the provided dictionary. Each key-value pair in the dictionary is treated as a property name and value, respectively.
+
+    :param value: A dictionary representing the structure and default values of the object to be defined in the schema.
+    :return: A JSON schema dictionary for an object type, including properties definitions.
+    """
+    if not value.keys():
+        return {"type": "object"}
+
+    properties = {}
+    for key, val in value.items():
+        schema = generate_schema(val)
+
+        schema["key"] = key
+        schema["description"] = schema.get("description", f"Description for {key}")
+        schema["required"] = schema.get("required", True)
+        schema["readonly"] = schema.get("readonly", False)
+
+        properties[key] = schema
+
+    return {"type": "object", "properties": properties}
+
+
+def generate_object_schema_with_buttons(
+    value: dict[str, Any], buttons: list[dict[str, Any]]
+) -> JsonSchemaObjectWithButtons:
+    """
+    Generates a JSON schema definition for an object, similar to `generate_object_schema`, but also includes definitions for one or more action buttons that can be associated with the object.
+
+    :param value: A dictionary representing the structure and default values of the object.
+    :param buttons: A list of dictionaries, where each dictionary defines an action button associated with the object.
+    :return: A JSON schema dictionary for an object type, including properties and buttons definitions.
+    """
+    base_schema: Any = generate_object_schema(value)
+    if buttons:
+        base_schema["buttons"] = buttons
+    return base_schema
+
+
+def generate_array_schema(
+    array: Union[list[str], list[int], list[bool], list[dict[str, Any]]],
+) -> JsonSchemaArray:
+    """
+    Generates a JSON schema definition for an array. The type of items in the array is determined by inspecting the provided list. Supports arrays of objects, as well as arrays of primitive types.
+
+    :param array: A list containing example items that the array will hold. Used to infer the item type for the schema.
+    :return: A JSON schema dictionary for an array type.
+    """
+    if len(array) == 0:
+        schema: Any = {"type": "array"}
+        return schema
+
+    all_objects = all(isinstance(item, dict) for item in array)
+    all_strings = all(isinstance(item, str) for item in array)
+    all_numbers = all(isinstance(item, (int, float)) for item in array)
+
+    if all_objects:
+        item_schemas = [generate_schema(item) for item in array]
+        schema: Any = {
+            "type": "array",
+            "items": {"type": "object", "properties": item_schemas[0]},
+        }
+        return schema
+
+    if all_strings:
+        schema: Any = {"type": "array", "items": {"type": "string"}}
+        return schema
+
+    if all_numbers:
+        schema: Any = {"type": "array", "items": {"type": "number"}}
+        return schema
+
+    return {"type": "array", "items": {"type": "boolean"}}
+
+
+def generate_schema(value: Any) -> JsonSchema:
+    """
+    Determines the appropriate JSON schema based on the Python type of the provided value. This is a generic entry point for schema generation that delegates to specific functions based on the value type.
+
+    :param value: A value whose type is used to generate the corresponding JSON schema.
+    :return: A JSON schema dictionary appropriate to the type of the provided value.
+    """
+    if isinstance(value, (int, float)):
+        return generate_number_schema(value)
+    elif isinstance(value, bool):
+        return generate_boolean_schema(value)
+    elif isinstance(value, str):
+        return generate_string_schema(value)
+    elif isinstance(value, list):
+        val: Any = value
+        return generate_array_schema(val)
+    elif isinstance(value, dict):
+        val: Any = value
+        return generate_object_schema(val)
+    else:
+        raise TypeError(f"Invalid JSON value: {value}")
+
+
+def is_string_type(json_schema: dict[str, Any]) -> bool:
+    return json_schema.get("type") == "string" and "enum" not in json_schema
+
+
+def is_number_type(json_schema: dict[str, Any]) -> bool:
+    return json_schema.get("type") == "number" and "enum" not in json_schema
+
+
+def is_boolean_type(json_schema: dict[str, Any]) -> bool:
+    return json_schema.get("type") == "boolean" and "enum" not in json_schema
+
+
+def is_enum_type(json_schema: dict[str, Any]) -> bool:
+    return json_schema.get("type") == "string" and "enum" in json_schema
+
+
+def is_object_type(json_schema: dict[str, Any]) -> bool:
+    return json_schema.get("type") == "object"
+
+
+def is_object_type_with_buttons(json_schema: Any) -> bool:
+    return is_object_type(json_schema) and "buttons" in json_schema
+
+
+def is_array_type(json_schema: dict[str, Any]) -> bool:
+    return json_schema.get("type") == "array"
+
+
+def is_primitive_type(value: dict[str, Any]) -> bool:
+    return "onGet" in value or "onSet" in value

package/dist/server/src/polyglot/python/plugins/storage_controller.py

@@ -0,0 +1,57 @@
+from typing import Any, Optional
+
+from camera_storage import CameraStorage
+from camera_ui_types import PluginJsonSchemaForm
+from logger import PluginLogger
+from plugin_api import PluginAPI
+
+
+class StorageController:
+    def __init__(self, api: PluginAPI, logger: PluginLogger) -> None:
+        self.__logger = logger
+        self.__api = api
+        self.__camera_storages: dict[str, CameraStorage] = {}
+
+    def create_camera_storage(
+        self,
+        instance: Any,
+        camera_id: str,
+        schema: Optional[PluginJsonSchemaForm] = None,
+    ) -> CameraStorage:
+        """
+        Creates or retrieves an existing camera storage instance for the specified camera ID. If a storage instance does not already exist, it is initialized and stored.
+
+        :param instance: The plugin instance associated with this camera storage.
+        :param camera_id: A unique identifier for the camera.
+        :param schema: The JSON schema form defining the data structure for this camera's storage.
+        :return: An instance of CameraStorage for the specified camera.
+        """
+        if schema is None:
+            schema = {}
+        camera_storage = self.__camera_storages.get(camera_id) or CameraStorage(
+            self.__api, self.__logger, instance, camera_id, schema
+        )
+
+        camera_storage.initialize_storage()
+
+        self.__camera_storages[camera_id] = camera_storage
+
+        return camera_storage
+
+    def get_camera_storage(self, camera_id: str) -> Optional[CameraStorage]:
+        """
+        Retrieves a camera storage instance for the specified camera ID, if one exists.
+
+        :param camera_id: The unique identifier for the camera whose storage instance is being requested.
+        :return: The CameraStorage instance for the specified camera, or None if no such instance exists.
+        """
+        return self.__camera_storages.get(camera_id)
+
+    def remove_camera_storage(self, camera_id: str) -> None:
+        """
+        Removes the camera storage instance associated with the specified camera ID, if it exists.
+
+        :param camera_id: The unique identifier for the camera whose storage instance should be removed.
+        """
+        if camera_id in self.__camera_storages:
+            del self.__camera_storages[camera_id]

package/dist/server/src/polyglot/python/plugins/typings.py

@@ -0,0 +1,248 @@
+from enum import Enum
+from typing import (
+    Any,
+    Callable,
+    Union,
+)
+
+from camera_ui_types import (
+    AudioSetEvent,
+    BatterySetEvent,
+    Camera,
+    CameraDelegate,
+    CameraPrebufferDelegate,
+    CameraPTZDelegate,
+    Container,
+    DoorbellSetEvent,
+    FrameData,
+    FrameMetadata,
+    ImageOptions,
+    LightSetEvent,
+    MotionSetEvent,
+    ObjectSetEvent,
+    PluginContract,
+    SirenSetEvent,
+    StateValues,
+)
+from typing_extensions import Literal, NotRequired, TypedDict
+
+
+class PLUGIN_STATUS(Enum):
+    READY = "ready"
+    STARTING = "starting"
+    STARTED = "started"
+    STOPPED = "stopped"
+    ERROR = "error"
+    UNKNOWN = "unknown"
+    DISABLED = "disabled"
+
+
+class PLUGIN_COMMAND(Enum):
+    START = "start"
+    STOP = "stop"
+
+
+class PluginStorage(TypedDict):
+    installPath: str
+    storagePath: str
+    configFile: str
+
+
+class PluginInfo(TypedDict):
+    id: str
+    name: str
+    contract: PluginContract
+
+
+class ProcessLoadMessage(TypedDict):
+    cameras: list[Camera]
+    plugin: PluginInfo
+    storage: PluginStorage
+
+
+class ProcessMessage(TypedDict, total=False):
+    type: str
+    data: ProcessLoadMessage
+
+
+class ProcessResponse(TypedDict, total=False):
+    type: str
+    data: str
+
+
+ProxyType = Literal["device", "plugin", "camera"]
+
+ClientType = Literal[
+    "cameraFn",
+    "pluginFn",
+    "deviceFn",
+    "storageFn",
+    "cameraDelegate",
+    "prebufferDelegate",
+    "ptzDelegate",
+]
+
+MessageType = Literal["request", "reply"]
+
+
+class QueueItem(TypedDict):
+    message: "ProxyMessageStructure"
+    resolve: Callable[[Any], None]
+    reject: Callable[["RemoteError"], None]
+
+
+class DeserializedError(TypedDict):
+    name: str
+    message: str
+    stack: str
+
+
+class RemoteError(Exception):
+    def __init__(self, error: DeserializedError, cause: "ProxyMessageStructure"):
+        super().__init__(error["message"])
+
+        self.name = error["name"]
+        self.message: str = error["message"]
+        self.cause = cause
+
+        if error["stack"] and error["stack"] != "":
+            self.stack = error["stack"]
+
+    def __str__(self):
+        return f"{self.name}: {self.message}"
+
+
+class ProxyMessageStructure(TypedDict):
+    requestId: str
+    cameraId: NotRequired[str]
+    targetId: str
+    targetName: NotRequired[str]
+    pluginId: str
+    type: MessageType
+    proxy: ProxyType
+    client: ClientType
+    fn: str
+    args: list[Any]
+    timeout: int
+    timestamp: int
+    response: NotRequired[Any]
+    error: NotRequired[DeserializedError]
+
+
+class AudioStreamOptions(TypedDict, total=False):
+    enabled: bool
+    codec: str
+    bitrate: int
+    sampleRate: int
+
+
+class VideoStreamOptions(TypedDict, total=False):
+    codec: str
+    width: int
+    height: int
+    bitrate: int
+    fps: int
+    idrInterval: int
+
+
+class StreamInfo(TypedDict):
+    audio: AudioStreamOptions
+    video: VideoStreamOptions
+
+
+class ProcessPrebufferedImageRequest(TypedDict):
+    frameData: FrameData
+    metadata: FrameMetadata
+    options: ImageOptions
+    prebufferDuration: int
+
+
+class ConnectData(TypedDict):
+    cameraId: str
+    pluginId: NotRequired[str]
+
+
+class DisconnectData(ConnectData): ...
+
+
+class RebootData(ConnectData): ...
+
+
+class StreamInfoData(ConnectData):
+    sourceName: str
+
+
+class FrameMetadataData(ConnectData): ...
+
+
+class FfmpegPathData(ConnectData): ...
+
+
+class IceServersData(ConnectData): ...
+
+
+class UpdateStateData(ConnectData):
+    stateName: Literal["light", "motion", "audio", "object", "doorbell", "siren", "battery"]
+    eventData: Union[
+        LightSetEvent,
+        MotionSetEvent,
+        AudioSetEvent,
+        ObjectSetEvent,
+        DoorbellSetEvent,
+        SirenSetEvent,
+        BatterySetEvent,
+    ]
+
+
+class UpdatePrebufferStateData(ConnectData):
+    sourceId: str
+    container: Container
+
+
+class RefreshStatesData(ConnectData): ...
+
+
+class SnapshotData(ConnectData):
+    forceNew: NotRequired[bool]
+
+
+class IsPrebufferingData(TypedDict):
+    sourceName: str
+    container: Container
+    cameraId: str
+    pluginId: NotRequired[str]
+    state: bool
+    url: NotRequired[str]
+
+
+class RefreshStatesReturnData(TypedDict):
+    camera: Camera
+    states: StateValues
+    cameraState: bool
+
+
+CameraDeviceProxyMethodNames = Literal[
+    "connect",
+    "disconnect",
+    "getFfmpegPath",
+    "getIceServers",
+    "updateState",
+    "updatePrebufferState",
+    "addCameraSource",
+    "removeCameraSource",
+    "updateCameraSource",
+    "refreshStates",
+]
+
+
+class CameraDelegates(TypedDict):
+    cameraDelegate: CameraDelegate
+    prebufferDelegate: CameraPrebufferDelegate
+    ptzDelegate: CameraPTZDelegate
+
+
+Delegates = Literal[
+    "cameraDelegate",
+    "prebufferDelegate",
+    "ptzDelegate",
+]