varco-fastapi 0.1.0__tar.gz

varco_fastapi-0.1.0/.gitignore

@@ -0,0 +1,209 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+todo*.txt
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

varco_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: varco-fastapi
+Version: 0.1.0
+Summary: FastAPI adapter for varco — routing, auth middleware, job running, typed HTTP client, and DI wiring
+Project-URL: Homepage, https://github.com/edoardoscarpaci/varco
+Project-URL: Repository, https://github.com/edoardoscarpaci/varco/tree/main/varco_fastapi
+Project-URL: Issues, https://github.com/edoardoscarpaci/varco/issues
+Author-email: "edoardo.scarpaci" <edoardo.scarpaci@gmail.com>
+License: Apache-2.0
+Keywords: async,auth,domain-model,fastapi,jobs,middleware,rest-api,varco
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: providify>=0.1.4a3
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: varco-core
+Provides-Extra: a2a
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.42b0; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: ws
+Requires-Dist: varco-ws; extra == 'ws'

varco_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[project]
+name          = "varco-fastapi"
+version       = "0.1.0"
+description   = "FastAPI adapter for varco — routing, auth middleware, job running, typed HTTP client, and DI wiring"
+authors       = [{ name = "edoardo.scarpaci", email = "edoardo.scarpaci@gmail.com" }]
+readme        = "README.md"
+license       = { text = "Apache-2.0" }
+requires-python = ">=3.12"
+keywords      = ["fastapi", "async", "rest-api", "domain-model", "varco", "middleware", "auth", "jobs"]
+classifiers   = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Framework :: FastAPI",
+    "Typing :: Typed",
+]
+dependencies = [
+    # Workspace sibling — resolved from the monorepo via [tool.uv.sources] below.
+    "varco-core",
+    # FastAPI provides the HTTP framework, routing, and OpenAPI schema generation.
+    "fastapi>=0.115.0",
+    # httpx is the async HTTP client used by AsyncVarcoClient and SyncVarcoClient.
+    "httpx>=0.27.0",
+    # pydantic-settings for env-var-based configuration (CORSConfig, TrustStore, etc.)
+    "pydantic-settings>=2.0",
+    # providify for DI wiring (@Configuration, @Provider, Inject[], DIContainer)
+    "providify>=0.1.4a3",
+    # python-multipart is required for FastAPI form data parsing (file uploads, etc.)
+    "python-multipart>=0.0.9",
+]
+
+[project.optional-dependencies]
+# WebSocket and SSE support (requires varco_ws from the workspace)
+ws  = ["varco-ws"]
+# MCP (Model Context Protocol) adapter support
+# Enables MCPAdapter.to_mcp_server() and MCPAdapter.mount()
+mcp = ["mcp>=1.0"]
+# A2A (Agent-to-Agent / Google A2A protocol) support
+# SkillAdapter works without this extra (it uses FastAPI directly);
+# install for the google-a2a SDK types if you need A2A client utilities.
+a2a = []
+# OpenTelemetry instrumentation — optional; gracefully no-ops when absent
+otel = [
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-instrumentation-fastapi>=0.42b0",
+]
+
+[project.urls]
+Homepage   = "https://github.com/edoardoscarpaci/varco"
+Repository = "https://github.com/edoardoscarpaci/varco/tree/main/varco_fastapi"
+Issues     = "https://github.com/edoardoscarpaci/varco/issues"
+
+[tool.uv.sources]
+# Resolve workspace siblings from the monorepo instead of PyPI.
+varco-core = { workspace = true }
+varco-ws   = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    # httpx is used as a test client via fastapi.testclient.TestClient + AsyncClient
+    "httpx>=0.27.0",
+    # uvicorn for integration test server
+    "uvicorn>=0.30",
+    # starlette test client
+    "anyio>=4.0",
+    # cryptography for JWT auth tests
+    "cryptography>=42.0",
+]
+
+[build-system]
+requires      = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["varco_fastapi"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths    = ["tests"]
+markers      = [
+    "integration: real external services required (disabled by default — use -m integration)",
+]

varco_fastapi-0.1.0/tests/milestone_a/test_context.py

@@ -0,0 +1,102 @@
+"""
+Tests for varco_fastapi.context — ContextVars and context managers.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from varco_core.auth.base import AuthContext
+from varco_fastapi.context import (
+    auth_context,
+    auth_context_var,
+    get_auth_context,
+    get_auth_context_or_none,
+    get_request_id,
+    get_request_token,
+    request_scope,
+    request_id_var,
+)
+
+
+async def test_get_auth_context_raises_outside_context():
+    """get_auth_context() raises RuntimeError when no context is set."""
+    auth_context_var.set(None)
+    with pytest.raises(RuntimeError, match="No AuthContext"):
+        get_auth_context()
+
+
+async def test_get_auth_context_or_none_returns_none_outside_context():
+    """get_auth_context_or_none() returns None when no context is set."""
+    auth_context_var.set(None)
+    assert get_auth_context_or_none() is None
+
+
+async def test_auth_context_sets_and_restores():
+    """auth_context() sets auth_context_var and restores on exit."""
+    ctx = AuthContext(user_id="usr_1", roles=frozenset({"admin"}))
+    auth_context_var.set(None)
+
+    async with auth_context(ctx, token="tok_abc"):
+        assert get_auth_context() is ctx
+        assert get_request_token() == "tok_abc"
+
+    # Restored to None after exit
+    assert get_auth_context_or_none() is None
+    assert get_request_token() is None
+
+
+async def test_auth_context_nested():
+    """Nested auth_context() restores each level correctly."""
+    outer = AuthContext(user_id="usr_outer")
+    inner = AuthContext(user_id="usr_inner")
+
+    async with auth_context(outer, token="tok_outer"):
+        assert get_auth_context().user_id == "usr_outer"
+        async with auth_context(inner, token="tok_inner"):
+            assert get_auth_context().user_id == "usr_inner"
+            assert get_request_token() == "tok_inner"
+        # Restored to outer
+        assert get_auth_context().user_id == "usr_outer"
+        assert get_request_token() == "tok_outer"
+
+    # Fully cleaned up
+    assert get_auth_context_or_none() is None
+
+
+async def test_request_scope_generates_request_id():
+    """request_scope() generates a request_id if not provided."""
+    request_id_var.set(None)
+
+    async with request_scope() as rid:
+        assert rid is not None
+        assert len(rid) > 0
+        assert get_request_id() == rid
+
+    # Restored
+    assert request_id_var.get() is None
+
+
+async def test_request_scope_uses_provided_id():
+    """request_scope() uses the provided request_id."""
+    async with request_scope(request_id="req_custom_123") as rid:
+        assert rid == "req_custom_123"
+        assert get_request_id() == "req_custom_123"
+
+
+async def test_request_scope_sets_correlation_id():
+    """request_scope() enters correlation_context with the request_id."""
+    from varco_core.tracing import current_correlation_id
+
+    async with request_scope(request_id="req_corr_456") as _rid:
+        assert current_correlation_id() == "req_corr_456"
+
+    # Correlation ID is restored to None after exit
+    assert current_correlation_id() is None
+
+
+async def test_get_request_id_raises_outside_scope():
+    """get_request_id() raises RuntimeError when request_scope() is not entered."""
+    request_id_var.set(None)
+    with pytest.raises(RuntimeError, match="No request_id"):
+        get_request_id()

varco_fastapi-0.1.0/tests/milestone_a/test_job_base.py

@@ -0,0 +1,215 @@
+"""
+Tests for varco_core.job.base — Job, JobStatus, auth snapshot helpers.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import uuid4
+
+import pytest
+
+from varco_core.auth.base import Action, AuthContext, ResourceGrant
+from varco_core.job.base import (
+    Job,
+    JobStatus,
+    auth_context_from_snapshot,
+    auth_context_to_snapshot,
+)
+
+
+# ── JobStatus ──────────────────────────────────────────────────────────────────
+
+
+def test_job_status_terminal_states():
+    """COMPLETED, FAILED, CANCELLED are terminal; PENDING, RUNNING are not."""
+    assert JobStatus.COMPLETED.is_terminal
+    assert JobStatus.FAILED.is_terminal
+    assert JobStatus.CANCELLED.is_terminal
+    assert not JobStatus.PENDING.is_terminal
+    assert not JobStatus.RUNNING.is_terminal
+
+
+# ── Job transitions ────────────────────────────────────────────────────────────
+
+
+def test_job_as_running():
+    """as_running() transitions PENDING → RUNNING and sets started_at."""
+    job = Job(job_id=uuid4(), created_at=datetime.now(timezone.utc))
+    running = job.as_running()
+    assert running.status == JobStatus.RUNNING
+    assert running.started_at is not None
+    assert running.job_id == job.job_id  # same job ID
+
+
+def test_job_as_completed():
+    """as_completed() transitions RUNNING → COMPLETED and sets result."""
+    job = Job(job_id=uuid4(), status=JobStatus.RUNNING)
+    completed = job.as_completed(result=b'{"ok": true}')
+    assert completed.status == JobStatus.COMPLETED
+    assert completed.result == b'{"ok": true}'
+    assert completed.completed_at is not None
+
+
+def test_job_as_failed():
+    """as_failed() transitions RUNNING → FAILED and sets error."""
+    job = Job(job_id=uuid4(), status=JobStatus.RUNNING)
+    failed = job.as_failed(error="Connection timeout")
+    assert failed.status == JobStatus.FAILED
+    assert failed.error == "Connection timeout"
+    assert failed.completed_at is not None
+
+
+def test_job_as_cancelled_from_pending():
+    """as_cancelled() transitions PENDING → CANCELLED."""
+    job = Job(job_id=uuid4(), status=JobStatus.PENDING)
+    cancelled = job.as_cancelled()
+    assert cancelled.status == JobStatus.CANCELLED
+    assert cancelled.completed_at is not None
+
+
+def test_job_as_cancelled_from_running():
+    """as_cancelled() transitions RUNNING → CANCELLED."""
+    job = Job(job_id=uuid4(), status=JobStatus.RUNNING)
+    cancelled = job.as_cancelled()
+    assert cancelled.status == JobStatus.CANCELLED
+
+
+def test_job_transitions_are_immutable():
+    """Job.as_*() returns a new Job instance; original is unchanged."""
+    job = Job(job_id=uuid4())
+    running = job.as_running()
+    assert job.status == JobStatus.PENDING  # original unchanged
+    assert running.status == JobStatus.RUNNING
+
+
+def test_job_as_running_raises_on_non_pending():
+    """as_running() raises ValueError if job is not PENDING."""
+    job = Job(job_id=uuid4(), status=JobStatus.RUNNING)
+    with pytest.raises(ValueError, match="Only PENDING"):
+        job.as_running()
+
+
+def test_job_as_completed_raises_on_non_running():
+    """as_completed() raises ValueError if job is not RUNNING."""
+    job = Job(job_id=uuid4(), status=JobStatus.PENDING)
+    with pytest.raises(ValueError, match="Only RUNNING"):
+        job.as_completed(result=b"")
+
+
+def test_job_as_cancelled_raises_on_terminal():
+    """as_cancelled() raises ValueError if job is already in a terminal state."""
+    job = Job(job_id=uuid4(), status=JobStatus.COMPLETED)
+    with pytest.raises(ValueError, match="terminal state"):
+        job.as_cancelled()
+
+
+# ── Auth snapshot serialization ────────────────────────────────────────────────
+
+
+def test_auth_context_to_snapshot_serializes_all_fields():
+    """auth_context_to_snapshot() produces a JSON-safe dict."""
+    ctx = AuthContext(
+        user_id="usr_1",
+        roles=frozenset({"admin", "editor"}),
+        scopes=frozenset({"write:posts"}),
+        grants=(
+            ResourceGrant(
+                resource="posts",
+                actions=frozenset({Action.CREATE, Action.READ}),
+            ),
+        ),
+        metadata={"tenant_id": "t1"},
+    )
+    snapshot = auth_context_to_snapshot(ctx)
+
+    assert snapshot["user_id"] == "usr_1"
+    assert sorted(snapshot["roles"]) == ["admin", "editor"]
+    assert snapshot["scopes"] == ["write:posts"]
+    assert snapshot["grants"][0]["resource"] == "posts"
+    assert sorted(snapshot["grants"][0]["actions"]) == ["create", "read"]
+    assert snapshot["metadata"] == {"tenant_id": "t1"}
+
+
+def test_auth_context_round_trip():
+    """Serializing and deserializing an AuthContext preserves all fields."""
+    original = AuthContext(
+        user_id="usr_2",
+        roles=frozenset({"manager"}),
+        scopes=frozenset({"read:reports"}),
+        grants=(
+            ResourceGrant(
+                resource="reports",
+                actions=frozenset({Action.LIST, Action.READ}),
+            ),
+        ),
+        metadata={"department": "finance"},
+    )
+    snapshot = auth_context_to_snapshot(original)
+    restored = auth_context_from_snapshot(snapshot)
+
+    assert restored.user_id == original.user_id
+    assert restored.roles == original.roles
+    assert restored.scopes == original.scopes
+    assert len(restored.grants) == 1
+    assert restored.grants[0].resource == "reports"
+    assert Action.READ in restored.grants[0].actions
+    assert restored.metadata == original.metadata
+
+
+def test_auth_context_from_snapshot_handles_missing_metadata():
+    """auth_context_from_snapshot() defaults to empty dict for missing metadata."""
+    snapshot = {"user_id": "usr_3", "roles": [], "scopes": [], "grants": []}
+    ctx = auth_context_from_snapshot(snapshot)
+    assert ctx.user_id == "usr_3"
+    assert ctx.metadata == {}
+
+
+def test_auth_context_from_snapshot_handles_anonymous():
+    """auth_context_from_snapshot() handles None user_id (anonymous)."""
+    snapshot = auth_context_to_snapshot(AuthContext())
+    restored = auth_context_from_snapshot(snapshot)
+    assert restored.is_anonymous()
+
+
+# ── VarcoLifespan ─────────────────────────────────────────────────────────────
+
+
+async def test_varco_lifespan_starts_and_stops_components():
+    """VarcoLifespan starts components in order and stops them in reverse."""
+    from fastapi import FastAPI
+
+    from varco_fastapi.lifespan import VarcoLifespan
+
+    events: list[str] = []
+
+    class FakeComponent:
+        def __init__(self, name: str):
+            self.name = name
+
+        async def start(self):
+            events.append(f"start:{self.name}")
+
+        async def stop(self):
+            events.append(f"stop:{self.name}")
+
+    c1 = FakeComponent("first")
+    c2 = FakeComponent("second")
+
+    lifespan = VarcoLifespan(c1, c2)
+
+    app = FastAPI(lifespan=lifespan)
+
+    async with lifespan(app):
+        pass  # Simulate app running
+
+    assert events == ["start:first", "start:second", "stop:second", "stop:first"]
+
+
+async def test_varco_lifespan_register_raises_for_invalid_component():
+    """VarcoLifespan.register() raises TypeError for objects without start/stop."""
+    from varco_fastapi.lifespan import VarcoLifespan
+
+    lifespan = VarcoLifespan()
+    with pytest.raises(TypeError, match="AbstractLifecycle"):
+        lifespan.register(object())