nlbone 0.6.19__py3-none-any.whl → 0.7.0__py3-none-any.whl

nlbone/core/application/di.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import inspect
+import sys
+from typing import Any, Callable, Dict, Optional, Type, get_args, get_origin, get_type_hints
+
+
+class TypeContainer:
+    """Tiny type-based DI: register_instance(T, obj) / register_factory(T, () -> obj)."""
+
+    def __init__(self) -> None:
+        self._instances: Dict[Type[Any], Any] = {}
+        self._factories: Dict[Type[Any], Callable[[], Any]] = {}
+
+    def register_instance(self, t: Type[Any], instance: Any) -> None:
+        self._instances[t] = instance
+
+    def register_factory(self, t: Type[Any], factory: Callable[[], Any]) -> None:
+        self._factories[t] = factory
+
+    def _providers(self):
+        for t, v in self._instances.items():
+            yield t, (lambda v=v: v)
+        for t, f in self._factories.items():
+            yield t, f
+
+    def _unwrap(self, ann: Any) -> tuple[list[Type[Any]], bool]:
+        if ann is inspect._empty:
+            return [], True
+        origin = get_origin(ann)
+        args = list(get_args(ann))
+        allow_none = False
+        if origin in (Optional, getattr(__import__("typing"), "Union")):
+            if type(None) in args:
+                allow_none = True
+                args = [a for a in args if a is not type(None)]
+            return [a for a in args if isinstance(a, type)], allow_none
+        if isinstance(ann, type):
+            return [ann], False
+        return [], True
+
+    def resolve(self, ann: Any) -> Any:
+        types, allow_none = self._unwrap(ann)
+        if not types:
+            if allow_none:
+                return None
+            raise LookupError(f"Cannot resolve {ann!r}")
+        for T in types:
+            # exact
+            for pt, make in self._providers():
+                if pt is T:
+                    return make()
+            # supertype/provider match
+            best = None
+            for pt, make in self._providers():
+                try:
+                    if issubclass(T, pt):
+                        dist = _mro_distance(T, pt)
+                        if best is None or dist < best[0]:
+                            best = (dist, make)
+                except TypeError:
+                    pass
+            if best:
+                return best[1]()
+        if allow_none:
+            return None
+        raise LookupError(f"No provider for {types}")
+
+
+def _mro_distance(sub: Type[Any], sup: Type[Any]) -> int:
+    try:
+        return sub.mro().index(sup)
+    except ValueError:
+        return 10**6
+
+
+def _type_hints(obj):
+    mod = sys.modules.get(getattr(obj, "__module__", "__name__"))
+    return get_type_hints(obj, globalns=vars(mod) if mod else None)
+
+
+def _build_kwargs(
+    sig: inspect.Signature,
+    hints: Dict[str, Any],
+    container: TypeContainer,
+    *,
+    skip_params: int = 0,
+) -> Dict[str, Any]:
+    kwargs: Dict[str, Any] = {}
+    for name, param in list(sig.parameters.items())[skip_params:]:
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+        ann = hints.get(name, param.annotation)
+        if param.default is not inspect._empty:
+            kwargs[name] = param.default
+        else:
+            kwargs[name] = container.resolve(ann)
+    return kwargs
+
+
+def bind_callable(fn: Callable[..., Any], c: TypeContainer) -> Callable[..., Any]:
+    sig = inspect.signature(fn)
+    hints = _type_hints(fn)
+
+    def wrapper(message: Any):
+        kwargs = _build_kwargs(sig, hints, c, skip_params=1)
+        return fn(message, **kwargs)
+
+    return wrapper
+
+
+def bind_handler(handler: Any, c: TypeContainer) -> Callable[..., Any]:
+    if inspect.isclass(handler):
+        init = handler.__init__
+        sig = inspect.signature(init)
+        hints = _type_hints(init)
+
+        kwargs = _build_kwargs(sig, hints, c, skip_params=1)
+
+        instance = handler(**kwargs)  # type: ignore[arg-type]
+        if not callable(instance):
+            raise TypeError(f"{handler!r} must implement __call__")
+        return instance
+
+    if callable(handler):
+        return bind_callable(handler, c)
+
+    raise TypeError(f"Unsupported handler: {handler!r}")

nlbone/core/application/registry.py

@@ -0,0 +1,129 @@
+from typing import Any, Callable, Coroutine, Dict, Iterable, List, Optional, Type, TypeVar
+
+from nlbone.core.application.di import TypeContainer, bind_handler
+from nlbone.core.domain.base import Command, DomainEvent, Message
+
+TMsg = TypeVar("TMsg", bound=Message)
+SyncHandler = Callable[[TMsg], Optional[Iterable[Message]]]
+AsyncHandler = Callable[[TMsg], Coroutine[Any, Any, Optional[Iterable[Message]]]]
+
+
+class HandlerRegistry:
+    def __init__(self) -> None:
+        self._event_handlers: Dict[Type[DomainEvent], List[SyncHandler[Any]]] = {}
+        self._command_handlers: Dict[Type[Command], SyncHandler[Any]] = {}
+
+    def register_event(self, event_type: Type[DomainEvent], handler: SyncHandler[Any]) -> None:
+        self._event_handlers.setdefault(event_type, []).append(handler)
+
+    def register_command(self, cmd_type: Type[Command], handler: SyncHandler[Any]) -> None:
+        if cmd_type in self._command_handlers:
+            raise ValueError(f"Command handler already registered for {cmd_type!r}")
+        self._command_handlers[cmd_type] = handler
+
+    def for_event(self, event_type: Type[DomainEvent]) -> List[SyncHandler[Any]]:
+        return self._event_handlers.get(event_type, [])
+
+    def for_command(self, cmd_type: Type[Command]) -> SyncHandler[Any]:
+        try:
+            return self._command_handlers[cmd_type]
+        except KeyError as e:
+            raise KeyError(f"No handler for command {cmd_type.__name__}") from e
+
+
+class AsyncHandlerRegistry:
+    def __init__(self) -> None:
+        self._event_handlers: Dict[Type[DomainEvent], List[AsyncHandler[Any]]] = {}
+        self._command_handlers: Dict[Type[Command], AsyncHandler[Any]] = {}
+
+    def register_event(self, event_type: Type[DomainEvent], handler: AsyncHandler[Any]) -> None:
+        self._event_handlers.setdefault(event_type, []).append(handler)
+
+    def register_command(self, cmd_type: Type[Command], handler: AsyncHandler[Any]) -> None:
+        if cmd_type in self._command_handlers:
+            raise ValueError(f"Command handler already registered for {cmd_type!r}")
+        self._command_handlers[cmd_type] = handler
+
+    def for_event(self, event_type: Type[DomainEvent]) -> List[AsyncHandler[Any]]:
+        return self._event_handlers.get(event_type, [])
+
+    def for_command(self, cmd_type: Type[Command]) -> AsyncHandler[Any]:
+        try:
+            return self._command_handlers[cmd_type]
+        except KeyError as e:
+            raise KeyError(f"No handler for command {cmd_type.__name__}") from e
+
+
+def handles_event(event_type: Type[DomainEvent], registry: HandlerRegistry):
+    def deco(fn: SyncHandler[Any]) -> SyncHandler[Any]:
+        registry.register_event(event_type, fn)
+        return fn
+
+    return deco
+
+
+def handles_command(cmd_type: Type[Command], registry: HandlerRegistry):
+    def deco(fn: SyncHandler[Any]) -> SyncHandler[Any]:
+        registry.register_command(cmd_type, fn)
+        return fn
+
+    return deco
+
+
+def handles_event_async(event_type: Type[DomainEvent], registry: AsyncHandlerRegistry):
+    def deco(fn: AsyncHandler[Any]) -> AsyncHandler[Any]:
+        registry.register_event(event_type, fn)
+        return fn
+
+    return deco
+
+
+def handles_command_async(cmd_type: Type[Command], registry: AsyncHandlerRegistry):
+    def deco(fn: AsyncHandler[Any]) -> AsyncHandler[Any]:
+        registry.register_command(cmd_type, fn)
+        return fn
+
+    return deco
+
+
+def make_sync_decorators(registry: HandlerRegistry, container: TypeContainer):
+    def handles_command(cmd_type):
+        def deco(h):
+            instance_ref = {"inst": None}
+
+            def lazy_handler(message):
+                if instance_ref["inst"] is None:
+                    instance_ref["inst"] = bind_handler(h, container)
+                return instance_ref["inst"](message)
+
+            registry.register_command(cmd_type, lazy_handler)
+            return h
+
+        return deco
+
+    def handles_event(evt_type: Type[Any]):
+        def deco(h: Any):
+            registry.register_event(evt_type, bind_handler(h, container))
+            return h
+
+        return deco
+
+    return handles_command, handles_event
+
+
+def make_async_decorators(registry: AsyncHandlerRegistry, container: TypeContainer):
+    def handles_command_async(cmd_type: Type[Any]):
+        def deco(h: Any):
+            registry.register_command(cmd_type, bind_handler(h, container))
+            return h
+
+        return deco
+
+    def handles_event_async(evt_type: Type[Any]):
+        def deco(h: Any):
+            registry.register_event(evt_type, bind_handler(h, container))
+            return h
+
+        return deco
+
+    return handles_command_async, handles_event_async

nlbone/core/domain/base.py

@@ -2,7 +2,11 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from datetime import datetime, timezone
+from enum import Enum
 from typing import Any, Generic, List, TypeVar
+from uuid import uuid4
+
+from pydantic import BaseModel
 
 TId = TypeVar("TId")
 
@@ -11,17 +15,28 @@ class DomainError(Exception):
     """Base domain exception."""
 
 
-@dataclass(frozen=True)
-class DomainEvent:
+
+class Message(BaseModel):
+    pass
+
+
+
+class DomainEvent(Message):
     """Immutable domain event."""
 
     occurred_at: datetime = datetime.now(timezone.utc)
+    event_id: str = uuid4()
 
     @property
     def name(self):
         return self.__class__.__name__
 
 
+@dataclass(frozen=True)
+class Command:
+    pass
+
+
 class ValueObject:
     """Base for value objects (immutable in practice)."""
 
@@ -39,13 +54,19 @@ class Entity(Generic[TId]):
 class AggregateRoot(Entity[TId]):
     """Aggregate root with domain event collection."""
 
-    def __init__(self, *args, **kwargs) -> None:
-        self._domain_events: List[DomainEvent] = []
+    def __init__(self) -> None:
+        self._events: List[DomainEvent] = []
+
+    @property
+    def events(self) -> List[DomainEvent]:
+        return self._events
 
     def _raise(self, event: DomainEvent) -> None:
-        self._domain_events.append(event)
+        self._events.append(event)
+
+    def clear_events(self) -> None:
+        self._events.clear()
+
 
-    def pull_events(self) -> List[DomainEvent]:
-        events = list(self._domain_events)
-        self._domain_events.clear()
-        return events
+class BaseEnum(Enum):
+    pass

nlbone/core/domain/models.py

@@ -1,12 +1,16 @@
+import enum
 import uuid
-from datetime import datetime
+from datetime import datetime, timezone, timedelta
+from typing import Any, Dict, Optional
 
+from sqlalchemy import JSON, DateTime, Index, Integer, String, Text
 from sqlalchemy import JSON as SA_JSON
-from sqlalchemy import DateTime, Index, String, Text
+from sqlalchemy import Enum as SA_Enum
 from sqlalchemy.orm import Mapped, mapped_column
 from sqlalchemy.sql import func
 
-from nlbone.adapters.db import Base
+from nlbone.adapters.db.postgres.base import Base
+from nlbone.utils.time import now
 
 try:
     from sqlalchemy.dialects.postgresql import JSONB, UUID
@@ -38,3 +42,42 @@ class AuditLog(Base):
         Index("ix_audit_entity_entityid", "entity", "entity_id"),
         Index("ix_audit_created_at", "created_at"),
     )
+
+
+class OutboxStatus(str, enum.Enum):
+    PENDING = "pending"
+    PROCESSING = "processing"
+    PUBLISHED = "published"
+    FAILED = "failed"
+
+
+class Outbox(Base):
+    __tablename__ = "outbox"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    topic: Mapped[str] = mapped_column(String(200), nullable=False, index=True)
+    payload: Mapped[Dict[str, Any]] = mapped_column(JSON, nullable=False)
+    headers: Mapped[Dict[str, Any]] = mapped_column(JSON, default=dict)
+    key: Mapped[Optional[str]] = mapped_column(String(200), nullable=True, index=True)
+
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
+    available_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), index=True
+    )
+
+    status: Mapped[OutboxStatus] = mapped_column(SA_Enum(OutboxStatus), default=OutboxStatus.PENDING, index=True)
+    attempts: Mapped[int] = mapped_column(Integer, default=0)
+    last_error: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    next_attempt_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True, index=True)
+
+    def mark_failed(self, error: str, *, backoff: timedelta = timedelta(seconds=30)):
+        self.status = OutboxStatus.FAILED
+        self.last_error = error
+        self.next_attempt_at = now() + backoff
+
+    def mark_published(self):
+        self.status = OutboxStatus.PUBLISHED
+        self.next_attempt_at = None
+
+def to_outbox_row(evt) -> Outbox:
+    return Outbox(topic=evt.topic, payload=evt.__dict__)

nlbone/core/ports/__init__.py

@@ -1,5 +1,3 @@
 from .auth import AuthService
-from .event_bus import EventBusPort
 from .files import AsyncFileServicePort, FileServicePort
-from .repo import AsyncRepository, Repository
 from .uow import AsyncUnitOfWork, UnitOfWork

nlbone/core/ports/event_bus.py

@@ -1,10 +1,27 @@
-from __future__ import annotations
+from typing import Any, Awaitable, Callable, Iterable, Protocol, Type, runtime_checkable
 
-from typing import Callable, Iterable, Protocol
+from nlbone.core.domain.base import DomainEvent, Message
 
-from nlbone.core.domain.base import DomainEvent
+EventHandler = Callable[[DomainEvent], Any] | Callable[[DomainEvent], Awaitable[Any]]
 
 
-class EventBusPort(Protocol):
-    def publish(self, events: Iterable[DomainEvent]) -> None: ...
-    def subscribe(self, event_name: str, handler: Callable[[DomainEvent], None]) -> None: ...
+class EventBus(Protocol):
+    def subscribe(self, event_type: Type[DomainEvent] | str, handler: EventHandler) -> None: ...
+
+    def publish(self, event: DomainEvent) -> None: ...
+
+
+class EventPublisher(Protocol):
+    def publish(self, event: DomainEvent) -> None: ...
+
+
+@runtime_checkable
+class OutboxPublisher(Protocol):
+    """Optional: publish integration messages reliably after commit."""
+
+    def publish(self, messages: Iterable[Message]) -> None: ...
+
+
+@runtime_checkable
+class AsyncOutboxPublisher(Protocol):
+    async def publish(self, messages: Iterable[Message]) -> None: ...

nlbone/core/ports/outbox.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Any, Dict, Iterable, List, Optional, Protocol, Tuple
+
+from nlbone.core.domain.models import Outbox, OutboxStatus
+
+
+class OutboxRepository(Protocol):
+    def enqueue(
+            self,
+            topic: str,
+            payload: Dict[str, Any],
+            *,
+            headers: Optional[Dict[str, Any]] = None,
+            key: Optional[str] = None,
+            available_at: Optional[datetime] = None,
+    ) -> Outbox: ...
+
+    def enqueue_many(
+            self,
+            items: Iterable[Tuple[str, Dict[str, Any]]],
+            *,
+            headers: Optional[Dict[str, Any]] = None,
+            available_at: Optional[datetime] = None,
+    ) -> List[Outbox]: ...
+
+    def claim_batch(
+            self,
+            *,
+            topics: list[str] = None,
+            limit: int = 100,
+            now: Optional[datetime] = None,
+    ) -> List[Outbox]: ...
+
+    def mark_published(self, ids: Iterable[int]) -> None: ...
+
+    def mark_failed(self, id: int, error: str, *, backoff: timedelta = timedelta(seconds=30)) -> None: ...
+
+    def delete_older_than(self, *, before: datetime, status: Optional[OutboxStatus] = None) -> int: ...
+
+
+class AsyncOutboxRepository(Protocol):
+    async def enqueue(
+            self,
+            topic: str,
+            payload: Dict[str, Any],
+            *,
+            headers: Optional[Dict[str, Any]] = None,
+            key: Optional[str] = None,
+            available_at: Optional[datetime] = None,
+    ) -> Outbox: ...
+
+    async def enqueue_many(
+            self,
+            items: Iterable[Tuple[str, Dict[str, Any]]],
+            *,
+            headers: Optional[Dict[str, Any]] = None,
+            available_at: Optional[datetime] = None,
+    ) -> List[Outbox]: ...
+
+    async def claim_batch(
+            self,
+            *,
+            limit: int = 100,
+            now: Optional[datetime] = None,
+    ) -> List[Outbox]: ...
+
+    async def mark_published(self, ids: Iterable[int]) -> None: ...
+
+    async def mark_failed(self, id: int, error: str, *, backoff: timedelta = timedelta(seconds=30)) -> None: ...
+
+    async def delete_older_than(self, *, before: datetime, status: Optional[OutboxStatus] = None) -> int: ...

nlbone/core/ports/repository.py

@@ -0,0 +1,116 @@
+from abc import ABC, abstractmethod
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Generic,
+    Iterable,
+    List,
+    Optional,
+    Type,
+    TypeVar,
+)
+
+from nlbone.core.domain.base import AggregateRoot
+from nlbone.interfaces.api.exceptions import NotFoundException
+
+ID = TypeVar("ID")
+T = TypeVar("T")
+
+
+class Repository(Generic[T, ID], ABC):
+    model: ClassVar[Type[Any]]
+    seen: set[AggregateRoot] = set()
+
+    @abstractmethod
+    def get(self, id: ID) -> Optional[T]: ...
+
+    def get_or_raise(self, id: ID) -> T:
+        ...
+        entity = self.get(id)
+        if entity is None:
+            raise NotFoundException(f"Entity with id={id!r} not found")
+        return entity
+
+    @abstractmethod
+    def list(
+        self,
+        *,
+        offset: int = 0,
+        limit: Optional[int] = None,
+        where: Optional[Callable[[T], bool]] = None,
+        order_by: Optional[Callable[[T], object]] = None,
+        reverse: bool = False,
+    ) -> List[T]: ...
+
+    @abstractmethod
+    def count(self, *, where: Optional[Callable[[T], bool]] = None) -> int: ...
+
+    @abstractmethod
+    def exists(self, id: ID) -> bool: ...
+
+    # --- Write ---
+    @abstractmethod
+    def add(self, entity: T) -> T: ...
+
+    @abstractmethod
+    def add_many(self, entities: Iterable[T]) -> List[T]: ...
+
+    @abstractmethod
+    def update(self, entity: T) -> T: ...
+
+    @abstractmethod
+    def delete(self, id: ID) -> bool: ...
+
+    @abstractmethod
+    def clear(self) -> None: ...
+
+
+# -----------------------------
+# Async Repository (Abstract)
+# -----------------------------
+class AsyncRepository(Generic[T, ID], ABC):
+    model: ClassVar[Type[Any]]
+    seen: set[AggregateRoot] = set()
+
+    @abstractmethod
+    async def get(self, id: ID) -> Optional[T]: ...
+
+    async def get_or_raise(self, id: ID) -> T:
+        entity = await self.get(id)
+        if entity is None:
+            raise NotFoundException(f"Entity with id={id!r} not found")
+        return entity
+
+    @abstractmethod
+    async def list(
+        self,
+        *,
+        offset: int = 0,
+        limit: Optional[int] = None,
+        where: Optional[Callable[[T], bool]] = None,
+        order_by: Optional[Callable[[T], object]] = None,
+        reverse: bool = False,
+    ) -> List[T]: ...
+
+    @abstractmethod
+    async def count(self, *, where: Optional[Callable[[T], bool]] = None) -> int: ...
+
+    @abstractmethod
+    async def exists(self, id: ID) -> bool: ...
+
+    # --- Write ---
+    @abstractmethod
+    async def add(self, entity: T) -> T: ...
+
+    @abstractmethod
+    async def add_many(self, entities: Iterable[T]) -> List[T]: ...
+
+    @abstractmethod
+    async def update(self, entity: T) -> T: ...
+
+    @abstractmethod
+    async def delete(self, id: ID) -> bool: ...
+
+    @abstractmethod
+    async def clear(self) -> None: ...

nlbone/core/ports/uow.py

@@ -1,19 +1,38 @@
 from __future__ import annotations
 
-from typing import Protocol, runtime_checkable
+from typing import AsyncIterator, Iterator, Protocol, runtime_checkable
+
+from nlbone.core.domain.base import DomainEvent
+from nlbone.core.ports.outbox import AsyncOutboxRepository, OutboxRepository
 
 
 @runtime_checkable
 class UnitOfWork(Protocol):
+    outbox: list
+    outbox_repo: OutboxRepository
+
     def __enter__(self) -> "UnitOfWork": ...
+
     def __exit__(self, exc_type, exc, tb) -> None: ...
+
     def commit(self) -> None: ...
+
     def rollback(self) -> None: ...
 
+    def collect_new_events(self) -> Iterator[DomainEvent]: ...
+
 
 @runtime_checkable
 class AsyncUnitOfWork(Protocol):
+    outbox: list
+    outbox_repo: AsyncOutboxRepository
+
     async def __aenter__(self) -> "AsyncUnitOfWork": ...
+
     async def __aexit__(self, exc_type, exc, tb) -> None: ...
+
     async def commit(self) -> None: ...
+
     async def rollback(self) -> None: ...
+
+    async def collect_new_events(self) -> AsyncIterator[DomainEvent]: ...

nlbone/interfaces/api/additional_filed/field_registry.py

@@ -11,6 +11,8 @@ Loader = Callable
 def _schema_fields(schema: Type[BaseModel], by_alias: bool = True) -> Set[str]:
     names = set()
     for name, f in schema.model_fields.items():
+        if f.json_schema_extra and f.json_schema_extra.get("exclude_none"):
+            continue
         names.add(f.alias or name if by_alias else name)
     return names
 

nlbone/interfaces/cli/crypto.py

@@ -0,0 +1,22 @@
+import typer
+
+from nlbone.utils.crypto import decrypt_text, encrypt_text
+
+crypto_command = typer.Typer(help="Encryption / Decryption utilities")
+
+
+@crypto_command.command("encrypt")
+def encrypt_cmd(value: str):
+    """Encrypt a plain text string."""
+    encrypted = encrypt_text(value)
+    typer.secho(f"🔐 Encrypted:\n{encrypted}", fg=typer.colors.GREEN)
+
+
+@crypto_command.command("decrypt")
+def decrypt_cmd(value: str):
+    """Decrypt an encrypted token string."""
+    try:
+        decrypted = decrypt_text(value)
+        typer.secho(f"🔓 Decrypted:\n{decrypted}", fg=typer.colors.CYAN)
+    except Exception as e:
+        typer.secho(f"❌ Failed to decrypt: {e}", fg=typer.colors.RED)