aspyx-service 0.10.0__tar.gz → 0.10.1__tar.gz

aspyx_service-0.10.1/PKG-INFO

@@ -0,0 +1,505 @@
+Metadata-Version: 2.4
+Name: aspyx_service
+Version: 0.10.1
+Summary: Aspyx Service framework
+Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Andreas Ernst
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: aspyx>=1.5.0
+Requires-Dist: fastapi~=0.115.13
+Requires-Dist: httpx~=0.28.1
+Requires-Dist: msgpack~=1.1.1
+Requires-Dist: python-consul2~=0.1.5
+Requires-Dist: uvicorn[standard]
+Description-Content-Type: text/markdown
+
+# Service
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Service and Component declaration](#service-and-component-declaration)
+- [Service and Component implementation](#service-and-component-implementation)
+- [Health Checks](#health-checks)
+- [Service Manager](#service-manager)
+- [Component Registry](#component-registry)
+- [Channels](#channels)
+  - [Performance](#performance)
+  - [Rest Calls](#rest-calls)
+  - [Intercepting calls](#intercepting-calls)
+- [FastAPI server](#fastapi-server)
+- [Implementing Channels](#implementing-channels)
+- [Version History](#version-history)
+
+## Introduction
+
+The Aspyx service library is built on top of the DI core framework and adds a microservice based architecture,
+that lets you deploy, discover and call services with different remoting protocols and pluggable discovery services.
+
+The basic design consists of four different concepts:
+
+!!! info "Service"
+  defines a group of methods that can be called either locally or remotely. 
+  These methods represent the functional interface exposed to clients — similar to an interface in traditional programming
+
+!!! info "Component"
+  a component bundles one or more services and declares the channels (protocols) used to expose them.
+  Think of a component as a deployment unit or module.
+
+!!! info "Component Registry "
+  acts as the central directory for managing available components.
+  It allows the framework to register, discover, and resolve components and their services.
+
+!!! info "Channel"
+  is a pluggable transport layer that defines how service method invocations are transmitted and handled.
+
+Let's look at the "interface" layer first.
+
+**Example**:
+```python
+@service(name="test-service", description="test service")
+class TestService(Service):
+    @abstractmethod
+    def hello(self, message: str) -> str:
+        pass
+
+@component(name="test-component", services =[TestService])
+class TestComponent(Component):
+    pass
+```
+
+After booting the DI infrastructure with a main module we could already call a service:
+
+**Example**:
+```python
+@module(imports=[ServiceModule])
+class Module:
+    def __init__(self):
+        pass
+    
+    @create()
+    def create_registry(self) -> ConsulComponentRegistry:
+        return ConsulComponentRegistry(Server.port, "http://localhost:8500") # a consul based registry!
+
+environment = Environment(Module)
+service_manager = environment.get(ServiceManager)
+
+service = service_manager.get_service(TestService)
+
+service.hello("world")
+```
+
+The technical details are completely transparent, as a dynamic proxy encapsulates the internals.
+
+As we can also host implementations, lets look at this side as well:
+
+```python
+@implementation()
+class TestComponentImpl(AbstractComponent, TestComponent):
+    # constructor
+
+    def __init__(self):
+        super().__init__()
+
+    # implement Component
+
+    def get_addresses(self, port: int) -> list[ChannelAddress]:
+        return [ChannelAddress("dispatch-json", f"http://{Server.get_local_ip()}:{port}")]
+
+@implementation()
+class TestServiceImpl(TestService):
+    def __init__(self):
+        pass
+
+    def hello(self, message: str) -> str:
+        return f"hello {message}"
+```
+
+The interesting part if the `get_addresses` method that return a list of channel addresses, that can be used to execute remote calls.
+In this case a channel is used that exposes a single http endpoint, that will dispatch to the correct service method.
+This information is registered with the appropriate component registry and is used by other processes. 
+
+The required - `FastAPI` - infrastructure to expose those services is started with the call:
+
+```python
+server = FastAPIServer(host="0.0.0.0", port=8000)
+
+environment = server.boot(Module)
+```
+
+Of course, service can also be called locally. In case of multiple possible channels, a keyword argument is used to 
+determine a specific channel. As a local channel has the name "local", the appropriate call is:
+
+```python
+ service = service_manager.get_service(TestService, preferred_channel="local")
+```
+
+## Features
+
+The library offers:
+
+- sync and async support
+- multiple - extensible - channel implementations supporting dataclasses and pydantic data models.
+- ability to customize http calls with interceptors ( via the AOP abilities )
+- `fastapi` based channels covering simple rest endpoints including `msgpack` support.
+- `httpx` based clients for dispatching channels and simple rest endpoint with the help of low-level decorators.
+- first registry implementation based on `consul`
+- support for configurable health checks
+
+As well as the DI and AOP core, all mechanisms are heavily optimized.
+A simple benchmark resulted in message roundtrips in significanlty under a ms per call.
+
+Let's see some details
+
+## Service and Component declaration 
+
+Every service needs to inherit from the "tagging interface" `Service`
+
+```python
+@service(name="test-service", description="test service")
+class TestService(Service):
+    @abstractmethod
+    def hello(self, message: str) -> str:
+        pass
+```
+
+The decorator can add a name and a description. If `name` is not set, the class name converted to snake case is used.
+
+A component needs to derive from `Component`:
+
+```python
+@component(services =[TestService])
+class TestComponent(Component):
+    pass
+```
+
+The `services` argument references a list of service interfaces that are managed by this component, meaning that they all are 
+exposed by the same channels.
+
+`Component` defines the abstract methods:
+
+- `def startup(self) -> None`
+   called initially after booting the system
+
+- `def shutdown(self) -> None:`
+   called before shutting fown the system
+
+- `def get_addresses(self, port: int) -> list[ChannelAddress]:`
+   return  a list of available `ChannelAddress`es that this component exposes
+
+- `def get_status(self) -> ComponentStatus:`
+   return the status of this component ( one of the `ComponentStatus` enums `VIRGIN`, `RUNNING`, and `STOPPED`)
+
+- `async def get_health(self) -> HealthCheckManager.Health:`
+   return the health status of a component implementation.
+
+## Service and Component implementation
+
+Service implementations implement the corresponding interface and are decorated with `@implementation`
+
+```python
+@implementation()
+class TestServiceImpl(TestService):
+    def __init__(self):
+        pass
+```
+
+The constructor is required since the instances are managed by the DI framework.
+
+Component implementations derive from the interface and the abstract base class `AbstractComponent`
+
+```python
+@implementation()
+class TestComponentImpl(AbstractComponent, TestComponent):
+    # constructor
+
+    def __init__(self):
+        super().__init__()
+
+    # implement Component
+
+    def get_addresses(self, port: int) -> list[ChannelAddress]:
+        return [ChannelAddress("dispatch-json", f"http://{Server.get_local_ip()}:{port}")]
+```
+
+As a minimum you have to declare the constructor and the `get_addresses` method, that exposes channel addresses
+
+## Health Checks
+
+Every component can declare a HTTP health endpoint and the corresponding logic to compute the current status.
+
+Two additional things have to be done:
+
+- adding a `@health(<endpoint>)` decorator to the class
+- implementing the `get_health()` method that returns a `HealthCheckManager.Health`
+
+While you can instantiate the `Health` class directly via
+ 
+```
+HealthCheckManager.Health(HealtStatus.OK)
+```
+
+it typically makes more sense to let the system execute a number of configured checks and compute the overall result automatically.
+
+For this purpose injectable classes can be decorated with `@health_checks()` that contain methods in turn decorated with `@health_check`
+
+**Example**:
+
+```python
+@health_checks()
+@injectable()
+class Checks:
+    def __init__(self):
+        pass
+
+    @health_check(fail_if_slower_than=1)
+    def check_performance(self, result: HealthCheckManager.Result):
+        ... # should be done in under a second
+
+    @health_check(name="check", cache=10)
+    def check(self, result: HealthCheckManager.Result):
+        ok = ...
+        result.set_status(if ok HealthStatus.OK else HealthStatus.ERROR)
+```
+
+The methods are expected to have a single parameter of type `HealthCheckManager.Result` that can be used to set the status including detail information with
+
+```
+set_status(status: HealthStatus, details = "")
+```
+
+When called, the default is already `OK`.
+
+The decorator accepts a couple of parameters:
+
+- `fail_if_slower_than=0` 
+   time in `s` that the check is expected to take as a maximum. As soon as the time is exceeded, the status is set to `ERROR`
+- `cache`
+   time in 's' that the last result is cached. This is done in order to prevent health-checks putting even more strain on a heavily used system.
+
+## Service Manager
+
+`ServiceManager` is the central class used to retrieve service proxies.
+
+```python
+def get_service(self, service_type: Type[T], preferred_channel="") -> T
+```
+
+- `type` is the requested service interface
+- `preferred_channel` the name of the preferred channel.
+
+If not specified, the first registered channel is used, which btw. is a local channel - called `local` -  in case of implementing services.
+
+## Component Registry
+
+The component registry is the place where component implementations are registered and retrieved.
+
+In addition to a `LocalComponentRegistry` ( which is used for testing purposes ) the only implementation is
+
+`ConsulComponentRegistry`
+
+Constructor arguments are
+
+- `port: int` the own port
+- `consul: Consul` the consul instance
+
+The component registry is also responsible to execute regular health-checks to track component healths.
+As soon as - in our case consul - decides that a component is not alive anymore, it will notify the clients via regular heartbeats about address changes
+which will be propagated to channels talking to the appropriate component.
+
+Currently, this only affects the list of possible URLs which are required by the channels!
+
+## Channels
+
+Channels implement the possible transport layer protocols. In the sense of a dynamic proxy, they are the invocation handlers!
+
+Several channels are implemented:
+
+- `dispatch-json`
+   channel that dispatches generic `Request` objects via a `invoke` POST-call
+- `dispatch-msgpack`
+   channel that dispatches generic `Request` objects via a `invoke` POST-call after packing the json with msgpack
+- `rest`
+  channel that executes regular rest-calls as defined by a couple of decorators.
+
+All channels react on changed URLs as provided by the component registry.
+
+A so called `URLSelector` is used internally to provide URLs for every single call. Two subclasses exist that offer a different logic
+
+- `FirstURLSelector` always returns the first URL of the list of possible URLs
+- `RoundRobinURLSelector` switches sequentially between all URLs.
+
+To customize the behavior, an around advice can be implemented easily:
+
+**Example**:
+ 
+```python
+@advice
+class ChannelAdvice:
+    def __init__(self):
+        pass
+
+@advice
+class ChannelAdvice:
+    def __init__(self):
+        pass
+
+    @around(methods().named("customize").of_type(Channel))
+    def customize_channel(self, invocation: Invocation):
+        channel = cast(Channel, invocation.args[0])
+
+        channel.select_round_robin() # or select_first_url()
+
+        return invocation.proceed()
+```
+
+### Performance
+
+I benchmarked the different implementations with a recursive dataclass as an argument and return value.
+The avg response times - on a local server - where all below 1ms per call.
+
+- rest calls are the slowest ( about 0.7ms )
+- dispatching-json 20% faster
+- dispatching-msgpack 30% faster
+
+The biggest advantage of the dispatching flavors is, that you don't have to worry about the additional decorators!
+
+### Rest Calls
+
+Invoking rest calls requires decorators and some marker annotations.
+
+**Example**:
+
+```python
+@service()
+@rest("/api")
+class TestService(Service):
+    @get("/hello/{message}")
+    def hello(self, message: str) -> str:
+        pass
+
+    @post("/post/")
+    def set_data(self, data: Body(Data)) -> Data:
+        pass
+```
+
+The decorators `get`,  `put`,  `post` and  `delete` specify the methods.
+
+If the class is decorated with `@rest(<prefix>)`, the corresponding prefix will be appended at the beginning.
+
+Additional annotations are
+- `Body` the post body
+- `QueryParam`marked for query params
+
+### Intercepting calls
+
+The client side HTTP calling is done with `httpx` instances of type `Httpx.Client` or `Httpx.AsyncClient`.
+
+To add the possibility to add interceptors - for token handling, etc. - the channel base class `HTTPXChannel` defines
+the methods `make_client()` and `make_async_client` that can be modified with an around advice.
+
+**Example**:
+
+```python
+class InterceptingClient(httpx.Client):
+    # constructor
+
+    def __init__(self, *args, **kwargs):
+        self.token_provider = ...
+        super().__init__(*args, **kwargs)
+
+    # override
+
+    def request(self, method, url, *args, **kwargs):
+        headers = kwargs.pop("headers", {})
+        headers["Authorization"] = f"Bearer {self.token_provider()}"
+        kwargs["headers"] = headers
+
+        return super().request(method, url, *args, **kwargs)
+    
+@advice
+class ChannelAdvice:
+    def __init__(self):
+        pass
+
+    @around(methods().named("make_client").of_type(HTTPXChannel))
+    def make_client(self, invocation: Invocation):
+        return InterceptingClient()
+```
+
+## FastAPI server
+
+In order to expose components via HTTP, the corresponding infrastructure in form of a FastAPI server needs to be setup. 
+
+
+```python
+@module()
+class Module():
+    def __init__(self):
+        pass
+    
+ server = FastAPIServer(host="0.0.0.0", port=8000)
+
+ environment = server.boot(Module) # will start the http server
+```
+
+This setup will also expose all service interfaces decorated with the corresponding http decorators!
+No need to add any FastAPI decorators, since the mapping is already done internally! 
+
+## Implementing Channels
+
+To implement a new channel, you only need to derive from one of the possible base classes ( `Channel` or `HTTPXChannel` that already has a `httpx` client)
+and decorate it with `@channel(<name>)`
+
+The main methods to implement are `ìnvoke` and `ìnvoke_async`
+
+**Example**:
+
+```python
+@channel("fancy")
+class FancyChannel(Channel):
+    # constructor
+
+    def __init__(self):
+        super().__init__()
+
+    # override
+
+    def invoke(self, invocation: DynamicProxy.Invocation):
+        return ...
+    
+     async def invoke_async(self, invocation: DynamicProxy.Invocation):
+        return await ...
+        
+```
+
+# Version History
+
+**0.10.0**
+
+- first release version
+
+
+
+
+

aspyx_service-0.10.1/README.md

@@ -0,0 +1,469 @@
+# Service
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Service and Component declaration](#service-and-component-declaration)
+- [Service and Component implementation](#service-and-component-implementation)
+- [Health Checks](#health-checks)
+- [Service Manager](#service-manager)
+- [Component Registry](#component-registry)
+- [Channels](#channels)
+  - [Performance](#performance)
+  - [Rest Calls](#rest-calls)
+  - [Intercepting calls](#intercepting-calls)
+- [FastAPI server](#fastapi-server)
+- [Implementing Channels](#implementing-channels)
+- [Version History](#version-history)
+
+## Introduction
+
+The Aspyx service library is built on top of the DI core framework and adds a microservice based architecture,
+that lets you deploy, discover and call services with different remoting protocols and pluggable discovery services.
+
+The basic design consists of four different concepts:
+
+!!! info "Service"
+  defines a group of methods that can be called either locally or remotely. 
+  These methods represent the functional interface exposed to clients — similar to an interface in traditional programming
+
+!!! info "Component"
+  a component bundles one or more services and declares the channels (protocols) used to expose them.
+  Think of a component as a deployment unit or module.
+
+!!! info "Component Registry "
+  acts as the central directory for managing available components.
+  It allows the framework to register, discover, and resolve components and their services.
+
+!!! info "Channel"
+  is a pluggable transport layer that defines how service method invocations are transmitted and handled.
+
+Let's look at the "interface" layer first.
+
+**Example**:
+```python
+@service(name="test-service", description="test service")
+class TestService(Service):
+    @abstractmethod
+    def hello(self, message: str) -> str:
+        pass
+
+@component(name="test-component", services =[TestService])
+class TestComponent(Component):
+    pass
+```
+
+After booting the DI infrastructure with a main module we could already call a service:
+
+**Example**:
+```python
+@module(imports=[ServiceModule])
+class Module:
+    def __init__(self):
+        pass
+    
+    @create()
+    def create_registry(self) -> ConsulComponentRegistry:
+        return ConsulComponentRegistry(Server.port, "http://localhost:8500") # a consul based registry!
+
+environment = Environment(Module)
+service_manager = environment.get(ServiceManager)
+
+service = service_manager.get_service(TestService)
+
+service.hello("world")
+```
+
+The technical details are completely transparent, as a dynamic proxy encapsulates the internals.
+
+As we can also host implementations, lets look at this side as well:
+
+```python
+@implementation()
+class TestComponentImpl(AbstractComponent, TestComponent):
+    # constructor
+
+    def __init__(self):
+        super().__init__()
+
+    # implement Component
+
+    def get_addresses(self, port: int) -> list[ChannelAddress]:
+        return [ChannelAddress("dispatch-json", f"http://{Server.get_local_ip()}:{port}")]
+
+@implementation()
+class TestServiceImpl(TestService):
+    def __init__(self):
+        pass
+
+    def hello(self, message: str) -> str:
+        return f"hello {message}"
+```
+
+The interesting part if the `get_addresses` method that return a list of channel addresses, that can be used to execute remote calls.
+In this case a channel is used that exposes a single http endpoint, that will dispatch to the correct service method.
+This information is registered with the appropriate component registry and is used by other processes. 
+
+The required - `FastAPI` - infrastructure to expose those services is started with the call:
+
+```python
+server = FastAPIServer(host="0.0.0.0", port=8000)
+
+environment = server.boot(Module)
+```
+
+Of course, service can also be called locally. In case of multiple possible channels, a keyword argument is used to 
+determine a specific channel. As a local channel has the name "local", the appropriate call is:
+
+```python
+ service = service_manager.get_service(TestService, preferred_channel="local")
+```
+
+## Features
+
+The library offers:
+
+- sync and async support
+- multiple - extensible - channel implementations supporting dataclasses and pydantic data models.
+- ability to customize http calls with interceptors ( via the AOP abilities )
+- `fastapi` based channels covering simple rest endpoints including `msgpack` support.
+- `httpx` based clients for dispatching channels and simple rest endpoint with the help of low-level decorators.
+- first registry implementation based on `consul`
+- support for configurable health checks
+
+As well as the DI and AOP core, all mechanisms are heavily optimized.
+A simple benchmark resulted in message roundtrips in significanlty under a ms per call.
+
+Let's see some details
+
+## Service and Component declaration 
+
+Every service needs to inherit from the "tagging interface" `Service`
+
+```python
+@service(name="test-service", description="test service")
+class TestService(Service):
+    @abstractmethod
+    def hello(self, message: str) -> str:
+        pass
+```
+
+The decorator can add a name and a description. If `name` is not set, the class name converted to snake case is used.
+
+A component needs to derive from `Component`:
+
+```python
+@component(services =[TestService])
+class TestComponent(Component):
+    pass
+```
+
+The `services` argument references a list of service interfaces that are managed by this component, meaning that they all are 
+exposed by the same channels.
+
+`Component` defines the abstract methods:
+
+- `def startup(self) -> None`
+   called initially after booting the system
+
+- `def shutdown(self) -> None:`
+   called before shutting fown the system
+
+- `def get_addresses(self, port: int) -> list[ChannelAddress]:`
+   return  a list of available `ChannelAddress`es that this component exposes
+
+- `def get_status(self) -> ComponentStatus:`
+   return the status of this component ( one of the `ComponentStatus` enums `VIRGIN`, `RUNNING`, and `STOPPED`)
+
+- `async def get_health(self) -> HealthCheckManager.Health:`
+   return the health status of a component implementation.
+
+## Service and Component implementation
+
+Service implementations implement the corresponding interface and are decorated with `@implementation`
+
+```python
+@implementation()
+class TestServiceImpl(TestService):
+    def __init__(self):
+        pass
+```
+
+The constructor is required since the instances are managed by the DI framework.
+
+Component implementations derive from the interface and the abstract base class `AbstractComponent`
+
+```python
+@implementation()
+class TestComponentImpl(AbstractComponent, TestComponent):
+    # constructor
+
+    def __init__(self):
+        super().__init__()
+
+    # implement Component
+
+    def get_addresses(self, port: int) -> list[ChannelAddress]:
+        return [ChannelAddress("dispatch-json", f"http://{Server.get_local_ip()}:{port}")]
+```
+
+As a minimum you have to declare the constructor and the `get_addresses` method, that exposes channel addresses
+
+## Health Checks
+
+Every component can declare a HTTP health endpoint and the corresponding logic to compute the current status.
+
+Two additional things have to be done:
+
+- adding a `@health(<endpoint>)` decorator to the class
+- implementing the `get_health()` method that returns a `HealthCheckManager.Health`
+
+While you can instantiate the `Health` class directly via
+ 
+```
+HealthCheckManager.Health(HealtStatus.OK)
+```
+
+it typically makes more sense to let the system execute a number of configured checks and compute the overall result automatically.
+
+For this purpose injectable classes can be decorated with `@health_checks()` that contain methods in turn decorated with `@health_check`
+
+**Example**:
+
+```python
+@health_checks()
+@injectable()
+class Checks:
+    def __init__(self):
+        pass
+
+    @health_check(fail_if_slower_than=1)
+    def check_performance(self, result: HealthCheckManager.Result):
+        ... # should be done in under a second
+
+    @health_check(name="check", cache=10)
+    def check(self, result: HealthCheckManager.Result):
+        ok = ...
+        result.set_status(if ok HealthStatus.OK else HealthStatus.ERROR)
+```
+
+The methods are expected to have a single parameter of type `HealthCheckManager.Result` that can be used to set the status including detail information with
+
+```
+set_status(status: HealthStatus, details = "")
+```
+
+When called, the default is already `OK`.
+
+The decorator accepts a couple of parameters:
+
+- `fail_if_slower_than=0` 
+   time in `s` that the check is expected to take as a maximum. As soon as the time is exceeded, the status is set to `ERROR`
+- `cache`
+   time in 's' that the last result is cached. This is done in order to prevent health-checks putting even more strain on a heavily used system.
+
+## Service Manager
+
+`ServiceManager` is the central class used to retrieve service proxies.
+
+```python
+def get_service(self, service_type: Type[T], preferred_channel="") -> T
+```
+
+- `type` is the requested service interface
+- `preferred_channel` the name of the preferred channel.
+
+If not specified, the first registered channel is used, which btw. is a local channel - called `local` -  in case of implementing services.
+
+## Component Registry
+
+The component registry is the place where component implementations are registered and retrieved.
+
+In addition to a `LocalComponentRegistry` ( which is used for testing purposes ) the only implementation is
+
+`ConsulComponentRegistry`
+
+Constructor arguments are
+
+- `port: int` the own port
+- `consul: Consul` the consul instance
+
+The component registry is also responsible to execute regular health-checks to track component healths.
+As soon as - in our case consul - decides that a component is not alive anymore, it will notify the clients via regular heartbeats about address changes
+which will be propagated to channels talking to the appropriate component.
+
+Currently, this only affects the list of possible URLs which are required by the channels!
+
+## Channels
+
+Channels implement the possible transport layer protocols. In the sense of a dynamic proxy, they are the invocation handlers!
+
+Several channels are implemented:
+
+- `dispatch-json`
+   channel that dispatches generic `Request` objects via a `invoke` POST-call
+- `dispatch-msgpack`
+   channel that dispatches generic `Request` objects via a `invoke` POST-call after packing the json with msgpack
+- `rest`
+  channel that executes regular rest-calls as defined by a couple of decorators.
+
+All channels react on changed URLs as provided by the component registry.
+
+A so called `URLSelector` is used internally to provide URLs for every single call. Two subclasses exist that offer a different logic
+
+- `FirstURLSelector` always returns the first URL of the list of possible URLs
+- `RoundRobinURLSelector` switches sequentially between all URLs.
+
+To customize the behavior, an around advice can be implemented easily:
+
+**Example**:
+ 
+```python
+@advice
+class ChannelAdvice:
+    def __init__(self):
+        pass
+
+@advice
+class ChannelAdvice:
+    def __init__(self):
+        pass
+
+    @around(methods().named("customize").of_type(Channel))
+    def customize_channel(self, invocation: Invocation):
+        channel = cast(Channel, invocation.args[0])
+
+        channel.select_round_robin() # or select_first_url()
+
+        return invocation.proceed()
+```
+
+### Performance
+
+I benchmarked the different implementations with a recursive dataclass as an argument and return value.
+The avg response times - on a local server - where all below 1ms per call.
+
+- rest calls are the slowest ( about 0.7ms )
+- dispatching-json 20% faster
+- dispatching-msgpack 30% faster
+
+The biggest advantage of the dispatching flavors is, that you don't have to worry about the additional decorators!
+
+### Rest Calls
+
+Invoking rest calls requires decorators and some marker annotations.
+
+**Example**:
+
+```python
+@service()
+@rest("/api")
+class TestService(Service):
+    @get("/hello/{message}")
+    def hello(self, message: str) -> str:
+        pass
+
+    @post("/post/")
+    def set_data(self, data: Body(Data)) -> Data:
+        pass
+```
+
+The decorators `get`,  `put`,  `post` and  `delete` specify the methods.
+
+If the class is decorated with `@rest(<prefix>)`, the corresponding prefix will be appended at the beginning.
+
+Additional annotations are
+- `Body` the post body
+- `QueryParam`marked for query params
+
+### Intercepting calls
+
+The client side HTTP calling is done with `httpx` instances of type `Httpx.Client` or `Httpx.AsyncClient`.
+
+To add the possibility to add interceptors - for token handling, etc. - the channel base class `HTTPXChannel` defines
+the methods `make_client()` and `make_async_client` that can be modified with an around advice.
+
+**Example**:
+
+```python
+class InterceptingClient(httpx.Client):
+    # constructor
+
+    def __init__(self, *args, **kwargs):
+        self.token_provider = ...
+        super().__init__(*args, **kwargs)
+
+    # override
+
+    def request(self, method, url, *args, **kwargs):
+        headers = kwargs.pop("headers", {})
+        headers["Authorization"] = f"Bearer {self.token_provider()}"
+        kwargs["headers"] = headers
+
+        return super().request(method, url, *args, **kwargs)
+    
+@advice
+class ChannelAdvice:
+    def __init__(self):
+        pass
+
+    @around(methods().named("make_client").of_type(HTTPXChannel))
+    def make_client(self, invocation: Invocation):
+        return InterceptingClient()
+```
+
+## FastAPI server
+
+In order to expose components via HTTP, the corresponding infrastructure in form of a FastAPI server needs to be setup. 
+
+
+```python
+@module()
+class Module():
+    def __init__(self):
+        pass
+    
+ server = FastAPIServer(host="0.0.0.0", port=8000)
+
+ environment = server.boot(Module) # will start the http server
+```
+
+This setup will also expose all service interfaces decorated with the corresponding http decorators!
+No need to add any FastAPI decorators, since the mapping is already done internally! 
+
+## Implementing Channels
+
+To implement a new channel, you only need to derive from one of the possible base classes ( `Channel` or `HTTPXChannel` that already has a `httpx` client)
+and decorate it with `@channel(<name>)`
+
+The main methods to implement are `ìnvoke` and `ìnvoke_async`
+
+**Example**:
+
+```python
+@channel("fancy")
+class FancyChannel(Channel):
+    # constructor
+
+    def __init__(self):
+        super().__init__()
+
+    # override
+
+    def invoke(self, invocation: DynamicProxy.Invocation):
+        return ...
+    
+     async def invoke_async(self, invocation: DynamicProxy.Invocation):
+        return await ...
+        
+```
+
+# Version History
+
+**0.10.0**
+
+- first release version
+
+
+
+
+

{aspyx_service-0.10.0 → aspyx_service-0.10.1}/pyproject.toml

@@ -2,7 +2,7 @@
 
 [project]
 name = "aspyx_service"
-version = "0.10.0"
+version = "0.10.1"
 description = "Aspyx Service framework"
 authors = [{ name = "Andreas Ernst", email = "andreas.ernst7@gmail.com" }]
 readme = "README.md"

{aspyx_service-0.10.0 → aspyx_service-0.10.1}/src/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
@@ -24,6 +26,33 @@ 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):
@@ -117,9 +146,10 @@ class DispatchJSONChannel(HTTPXChannel):
         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}")
 
@@ -134,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}")
@@ -171,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",
@@ -196,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",

{aspyx_service-0.10.0 → aspyx_service-0.10.1}/src/aspyx_service/registries.py

@@ -10,6 +10,7 @@ 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
@@ -24,35 +25,23 @@ class ConsulComponentRegistry(ComponentRegistry):
     """
     # 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, 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="", port="") -> consul.Consul:
-        """
-        create and return a consul instance
-
-        Args:
-            host: the host
-            port: the port
-
-        Returns:
-            a consul instance
-
-        """
-        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
 
@@ -60,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
@@ -122,7 +110,7 @@ class ConsulComponentRegistry(ComponentRegistry):
 
             # time to sleep
 
-            time.sleep(5)
+            time.sleep(self.watchdog_interval)
 
     @abstractmethod
     def watch(self, channel: Channel) -> None:

{aspyx_service-0.10.0 → aspyx_service-0.10.1}/src/aspyx_service/restchannel.py

@@ -189,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):

{aspyx_service-0.10.0 → aspyx_service-0.10.1}/src/aspyx_service/server.py

@@ -88,7 +88,7 @@ class FastAPIServer(Server):
         start the fastapi server in a thread
         """
 
-        config = uvicorn.Config(self.fast_api, host=self.host, port=self.port, log_level="info")
+        config = uvicorn.Config(self.fast_api, host=self.host, port=self.port, log_level="debug")
         server = uvicorn.Server(config)
 
         thread = threading.Thread(target=server.run, daemon=True)

aspyx_service-0.10.0/PKG-INFO

@@ -1,37 +0,0 @@
-Metadata-Version: 2.4
-Name: aspyx_service
-Version: 0.10.0
-Summary: Aspyx Service framework
-Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
-License: MIT License
-        
-        Copyright (c) 2025 Andreas Ernst
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-License-File: LICENSE
-Requires-Python: >=3.9
-Requires-Dist: aspyx>=1.5.0
-Requires-Dist: fastapi~=0.115.13
-Requires-Dist: httpx~=0.28.1
-Requires-Dist: msgpack~=1.1.1
-Requires-Dist: python-consul2~=0.1.5
-Requires-Dist: uvicorn[standard]
-Description-Content-Type: text/markdown
-
-aspyx-service

aspyx_service-0.10.0/README.md

@@ -1 +0,0 @@
-aspyx-service