aspyx-service 0.11.2__py3-none-any.whl

aspyx_service/session.py

@@ -0,0 +1,136 @@
+"""
+session related module
+"""
+from abc import ABC, abstractmethod
+import contextvars
+from typing import Type, Optional, Callable, Any, TypeVar
+from datetime import datetime, timezone, timedelta
+from cachetools import TTLCache
+
+from aspyx.di import injectable
+
+
+class Session:
+    """
+    Base class for objects covers data related to a server side session.
+    """
+    def __init__(self):
+        pass
+
+T = TypeVar("T")
+
+class SessionContext:
+    # class properties
+
+    # current_session = ThreadLocal[Session]()
+    current_session = contextvars.ContextVar("session")
+
+    @classmethod
+    def get(cls, type: Type[T]) -> T:
+        """
+        return the current session associated with the context
+        Args:
+            type:  the session type
+
+        Returns:
+            the current session
+        """
+        return cls.current_session.get()
+
+    @classmethod
+    def set(cls, session: Session) -> None:
+        """
+        set the current session in the context
+        Args:
+            session: the session
+        """
+        cls.current_session.set(session)
+
+    @classmethod
+    def clear(cls) -> None:
+        """
+        delete the current session
+        """
+        cls.current_session.set(None)  # clear()
+
+@injectable()
+class SessionManager(SessionContext):
+    """
+    A SessionManager controls the lifecycle of sessions and is responsible to establish a session context local.
+    """
+
+    # local classes
+
+    class Storage(ABC):
+        @abstractmethod
+        def store(self, token: str, session: Session, ttl_seconds: int):
+            pass
+
+        @abstractmethod
+        def read(self, token: str) -> Optional[Session]:
+            pass
+
+    class InMemoryStorage(Storage):
+        """
+        InMemoryStorage is a simple in-memory storage for sessions.
+        It uses a TTLCache to store sessions with a time-to-live.
+        """
+        # constructor
+
+        def __init__(self, max_size = 1000, ttl = 3600):
+            self.cache = TTLCache(maxsize=max_size, ttl=ttl)
+
+        # implement
+
+        def store(self, token: str, session: 'Session', ttl_seconds: int):
+            expiry_time = datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)
+            self.cache[token] = (session, expiry_time)
+
+        def read(self, token: str) -> Optional['Session']:
+            value = self.cache.get(token)
+            if value is None:
+                return None
+
+            session, expiry = value
+            if expiry < datetime.now(timezone.utc):
+                del self.cache[token]
+                return None
+
+            return session
+
+    # constructor
+
+    def __init__(self, storage: 'SessionManager.Storage'):
+        self.storage = storage
+        self.session_factory : Optional[Callable[[Any], Session]] = None
+
+    # public
+
+    def set_factory(self, factory: Callable[..., Session]) -> None:
+        """
+        set a factory function that will be used to create a concrete session
+        Args:
+            factory: the function
+        """
+        self.session_factory = factory
+
+    def create_session(self, *args, **kwargs) -> Session:
+        """
+        create a session given the arguments (usually a token, etc.)
+        Args:
+            args: rest args
+            kwargs: keyword args
+
+        Returns:
+            the new session
+        """
+        return self.session_factory(*args, **kwargs)
+
+    def store_session(self, token: str, session: Session, expiry: datetime):
+        now = datetime.now(timezone.utc)
+        ttl_seconds = max(int((expiry - now).total_seconds()), 0)
+
+        self.storage.store(token, session, ttl_seconds)
+
+    def read_session(self, token: str) -> Optional[Session]:
+        return self.storage.read(token)

aspyx_service-0.11.2.dist-info/METADATA

@@ -0,0 +1,555 @@
+Metadata-Version: 2.4
+Name: aspyx_service
+Version: 0.11.2
+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.9.1
+Requires-Dist: fastapi~=0.115.13
+Requires-Dist: httpx~=0.28.1
+Requires-Dist: msgpack~=1.1.1
+Requires-Dist: protobuf~=5.29.4
+Requires-Dist: python-consul2~=0.1.5
+Requires-Dist: uvicorn[standard]
+Description-Content-Type: text/markdown
+
+# aspyx
+
+![Pylint](https://github.com/coolsamson7/aspyx/actions/workflows/pylint.yml/badge.svg)
+![Build Status](https://github.com/coolsamson7/aspyx/actions/workflows/ci.yml/badge.svg)
+![Python Versions](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12-blue)
+![License](https://img.shields.io/github/license/coolsamson7/aspyx)
+![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
+[![PyPI](https://img.shields.io/pypi/v/aspyx)](https://pypi.org/project/aspyx/)
+[![Docs](https://img.shields.io/badge/docs-online-blue?logo=github)](https://coolsamson7.github.io/aspyx/index/introduction)
+
+![image](https://github.com/user-attachments/assets/e808210a-b1a4-4fd0-93f1-b5f9845fa520)
+
+# 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)
+- [Session](#session)
+- [Authorization](#authorization)
+- [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:
+
+**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
+
+**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.
+
+**Component Registry**
+
+  acts as the central directory for managing available components.
+  It allows the framework to register, discover, and resolve components and their services.
+
+**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:
+    @create()
+    def create_registry(self) -> ConsulComponentRegistry:
+        return ConsulComponentRegistry(Server.port, Consul(host="localhost", port=8500))  # a consul based registry!
+
+
+environment = Environment(Module)
+service_manager = environment.read(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):
+    # 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 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:
+
+**Example**:
+
+```python
+ service = service_manager.get_service(TestService, preferred_channel="local")
+```
+
+The default can be set globally with the method `set_preferred_channel(channel: str)`
+
+Injecting services is also possible via the decorator `@inject_service(preferred_channel=""")`
+
+**Example**:
+
+```python
+@inject_service()
+def set_service(self, service: TestService)
+   self.service = service
+```
+
+## 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.
+
+## Installation
+
+Just install from PyPI with 
+
+`pip install aspyx-service`
+
+The library is tested with all Python version >= 3.9
+
+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):
+    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):
+    # 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 #  normally, we would inject stuff here
+    
+    # checks
+
+    @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 posts generic `Request` objects via a `invoke` POST-call
+- `dispatch-msgpack`
+   channel that posts generic `Request` objects via a `invoke` POST-call after packing the json with msgpack
+- `dispatch-protobuf`
+   channel that posts parameters via a `invoke` POST-call after packing the arguments with protobuf
+- `rest`
+  channel that executes regular rest-calls as defined by a couple of decorators.
+
+The `dispatch`channels have the big advantage, that you don`t have to deal with additional http 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:
+    @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
+- dispatching protobuf
+
+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
+
+You can skip the annotations, assuming the following heuristic:
+
+- if no body is marked it will pick the first parameter which is a dataclass or a pydantic model
+- all parameters which are not in the path or equal to the body are assumed to be 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
+
+The required - `FastAPI` - infrastructure to expose those services requires:
+
+- a `FastAPI` instance
+- an injectable `FastAPIServer`
+- and a final `boot` call with the root module, which will return an `Environment`
+
+```python
+fast_api = FastAPI() # so you can run it with uvicorn from command-line
+
+@module(imports=[ServiceModule])
+class Module:
+    def __init__(self):
+        pass
+
+    @create()
+    def create_server(self,  service_manager: ServiceManager, component_registry: ComponentRegistry) -> FastAPIServer:
+        return FastAPIServer(fastapi, service_manager, component_registry)
+    
+
+environment = FastAPIServer.boot(Module, host="0.0.0.0", port=8000)
+```
+
+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! 
+
+## Session
+
+TODO
+
+## Authorization
+
+TODO
+
+## 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
+
+**0.11.0**
+
+- added protobuf support
+
+
+
+
+

aspyx_service-0.11.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+aspyx_service/__init__.py,sha256=Mzt6pBhME_qDij2timEZT0emTTXRues_xXu3muhk3Jc,2642
+aspyx_service/authorization.py,sha256=0B1xb0WrRaj2rcGTHVUhh6i8aA0sy7BmpYA18xI9LQA,3833
+aspyx_service/channels.py,sha256=-MSOv4wh9rUy2JbxwkOKjItgYDyHyjbFfAIy-BCaIOc,15587
+aspyx_service/healthcheck.py,sha256=XiQx1T0DP0kcCyK_sYBuE-JHs5N285HotLVycFCgzBU,5612
+aspyx_service/protobuf.py,sha256=w2wZymTSObGhgevIRZJ9kRxiEel8f6BycMPQiTYNMzI,39595
+aspyx_service/registries.py,sha256=bnTjKb40fbZXA52E2lDSEzCWI5_NBKZzQjc8ffufB5g,8039
+aspyx_service/restchannel.py,sha256=9LAQA29fHuzao-U4-XWUEozugLczG2sqYLy-AeNNRAg,9138
+aspyx_service/server.py,sha256=C17Rvs3yMUW6pH7YyvmpoFsjAhWpp-8w-NpMLGbENPw,21516
+aspyx_service/service.py,sha256=gOX5rbOOLJ-cSIvxa_5lqo1DzcPmDoJCBbMP-ZYKYxs,27972
+aspyx_service/session.py,sha256=HjGpnmwdislc8Ur6pQbSMi2K-lvTsb9_XyO80zupiF8,3713
+aspyx_service/generator/__init__.py,sha256=FdQpi__6uB56pDjVk7MVf5fV3uLh4PeS9JNI3aKVVy8,297
+aspyx_service/generator/json_schema_generator.py,sha256=A26cd0-3MAUQWe_VwP5mJDaGYhV0ukU3i9SPxZxVQXI,6857
+aspyx_service/generator/openapi_generator.py,sha256=81ica1j60o6FQji7z_m0U0FfEieX4cjnaJpbtD7lQM0,4348
+aspyx_service-0.11.2.dist-info/METADATA,sha256=frRVfFVnqZi3fd4DC2fixRk-bG3OmZHXVllX3JsjRQ4,18127
+aspyx_service-0.11.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+aspyx_service-0.11.2.dist-info/licenses/LICENSE,sha256=n4jfx_MNj7cBtPhhI7MCoB_K35cj1icP9yJ4Rh4vlvY,1070
+aspyx_service-0.11.2.dist-info/RECORD,,