app-platform 0.2.0__tar.gz

app_platform-0.2.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: app-platform
+Version: 0.2.0
+Summary: Generic web app infrastructure: PostgreSQL pooling, structured logging, rate limiting, FastAPI middleware, auth service, gateway proxy
+Project-URL: Homepage, https://github.com/henrysouchien/app-platform
+Project-URL: Repository, https://github.com/henrysouchien/app-platform
+Author: Henry Chien
+License-Expression: MIT
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Requires-Dist: psycopg2-binary>=2.9
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100; extra == 'all'
+Requires-Dist: google-auth>=2.0; extra == 'all'
+Requires-Dist: httpx>=0.24; extra == 'all'
+Requires-Dist: itsdangerous>=2.0; extra == 'all'
+Requires-Dist: requests>=2.20; extra == 'all'
+Requires-Dist: slowapi>=0.1.9; extra == 'all'
+Requires-Dist: starlette; extra == 'all'
+Provides-Extra: auth-google
+Requires-Dist: google-auth>=2.0; extra == 'auth-google'
+Requires-Dist: requests>=2.20; extra == 'auth-google'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: itsdangerous>=2.0; extra == 'fastapi'
+Requires-Dist: slowapi>=0.1.9; extra == 'fastapi'
+Requires-Dist: starlette; extra == 'fastapi'
+Provides-Extra: gateway
+Requires-Dist: fastapi>=0.100; extra == 'gateway'
+Requires-Dist: httpx>=0.24; extra == 'gateway'
+Description-Content-Type: text/markdown
+
+# app-platform
+
+Generic web app infrastructure for PostgreSQL pooling, structured logging, auth, middleware, and gateway proxying.
+
+## Installation
+
+```bash
+pip install app-platform
+pip install "app-platform[all]"
+pip install "app-platform[fastapi]"
+pip install "app-platform[auth-google]"
+pip install "app-platform[gateway]"
+```
+
+## Included subpackages
+
+| Subpackage | Provides |
+| --- | --- |
+| `db` | PostgreSQL connection pooling, pooled session helpers, migrations, and database exception utilities |
+| `logging` | Structured file and JSONL logging, context helpers, logger access, and decorators for timing/error instrumentation |
+| `middleware` | FastAPI middleware configuration for rate limiting, sessions, CORS, and validation/error handling |
+| `auth` | Pluggable auth service base with in-memory and PostgreSQL-backed user/session stores |
+| `gateway` | FastAPI router factory for proxying chat and tool approval requests to an upstream gateway |
+
+## Quick usage
+
+### Database
+
+```python
+import os
+
+from app_platform.db import PoolManager, get_db_session
+
+os.environ["DATABASE_URL"] = "postgresql://postgres:postgres@localhost:5432/app"
+
+pool_manager = PoolManager(min_connections=2, max_connections=10)
+pool_manager.get_pool()
+
+with get_db_session() as conn:
+    with conn.cursor() as cursor:
+        cursor.execute("SELECT 1 AS ok")
+        print(cursor.fetchone())
+
+pool_manager.close()
+```
+
+### Logging
+
+```python
+from app_platform.logging import (
+    LoggingManager,
+    configure_logging,
+    log_errors,
+    log_operation,
+    log_timing,
+)
+
+logging_manager: LoggingManager = configure_logging(app_name="orders", log_dir="./logs")
+logger = logging_manager.get_logger("service")
+
+@log_errors()
+@log_timing(threshold_s=0.25)
+@log_operation("create_order")
+def create_order(order_id: str) -> None:
+    logger.info("creating order %s", order_id)
+
+
+create_order("ord_123")
+```
+
+### Auth
+
+```python
+from app_platform.auth import AuthServiceBase, InMemorySessionStore, InMemoryUserStore
+
+users = {}
+sessions = {}
+
+auth = AuthServiceBase(
+    session_store=InMemorySessionStore(users_dict=users, sessions_dict=sessions),
+    user_store=InMemoryUserStore(users_dict=users),
+)
+
+session_id = auth.create_user_session(
+    {
+        "google_user_id": "user-123",
+        "email": "user@example.com",
+        "name": "Example User",
+    }
+)
+
+print(auth.get_user_by_session(session_id))
+```
+
+### Gateway
+
+```python
+from fastapi import FastAPI
+
+from app_platform.gateway import GatewayConfig, create_gateway_router
+
+app = FastAPI()
+
+
+def get_current_user():
+    return {"user_id": "user-123", "email": "user@example.com"}
+
+
+gateway_router = create_gateway_router(
+    GatewayConfig(
+        gateway_url="https://gateway.example.com",
+        api_key="gateway-api-key",
+        channel="web",
+    ),
+    get_current_user=get_current_user,
+)
+
+app.include_router(gateway_router, prefix="/gateway")
+```
+
+## Requirements
+
+Python 3.11+
+
+## License
+
+MIT

app_platform-0.2.0/README.md

@@ -0,0 +1,127 @@
+# app-platform
+
+Generic web app infrastructure for PostgreSQL pooling, structured logging, auth, middleware, and gateway proxying.
+
+## Installation
+
+```bash
+pip install app-platform
+pip install "app-platform[all]"
+pip install "app-platform[fastapi]"
+pip install "app-platform[auth-google]"
+pip install "app-platform[gateway]"
+```
+
+## Included subpackages
+
+| Subpackage | Provides |
+| --- | --- |
+| `db` | PostgreSQL connection pooling, pooled session helpers, migrations, and database exception utilities |
+| `logging` | Structured file and JSONL logging, context helpers, logger access, and decorators for timing/error instrumentation |
+| `middleware` | FastAPI middleware configuration for rate limiting, sessions, CORS, and validation/error handling |
+| `auth` | Pluggable auth service base with in-memory and PostgreSQL-backed user/session stores |
+| `gateway` | FastAPI router factory for proxying chat and tool approval requests to an upstream gateway |
+
+## Quick usage
+
+### Database
+
+```python
+import os
+
+from app_platform.db import PoolManager, get_db_session
+
+os.environ["DATABASE_URL"] = "postgresql://postgres:postgres@localhost:5432/app"
+
+pool_manager = PoolManager(min_connections=2, max_connections=10)
+pool_manager.get_pool()
+
+with get_db_session() as conn:
+    with conn.cursor() as cursor:
+        cursor.execute("SELECT 1 AS ok")
+        print(cursor.fetchone())
+
+pool_manager.close()
+```
+
+### Logging
+
+```python
+from app_platform.logging import (
+    LoggingManager,
+    configure_logging,
+    log_errors,
+    log_operation,
+    log_timing,
+)
+
+logging_manager: LoggingManager = configure_logging(app_name="orders", log_dir="./logs")
+logger = logging_manager.get_logger("service")
+
+@log_errors()
+@log_timing(threshold_s=0.25)
+@log_operation("create_order")
+def create_order(order_id: str) -> None:
+    logger.info("creating order %s", order_id)
+
+
+create_order("ord_123")
+```
+
+### Auth
+
+```python
+from app_platform.auth import AuthServiceBase, InMemorySessionStore, InMemoryUserStore
+
+users = {}
+sessions = {}
+
+auth = AuthServiceBase(
+    session_store=InMemorySessionStore(users_dict=users, sessions_dict=sessions),
+    user_store=InMemoryUserStore(users_dict=users),
+)
+
+session_id = auth.create_user_session(
+    {
+        "google_user_id": "user-123",
+        "email": "user@example.com",
+        "name": "Example User",
+    }
+)
+
+print(auth.get_user_by_session(session_id))
+```
+
+### Gateway
+
+```python
+from fastapi import FastAPI
+
+from app_platform.gateway import GatewayConfig, create_gateway_router
+
+app = FastAPI()
+
+
+def get_current_user():
+    return {"user_id": "user-123", "email": "user@example.com"}
+
+
+gateway_router = create_gateway_router(
+    GatewayConfig(
+        gateway_url="https://gateway.example.com",
+        api_key="gateway-api-key",
+        channel="web",
+    ),
+    get_current_user=get_current_user,
+)
+
+app.include_router(gateway_router, prefix="/gateway")
+```
+
+## Requirements
+
+Python 3.11+
+
+## License
+
+MIT

app_platform-0.2.0/app_platform/__init__.py

@@ -0,0 +1,123 @@
+"""Public app_platform exports for the extracted platform package."""
+
+from .db import (
+    AuthenticationError,
+    ConnectionError,
+    DataConsistencyError,
+    DatabaseClientBase,
+    DatabaseError,
+    DatabasePermissionError,
+    MigrationError,
+    NotFoundError,
+    PoolExhaustionError,
+    PoolManager,
+    SchemaError,
+    SessionManager,
+    SessionNotFoundError,
+    TimeoutError,
+    TransactionError,
+    ValidationError,
+    get_db_session,
+    get_pool,
+    handle_database_error,
+    is_recoverable_error,
+    log_database_error,
+    run_migration,
+    run_migrations_dir,
+)
+from .logging import (
+    APP_LOG_FORMAT,
+    DEDUP_WINDOW_S,
+    JSON_LOG_FORMAT,
+    MAX_DEDUP_KEYS,
+    SLOW_OPERATION_THRESHOLD,
+    VERY_SLOW_OPERATION_THRESHOLD,
+    LoggingManager,
+    clear_log_context,
+    configure_logging,
+    get_logger,
+    get_logging_manager,
+    log_alert,
+    log_error,
+    log_errors,
+    log_event,
+    log_operation,
+    log_service_status,
+    log_slow_operation,
+    log_timing,
+    set_log_context,
+)
+from .middleware import (
+    ApiKeyRegistry,
+    DEFAULT_HEADERS,
+    DEFAULT_METHODS,
+    DEFAULT_SESSION_SECRET,
+    MiddlewareConfig,
+    RateLimitConfig,
+    add_rate_limit_handler,
+    add_validation_error_handler,
+    configure_cors,
+    configure_middleware,
+    configure_sessions,
+    create_limiter,
+    resolve_session_secret,
+)
+
+__all__ = [
+    "APP_LOG_FORMAT",
+    "ApiKeyRegistry",
+    "AuthenticationError",
+    "ConnectionError",
+    "DEDUP_WINDOW_S",
+    "DEFAULT_HEADERS",
+    "DEFAULT_METHODS",
+    "DEFAULT_SESSION_SECRET",
+    "DataConsistencyError",
+    "DatabaseClientBase",
+    "DatabaseError",
+    "DatabasePermissionError",
+    "JSON_LOG_FORMAT",
+    "LoggingManager",
+    "MAX_DEDUP_KEYS",
+    "MigrationError",
+    "MiddlewareConfig",
+    "NotFoundError",
+    "PoolExhaustionError",
+    "PoolManager",
+    "RateLimitConfig",
+    "SLOW_OPERATION_THRESHOLD",
+    "SchemaError",
+    "SessionManager",
+    "SessionNotFoundError",
+    "TimeoutError",
+    "TransactionError",
+    "VERY_SLOW_OPERATION_THRESHOLD",
+    "ValidationError",
+    "clear_log_context",
+    "configure_logging",
+    "configure_cors",
+    "configure_middleware",
+    "configure_sessions",
+    "get_db_session",
+    "get_logger",
+    "get_logging_manager",
+    "get_pool",
+    "handle_database_error",
+    "is_recoverable_error",
+    "create_limiter",
+    "log_alert",
+    "log_error",
+    "log_database_error",
+    "log_errors",
+    "log_event",
+    "log_operation",
+    "log_service_status",
+    "log_slow_operation",
+    "log_timing",
+    "add_rate_limit_handler",
+    "add_validation_error_handler",
+    "resolve_session_secret",
+    "run_migration",
+    "run_migrations_dir",
+    "set_log_context",
+]

app_platform-0.2.0/app_platform/auth/__init__.py

@@ -0,0 +1,21 @@
+"""Core exports for app_platform.auth."""
+
+from .protocols import SessionStore, TokenVerifier, UserStore
+from .service import AuthServiceBase
+from .stores import (
+    InMemorySessionStore,
+    InMemoryUserStore,
+    PostgresSessionStore,
+    PostgresUserStore,
+)
+
+__all__ = [
+    "AuthServiceBase",
+    "InMemorySessionStore",
+    "InMemoryUserStore",
+    "PostgresSessionStore",
+    "PostgresUserStore",
+    "SessionStore",
+    "TokenVerifier",
+    "UserStore",
+]

app_platform-0.2.0/app_platform/auth/dependencies.py

@@ -0,0 +1,28 @@
+"""FastAPI dependency helpers for app_platform.auth."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from fastapi import HTTPException, Request
+
+from .service import AuthServiceBase
+
+
+def create_auth_dependency(
+    auth_service: AuthServiceBase,
+    cookie_name: str = "session_id",
+) -> Callable[[Request], dict[str, Any]]:
+    """Return a FastAPI dependency that resolves the current user from a cookie."""
+
+    def get_current_user(request: Request) -> dict[str, Any]:
+        session_id = request.cookies.get(cookie_name)
+        user = auth_service.get_user_by_session(session_id)
+        if not user:
+            raise HTTPException(status_code=401, detail="Authentication required")
+        return user
+
+    return get_current_user
+
+
+__all__ = ["create_auth_dependency"]

app_platform-0.2.0/app_platform/auth/google.py

@@ -0,0 +1,50 @@
+"""Google OAuth token verification for app_platform.auth."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from google.auth.transport import requests as google_requests
+from google.oauth2 import id_token
+
+
+class GoogleTokenVerifier:
+    """TokenVerifier implementation backed by google-auth."""
+
+    def __init__(
+        self,
+        client_id: Optional[str],
+        dev_mode: bool = False,
+        dev_user: Optional[Dict[str, Any]] = None,
+    ):
+        self.client_id = client_id
+        self.dev_mode = dev_mode
+        self.dev_user = dev_user or {
+            "user_id": "dev_user_123",
+            "email": "dev@example.com",
+            "name": "Development User",
+            "google_user_id": "dev_google_123",
+        }
+
+    def verify(self, token: str) -> tuple[Optional[Dict[str, Any]], Optional[str]]:
+        try:
+            if self.dev_mode or not self.client_id:
+                return dict(self.dev_user), None
+
+            id_info = id_token.verify_oauth2_token(
+                token,
+                google_requests.Request(),
+                self.client_id,
+            )
+            return {
+                "user_id": id_info["sub"],
+                "email": id_info["email"],
+                "name": id_info.get("name", ""),
+                "google_user_id": id_info["sub"],
+            }, None
+
+        except Exception as exc:
+            return None, f"Google token verification failed: {exc}"
+
+
+__all__ = ["GoogleTokenVerifier"]

app_platform-0.2.0/app_platform/auth/protocols.py

@@ -0,0 +1,50 @@
+"""Protocol contracts for app_platform.auth."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SessionStore(Protocol):
+    """Backend contract for session persistence."""
+
+    def create_session(self, session_id: str, user_id: Any, expires_at: datetime) -> None:
+        """Persist a new session."""
+
+    def get_session(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """Resolve a session id to the normalized auth payload."""
+
+    def delete_session(self, session_id: str) -> bool:
+        """Delete a session if present."""
+
+    def cleanup_expired(self) -> int:
+        """Delete expired sessions and return the cleanup count."""
+
+    def touch_session(self, session_id: str) -> None:
+        """Update last-accessed metadata for a session."""
+
+
+@runtime_checkable
+class UserStore(Protocol):
+    """Backend contract for user persistence."""
+
+    def get_or_create_user(
+        self,
+        provider_user_id: str,
+        email: str,
+        name: str,
+    ) -> tuple[Any, Dict[str, Any]]:
+        """Return the resolved user id and normalized user payload."""
+
+
+@runtime_checkable
+class TokenVerifier(Protocol):
+    """Contract for OAuth/OIDC token verification."""
+
+    def verify(self, token: str) -> tuple[Optional[Dict[str, Any]], Optional[str]]:
+        """Validate a provider token and return either user info or an error."""
+
+
+__all__ = ["SessionStore", "TokenVerifier", "UserStore"]