yirifi-ops-auth-client 3.2.3__py3-none-any.whl

yirifi_ops_auth/deeplink/blueprint.py

@@ -0,0 +1,155 @@
+"""Flask blueprint for exposing entity references via API.
+
+This blueprint exposes the /api/v1/references endpoint that returns
+this microsite's entity definitions for federation discovery.
+
+Usage:
+    from yirifi_ops_auth.deeplink import setup_deeplinks
+
+    # In your app factory
+    setup_deeplinks(
+        app,
+        expose_references=True,  # Registers this blueprint
+    )
+
+    # Or manually:
+    from yirifi_ops_auth.deeplink.blueprint import references_bp
+    app.register_blueprint(references_bp)
+"""
+
+from datetime import datetime
+from flask import Blueprint, jsonify, request, current_app
+
+from .registry import (
+    get_microsite_config,
+    list_entity_types_for_microsite,
+    get_entity_definition,
+)
+
+
+references_bp = Blueprint("deeplink_references", __name__, url_prefix="/api/v1")
+
+
+@references_bp.route("/references", methods=["GET"])
+def get_references():
+    """Expose this microsite's entity definitions for federation.
+
+    This endpoint allows other microsites to discover what entity types
+    this microsite serves and how to construct URLs for them.
+
+    Query Parameters:
+        entity_type (str, optional): Filter to specific entity type
+        include_urls (bool, default=true): Include URL mappings in response
+
+    Returns:
+        JSON response with schema:
+        {
+            "schema_version": "1.0",
+            "microsite": {
+                "id": "risk",
+                "name": "Risk Dashboard",
+                "urls": {
+                    "dev": "http://localhost:5012",
+                    "uat": "https://risk-uat.ops.yirifi.com",
+                    "prd": "https://risk.ops.yirifi.com"
+                }
+            },
+            "entities": [
+                {
+                    "type": "risk_item",
+                    "path": "/items/{id}",
+                    "description": "Risk management item"
+                }
+            ],
+            "timestamp": "2024-12-23T10:30:00Z"
+        }
+
+    Response Headers:
+        Cache-Control: public, max-age=300
+        X-Federation-Version: 1.0
+    """
+    # Get microsite config (set during setup)
+    microsite_id = current_app.config.get("DEEPLINK_MICROSITE_ID")
+    if not microsite_id:
+        return (
+            jsonify(
+                {
+                    "error": "microsite_not_configured",
+                    "message": "This microsite has not configured deep linking. "
+                    "Call setup_deeplinks() with a microsite parameter.",
+                }
+            ),
+            500,
+        )
+
+    config = get_microsite_config(microsite_id)
+    if not config:
+        return (
+            jsonify(
+                {
+                    "error": "microsite_not_found",
+                    "message": f"Microsite '{microsite_id}' not registered in local registry.",
+                }
+            ),
+            500,
+        )
+
+    # Parse query parameters
+    entity_type_filter = request.args.get("entity_type")
+    include_urls = request.args.get("include_urls", "true").lower() == "true"
+
+    # Get entities for this microsite
+    entity_types = list_entity_types_for_microsite(microsite_id)
+
+    if entity_type_filter:
+        entity_types = [et for et in entity_types if et == entity_type_filter]
+
+    entities = []
+    for entity_type in entity_types:
+        defn = get_entity_definition(entity_type)
+        if defn:
+            entity_data = {
+                "type": defn.entity_type,
+                "path": defn.path_template,
+            }
+            if defn.description:
+                entity_data["description"] = defn.description
+            entities.append(entity_data)
+
+    # Build response
+    response_data = {
+        "schema_version": "1.0",
+        "microsite": {
+            "id": config.id,
+            "name": config.name,
+        },
+        "entities": entities,
+        "timestamp": datetime.utcnow().isoformat() + "Z",
+    }
+
+    if include_urls:
+        response_data["microsite"]["urls"] = config.urls
+
+    # Build response with cache headers
+    resp = jsonify(response_data)
+    resp.headers["Cache-Control"] = "public, max-age=300"
+    resp.headers["X-Federation-Version"] = "1.0"
+
+    return resp
+
+
+@references_bp.route("/references/health", methods=["GET"])
+def references_health():
+    """Health check for the references endpoint.
+
+    Returns simple status for monitoring/load balancer health checks.
+    """
+    microsite_id = current_app.config.get("DEEPLINK_MICROSITE_ID")
+
+    return jsonify(
+        {
+            "status": "ok",
+            "microsite_id": microsite_id,
+            "federation_version": "1.0",
+        }
+    )

yirifi_ops_auth/deeplink/environment.py

@@ -0,0 +1,156 @@
+"""Thread-safe environment configuration using contextvars.
+
+Provides isolation for environment settings across threads and async contexts,
+with a context manager for temporary overrides.
+"""
+
+import os
+from contextvars import ContextVar
+from contextlib import contextmanager
+from typing import Optional, Generator
+
+
+# Thread-safe environment storage
+_env_var: ContextVar[Optional[str]] = ContextVar('deeplink_env', default=None)
+
+# Valid environments
+VALID_ENVIRONMENTS = ("dev", "uat", "prd")
+
+# Environment name aliases
+ENV_ALIASES = {
+    "development": "dev",
+    "local": "dev",
+    "staging": "uat",
+    "test": "uat",
+    "production": "prd",
+    "prod": "prd",
+}
+
+
+class Environment:
+    """Thread-safe environment configuration.
+
+    Usage:
+        # Get current environment
+        env = Environment.get()  # -> 'dev', 'uat', or 'prd'
+
+        # Set environment
+        Environment.set('prd')
+
+        # Temporary override (for testing)
+        with Environment.override('uat'):
+            # Inside this block, env is 'uat'
+            do_something()
+        # Outside, env is restored to previous value
+    """
+
+    VALID = VALID_ENVIRONMENTS
+
+    @classmethod
+    def get(cls) -> str:
+        """Get the current environment.
+
+        Resolution order:
+        1. Explicitly set via Environment.set() (thread-local)
+        2. YIRIFI_ENV environment variable
+        3. FLASK_ENV environment variable
+        4. Default to 'dev'
+
+        Returns:
+            Environment string: 'dev', 'uat', or 'prd'
+        """
+        # Check thread-local context first
+        env = _env_var.get()
+        if env is not None:
+            return env
+
+        # Fall back to environment variables
+        return cls._from_env_vars()
+
+    @classmethod
+    def _from_env_vars(cls) -> str:
+        """Read environment from OS environment variables."""
+        env = os.getenv("YIRIFI_ENV") or os.getenv("FLASK_ENV", "dev")
+        return cls._normalize(env)
+
+    @classmethod
+    def _normalize(cls, env: str) -> str:
+        """Normalize environment name to standard form.
+
+        Args:
+            env: Raw environment string
+
+        Returns:
+            Normalized environment: 'dev', 'uat', or 'prd'
+        """
+        env = env.lower()
+        env = ENV_ALIASES.get(env, env)
+        return env if env in VALID_ENVIRONMENTS else "dev"
+
+    @classmethod
+    def set(cls, env: str) -> None:
+        """Set the environment for the current context.
+
+        Args:
+            env: Environment string ('dev', 'uat', or 'prd') or alias
+
+        Raises:
+            ValueError: If env is not a valid environment or alias
+        """
+        env_lower = env.lower()
+        # Check if it's a valid environment or a known alias
+        if env_lower not in VALID_ENVIRONMENTS and env_lower not in ENV_ALIASES:
+            raise ValueError(
+                f"Invalid environment: {env}. Must be one of {VALID_ENVIRONMENTS} "
+                f"or aliases: {list(ENV_ALIASES.keys())}"
+            )
+        normalized = cls._normalize(env)
+        _env_var.set(normalized)
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset environment to auto-detection (clear explicit setting)."""
+        _env_var.set(None)
+
+    @classmethod
+    @contextmanager
+    def override(cls, env: str) -> Generator[None, None, None]:
+        """Temporarily override the environment.
+
+        Useful for testing or when you need to resolve links for a different
+        environment temporarily.
+
+        Args:
+            env: Environment to use within the context
+
+        Example:
+            Environment.set('dev')
+            print(Environment.get())  # 'dev'
+
+            with Environment.override('prd'):
+                print(Environment.get())  # 'prd'
+
+            print(Environment.get())  # 'dev' (restored)
+        """
+        normalized = cls._normalize(env)
+        if normalized not in VALID_ENVIRONMENTS:
+            raise ValueError(
+                f"Invalid environment: {env}. Must be one of {VALID_ENVIRONMENTS}"
+            )
+
+        token = _env_var.set(normalized)
+        try:
+            yield
+        finally:
+            _env_var.reset(token)
+
+
+# Convenience functions for backwards compatibility and simpler imports
+def get_environment() -> str:
+    """Get the current environment. Alias for Environment.get()."""
+    return Environment.get()
+
+
+def set_environment(env: str) -> None:
+    """Set the environment. Alias for Environment.set()."""
+    Environment.set(env)