fastloom 0.4.2__tar.gz

fastloom-0.4.2/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.3
+Name: fastloom
+Version: 0.4.2
+Summary: Core package
+Requires-Python: >=3.12,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: celery
+Provides-Extra: dev
+Provides-Extra: fastapi
+Provides-Extra: httpx
+Provides-Extra: mongodb
+Provides-Extra: openai
+Provides-Extra: rabbit
+Provides-Extra: redis
+Provides-Extra: requests
+Requires-Dist: babel (>=2.17.0,<3.0.0)
+Requires-Dist: beanie (>=2.0.0,<3.0.0) ; extra == "mongodb"
+Requires-Dist: celery (>=5.5.3,<6.0.0) ; extra == "celery"
+Requires-Dist: fastapi (>=0,<1) ; extra == "fastapi" or extra == "rabbit"
+Requires-Dist: faststream[otel,rabbit] (>=0.6.0,<0.7.0) ; extra == "rabbit"
+Requires-Dist: httpx (>=0.28.0,<0.29.0) ; extra == "httpx"
+Requires-Dist: ipykernel (>=6.30.0,<7.0.0) ; extra == "dev"
+Requires-Dist: jdatetime (>=4.1.1,<5.0.0)
+Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
+Requires-Dist: logfire[asgi,celery,fastapi,httpx,openai,pymongo,redis,requests,system-metrics] (>=4.0.0,<5.0.0)
+Requires-Dist: mypy (>=1.17.0,<2.0.0) ; extra == "dev"
+Requires-Dist: openai (>=1,<2) ; extra == "openai"
+Requires-Dist: opentelemetry-distro
+Requires-Dist: opentelemetry-exporter-otlp
+Requires-Dist: opentelemetry-instrumentation-aio-pika ; extra == "rabbit"
+Requires-Dist: orjson (==3.10.14)
+Requires-Dist: pre-commit (>=4.2.0,<5.0.0) ; extra == "dev"
+Requires-Dist: pydantic[email] (>=2.12,<3.0)
+Requires-Dist: python-jose (>=3.5.0,<4.0.0)
+Requires-Dist: python-multipart ; extra == "fastapi"
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: redis-om (>=1.0,<2.0) ; extra == "redis"
+Requires-Dist: requests (>=2.32.0,<3.0.0) ; extra == "requests"
+Requires-Dist: ruff (>=0.12.5,<0.13.0) ; extra == "dev"
+Requires-Dist: sentry-sdk[fastapi] (>=2.0.0,<3.0.0)
+Requires-Dist: uvicorn (>=0.35.0,<0.36.0) ; extra == "fastapi" or extra == "rabbit"
+Description-Content-Type: text/markdown
+
+# Fastloom – The Open Foundation for Building Event-Driven Services
+
+Fastloom is a lightweight, batteries-included foundation for building modern backends. Define your settings, schemas, and endpoints; Fastloom wires up the rest: FastAPI, Mongo (Beanie), Rabbit (FastStream), metrics/traces/logs/errors, and more.
+
+Think of it as the glue for your stack: web, messaging, caching, DB, observability, and integrations with best-in-class tools.
+
+---
+
+## Why FastLoom
+
+- No boilerplate: minimal scaffolding/templating; most wiring is handled inside Core.
+- Composable: opt into only what you need (`FastAPI`, `Rabbit`, `MongoDB`, `Redis`, `OpenAI`).
+- Pydantic-first: type-safe models, validators, and clear input/output contracts.
+- Multi-tenant by design: tenant context flows through DI and storage.
+- AuthN/Z via DI: OIDC token introspection and pluggable PDP (ABAC/RBAC/ReBAC) hooks.
+- Event-driven ready: publish/subscribe with routing keys and health.
+- Observability-native: metrics, traces, logs from day one.
+- Self-hostable: production parity with a cloud/aaS setup.
+
+---
+
+## Integrated Services (the platform)
+
+Core plugs into a family of self-hostable services:
+
+- IAM → OIDC/SSO, authN/Z, RBAC/ABAC/ReBAC.
+- Notify → realtime notifications, Pusher-compatible API.
+- Pulse → user activity + event tracking with OpenTelemetry hooks.
+- File → object storage on MinIO (S3-compatible).
+- Finance, Subscription, SMS/Email, Meet, Persona → optional services you can wire in.
+
+Each service is:
+- self-hostable (Docker Compose or Helm),
+- BaaS-available,
+
+---
+
+## Quick start
+
+```bash
+# Install core
+poetry add core-bluprint -E FastAPI
+
+# Scaffold a new service
+launch init myservice --stack fastapi
+
+# Run it
+cd myservice
+launch dev
+```
+
+See pyproject extras for the full list.
+
+---
+
+## What you get out of the box
+
+- App orchestrator (`core_bluprint.launcher`)
+  - Loads your routes, models, signals, and healthchecks
+  - Exposes settings and health endpoints (public toggle)
+- FastAPI-native
+  - Dependency-injected request/tenant context and guards
+  - Clear routing, OpenAPI, and dependency injection patterns
+- Auth & Access
+  - DI-based guards with OIDC token introspection
+  - Pluggable PDP for ABAC/RBAC/ReBAC decisions
+- Multi-tenancy
+  - Tenant-aware DI context across web, DB, and messaging
+  - Automatic per-tenant settings endpoint backed by DB + cache
+- Database layer (MongoDB via Beanie)
+  - Created/updated mixins, pagination utilities, typed helpers
+  - Helper classes/methods for common patterns (queries, projections, pagination)
+  - Auto model discovery for DB init
+- Signals / Messaging (Rabbit via FastStream)
+  - Event-driven publish/subscribe integration with DI and retries
+  - Subscriber wiring and healthchecks
+- Observability
+  - OpenTelemetry distro + OTLP exporter, Logfire, Sentry (error/bug tracking)
+- I18N
+  - Exception handler and template utils with Babel/Jinja2
+- Healthchecks
+  - Automatic app/DB/messaging checks + system routes
+- Pydantic-native schemas and validators
+  - SchemaIn/Out validation for request/response contracts
+  - Common types and validators (`core_bluprint.types`)
+
+Dive deeper in the docs below.
+
+---
+
+## Documentation
+
+- Auth → docs/auth.md
+- Tenant → docs/tenant.md
+- DB (Mongo/Beanie) → docs/db.md
+- Signals (Rabbit) → docs/signals.md
+- Observability → docs/observability.md
+- File storage → docs/file.md
+- I18N → docs/i18n.md
+- Settings & Configs → docs/settings.md
+- Launcher & App model → docs/launcher.md
+
+---
+
+## Roadmap
+
+- More CLI scaffolds and blueprints.
+- Automatic `pydantic ai` agentic tool creation from apis
+- Migrate PDP to [`OPAL`](https://github.com/permitio/opal) [opa](https://github.com/open-policy-agent/opa) based
+

fastloom-0.4.2/README.md

@@ -0,0 +1,109 @@
+# Fastloom – The Open Foundation for Building Event-Driven Services
+
+Fastloom is a lightweight, batteries-included foundation for building modern backends. Define your settings, schemas, and endpoints; Fastloom wires up the rest: FastAPI, Mongo (Beanie), Rabbit (FastStream), metrics/traces/logs/errors, and more.
+
+Think of it as the glue for your stack: web, messaging, caching, DB, observability, and integrations with best-in-class tools.
+
+---
+
+## Why FastLoom
+
+- No boilerplate: minimal scaffolding/templating; most wiring is handled inside Core.
+- Composable: opt into only what you need (`FastAPI`, `Rabbit`, `MongoDB`, `Redis`, `OpenAI`).
+- Pydantic-first: type-safe models, validators, and clear input/output contracts.
+- Multi-tenant by design: tenant context flows through DI and storage.
+- AuthN/Z via DI: OIDC token introspection and pluggable PDP (ABAC/RBAC/ReBAC) hooks.
+- Event-driven ready: publish/subscribe with routing keys and health.
+- Observability-native: metrics, traces, logs from day one.
+- Self-hostable: production parity with a cloud/aaS setup.
+
+---
+
+## Integrated Services (the platform)
+
+Core plugs into a family of self-hostable services:
+
+- IAM → OIDC/SSO, authN/Z, RBAC/ABAC/ReBAC.
+- Notify → realtime notifications, Pusher-compatible API.
+- Pulse → user activity + event tracking with OpenTelemetry hooks.
+- File → object storage on MinIO (S3-compatible).
+- Finance, Subscription, SMS/Email, Meet, Persona → optional services you can wire in.
+
+Each service is:
+- self-hostable (Docker Compose or Helm),
+- BaaS-available,
+
+---
+
+## Quick start
+
+```bash
+# Install core
+poetry add core-bluprint -E FastAPI
+
+# Scaffold a new service
+launch init myservice --stack fastapi
+
+# Run it
+cd myservice
+launch dev
+```
+
+See pyproject extras for the full list.
+
+---
+
+## What you get out of the box
+
+- App orchestrator (`core_bluprint.launcher`)
+  - Loads your routes, models, signals, and healthchecks
+  - Exposes settings and health endpoints (public toggle)
+- FastAPI-native
+  - Dependency-injected request/tenant context and guards
+  - Clear routing, OpenAPI, and dependency injection patterns
+- Auth & Access
+  - DI-based guards with OIDC token introspection
+  - Pluggable PDP for ABAC/RBAC/ReBAC decisions
+- Multi-tenancy
+  - Tenant-aware DI context across web, DB, and messaging
+  - Automatic per-tenant settings endpoint backed by DB + cache
+- Database layer (MongoDB via Beanie)
+  - Created/updated mixins, pagination utilities, typed helpers
+  - Helper classes/methods for common patterns (queries, projections, pagination)
+  - Auto model discovery for DB init
+- Signals / Messaging (Rabbit via FastStream)
+  - Event-driven publish/subscribe integration with DI and retries
+  - Subscriber wiring and healthchecks
+- Observability
+  - OpenTelemetry distro + OTLP exporter, Logfire, Sentry (error/bug tracking)
+- I18N
+  - Exception handler and template utils with Babel/Jinja2
+- Healthchecks
+  - Automatic app/DB/messaging checks + system routes
+- Pydantic-native schemas and validators
+  - SchemaIn/Out validation for request/response contracts
+  - Common types and validators (`core_bluprint.types`)
+
+Dive deeper in the docs below.
+
+---
+
+## Documentation
+
+- Auth → docs/auth.md
+- Tenant → docs/tenant.md
+- DB (Mongo/Beanie) → docs/db.md
+- Signals (Rabbit) → docs/signals.md
+- Observability → docs/observability.md
+- File storage → docs/file.md
+- I18N → docs/i18n.md
+- Settings & Configs → docs/settings.md
+- Launcher & App model → docs/launcher.md
+
+---
+
+## Roadmap
+
+- More CLI scaffolds and blueprints.
+- Automatic `pydantic ai` agentic tool creation from apis
+- Migrate PDP to [`OPAL`](https://github.com/permitio/opal) [opa](https://github.com/open-policy-agent/opa) based

fastloom-0.4.2/fastloom/auth/__init__.py

@@ -0,0 +1,5 @@
+from contextvars import ContextVar
+
+from fastloom.auth.schemas import UserClaims
+
+Claims: ContextVar[UserClaims] = ContextVar("claims")

fastloom-0.4.2/fastloom/auth/depends.py

@@ -0,0 +1,145 @@
+from collections.abc import Callable, Coroutine
+from typing import Annotated, Any
+
+import httpx
+from fastapi import Depends, HTTPException, Request
+from fastapi.security import OAuth2, OpenIdConnect
+from jose.jwt import get_unverified_claims
+
+from fastloom.auth import Claims
+from fastloom.auth.schemas import (
+    IntrospectionResponse,
+    UserClaims,
+)
+from fastloom.settings.base import IAMSettings
+
+
+class OptionalJWTAuth:
+    settings: IAMSettings
+    _security_scheme: OAuth2 | OpenIdConnect | None = None
+
+    def __init__(self, settings: IAMSettings):
+        self.settings = settings
+
+        if self.settings.oidc_enabled:
+            assert self.settings.OIDC_URL is not None
+            self._security_scheme = OpenIdConnect(
+                openIdConnectUrl=self.settings.OIDC_URL,
+                scheme_name="OIDC",
+                auto_error=False,
+            )
+        elif self.settings.oauth2_enabled:
+            self._security_scheme = OAuth2(
+                flows=self.settings.flows, auto_error=False
+            )
+
+    async def _introspect(
+        self, token: Annotated[str, Depends(_security_scheme)]
+    ):
+        async with httpx.AsyncClient() as client:
+            response: httpx.Response = await client.post(
+                f"{self.settings.IAM_SIDECAR_URL}/introspect",
+                json=dict(token=token),
+            )
+        if response.status_code != 200:
+            raise HTTPException(status_code=403, detail=response.text)
+        data = IntrospectionResponse.model_validate(response.json())
+        if not data.active:
+            raise HTTPException(status_code=403, detail="Inactive token")
+
+    def _transform_bearer(self, token: str) -> str:
+        if token.startswith("Bearer "):
+            return token.removeprefix("Bearer ").strip()
+        return token
+
+    async def _acl(
+        self,
+        request: Request,
+        token: Annotated[str, Depends(_security_scheme)],
+    ) -> None:
+        async with httpx.AsyncClient() as client:
+            response: httpx.Response = await client.post(
+                url=f"{self.settings.IAM_SIDECAR_URL}/acl",
+                json={
+                    "token": token,
+                    "endpoint": request.url.path,
+                    "method": request.method,
+                },
+            )
+
+        if response.status_code != 200:
+            raise HTTPException(status_code=403, detail=response.text)
+        if not response.json():
+            raise HTTPException(status_code=403)
+
+    @classmethod
+    def _parse_token(cls, token: str) -> UserClaims:
+        return UserClaims.model_validate(get_unverified_claims(token))
+
+    async def _validate_token(
+        self, token: str, request: Request
+    ) -> UserClaims:
+        token = self._transform_bearer(token)
+        if self.settings.INTROSPECT:
+            await self._introspect(token)
+        if self.settings.ACL:
+            await self._acl(request, token)
+        claims = self._parse_token(token)
+        Claims.set(claims)
+        return claims
+
+    @property
+    def get_token(
+        self,
+    ) -> Callable[..., Coroutine[Any, Any, str | None]]:
+        async def _inner(
+            token: Annotated[str | None, Depends(self._security_scheme)],
+        ) -> str | None:
+            if token is None:
+                return None
+            return self._transform_bearer(token)
+
+        return _inner
+
+    @property
+    def get_claims(
+        self,
+    ) -> Callable[..., Coroutine[Any, Any, UserClaims | None]]:
+        async def _inner(
+            request: Request,
+            token: Annotated[str | None, Depends(self._security_scheme)],
+        ) -> UserClaims | None:
+            if token is None:
+                return None
+
+            return await self._validate_token(token, request)
+
+        return _inner
+
+
+class JWTAuth(OptionalJWTAuth):
+    def __init__(self, settings: IAMSettings):
+        super().__init__(settings)
+        assert self._security_scheme is not None
+        self._security_scheme.auto_error = True
+
+    @property
+    def get_claims(self) -> Callable[..., Coroutine[Any, Any, UserClaims]]:
+        async def _inner(
+            request: Request,
+            token: Annotated[str, Depends(self._security_scheme)],
+        ) -> UserClaims:
+            return await self._validate_token(token, request)
+
+        return _inner
+
+    @property
+    def get_token(
+        self,
+    ) -> Callable[..., Coroutine[Any, Any, str]]:
+        async def _inner(
+            token: Annotated[str, Depends(self._security_scheme)],
+        ) -> str:
+            return self._transform_bearer(token)
+
+        return _inner

fastloom-0.4.2/fastloom/auth/schemas.py

@@ -0,0 +1,69 @@
+from fastapi.openapi.models import OAuthFlow, OAuthFlows
+from pydantic import BaseModel, Field, HttpUrl, computed_field, field_validator
+
+from fastloom.types import Str
+
+ADMIN_ROLE = "ADMIN"
+
+
+class OAuth2MergedScheme(OAuthFlow):
+    authorizationUrl: Str[HttpUrl] | None = None
+    tokenUrl: Str[HttpUrl] | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def flows(self) -> OAuthFlows:
+        if self.authorizationUrl is None and self.tokenUrl is None:
+            return OAuthFlows()
+        return OAuthFlows.model_validate(
+            dict(
+                authorizationCode=self.model_dump(
+                    exclude_computed_fields=True
+                ),
+            )
+        )
+        # ^ implicit & ROPC are deprecated in OAUTH2.1
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def oauth2_enabled(self) -> bool:
+        return self.authorizationUrl is not None and self.tokenUrl is not None
+
+
+class OIDCCScheme(BaseModel):
+    OIDC_URL: Str[HttpUrl] | None = None
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def oidc_enabled(self) -> bool:
+        return self.OIDC_URL is not None
+
+
+class IntrospectionResponse(BaseModel):
+    active: bool
+
+
+class Role(BaseModel):
+    name: str
+    users: list[str] | None = None
+
+
+class UserClaims(BaseModel):
+    tenant: str = Field(alias="owner")
+    id: str
+    username: str = Field(..., validation_alias="name")
+    email: str | None = None
+    phone: str | None = None
+    roles: list[Role] = Field(default_factory=list)
+
+    @field_validator("roles", mode="before")
+    @classmethod
+    def validate_roles(cls, v: list[Role] | None) -> list[Role]:
+        if not v:
+            return []
+        return v
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def is_admin(self) -> bool:
+        return any(role.name == ADMIN_ROLE for role in self.roles or [])

fastloom-0.4.2/fastloom/cache/base.py

@@ -0,0 +1,33 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from aredis_om import Field, JsonModel
+else:
+    try:
+        from aredis_om import Field, JsonModel
+    except ImportError:
+        from pydantic import BaseModel as JsonModel
+        from pydantic import Field
+
+
+class BaseCache(JsonModel):
+    class Meta:
+        global_key_prefix = "cache"
+        model_key_prefix = "base"
+        # ^should be overriden in sub
+
+    @property
+    async def invalidate(self):
+        return await self.expire(0)
+
+
+class BaseTenantSettingCache(BaseCache):
+    id: str = Field(primary_key=True)
+
+
+class HostTenantMapping(BaseCache, index=True):  # type: ignore[call-arg]
+    host: str = Field(primary_key=True)
+    tenant: str = Field(index=True)
+
+    class Meta:
+        model_key_prefix = "host_mapping"

fastloom-0.4.2/fastloom/cache/gate.py

@@ -0,0 +1,67 @@
+from collections.abc import Awaitable
+from functools import wraps
+from os import getpid
+from typing import Callable
+
+from fastloom.cache.lifehooks import RedisHandler
+from fastloom.settings.base import ProjectSettings
+from fastloom.tenant.settings import ConfigAlias as Configs
+
+
+class RedisGuardGate:
+    """
+    - *context manager*:
+    ```
+    async with RedisGuardGate("boostrap", ttl=30, grace=10) as acquired:
+        if acquired:
+            await lifespan_init()
+    ```
+    - *decorator*:
+    ```
+    @RedisGuardGate("boostrap", ttl=30)
+    async def lifespan_init():
+        ...
+    ```
+    """
+
+    key: str
+    ttl: int
+    grace: int
+    _acquired: bool = False
+
+    def __init__(self, key: str, ttl: int = 60, grace: int = 0):
+        self.key = (
+            f"{Configs[ProjectSettings].general.PROJECT_NAME}:{key}:leader"  # type: ignore[misc]
+        )
+        self.ttl = ttl
+        self.grace = grace
+
+    def __call__[T, **P](self, func: Callable[P, Awaitable[T]]):
+        @wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T | None:
+            async with self as acquired:
+                if acquired:
+                    return await func(*args, **kwargs)
+                return None
+
+        return wrapper
+
+    async def _acquire(self):
+        acquired = await RedisHandler.redis.set(
+            self.key,
+            str(getpid()),
+            nx=True,
+            ex=self.ttl,
+        )
+        return acquired is not None
+
+    async def _release(self):
+        await RedisHandler.redis.expire(self.key, self.grace)
+
+    async def __aenter__(self) -> bool:
+        self._acquired = await self._acquire()
+        return self._acquired
+
+    async def __aexit__(self, exc_type, exc, tb):
+        if self._acquired:
+            await self._release()

fastloom-0.4.2/fastloom/cache/healthcheck.py

@@ -0,0 +1,22 @@
+from collections.abc import Callable, Coroutine
+from functools import partial
+from typing import Any
+
+
+class RedisConnectionError(Exception): ...
+
+
+async def check_redis_connection(redis_url: str) -> None:
+    from redis.asyncio import Redis
+
+    try:
+        client: Redis = Redis.from_url(redis_url)
+        await client.ping()
+    except Exception as er:
+        raise RedisConnectionError(f"Redis connection error: {er}") from er
+
+
+def get_healthcheck(
+    redis_url: str,
+) -> Callable[[], Coroutine[Any, Any, None]]:
+    return partial(check_redis_connection, redis_url=redis_url)

fastloom-0.4.2/fastloom/cache/lifehooks.py

@@ -0,0 +1,37 @@
+from contextlib import suppress
+from typing import TYPE_CHECKING
+
+from fastloom.cache.settings import RedisSettings
+from fastloom.meta import SelfSustaining
+
+_HAS_REDIS = False
+with suppress(ImportError):
+    from aredis_om import get_redis_connection
+    from redis import Redis as SyncRedis
+    from redis.asyncio import Redis
+    from redis.exceptions import ConnectionError
+
+    _HAS_REDIS = True
+
+if TYPE_CHECKING:
+    from redis import Redis as SyncRedis
+    from redis.asyncio import Redis
+
+if not TYPE_CHECKING and not _HAS_REDIS:
+    SyncRedis = None
+    Redis = None
+
+
+class RedisHandler(SelfSustaining):
+    enabled: bool = False
+    redis: Redis
+    sync_redis: SyncRedis
+
+    def __init__(self, settings: RedisSettings) -> None:
+        super().__init__()
+        if not _HAS_REDIS:
+            return
+        self.redis = get_redis_connection(url=str(settings.REDIS_URL))
+        self.sync_redis = SyncRedis.from_url(url=str(settings.REDIS_URL))
+        with suppress(ConnectionError):
+            self.enabled = self.sync_redis.ping()

fastloom-0.4.2/fastloom/cache/settings.py

@@ -0,0 +1,13 @@
+from pydantic import (
+    BaseModel,
+    Field,
+    RedisDsn,
+)
+
+from fastloom.types import Str
+
+
+class RedisSettings(BaseModel):
+    REDIS_URL: Str[RedisDsn] = Field(
+        "redis://localhost:6379/0", validate_default=True
+    )

fastloom-0.4.2/fastloom/crypto.py

@@ -0,0 +1,20 @@
+import secrets
+
+
+def generate_token(length: int):
+    """
+    Generates a n-digits numeral token, that used for OTP
+    """
+    min_value = 10 ** (length - 1)
+    max_value = 10**length - 1
+    return str(secrets.randbelow(max_value - min_value + 1) + min_value).zfill(
+        length
+    )
+
+
+def generate_alphanumeric_token(length: int):
+    """
+    Generates a n-digits alphanumeric token, that used for OTP
+    """
+    alphabet = "0123456789abcdefghijklmnopqrstuvwxyz"
+    return "".join(secrets.choice(alphabet) for _ in range(length))