auto-trainer-api 0.9.0__tar.gz

auto_trainer_api-0.9.0/.gitignore

@@ -0,0 +1,355 @@
+.idea
+
+# Build results
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+x64/
+x86/
+[Ww][Ii][Nn]32/
+[Aa][Rr][Mm]/
+[Aa][Rr][Mm]64/
+bld/
+[Bb]in/
+[Oo]bj/
+[Ll]og/
+[Ll]ogs/
+
+# .NET Core
+project.lock.json
+project.fragment.lock.json
+artifacts/
+
+# ASP.NET Scaffolding
+ScaffoldingReadMe.txt
+
+# NuGet Packages
+*.nupkg
+# NuGet Symbol Packages
+*.snupkg
+
+# Others
+~$*
+*~
+CodeCoverage/
+
+# MSBuild Binary and Structured Log
+*.binlog
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+
+# NUnit
+*.VisualState.xml
+TestResult.xml
+nunit-*.xml
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+site/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+## Ignore Visual Studio temporary files, build results, and
+## files generated by popular Visual Studio add-ons.
+
+# User-specific files
+*.suo
+*.user
+*.userosscache
+*.sln.docstates
+
+# User-specific files (MonoDevelop/Xamarin Studio)
+*.userprefs
+
+# Build results
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+x64/
+x86/
+bld/
+[Bb]in/
+[Oo]bj/
+[Ll]og/
+
+# Visual Studio 2015 cache/options directory
+.vs/
+# Uncomment if you have tasks that create the project's static files in wwwroot
+#wwwroot/
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+
+# NUNIT
+*.VisualState.xml
+TestResult.xml
+
+# Build Results of an ATL Project
+[Dd]ebugPS/
+[Rr]eleasePS/
+dlldata.c
+
+# DNX
+project.lock.json
+artifacts/
+
+*_i.c
+*_p.c
+*_i.h
+*.ilk
+*.meta
+*.obj
+*.pch
+*.pdb
+*.pgc
+*.pgd
+*.rsp
+*.sbr
+*.tlb
+*.tli
+*.tlh
+*.tmp
+*.tmp_proj
+*.log
+*.vspscc
+*.vssscc
+.builds
+*.pidb
+*.svclog
+*.scc
+
+# Chutzpah Test files
+_Chutzpah*
+
+# Visual C++ cache files
+ipch/
+*.aps
+*.ncb
+*.opendb
+*.opensdf
+*.sdf
+*.cachefile
+*.VC.db
+*.VC.VC.opendb
+
+# Visual Studio profiler
+*.psess
+*.vsp
+*.vspx
+*.sap
+
+# TFS 2012 Local Workspace
+$tf/
+
+# Guidance Automation Toolkit
+*.gpState
+
+# ReSharper is a .NET coding add-in
+_ReSharper*/
+*.[Rr]e[Ss]harper
+*.DotSettings.user
+
+# JustCode is a .NET coding add-in
+.JustCode
+
+# TeamCity is a build add-in
+_TeamCity*
+
+# DotCover is a Code Coverage Tool
+*.dotCover
+
+# NCrunch
+_NCrunch_*
+.*crunch*.local.xml
+nCrunchTemp_*
+
+# MightyMoose
+*.mm.*
+AutoTest.Net/
+
+# Web workbench (sass)
+.sass-cache/
+
+# Installshield output folder
+[Ee]xpress/
+
+MigrationBackup
+
+# DocProject is a documentation generator add-in
+DocProject/buildhelp/
+DocProject/Help/*.HxT
+DocProject/Help/*.HxC
+DocProject/Help/*.hhc
+DocProject/Help/*.hhk
+DocProject/Help/*.hhp
+DocProject/Help/Html2
+DocProject/Help/html
+
+# Click-Once directory
+publish/
+
+# Publish Web Output
+*.[Pp]ublish.xml
+*.azurePubxml
+# TODO: Comment the next line if you want to checkin your web deploy settings
+# but database connection strings (with potential passwords) will be unencrypted
+# *.pubxml
+*.publishproj
+
+# Microsoft Azure Web App publish settings. Comment the next line if you want to
+# checkin your Azure Web App publish settings, but sensitive information contained
+# in these scripts will be unencrypted
+PublishScripts/
+
+# NuGet Packages
+*.nupkg
+# The packages folder can be ignored because of Package Restore
+**/packages/*
+# except build/, which is used as an MSBuild target.
+!**/packages/build/
+# Uncomment if necessary however generally it will be regenerated when needed
+#!**/packages/repositories.config
+# NuGet v3's project.json files produces more ignoreable files
+*.nuget.props
+*.nuget.targets
+
+# Microsoft Azure Build Output
+csx/
+*.build.csdef
+
+# Microsoft Azure Emulator
+ecf/
+rcf/
+
+# Windows Store app package directories and files
+AppPackages/
+BundleArtifacts/
+Package.StoreAssociation.xml
+_pkginfo.txt
+
+# Visual Studio cache files
+# files ending in .cache can be ignored
+*.[Cc]ache
+# but keep track of directories ending in .cache
+!*.[Cc]ache/
+
+# Others
+ClientBin/
+~$*
+*~
+*.dbmdl
+*.dbproj.schemaview
+*.pfx
+*.publishsettings
+node_modules/
+orleans.codegen.cs
+
+# Since there are multiple workflows, uncomment next line to ignore bower_components
+# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)
+#bower_components/
+
+# RIA/Silverlight projects
+Generated_Code/
+
+# Backup & report files from converting an old project file
+# to a newer Visual Studio version. Backup files are not needed,
+# because we have git ;-)
+_UpgradeReport_Files/
+UpgradeLog*.XML
+UpgradeLog*.htm
+
+# SQL Server files
+*.mdf
+*.ldf
+
+# Business Intelligence projects
+*.rdl.data
+*.bim.layout
+*.bim_*.settings
+
+# Microsoft Fakes
+FakesAssemblies/
+
+# GhostDoc plugin setting file
+*.GhostDoc.xml
+
+# Node.js Tools for Visual Studio
+.ntvs_analysis.dat
+
+# Visual Studio 6 build log
+*.plg
+
+# Visual Studio 6 workspace options file
+*.opt
+
+# Visual Studio LightSwitch build output
+**/*.HTMLClient/GeneratedArtifacts
+**/*.DesktopClient/GeneratedArtifacts
+**/*.DesktopClient/ModelManifest.xml
+**/*.Server/GeneratedArtifacts
+**/*.Server/ModelManifest.xml
+_Pvt_Extensions
+
+# Paket dependency manager
+.paket/paket.exe
+paket-files/
+
+# FAKE - F# Make
+.fake/
+
+# JetBrains Rider
+.idea/
+*.sln.iml
+
+OriginTheme/
+obj.*/
+
+# Part of text fixture datasets that may occur but are not necessary.
+
+System/Migrations/
+System/Autobackup/
+.DS_Store
+
+Deployment/*/AppComponents.wxs
+Deployment/*/AnalysisComponents.wxs
+
+local.settings.json

auto_trainer_api-0.9.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: auto-trainer-api
+Version: 0.9.0
+Summary: API for interfacing with the core acquisition process via platform and language agnostic message queues.
+License: AGPL-3.0-only
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: pyhumps==3.8.0
+Requires-Dist: pyzmq==26.4
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk; extra == 'telemetry'
+Provides-Extra: test
+Requires-Dist: pytest==8.2.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Autotrainer API: Python Integration
+
+The python `auto-trainer-api` module is intended to provide an efficient means to emit information that
+is needed for local or remote management and to receive commands from those sources.
+
+The exposed API is intended to be agnostic to the underlying transport layer.  The current implementation uses
+ZeroMQ for reasons described in the top-level README.
+
+# Installation
+The package is published to the PyPi package index and can installed normally.

auto_trainer_api-0.9.0/README.md

@@ -0,0 +1,10 @@
+# Autotrainer API: Python Integration
+
+The python `auto-trainer-api` module is intended to provide an efficient means to emit information that
+is needed for local or remote management and to receive commands from those sources.
+
+The exposed API is intended to be agnostic to the underlying transport layer.  The current implementation uses
+ZeroMQ for reasons described in the top-level README.
+
+# Installation
+The package is published to the PyPi package index and can installed normally.

auto_trainer_api-0.9.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/autotrainer"]
+namespaces = true
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/mkdocs.yml",
+    "/docs",
+]
+
+[project]
+name = "auto-trainer-api"
+version = "0.9.0"
+description = "API for interfacing with the core acquisition process via platform and language agnostic message queues."
+license = { text = "AGPL-3.0-only" }
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent"
+]
+dependencies = [
+    "pyhumps==3.8.0",
+    "pyzmq==26.4"
+]
+
+[project.optional-dependencies]
+telemetry = [
+    "opentelemetry-api",
+    "opentelemetry-sdk"
+]
+test = [
+    "pytest==8.2.0"
+]

auto_trainer_api-0.9.0/scripts/run_service.py

@@ -0,0 +1,6 @@
+from autotrainer.api import run_server
+
+if __name__ == '__main__':
+    # Starts a simple application in lieu of a real auto-trainer application to publish heartbeat messages and receive
+    # command requests for development and testing.
+    run_server()

auto_trainer_api-0.9.0/src/autotrainer/api/__init__.py

@@ -0,0 +1,27 @@
+"""
+API Service functionality for Autotrainer.
+"""
+
+from typing import Optional
+
+from .api_options import ApiOptions, RpcOptions, TelemetryOptions, create_default_api_options
+from .rpc_service import ApiTopic, RpcService, ApiCommandRequest, ApiCommandRequestResponse, ApiCommandReqeustResult
+from .telemtry import configure_telemetry
+
+from .util import patch_uuid_encoder
+
+from .tools import run_server
+
+
+def create_api_service(options: ApiOptions) -> Optional[RpcService]:
+    from .zeromq import ZeroMQApiService
+
+    # Several autotrainer messages may contain a UUID, which is not handled by the default JSON encoder.
+    # patch_uuid_encoder()
+
+    configure_telemetry(options.telemetry)
+
+    if options.rpc.enable:
+        return ZeroMQApiService(options.rpc)
+    else:
+        return None

auto_trainer_api-0.9.0/src/autotrainer/api/api_options.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class TelemetryOptions:
+    enable: bool = False
+    endpoint: Optional[str] = None
+    api_key: str = ""
+
+
+@dataclass(frozen=True)
+class RpcOptions:
+    enable: bool = True
+    identifier: str = "autotrainer-device"
+    heartbeat_interval: int = 5
+    subscriber_port: int = 5556
+    command_port: int = 5557
+
+
+@dataclass(frozen=True)
+class ApiOptions:
+    rpc: Optional[RpcOptions] = None
+    telemetry: Optional[TelemetryOptions] = None
+
+
+def create_default_api_options() -> ApiOptions:
+    """
+    Create default API options for the Autotrainer API service.
+    """
+
+    return ApiOptions(rpc=RpcOptions(), telemetry=TelemetryOptions())

auto_trainer_api-0.9.0/src/autotrainer/api/rpc_service.py

@@ -0,0 +1,403 @@
+import json
+import logging
+import time
+from dataclasses import dataclass, asdict
+from enum import IntEnum
+from queue import Queue, Empty
+from threading import Timer, Thread
+from typing import Optional, Protocol, Any
+from typing_extensions import Self
+
+import humps
+
+from .api_options import RpcOptions
+
+logger = logging.getLogger(__name__)
+
+
+class ApiTopic(IntEnum):
+    """
+    A topic is required for all published messages.  This allows subscribers to filter messages through the message
+    queue functionality rather than seeing all messages and filtering themselves.
+
+    Any 4-byte integer value is valid.
+    """
+    ANY = 0,
+    HEARTBEAT = 1001,
+    """System heartbeat message indicating service availability."""
+    EVENT = 2001,
+    """
+    Data generated from the published under the 'Event' umbrella, which is typically major system/application events.
+    """
+    COMMAND_RESULT = 3001,
+    """ Responses to asynchronous command handling. """
+
+
+class ApiCommand(IntEnum):
+    """
+    A command value is required for all command requests.
+    """
+    NONE = 0,
+    USER_DEFINED = 99999
+
+    @classmethod
+    def is_member(cls, value):
+        return value in cls._value2member_map_
+
+
+@dataclass(frozen=True)
+class ApiCommandRequest:
+    """
+    A command request contains the command and any associated data.
+    """
+    command: ApiCommand
+    custom_command: int = -1
+    nonce: int = -1
+    data: Optional[dict] = None
+
+    @classmethod
+    def parse_bytes(cls, message: bytes) -> Optional[Self]:
+        obj = json.loads(humps.decamelize(message.decode("utf8")))
+
+        return ApiCommandRequest.parse_object(obj)
+
+    @classmethod
+    def parse_object(cls, obj: Any) -> Optional[Self]:
+        if "command" in obj:
+            command = obj["command"]
+            if ApiCommand.is_member(command):
+                command = ApiCommand(command)
+            else:
+                command = ApiCommand.USER_DEFINED
+            if "custom_command" in obj:
+                custom_command = obj["custom_command"]
+            else:
+                custom_command = -1
+            if "data" in obj:
+                data = obj["data"]
+            else:
+                data = None
+            if "nonce" in obj:
+                nonce = obj["nonce"]
+            else:
+                nonce = 0
+
+            return ApiCommandRequest(command=command, custom_command=custom_command, nonce=nonce, data=data)
+
+        return None
+
+
+class ApiCommandReqeustResult(IntEnum):
+    """
+    Result of a command request.
+    """
+    UNRECOGNIZED = 0,
+    SUCCESS = 1,
+    PENDING = 2,
+    PENDING_WITH_NOTIFICATION = 3,
+    FAILED = 4,
+    EXCEPTION = 5,
+    UNAVAILABLE = 9999
+
+
+class ApiCommandRequestErrorKind(IntEnum):
+    NONE = 0,
+    SYSTEM_ERROR = 0x01,
+    COMMAND_ERROR = 0x02
+
+
+ApiCommandRequestSystemErrorSerialization: int = 0
+
+
+@dataclass(frozen=True)
+class ApiCommandRequestResponse:
+    """
+    A command response contains the command and any associated data.
+
+    If the command request will have a result asynchronously in the future, one pattern would be to return some form
+    of context in the data field that the client can use as a reference in a future published message.
+    """
+    nonce: int
+    """
+    This will be set to 0 if a command request could not be deserialized.  Caller should set the nonce to any value > 0
+    if they want to be able to identify commands that were not simple unrecognized, but unparseable.
+    """
+    command: ApiCommand
+    result: ApiCommandReqeustResult = ApiCommandReqeustResult.UNRECOGNIZED
+    data: Optional[dict] = None
+    error_kind: ApiCommandRequestErrorKind = ApiCommandRequestErrorKind.NONE
+    error_code: int = 0
+    error_message: Optional[str] = None
+
+    def as_bytes(self, allow_fallback: bool = True) -> bytes:
+        """
+        This is guaranteed to return a valid response, even if modified due to any errors in serialization.  It must
+        not throw.
+
+        :param allow_fallback: true to allow serialization without the 'data' element if serialization initially fails.
+        :return: serialized message as bytes
+        """
+        try:
+            return humps.camelize(json.dumps(self.__dict__)).encode("utf8")
+        except Exception as ex:
+            logger.error(ex)
+
+        if allow_fallback:
+            # Assume it is an issue w/the contents of the user-definable dictionary contents
+            contents = self.__dict__
+            contents["data"] = None
+            # If the next attempt works, this will have been the situation.
+            contents["error_kind"] = ApiCommandRequestErrorKind.SYSTEM_ERROR
+            contents["error_code"] = ApiCommandRequestSystemErrorSerialization
+            contents["error_message"] = "An error occurred serializing the 'data' element of the response."
+            try:
+                return humps.camelize(json.dumps(contents)).encode("utf8")
+            except Exception as ex:
+                logger.error(ex)
+
+        serialization_error = {"nonce": self.nonce, "command": self.command, "result": self.result,
+                               "error_kind": ApiCommandRequestErrorKind.SYSTEM_ERROR,
+                               "error_code": ApiCommandRequestSystemErrorSerialization,
+                               "error_message": "An error occurred serializing the response."}
+
+        return humps.camelize(json.dumps(serialization_error)).encode("utf8")
+
+    @staticmethod
+    def for_exception(command: ApiCommand, nonce: int, ex: Exception):
+        return ApiCommandRequestResponse(command=command, nonce=nonce, result=ApiCommandReqeustResult.EXCEPTION,
+                                         error_message=str(ex))
+
+
+class CommandRequestDelegate(Protocol):
+    """
+    This callback is expected to be fast.  It is intended to initiate a command, not necessarily complete it.  Any
+    non-trivial action is expected to accept the command request and return, perform the action on a non-calling thread
+    or process, and use the message publishing API to report changes, results, etc.
+    """
+
+    def __call__(self, request: ApiCommandRequest) -> ApiCommandRequestResponse: ...
+
+
+class ApiMessageQueueService(Protocol):
+    """
+    Minimum requirements to fulfill the API service message queue interface.  Implementation details are left to the
+    implementation.
+
+    Implementations are required to be able to publish messages to one or more subscribers.
+    """
+
+    def send(self, topic: ApiTopic, data: bytes) -> bool: ...
+
+    def send_string(self, topic: ApiTopic, message: str) -> bool: ...
+
+    def send_dict(self, topic: ApiTopic, message: dict) -> bool: ...
+
+
+class ApiCommandRequestService(Protocol):
+    """
+    Minimum requirements to fulfill the API service command provider interface.  Implementation details are left to the
+    implementation.
+
+    Implementations are required to be able to receive command requests from one or more clients, deliver those requests
+    to a registered handler, and provide an immediate response to the requester.  The response is a response to the
+    _command request_ not necessarily the response to the command itself.  See CommandCallback for additional details.
+    """
+
+    @property
+    def command_request_delegate(self) -> Optional[CommandRequestDelegate]: ...
+
+    @command_request_delegate.setter
+    def command_request_delegate(self, value: Optional[CommandRequestDelegate]): ...
+
+
+@dataclass
+class HeartbeatMessage:
+    identifier: str
+    version: str
+    timestamp: float
+
+
+class RpcService(ApiMessageQueueService, ApiCommandRequestService):
+    def __init__(self, options: RpcOptions):
+        self._subscriber_port = options.subscriber_port
+        self._command_port = options.command_port
+        self._identifier = options.identifier
+        self._heartbeat_interval = options.heartbeat_interval
+        self._heartbeat: HeartbeatMessage = HeartbeatMessage(
+            identifier=options.identifier,
+            version="0.9.0",
+            timestamp=0.0
+        )
+
+        self._command_callback = None
+
+        self._thread = None
+
+        self._termination_requested = False
+
+        self._queue = Queue()
+
+    @property
+    def subscriber_port(self) -> int:
+        return self._subscriber_port
+
+    @property
+    def command_port(self) -> int:
+        return self._command_port
+
+    @property
+    def identifier(self) -> str:
+        return self._identifier
+
+    @property
+    def heartbeat_interval(self) -> int:
+        return self._heartbeat_interval
+
+    @property
+    def command_request_delegate(self) -> Optional[CommandRequestDelegate]:
+        return self._command_callback
+
+    @command_request_delegate.setter
+    def command_request_delegate(self, value: Optional[CommandRequestDelegate]):
+        self._command_callback = value
+
+    def start(self):
+        if self._thread is None or not self._thread.is_alive():
+            self._termination_requested = False
+            self._queue = Queue()
+            self._thread = Thread(target=self._run)
+            self._thread.start()
+
+    def stop(self):
+        self._termination_requested = True
+
+    def send(self, topic: ApiTopic, data: bytes) -> bool:
+        self._queue.put(lambda: self._send(topic, data))
+        return True
+
+    def send_string(self, topic: ApiTopic, message: str) -> bool:
+        self._queue.put(lambda: self._send_string(topic, message))
+        return True
+
+    def send_dict(self, topic: ApiTopic, message: dict) -> bool:
+        try:
+            self._queue.put(lambda: self._send_dict(topic, message))
+            return True
+        except:
+            pass
+
+        return False
+
+    def _run(self):
+        try:
+            if not self._start():
+                logger.error(f"failed to start api service")
+                self._update_after_run()
+                return
+        except Exception:
+            logger.exception("exception starting api service")
+            self._update_after_run()
+            return
+
+        self._queue_heartbeat()
+
+        while not self._termination_requested:
+            try:
+                # Expected to be non-blocking.
+                request = self._get_next_command_request()
+
+                if request is not None:
+                    # Expected to happen fast.  Most message queue implementations that provide a request/response-type
+                    # pattern require that a response be sent before the next request is received.  And the associated
+                    # client/caller implementation requires the response before accepting another request.
+                    #
+                    # If this becomes an untenable requirement, a different pattern will be required for command
+                    # requests (and the underlying implementations update).  However, anything that allow interleaving
+                    # multiple requests from the same client with responses would effectively be the same as this
+                    # pattern where there is an immediate _request_ response and a delayed _command_ response through
+                    # the message queue.
+                    #
+                    # NOTE: There is no inherent limitation in this pattern with multiple requests from multiple
+                    # clients.  This is related to the handling of each individual client.
+
+                    if self._command_callback is not None:
+                        try:
+                            # Can not assume the registered delegate will be well-behaved.
+                            self._send_command_response(self._command_callback(request))
+                        except Exception as e:
+                            self._send_command_response(
+                                ApiCommandRequestResponse.for_exception(request.command, request.nonce, e))
+                    else:
+                        # Must provide a response, even if no one that registered this service cares (using for the
+                        # message queue only, etc.).
+                        self._send_command_response(
+                            ApiCommandRequestResponse(command=request.command, nonce=request.nonce,
+                                                      result=ApiCommandReqeustResult.UNAVAILABLE))
+
+                # Expected to be non-blocking.
+                action = self._queue.get(timeout=0.05)
+
+                # This is performed by the implementation.  It should be exception safe or the implementation should be
+                # updated.
+                action()
+
+            except Empty:
+                # Expected from get_nowait() if there is nothing in the queue.
+                pass
+
+        time.sleep(0.1)
+
+        self._update_after_run()
+
+    def _update_after_run(self):
+        self._cancel_heartbeat()
+
+        self._stop()
+
+        self._thread = None
+
+    def _queue_heartbeat(self):
+        self._heartbeat_timer = Timer(self._heartbeat_interval, self._heartbeat_timer_callback)
+        self._heartbeat_timer.start()
+
+    def _cancel_heartbeat(self):
+        if self._heartbeat_timer is not None:
+            self._heartbeat_timer.cancel()
+            self._heartbeat_timer = None
+
+    def _heartbeat_timer_callback(self):
+        # Must happen on the queue processing thread.
+        if not self._termination_requested:
+            self._heartbeat.timestamp = time.time()
+            self._send_dict(ApiTopic.HEARTBEAT, asdict(self._heartbeat))
+            self._queue_heartbeat()
+
+    def _start(self) -> bool:
+        raise NotImplementedError("Subclasses must implement _start()")
+
+    def _stop(self):
+        raise NotImplementedError("Subclasses must implement _stop()")
+
+    def _send(self, topic: ApiTopic, data: bytes) -> bool:
+        return False
+
+    def _send_string(self, topic: ApiTopic, message: str) -> bool:
+        return False
+
+    def _send_dict(self, topic: ApiTopic, message: dict) -> bool:
+        return False
+
+    def _get_next_command_request(self) -> Optional[ApiCommandRequest]:
+        """
+        If a command request is returned, the subclass/implementation can assume that a responses will be sent
+        (via the `_command_response()_` method).  If something is received by the implementation that can not be
+        returned as a valid command request (malformed, incomplete, etc.), it is the responsibility of the
+        implementation to provide a response if that is required by the particular implementation (e.g., request/reply
+        requiring a response to every request, etc.).
+
+        :return: a command request if available, None otherwise
+        """
+        return None
+
+    def _send_command_response(self, response: ApiCommandRequestResponse):
+        pass

auto_trainer_api-0.9.0/src/autotrainer/api/telemtry/__init__.py

@@ -0,0 +1 @@
+from .open_telemetry_service import configure_telemetry

auto_trainer_api-0.9.0/src/autotrainer/api/telemtry/open_telemetry_service.py

@@ -0,0 +1,51 @@
+import importlib.util
+import logging
+import os
+from typing import Optional
+
+from ..api_options import TelemetryOptions
+
+_spec_opentelemetry = importlib.util.find_spec("opentelemetry")
+
+logger = logging.getLogger(__name__)
+
+
+def configure_telemetry(options: Optional[TelemetryOptions]) -> bool:
+    if options is None or not options.enable:
+        logger.debug(f"telemetry options {'missing' if options is None else 'disabled'}.")
+        return False
+
+    if _spec_opentelemetry is None:
+        logger.warning("telemetry enabled however a required dependency is missing.")
+        return False
+
+    endpoint = options.endpoint if options.endpoint is not None else os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+
+    if endpoint is None:
+        logger.warning("telemetry enabled however the endpoint is not specified.")
+        return False
+
+    from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    from opentelemetry import metrics
+    from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+    from opentelemetry.sdk.metrics import MeterProvider
+    from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+
+    resource = Resource(attributes={SERVICE_NAME: "auto-trainer"})
+
+    trace_provider = TracerProvider(resource=resource)
+    processor = BatchSpanProcessor(OTLPSpanExporter(endpoint=f"{endpoint}/v1/traces"))
+    trace_provider.add_span_processor(processor)
+    trace.set_tracer_provider(trace_provider)
+
+    reader = PeriodicExportingMetricReader(OTLPMetricExporter(endpoint=f"{endpoint}/v1/metrics"))
+    meter_provider = MeterProvider(resource=resource, metric_readers=[reader])
+    metrics.set_meter_provider(meter_provider)
+
+    return True

auto_trainer_api-0.9.0/src/autotrainer/api/tools/__init__.py

@@ -0,0 +1 @@
+from .pub_sub_server import run_server

auto_trainer_api-0.9.0/src/autotrainer/api/tools/pub_sub_server.py

@@ -0,0 +1,39 @@
+"""
+Create an instance of an Api Service implementation to received published messages and send command requests.
+"""
+
+import logging
+
+from ..rpc_service import ApiCommandRequest, ApiCommandRequestResponse, ApiCommandReqeustResult
+from ..zeromq import ZeroMQApiService
+from ..api_options import create_default_api_options
+
+logging.basicConfig(level=logging.DEBUG, format="%(asctime)s %(levelname)s\t [%(name)s] %(message)s")
+logging.getLogger('autotrainer').setLevel(logging.DEBUG)
+logging.getLogger('tools').setLevel(logging.DEBUG)
+
+logger = logging.getLogger(__name__)
+
+
+def _respond_to_command_request(request: ApiCommandRequest) -> ApiCommandRequestResponse:
+    logger.debug("Received command request: %s", request.command)
+    return ApiCommandRequestResponse(command=request.command, data={"seen": True},
+                                     result=ApiCommandReqeustResult.SUCCESS)
+
+
+def run_server():
+    options = create_default_api_options()
+
+    service = ZeroMQApiService(options.rpc)
+
+    service.command_request_delegate = _respond_to_command_request
+
+    service.start()
+
+    input("Press enter to stop the service...\n")
+
+    service.stop()
+
+
+if __name__ == '__main__':
+    run_server()

auto_trainer_api-0.9.0/src/autotrainer/api/util.py

@@ -0,0 +1,40 @@
+import socket
+from datetime import datetime
+from json import JSONEncoder
+from uuid import UUID
+
+_IS_JSON_ENCODER_PATCHED = False
+
+
+def get_ip4_addr_str() -> str:
+    # gethostname() and gethostbyname() and associated IP lookup have proven unreliable on deployed devices where the
+    # configuration is not perfect.  This method assumes access to the internet (Google DNS) which has its own
+    # limitations.  A more complex implementation to manage all conditions but avoid ending up with 12.0.0.1 when an
+    # actual address is available is needed.
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.connect(("8.8.8.8", 80))
+        ip = s.getsockname()[0]
+    except Exception:
+        ip = "127.0.0.1"
+    finally:
+        s.close()
+
+    return ip
+
+
+def patch_uuid_encoder():
+    global _IS_JSON_ENCODER_PATCHED
+
+    if not _IS_JSON_ENCODER_PATCHED:
+        JSONEncoder.default = UUIDEncoder.default
+        _IS_JSON_ENCODER_PATCHED = True
+
+
+class UUIDEncoder(JSONEncoder):
+    def default(self, obj):
+        if isinstance(obj, UUID):
+            return str(obj)
+        if isinstance(obj, datetime):
+            return obj.timestamp()
+        return super().default(obj)

auto_trainer_api-0.9.0/src/autotrainer/api/zeromq/__init__.py

@@ -0,0 +1 @@
+from .zeromq_api_service import ZeroMQApiService

auto_trainer_api-0.9.0/src/autotrainer/api/zeromq/zeromq_api_service.py

@@ -0,0 +1,123 @@
+import json
+import logging
+from typing import Optional
+
+import zmq
+import humps
+
+from ..rpc_service import RpcService, RpcOptions, ApiTopic, ApiCommandRequestResponse, ApiCommandRequest, ApiCommand
+from ..util import get_ip4_addr_str, UUIDEncoder
+
+logger = logging.getLogger(__name__)
+
+
+class ZeroMQApiService(RpcService):
+    def __init__(self, options: RpcOptions):
+        super().__init__(options)
+
+        ips = [get_ip4_addr_str()]
+
+        if ips[0] != "127.0.0.1":
+            ips.append("127.0.0.1")
+
+        self._pub_addresses = [f"tcp://{ip}:{self.subscriber_port}" for ip in ips]
+        self._pub_socket = None
+
+        self._cmd_addresses = [f"tcp://{ip}:{self.command_port}" for ip in ips]
+        self._cmd_socket = None
+
+        self._response_pending = False
+
+    def _start(self) -> bool:
+        if self._pub_socket is not None:
+            return True
+
+        context = zmq.Context()
+
+        self._pub_socket = context.socket(zmq.PUB)
+        for address in self._pub_addresses:
+            self._pub_socket.bind(address)
+            logger.debug(f"ZMQ PUB socket bound to {address}")
+
+        context = zmq.Context()
+
+        self._cmd_socket = context.socket(zmq.REP)
+        for address in self._cmd_addresses:
+            self._cmd_socket.bind(address)
+            logger.debug(f"ZMQ REP socket bound to {address}")
+
+        return True
+
+    def _stop(self):
+        if self._pub_socket is not None:
+            for address in self._pub_addresses:
+                self._pub_socket.disconnect(address)
+            self._pub_socket = None
+        if self._cmd_socket is not None:
+            for address in self._cmd_addresses:
+                self._cmd_socket.disconnect(address)
+            self._cmd_socket = None
+
+    def _send(self, topic: ApiTopic, data: bytes):
+        if self._pub_socket is not None:
+            self._pub_socket.send(topic.to_bytes(4, "little"), flags=zmq.SNDMORE)
+            self._pub_socket.send(data)
+
+    def _send_string(self, topic: ApiTopic, message: str):
+        if self._pub_socket is not None:
+            self._pub_socket.send(topic.to_bytes(4, "little"), flags=zmq.SNDMORE)
+            self._pub_socket.send(message.encode("utf8"))
+
+    def _send_dict(self, topic: ApiTopic, message: dict):
+        if self._pub_socket is not None:
+            try:
+                # Convert the dictionary to a JSON string and then encode it to bytes.
+                json_data = humps.camelize(json.dumps(message, cls=UUIDEncoder))
+                self._pub_socket.send(topic.to_bytes(4, "little"), flags=zmq.SNDMORE)
+                self._pub_socket.send_json(json_data)
+            except Exception as ex:
+                logger.error(ex)
+
+    def _get_next_command_request(self) -> Optional[ApiCommandRequest]:
+        if self._cmd_socket is not None and not self._response_pending:
+            try:
+                message = self._cmd_socket.recv(flags=zmq.NOBLOCK)
+
+                self._response_pending = True
+
+                request = ZeroMQApiService._parse_command_request(message)
+
+                if request is None:
+                    # If a request was received, but could not be parsed, the requester is still expecting a response.
+                    # Otherwise, the ZeroMQ socket on both ends will be in a lingering state.  Send it ourselves since
+                    # returning None will not generate a response by the caller.
+                    self._send_command_response(ApiCommandRequestResponse(command=ApiCommand.NONE, nonce=0))
+
+                # A response will be sent by the caller if a request is returned.
+                return request
+
+            except zmq.Again:
+                pass
+
+        return None
+
+    def _send_command_response(self, response: ApiCommandRequestResponse):
+        if self._cmd_socket is not None:
+            # This is guaranteed to return a valid response, even if modified due to any errors in serialization.
+            data = response.as_bytes(True)
+
+            self._cmd_socket.send(data)
+
+            self._response_pending = False
+
+    @staticmethod
+    def _parse_command_request(message: bytes) -> Optional[ApiCommandRequest]:
+        try:
+            return ApiCommandRequest.parse_bytes(message)
+        except json.decoder.JSONDecodeError as ex:
+            # Might do something different here.
+            logger.error(ex)
+        except Exception as ex:
+            logger.error(ex)
+
+        return None