aspyx-service 0.9.0__py3-none-any.whl → 0.10.1__py3-none-any.whl

aspyx_service/__init__.py

@@ -4,7 +4,7 @@ This module provides the core Aspyx service management framework allowing for se
 
 from aspyx.di import module
 
-from .service import ServiceException, Server, Channel, ComponentDescriptor, inject_service, ChannelAddress, ServiceAddress, ServiceManager, Component, Service, AbstractComponent, ComponentStatus, ComponentRegistry, implementation, health, component, service
+from .service import ServiceException, Server, Channel, ComponentDescriptor, inject_service, ChannelAddress, ChannelInstances, ServiceManager, Component, Service, AbstractComponent, ComponentStatus, ComponentRegistry, implementation, health, component, service
 from .channels import HTTPXChannel, DispatchJSONChannel
 from .registries import ConsulComponentRegistry
 from .server import FastAPIServer
@@ -32,7 +32,7 @@ __all__ = [
     "ComponentDescriptor",
     "ComponentRegistry",
     "ChannelAddress",
-    "ServiceAddress",
+    "ChannelInstances",
     "health",
     "component",
     "service",
@@ -41,6 +41,11 @@ __all__ = [
 
     # healthcheck
 
+    "health_checks",
+    "health_check",
+    "HealthStatus",
+    "HealthCheckManager",
+
     # serialization
 
    # "deserialize",

aspyx_service/channels.py

@@ -3,6 +3,8 @@ Service management and dependency injection framework.
 """
 from __future__ import annotations
 
+import json
+from dataclasses import is_dataclass, asdict, fields
 from typing import Type, Optional, Any, Callable
 
 import msgpack
@@ -12,7 +14,7 @@ from pydantic import BaseModel
 from aspyx.reflection import DynamicProxy, TypeDescriptor
 from .service import ServiceManager
 
-from .service import ComponentDescriptor, ServiceAddress, ServiceException, channel, Channel, RemoteServiceException
+from .service import ComponentDescriptor, ChannelInstances, ServiceException, channel, Channel, RemoteServiceException
 from .serialization import get_deserializer
 
 
@@ -24,10 +26,37 @@ class HTTPXChannel(Channel):
         "deserializers"
     ]
 
+    # class methods
+
+    @classmethod
+    def to_dict(cls, obj: Any) -> Any:
+        if isinstance(obj, BaseModel):
+            return obj.dict()
+
+
+        elif is_dataclass(obj):
+            return {
+                f.name: cls.to_dict(getattr(obj, f.name))
+
+                for f in fields(obj)
+            }
+
+        elif isinstance(obj, (list, tuple)):
+            return [cls.to_dict(item) for item in obj]
+
+        elif isinstance(obj, dict):
+            return {key: cls.to_dict(value) for key, value in obj.items()}
+
+        return obj
+
+    @classmethod
+    def to_json(cls, obj) -> str:
+        return json.dumps(cls.to_dict(obj))
+
     # constructor
 
-    def __init__(self, name):
-        super().__init__(name)
+    def __init__(self):
+        super().__init__()
 
         self.client: Optional[Client] = None
         self.async_client: Optional[AsyncClient] = None
@@ -49,7 +78,7 @@ class HTTPXChannel(Channel):
 
     # override
 
-    def setup(self, component_descriptor: ComponentDescriptor, address: ServiceAddress):
+    def setup(self, component_descriptor: ComponentDescriptor, address: ChannelInstances):
         super().setup(component_descriptor, address)
 
         # remember service names
@@ -92,30 +121,35 @@ class Response(BaseModel):
 
 @channel("dispatch-json")
 class DispatchJSONChannel(HTTPXChannel):
+    """
+    A channel that calls a POST on th endpoint `ìnvoke` sending a request body containing information on the
+    called component, service and method and the arguments.
+    """
     # constructor
 
     def __init__(self):
-        super().__init__("dispatch-json")
+        super().__init__()
 
     # internal
 
     # implement Channel
 
-    def set_address(self, address: Optional[ServiceAddress]):
+    def set_address(self, address: Optional[ChannelInstances]):
         ServiceManager.logger.info("channel %s got an address %s", self.name, address)
 
         super().set_address(address)
 
-    def setup(self, component_descriptor: ComponentDescriptor, address: ServiceAddress):
+    def setup(self, component_descriptor: ComponentDescriptor, address: ChannelInstances):
         super().setup(component_descriptor, address)
 
     def invoke(self, invocation: DynamicProxy.Invocation):
         service_name = self.service_names[invocation.type]  # map type to registered service name
         request = Request(method=f"{self.component_descriptor.name}:{service_name}:{invocation.method.__name__}", args=invocation.args)
 
+        dict = self.to_dict(request)
         try:
             if self.client is not None:
-                result = Response(**self.get_client().post(f"{self.get_url()}/invoke", json=request.dict(), timeout=30000.0).json())
+                result = Response(**self.get_client().post(f"{self.get_url()}/invoke", json=dict, timeout=30000.0).json())
                 if result.exception is not None:
                     raise RemoteServiceException(f"server side exception {result.exception}")
 
@@ -130,9 +164,10 @@ class DispatchJSONChannel(HTTPXChannel):
         request = Request(method=f"{self.component_descriptor.name}:{service_name}:{invocation.method.__name__}",
                           args=invocation.args)
 
+        dict = self.to_dict(request)
         try:
             if self.async_client is not None:
-                data =  await self.async_client.post(f"{self.get_url()}/invoke", json=request.dict(), timeout=30000.0)
+                data =  await self.async_client.post(f"{self.get_url()}/invoke", json=dict, timeout=30000.0)
                 result = Response(**data.json())
                 if result.exception is not None:
                     raise RemoteServiceException(f"server side exception {result.exception}")
@@ -146,14 +181,17 @@ class DispatchJSONChannel(HTTPXChannel):
 
 @channel("dispatch-msgpack")
 class DispatchMSPackChannel(HTTPXChannel):
+    """
+    A channel that sends a POST on the ìnvoke `endpoint`with an msgpack encoded request body.
+    """
     # constructor
 
     def __init__(self):
-        super().__init__("dispatch-msgpack")
+        super().__init__()
 
     # override
 
-    def set_address(self, address: Optional[ServiceAddress]):
+    def set_address(self, address: Optional[ChannelInstances]):
         ServiceManager.logger.info("channel %s got an address %s", self.name, address)
 
         super().set_address(address)
@@ -164,7 +202,7 @@ class DispatchMSPackChannel(HTTPXChannel):
                           args=invocation.args)
 
         try:
-            packed = msgpack.packb(request.dict(), use_bin_type=True)
+            packed = msgpack.packb(self.to_dict(request), use_bin_type=True)
 
             response = self.get_client().post(
                 f"{self.get_url()}/invoke",
@@ -189,7 +227,7 @@ class DispatchMSPackChannel(HTTPXChannel):
                           args=invocation.args)
 
         try:
-            packed = msgpack.packb(request.dict(), use_bin_type=True)
+            packed = msgpack.packb(self.to_dict(request), use_bin_type=True)
 
             response = await self.get_async_client().post(
                 f"{self.get_url()}/invoke",
@@ -207,4 +245,3 @@ class DispatchMSPackChannel(HTTPXChannel):
 
         except Exception as e:
             raise ServiceException(f"msgpack exception: {e}") from e
-

aspyx_service/healthcheck.py

@@ -9,7 +9,7 @@ import time
 from enum import Enum
 from typing import Any, Callable, Type, Optional
 
-from aspyx.di import Providers, ClassInstanceProvider, injectable, Environment, inject_environment, on_init
+from aspyx.di import injectable, Environment, inject_environment, on_init
 from aspyx.reflection import Decorators, TypeDescriptor
 
 
@@ -31,7 +31,8 @@ def health_checks():
 
 def health_check(name="", cache = 0, fail_if_slower_than = 0):
     """
-    Methods annotated with `@on_init` will be called when the instance is created."""
+    Methods annotated with `@on_init` will be called when the instance is created.
+    """
     def decorator(func):
         Decorators.add(func, health_check, name, cache, fail_if_slower_than)
         return func
@@ -39,6 +40,13 @@ def health_check(name="", cache = 0, fail_if_slower_than = 0):
     return decorator
 
 class HealthStatus(Enum):
+    """
+    A enum specifying the health status of a service. The values are:
+
+    - `OK` service is healthy
+    - `WARNING` service has some problems
+    - `CRITICAL` service is unhealthy
+    """
     OK = 1
     WARNING = 2
     ERROR = 3
@@ -49,6 +57,9 @@ class HealthStatus(Enum):
 
 @injectable()
 class HealthCheckManager:
+    """
+    The health manager is able to run all registered health checks and is able to return an overall status.
+    """
     logger = logging.getLogger("aspyx.service.health")
 
     # local classes
@@ -112,8 +123,8 @@ class HealthCheckManager:
             return result
 
     class Health:
-        def __init__(self):
-            self.status = HealthStatus.OK
+        def __init__(self, status: HealthStatus = HealthStatus.OK):
+            self.status = status
             self.results : list[HealthCheckManager.Result] = []
 
         def to_dict(self):
@@ -135,6 +146,11 @@ class HealthCheckManager:
     # check
 
     async def check(self) -> HealthCheckManager.Health:
+        """
+        run all registered health checks and return an overall result.
+        Returns: the overall result.
+
+        """
         self.logger.info("Checking health...")
 
         health = HealthCheckManager.Health()

aspyx_service/registries.py

@@ -10,34 +10,38 @@ from urllib.parse import urlparse
 
 import consul
 
+from aspyx.di.configuration import inject_value
 from aspyx.util import StringBuilder
 from aspyx.di import on_init
 from .healthcheck import HealthCheckManager, HealthStatus
 
 from .server import Server
-from .service import ComponentRegistry, Channel, ServiceAddress, ServiceManager, ComponentDescriptor, Component, ChannelAddress
+from .service import ComponentRegistry, Channel, ChannelInstances, ServiceManager, ComponentDescriptor, Component, ChannelAddress
 
 class ConsulComponentRegistry(ComponentRegistry):
+    """
+    A specialized registry using consul.
+    A polling mechanism is used to identify changes in the component health.
+    """
     # constructor
 
-    def __init__(self, port: int, consul_url: str):
+    def __init__(self, port: int, consul: consul.Consul):
         self.port = port
         self.ip = Server.get_local_ip()
         self.running = False
-        self.consul = None
+        self.consul = consul
         self.watchdog = None
         self.interval = 5
         self.last_index = {}
-        self.component_addresses : dict[str, dict[str, ServiceAddress]] = {} # comp -> channel -> address
+        self.component_addresses : dict[str, dict[str, ChannelInstances]] = {} # comp -> channel -> address
         self.watch_channels : list[Channel] = []
+        self.watchdog_interval = 5
 
-        parsed = urlparse(consul_url)
+    # injections
 
-        self.consul_host = parsed.hostname
-        self.consul_port = parsed.port
-
-    def make_consul(self, host: str, port: int) -> consul.Consul:
-        return consul.Consul(host=host, port=port)
+    @inject_value("consul.watchdog.interval", default=5)
+    def set_interval(self, interval):
+        self.watchdog_interval = interval
 
     # lifecycle hooks
 
@@ -45,7 +49,6 @@ class ConsulComponentRegistry(ComponentRegistry):
     def setup(self):
         # create consul client
 
-        self.consul = self.make_consul(host=self.consul_host, port=self.consul_port)
         self.running = True
 
         # start thread
@@ -53,7 +56,7 @@ class ConsulComponentRegistry(ComponentRegistry):
         self.watchdog = threading.Thread(target=self.watch_consul, daemon=True)
         self.watchdog.start()
 
-    def inform_channels(self, old_address: ServiceAddress, new_address: Optional[ServiceAddress]):
+    def inform_channels(self, old_address: ChannelInstances, new_address: Optional[ChannelInstances]):
         for channel in self.watch_channels:
             if channel.address is old_address:
                 channel.set_address(new_address)
@@ -107,19 +110,17 @@ class ConsulComponentRegistry(ComponentRegistry):
 
             # time to sleep
 
-            time.sleep(5)
+            time.sleep(self.watchdog_interval)
 
     @abstractmethod
-    def watch(self, channel: Channel):
+    def watch(self, channel: Channel) -> None:
         self.watch_channels.append(channel)
 
         #self.component_addresses[channel.component_descriptor.name] = {}
 
    # public
 
-    def register_service(self, name, service_id, health: str, tags=None, meta=None):
-        ip = "host.docker.internal" # TODO
-
+    def register_service(self, name, service_id, health: str, tags=None, meta=None) -> None:
         self.consul.agent.service.register(
             name=name,
             service_id=service_id,
@@ -128,13 +129,13 @@ class ConsulComponentRegistry(ComponentRegistry):
             tags=tags or [],
             meta=meta or {},
             check=consul.Check().http(
-                url=f"http://{ip}:{self.port}{health}",
+                url=f"http://{self.ip}:{self.port}{health}",
                 interval="10s",
                 timeout="3s",
                 deregister="5m")
             )
 
-    def deregister(self, descriptor: ComponentDescriptor[Component]):
+    def deregister(self, descriptor: ComponentDescriptor[Component]) -> None:
         name = descriptor.name
 
         service_id = f"{self.ip}:{self.port}:{name}"
@@ -149,8 +150,8 @@ class ConsulComponentRegistry(ComponentRegistry):
 
     # private
 
-    def fetch_addresses(self, component: str, wait=None) -> dict[str, ServiceAddress]:
-        addresses : dict[str, ServiceAddress] = {} # channel name -> ServiceAddress
+    def fetch_addresses(self, component: str, wait=None) -> dict[str, ChannelInstances]:
+        addresses : dict[str, ChannelInstances] = {} # channel name -> ServiceAddress
 
         index, nodes = self.consul.health.service(component, passing=True, index=self.last_index.get(component, None), wait=wait)
         self.last_index[component] = index
@@ -170,7 +171,7 @@ class ConsulComponentRegistry(ComponentRegistry):
 
                 address = addresses.get(channel, None)
                 if address is None:
-                    address = ServiceAddress(component=component, channel=channel_name)
+                    address = ChannelInstances(component=component, channel=channel_name)
                     addresses[channel] = address
 
                 address.urls.append(url)
@@ -200,7 +201,7 @@ class ConsulComponentRegistry(ComponentRegistry):
 
         self.register_service(name, id, descriptor.health, tags =["component"], meta={"channels": addresses})
 
-    def get_addresses(self, descriptor: ComponentDescriptor) -> list[ServiceAddress]:
+    def get_addresses(self, descriptor: ComponentDescriptor) -> list[ChannelInstances]:
         component_addresses = self.component_addresses.get(descriptor.name, None)
         if component_addresses is None:
             component_addresses = self.fetch_addresses(descriptor.name)

aspyx_service/restchannel.py

@@ -1,3 +1,6 @@
+"""
+rest channel implementation
+"""
 import inspect
 import re
 from dataclasses import is_dataclass, asdict
@@ -7,7 +10,7 @@ from typing import get_type_hints, TypeVar, Annotated, Callable, get_origin, get
 from pydantic import BaseModel
 
 from aspyx.reflection import DynamicProxy, Decorators
-from .service import RemoteServiceException, ServiceException, channel
+from .service import ServiceException, channel
 
 T = TypeVar("T")
 
@@ -25,14 +28,26 @@ QueryParam = lambda t: Annotated[t, QueryParamMarker]
 
 # decorators
 
-def rest(url):
+def rest(url=""):
+    """
+    mark service interfaces to add a url prefix
+
+    Args:
+        url: prefix that will be added to all urls
+    """
     def decorator(cls):
         Decorators.add(cls, rest, url)
 
         return cls
     return decorator
 
-def get(url):
+def get(url: str):
+    """
+    methods marked with `get` will be executed by calling a http get request.
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, get, url)
 
@@ -40,7 +55,14 @@ def get(url):
     return decorator
 
 
-def post(url):
+def post(url: str):
+    """
+    methods marked with `post` will be executed by calling a http get request.
+    The body parameter should be marked with `Body(<param>)`
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, post, url)
 
@@ -48,7 +70,13 @@ def post(url):
 
     return decorator
 
-def put(url):
+def put(url: str):
+    """
+    methods marked with `put` will be executed by calling a http put request.
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, put, url)
 
@@ -56,7 +84,13 @@ def put(url):
 
     return decorator
 
-def delete(url):
+def delete(url: str):
+    """
+    methods marked with `delete` will be executed by calling a http delete request.
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, delete, url)
 
@@ -64,7 +98,13 @@ def delete(url):
 
     return decorator
 
-def patch(url):
+def patch(url: str):
+    """
+    methods marked with `patch` will be executed by calling a http patch request.
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, patch, url)
 
@@ -72,20 +112,22 @@ def patch(url):
 
     return decorator
 
-
-
-
 @channel("rest")
 class RestChannel(HTTPXChannel):
+    """
+    A rest channel executes http requests as specified by the corresponding decorators and annotations,
+    """
     __slots__ = [
         "signature",
         "url_template",
         "type",
+        "calls",
         "return_type",
         "path_param_names",
         "query_param_names",
         "body_param_name"
     ]
+
     # local class
 
     class Call:
@@ -133,7 +175,7 @@ class RestChannel(HTTPXChannel):
     # constructor
 
     def __init__(self):
-        super().__init__("rest")
+        super().__init__()
 
         self.calls : dict[Callable, RestChannel.Call] = {}
 
@@ -147,19 +189,6 @@ class RestChannel(HTTPXChannel):
 
         return call
 
-    def to_dict(self, obj):
-        if obj is None:
-            return None
-        if is_dataclass(obj):
-            return asdict(obj)
-        elif isinstance(obj, BaseModel):
-            return obj.dict()
-        elif hasattr(obj, "__dict__"):
-            return vars(obj)
-        else:
-            # fallback for primitives etc.
-            return obj
-
     # override
 
     def invoke(self, invocation: DynamicProxy.Invocation):
@@ -196,4 +225,4 @@ class RestChannel(HTTPXChannel):
                 raise ServiceException(
                     f"no url for channel {self.name} for component {self.component_descriptor.name} registered")
         except Exception as e:
-            raise ServiceException(f"communication exception {e}") from e
+            raise ServiceException(f"communication exception {e}") from e

aspyx_service/serialization.py

@@ -98,7 +98,7 @@ class TypeDeserializer:
             return deser_union
 
         if isinstance(typ, type) and issubclass(typ, BaseModel):
-            return lambda v: typ.parse_obj(v)
+            return typ.parse_obj
 
         if is_dataclass(typ):
             field_deserializers = {f.name: TypeDeserializer(f.type) for f in fields(typ)}
@@ -122,4 +122,13 @@ class TypeDeserializer:
 
 @lru_cache(maxsize=512)
 def get_deserializer(typ):
+    """
+    return a function that is able to deserialize a value of the specified type
+
+    Args:
+        typ: the type
+
+    Returns:
+
+    """
     return TypeDeserializer(typ)

aspyx_service/server.py

@@ -2,7 +2,6 @@
 FastAPI server implementation for the aspyx service framework.
 """
 import atexit
-import functools
 import inspect
 import threading
 from typing import Type, Optional, Callable
@@ -28,6 +27,9 @@ from .restchannel import get, post, put, delete, rest
 
 
 class FastAPIServer(Server):
+    """
+    A server utilizing fastapi framework.
+    """
     # constructor
 
     def __init__(self, host="0.0.0.0", port=8000, **kwargs):
@@ -41,7 +43,7 @@ class FastAPIServer(Server):
         self.component_registry: Optional[ComponentRegistry] = None
 
         self.router = APIRouter()
-        self.fast_api = FastAPI(host=self.host, port=Server.port, debug=True)
+        self.fast_api = FastAPI()
 
         # cache
 
@@ -82,14 +84,21 @@ class FastAPIServer(Server):
                         )
 
     def start(self):
-        def run():
-            uvicorn.run(self.fast_api, host=self.host, port=self.port, access_log=False)
+        """
+        start the fastapi server in a thread
+        """
+
+        config = uvicorn.Config(self.fast_api, host=self.host, port=self.port, log_level="debug")
+        server = uvicorn.Server(config)
 
-        self.server_thread = threading.Thread(target=run, daemon=True)
-        self.server_thread.start()
+        thread = threading.Thread(target=server.run, daemon=True)
+        thread.start()
 
         print(f"server started on {self.host}:{self.port}")
 
+        return thread
+
+
     def get_deserializers(self, service: Type, method):
         deserializers = self.deserializers.get(method, None)
         if deserializers is None:
@@ -105,8 +114,8 @@ class FastAPIServer(Server):
 
         deserializers = self.get_deserializers(type, method)
 
-        for i in range(0, len(args)):
-            args[i] = deserializers[i](args[i])
+        for i, arg in enumerate(args):
+            args[i] = deserializers[i](arg)
 
         return args
 
@@ -181,6 +190,15 @@ class FastAPIServer(Server):
         self.router.get(url)(get_health_response)
 
     def boot(self, module_type: Type) -> Environment:
+        """
+        startup the service manager, DI framework and the fastapi server based on the supplied module
+
+        Args:
+            module_type: the module
+
+        Returns:
+
+        """
         # setup environment
 
         self.environment = Environment(module_type)
@@ -194,8 +212,8 @@ class FastAPIServer(Server):
         self.add_routes()
         self.fast_api.include_router(self.router)
 
-        #for route in self.fast_api.routes:
-        #    print(f"{route.name}: {route.path} [{route.methods}]")
+        for route in self.fast_api.routes:
+            print(f"{route.name}: {route.path} [{route.methods}]")
 
         # start server thread