functualize-http 0.1.0__tar.gz

functualize_http-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/features/
+.spec/scrutiny-reports/
+.spec/.agentic-coding
+.spec/STATE.md
+.spec/PROJECT.md
+.spec/REQUIREMENTS.md
+.spec/ROADMAP.md
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/

functualize_http-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: functualize-http
+Version: 0.1.0
+Summary: HTTP delivery adapter plugin for functualize using asyncio
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: functualize<1.0.0,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-http
+
+> **Status: Published** — Independently installable from PyPI.
+
+HTTP delivery adapter plugin for functualize using Python's stdlib asyncio.
+
+## Installation
+
+```bash
+pip install functualize-http
+```
+
+## Usage
+
+### As an Adapter
+
+```python
+from functualize.app import FunctualizeApp
+from functualize_http import HttpAdapter
+
+app = FunctualizeApp("myapp", job_sources=...)
+adapter = HttpAdapter()
+adapter(app)
+adapter.run(host="0.0.0.0", port=8000)
+```
+
+### As a CLI Plugin
+
+```python
+from functualize.app import FunctualizeApp
+from functualize_http import HttpServerPlugin
+
+app = FunctualizeApp("myapp", job_sources=...)
+plugin = HttpServerPlugin()
+plugin(app)
+# The 'serve' command is now available in the CLI
+```
+
+## Endpoints
+
+- `GET /health` — Health check
+- `GET /jobs` — List available jobs
+- `POST /jobs/{job_name}/execute` — Execute a job with JSON body as kwargs

functualize_http-0.1.0/README.md

@@ -0,0 +1,43 @@
+# functualize-http
+
+> **Status: Published** — Independently installable from PyPI.
+
+HTTP delivery adapter plugin for functualize using Python's stdlib asyncio.
+
+## Installation
+
+```bash
+pip install functualize-http
+```
+
+## Usage
+
+### As an Adapter
+
+```python
+from functualize.app import FunctualizeApp
+from functualize_http import HttpAdapter
+
+app = FunctualizeApp("myapp", job_sources=...)
+adapter = HttpAdapter()
+adapter(app)
+adapter.run(host="0.0.0.0", port=8000)
+```
+
+### As a CLI Plugin
+
+```python
+from functualize.app import FunctualizeApp
+from functualize_http import HttpServerPlugin
+
+app = FunctualizeApp("myapp", job_sources=...)
+plugin = HttpServerPlugin()
+plugin(app)
+# The 'serve' command is now available in the CLI
+```
+
+## Endpoints
+
+- `GET /health` — Health check
+- `GET /jobs` — List available jobs
+- `POST /jobs/{job_name}/execute` — Execute a job with JSON body as kwargs

functualize_http-0.1.0/examples/README.md

@@ -0,0 +1,22 @@
+# functualize-http Examples
+
+The HTTP delivery adapter: expose the same jobs as API endpoints and CLI commands.
+
+| Directory | Demonstrates |
+|-----------|--------------|
+| [`http_service/`](http_service/) | A full project serving jobs over HTTP via `HttpAdapter`, with the same jobs runnable via CLI |
+
+```bash
+cd plugins/functualize-http/examples/http_service
+uv sync
+uv run python -m http_service        # starts on :8000
+
+# Same jobs via CLI
+uv run http-service healthcheck run --service-url https://example.com
+```
+
+Tests:
+
+```bash
+uv run pytest plugins/functualize-http/examples/ -v
+```

functualize_http-0.1.0/examples/http_service/README.md

@@ -0,0 +1,45 @@
+# HTTP Service — Project Example
+
+A functualize project deployed as an HTTP API using the `functualize-http` adapter. Same jobs, different delivery surface — no code changes required.
+
+## Setup
+
+```bash
+cd plugins/functualize-http/examples/http_service
+uv sync
+```
+
+## Running
+
+```bash
+# Start the HTTP server
+uv run python -m http_service
+
+# Or use the CLI adapter (same jobs)
+uv run http-service --help
+```
+
+## Endpoints
+
+Once the server is running:
+
+```bash
+# Health check
+curl http://localhost:8000/health
+
+# List available jobs
+curl http://localhost:8000/jobs
+
+# Execute a job
+curl -X POST http://localhost:8000/jobs/healthcheck/execute \
+  -H "Content-Type: application/json" \
+  -d '{"service_url": "https://api.example.com", "timeout": 5}'
+```
+
+## What This Demonstrates
+
+- `FunctualizeApp` with `JobSources` and `twelve_factor()` config preset
+- `HttpAdapter` for HTTP API delivery
+- Same jobs work via CLI and HTTP without modification
+- Pydantic config models become JSON request schemas
+- `@job_metadata` tags control which jobs are exposed

functualize_http-0.1.0/examples/http_service/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "http-service"
+version = "0.1.0"
+description = "Example: Functualize jobs exposed as an HTTP API"
+requires-python = ">=3.11"
+dependencies = [
+    "functualize",
+    "functualize-http",
+    "functualize-state",
+]
+
+[project.scripts]
+http-service = "http_service.app:run_cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/http_service"]
+
+[tool.uv.sources]
+functualize = { path = "../../../..", editable = true }
+functualize-http = { path = "../..", editable = true }
+functualize-state = { path = "../../../functualize-state", editable = true }

functualize_http-0.1.0/examples/http_service/src/http_service/__init__.py

@@ -0,0 +1 @@
+"""HTTP Service example — functualize jobs delivered via HTTP API."""

functualize_http-0.1.0/examples/http_service/src/http_service/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the package directly: python -m http_service"""
+
+from http_service.app import run_http
+
+if __name__ == "__main__":
+    run_http()

functualize_http-0.1.0/examples/http_service/src/http_service/app.py

@@ -0,0 +1,36 @@
+"""Application entry point — configures FunctualizeApp with HTTP adapter.
+
+This module wires together job discovery, configuration, and the HTTP
+delivery adapter. The same jobs are accessible via both CLI and HTTP.
+"""
+
+from pathlib import Path
+
+from functualize_http import HttpAdapter
+
+from functualize.app import FunctualizeApp, JobSources, twelve_factor
+
+JOBS_DIR = str(Path(__file__).parent / "jobs")
+
+# Create the app with twelve-factor config (env vars, no files)
+app = FunctualizeApp(
+    name="http-service",
+    job_sources=JobSources(directories=[JOBS_DIR]),
+    config_sources=twelve_factor(dotenv=True),
+)
+
+
+def run_http(host: str = "0.0.0.0", port: int = 8000) -> None:
+    """Start the HTTP server."""
+    adapter = HttpAdapter()
+    adapter(app)
+    adapter.run(host=host, port=port)
+
+
+def run_cli() -> None:
+    """Start the CLI interface (same jobs, different delivery)."""
+    app.run()
+
+
+if __name__ == "__main__":
+    run_http()

functualize_http-0.1.0/examples/http_service/src/http_service/jobs/__init__.py

@@ -0,0 +1 @@
+"""Jobs for the HTTP service example."""

functualize_http-0.1.0/examples/http_service/src/http_service/jobs/deploy.py

@@ -0,0 +1,64 @@
+"""Deploy job — deploy application artifacts to an environment."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from functualize.job.context import RunContext
+from functualize.job.decorators import job
+
+JOB_NAME = "deploy"
+
+
+class Environment(StrEnum):
+    """Target deployment environment."""
+
+    staging = "staging"
+    production = "production"
+
+
+class DeployConfig(BaseModel):
+    """Configuration for the deploy job."""
+
+    version: str = Field(description="Version tag to deploy (e.g., v1.2.3)")
+    environment: Environment = Field(
+        default=Environment.staging, description="Target environment"
+    )
+    dry_run: bool = Field(default=False, description="Preview without applying changes")
+
+
+@job(
+    extra_description="Deploy application artifacts to staging or production",
+    category="deployment",
+    tags=["deploy", "infrastructure"],
+    examples=["deploy --version v1.2.3 --environment production"],
+    visibility="external",
+)
+def run(config: DeployConfig, rc: RunContext) -> dict:
+    """Deploy the application to the specified environment.
+
+    Builds a container image, pushes to the registry, and updates
+    the target environment's deployment manifest.
+    """
+    rc.log(f"Deploying {config.version} to {config.environment.value}")
+
+    if config.dry_run:
+        rc.log("DRY RUN — no changes applied")
+        return {
+            "version": config.version,
+            "environment": config.environment.value,
+            "status": "dry_run",
+            "changes_applied": False,
+        }
+
+    # Simulated deployment steps
+    rc.log("Building container image...")
+    rc.log("Pushing to registry...")
+    rc.log("Updating deployment manifest...")
+
+    return {
+        "version": config.version,
+        "environment": config.environment.value,
+        "status": "deployed",
+        "changes_applied": True,
+    }

functualize_http-0.1.0/examples/http_service/src/http_service/jobs/healthcheck.py

@@ -0,0 +1,45 @@
+"""Health check job — verify a service is responding."""
+
+from pydantic import BaseModel, Field
+
+from functualize.job.context import RunContext
+from functualize.job.decorators import job
+
+JOB_NAME = "healthcheck"
+
+
+class HealthcheckConfig(BaseModel):
+    """Configuration for the healthcheck job."""
+
+    service_url: str = Field(description="URL of the service to check")
+    timeout: int = Field(
+        default=5, ge=1, le=30, description="Request timeout in seconds"
+    )
+    expected_status: int = Field(default=200, description="Expected HTTP status code")
+
+
+@job(
+    extra_description="Check if a service endpoint is healthy and responding",
+    category="monitoring",
+    tags=["health", "monitoring", "safe", "read-only"],
+    visibility="external",
+)
+def run(config: HealthcheckConfig, rc: RunContext) -> dict:
+    """Check service health by making a request to the configured URL.
+
+    Returns status information including response time and status code.
+    This is a read-only operation suitable for automated monitoring.
+    """
+    rc.log(f"Checking health: {config.service_url}")
+
+    # Simulated health check (real impl would use httpx/urllib)
+    result = {
+        "url": config.service_url,
+        "status": "healthy",
+        "status_code": config.expected_status,
+        "response_time_ms": 42,
+        "timeout_configured": config.timeout,
+    }
+
+    rc.log(f"Service healthy: {result['response_time_ms']}ms response time")
+    return result

functualize_http-0.1.0/examples/http_service/tests/test_http_jobs.py

@@ -0,0 +1,88 @@
+"""Tests for HTTP service jobs — prove they work without the HTTP adapter."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+# Add the src directory so we can import the jobs directly
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from http_service.jobs.deploy import DeployConfig, Environment
+from http_service.jobs.deploy import run as deploy_run
+from http_service.jobs.healthcheck import HealthcheckConfig
+from http_service.jobs.healthcheck import run as healthcheck_run
+
+
+def _make_rc():
+    """Create a minimal mock RunContext for testing."""
+    rc = MagicMock()
+    rc.log = MagicMock()
+    return rc
+
+
+class TestHealthcheck:
+    """Tests for the healthcheck job."""
+
+    def test_returns_healthy_status(self):
+        rc = _make_rc()
+        config = HealthcheckConfig(service_url="https://api.example.com")
+        result = healthcheck_run(config, rc)
+
+        assert result["status"] == "healthy"
+        assert result["url"] == "https://api.example.com"
+        assert result["status_code"] == 200
+
+    def test_respects_timeout_config(self):
+        rc = _make_rc()
+        config = HealthcheckConfig(service_url="https://slow.example.com", timeout=10)
+        result = healthcheck_run(config, rc)
+
+        assert result["timeout_configured"] == 10
+
+    def test_custom_expected_status(self):
+        rc = _make_rc()
+        config = HealthcheckConfig(
+            service_url="https://api.example.com", expected_status=204
+        )
+        result = healthcheck_run(config, rc)
+
+        assert result["status_code"] == 204
+
+
+class TestDeploy:
+    """Tests for the deploy job."""
+
+    def test_deploy_to_staging(self):
+        rc = _make_rc()
+        config = DeployConfig(version="v1.0.0", environment=Environment.staging)
+        result = deploy_run(config, rc)
+
+        assert result["version"] == "v1.0.0"
+        assert result["environment"] == "staging"
+        assert result["status"] == "deployed"
+        assert result["changes_applied"] is True
+
+    def test_deploy_dry_run(self):
+        rc = _make_rc()
+        config = DeployConfig(version="v2.0.0", dry_run=True)
+        result = deploy_run(config, rc)
+
+        assert result["status"] == "dry_run"
+        assert result["changes_applied"] is False
+
+    def test_deploy_to_production(self):
+        rc = _make_rc()
+        config = DeployConfig(version="v1.5.0", environment=Environment.production)
+        result = deploy_run(config, rc)
+
+        assert result["environment"] == "production"
+        assert result["changes_applied"] is True
+
+    def test_deploy_logs_steps(self):
+        rc = _make_rc()
+        config = DeployConfig(version="v3.0.0")
+        deploy_run(config, rc)
+
+        log_calls = [str(call) for call in rc.log.call_args_list]
+        assert any("Deploying" in call for call in log_calls)
+        assert any("container image" in call for call in log_calls)

functualize_http-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "functualize-http"
+version = "0.1.0"
+description = "HTTP delivery adapter plugin for functualize using asyncio"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "functualize>=0.1.0,<1.0.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.entry-points."functualize.plugins"]
+http = "functualize_http:HttpAdapter"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+functualize = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_http"]

functualize_http-0.1.0/src/functualize_http/__init__.py

@@ -0,0 +1,423 @@
+"""Functualize HTTP Plugin - HTTP delivery adapter using asyncio.
+
+Provides HTTP serving support both as a standalone adapter (HttpAdapter)
+and as a CLI command plugin (HttpServerPlugin). Both share a common
+HttpServerCore class containing route building, request handling, and
+async-to-sync bridging logic.
+
+Uses Python's stdlib asyncio for a lightweight HTTP server without
+heavy dependencies (no uvicorn/starlette required).
+
+Key design:
+- HttpServerCore: shared class with route building, request handling,
+  async-to-sync bridging via asyncio.to_thread()
+- HttpAdapter: satisfies AdapterPlugin Protocol, adapter_type="http"
+- HttpServerPlugin: capability plugin registering a "serve" command
+
+The kernel stays synchronous — the adapter owns the event loop internally
+via asyncio.run().
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from asyncio import AbstractEventLoop
+
+    from functualize.app.core import FunctualizeApp
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PluginMetadata:
+    """Metadata for the functualize-http plugin package."""
+
+    name: str = "functualize-http"
+    version: str = "0.1.0"
+    description: str = "HTTP delivery adapter plugin for functualize using asyncio"
+
+
+class HttpServerCore:
+    """Shared HTTP server logic for route building and request handling.
+
+    Contains:
+    - Route building: maps each job to POST /jobs/{job_name}/execute
+    - Request handling: parse JSON body as kwargs, call app.execute()
+    - Async-to-sync bridging: asyncio.to_thread() for kernel execution
+    - Response formatting: JSON response with status and result
+    - Health endpoint: GET /health returns 200
+    - Job listing: GET /jobs returns available jobs
+
+    Both HttpAdapter and HttpServerPlugin use this class internally
+    to avoid code duplication.
+    """
+
+    def __init__(self, app: FunctualizeApp) -> None:
+        self._app = app
+        self._server: asyncio.Server | None = None
+
+    async def start(self, host: str, port: int) -> None:
+        """Start the HTTP server (async).
+
+        Blocks until the server is shut down via stop().
+
+        Args:
+            host: Host address to bind to.
+            port: Port number to listen on.
+        """
+        self._server = await asyncio.start_server(self._handle_connection, host, port)
+        addrs = ", ".join(str(s.getsockname()) for s in self._server.sockets)
+        logger.info(f"HTTP server listening on {addrs}")
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def stop(self) -> None:
+        """Stop the HTTP server gracefully."""
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+    def build_routes(self) -> dict[str, dict[str, Any]]:
+        """Build route map from registered jobs.
+
+        Returns a dict mapping (method, path) tuples conceptually:
+        - GET /health
+        - GET /jobs
+        - POST /jobs/{job_name}/execute for each job
+
+        This is used internally for request routing.
+        """
+        routes: dict[str, dict[str, Any]] = {}
+        for descriptor in self._app.get_jobs():
+            route_path = f"/jobs/{descriptor.name}/execute"
+            routes[route_path] = {
+                "method": "POST",
+                "job_name": descriptor.name,
+            }
+        return routes
+
+    async def handle_request(
+        self, method: str, path: str, body: bytes
+    ) -> tuple[int, dict[str, Any]]:
+        """Route and handle a single HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: Request path.
+            body: Request body bytes.
+
+        Returns:
+            Tuple of (status_code, response_dict).
+        """
+        # Health check
+        if method == "GET" and path == "/health":
+            return 200, {"status": "healthy"}
+
+        # List jobs
+        if method == "GET" and path == "/jobs":
+            jobs = self._app.get_jobs()
+            job_list = [
+                {
+                    "name": d.name,
+                    "group": d.group,
+                    "docstring": d.docstring,
+                }
+                for d in jobs
+            ]
+            return 200, {"jobs": job_list}
+
+        # Execute job: POST /jobs/{job_name}/execute
+        if method == "POST" and path.startswith("/jobs/") and path.endswith("/execute"):
+            # Extract job name from path
+            parts = path.split("/")
+            # Expected: ["", "jobs", "<job_name>", "execute"]
+            if len(parts) == 4:
+                job_name = parts[2]
+                return await self._execute_job(job_name, body)
+
+        # Not found
+        return 404, {"error": "Not found", "path": path}
+
+    async def _execute_job(
+        self, job_name: str, body: bytes
+    ) -> tuple[int, dict[str, Any]]:
+        """Execute a job with kwargs from the request body.
+
+        Uses asyncio.to_thread() to bridge the synchronous kernel
+        execution into the async server context.
+        """
+        # Parse body
+        kwargs: dict[str, Any] = {}
+        if body:
+            try:
+                kwargs = json.loads(body)
+            except (json.JSONDecodeError, UnicodeDecodeError) as e:
+                return 400, {"error": f"Invalid JSON body: {e}"}
+
+            if not isinstance(kwargs, dict):
+                return 400, {"error": "Request body must be a JSON object"}
+
+        # Check job exists
+        job = self._app.get_job(job_name)
+        if job is None:
+            return 404, {"error": f"Job '{job_name}' not found"}
+
+        # Execute via asyncio.to_thread (async-to-sync bridge)
+        try:
+            result = await asyncio.to_thread(self._app.execute, job_name, **kwargs)
+            return 200, {
+                "status": result.status.value
+                if hasattr(result.status, "value")
+                else str(result.status),
+                "duration_ms": result.duration_ms,
+                "return_value": self._serialize_return_value(result.return_value),
+            }
+        except Exception as e:
+            logger.exception(f"Error executing job '{job_name}'")
+            return 500, {"error": str(e)}
+
+    @staticmethod
+    def _serialize_return_value(value: Any) -> Any:
+        """Attempt to serialize a return value to JSON-compatible form."""
+        if value is None:
+            return None
+        if isinstance(value, str | int | float | bool):
+            return value
+        if isinstance(value, list | tuple):
+            return [HttpServerCore._serialize_return_value(v) for v in value]
+        if isinstance(value, dict):
+            return {
+                str(k): HttpServerCore._serialize_return_value(v)
+                for k, v in value.items()
+            }
+        # Fall back to string representation
+        return str(value)
+
+    async def _handle_connection(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        """Handle a single TCP connection (HTTP/1.1 basic parsing)."""
+        try:
+            # Read request line
+            request_line = await reader.readline()
+            if not request_line:
+                writer.close()
+                await writer.wait_closed()
+                return
+
+            request_str = request_line.decode("utf-8", errors="replace").strip()
+            parts = request_str.split(" ")
+            if len(parts) < 2:
+                await self._send_response(writer, 400, {"error": "Bad request"})
+                return
+
+            method = parts[0].upper()
+            path = parts[1].split("?")[0]  # Strip query params
+
+            # Read headers
+            content_length = 0
+            while True:
+                header_line = await reader.readline()
+                if header_line in (b"\r\n", b"\n", b""):
+                    break
+                header_str = header_line.decode("utf-8", errors="replace").strip()
+                if header_str.lower().startswith("content-length:"):
+                    with contextlib.suppress(ValueError):
+                        content_length = int(header_str.split(":", 1)[1].strip())
+
+            # Read body
+            body = b""
+            if content_length > 0:
+                body = await reader.readexactly(content_length)
+
+            # Handle request
+            status_code, response_body = await self.handle_request(method, path, body)
+            await self._send_response(writer, status_code, response_body)
+
+        except (ConnectionResetError, asyncio.IncompleteReadError):
+            pass
+        except Exception:
+            logger.exception("Error handling HTTP connection")
+            with contextlib.suppress(Exception):
+                await self._send_response(
+                    writer, 500, {"error": "Internal server error"}
+                )
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    @staticmethod
+    async def _send_response(
+        writer: asyncio.StreamWriter,
+        status_code: int,
+        body: dict[str, Any],
+    ) -> None:
+        """Send an HTTP response with JSON body."""
+        status_messages = {
+            200: "OK",
+            400: "Bad Request",
+            404: "Not Found",
+            500: "Internal Server Error",
+        }
+        status_text = status_messages.get(status_code, "Unknown")
+        body_bytes = json.dumps(body).encode("utf-8")
+
+        response = (
+            f"HTTP/1.1 {status_code} {status_text}\r\n"
+            f"Content-Type: application/json\r\n"
+            f"Content-Length: {len(body_bytes)}\r\n"
+            f"Connection: close\r\n"
+            f"\r\n"
+        ).encode() + body_bytes
+
+        writer.write(response)
+        await writer.drain()
+
+
+class HttpAdapter:
+    """HTTP delivery adapter — satisfies AdapterPlugin Protocol.
+
+    Starts an async HTTP server that blocks until shutdown, exposing
+    all registered jobs as HTTP endpoints.
+
+    The adapter owns the event loop internally via asyncio.run(),
+    keeping the kernel synchronous.
+
+    Usage:
+        app = FunctualizeApp("myapp", job_sources=...)
+        adapter = HttpAdapter()
+        adapter(app)
+        adapter.run(host="0.0.0.0", port=8000)
+    """
+
+    name: str = "functualize-http"
+    version: str = "1.0.0"
+    description: str = "HTTP delivery adapter plugin for functualize using asyncio"
+    adapter_type: str = "http"
+
+    def __init__(self) -> None:
+        self._app: FunctualizeApp | None = None
+        self._core: HttpServerCore | None = None
+
+    def __call__(self, app: FunctualizeApp) -> None:
+        """Setup phase — store app reference and create server core.
+
+        Args:
+            app: The FunctualizeApp kernel instance.
+        """
+        self._app = app
+        self._core = HttpServerCore(app)
+
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        """Start the HTTP server (blocking).
+
+        Accepts keyword arguments:
+            host: Host address to bind to (default: "0.0.0.0").
+            port: Port number to listen on (default: 8000).
+
+        The adapter creates and runs an asyncio event loop internally.
+        This method blocks until shutdown() is called or the server
+        is interrupted.
+        """
+        if self._core is None:
+            raise RuntimeError("HttpAdapter.run() called before __call__(app)")
+
+        host = kwargs.get("host", "0.0.0.0")
+        port = kwargs.get("port", 8000)
+
+        asyncio.run(self._core.start(host, port))
+
+    def shutdown(self) -> None:
+        """Graceful shutdown — stops the HTTP server."""
+        if self._core is not None and self._core._server is not None:
+            # Schedule the stop coroutine on the running loop
+            loop = self._get_running_loop()
+            if loop is not None and loop.is_running():
+                loop.call_soon_threadsafe(
+                    lambda: asyncio.ensure_future(self._core.stop())  # type: ignore[union-attr]
+                )
+
+    @staticmethod
+    def _get_running_loop() -> AbstractEventLoop | None:
+        """Get the currently running event loop, if any."""
+        try:
+            return asyncio.get_running_loop()
+        except RuntimeError:
+            return None
+
+
+class HttpServerPlugin:
+    """Capability plugin that registers a 'serve' CLI command.
+
+    This plugin registers a `serve` command via
+    `app.register_plugin_command()`. When invoked, the serve command
+    starts an HTTP server using the shared HttpServerCore.
+
+    Usage:
+        app = FunctualizeApp("myapp", ...)
+        plugin = HttpServerPlugin()
+        plugin(app)
+        # The 'serve' command is now available in the CLI
+
+    The plugin is NOT an adapter — it augments the CLI adapter with
+    an HTTP serving command.
+    """
+
+    name: str = "functualize-http-server"
+    version: str = "1.0.0"
+    description: str = "Registers a 'serve' command for HTTP serving"
+
+    def __init__(self) -> None:
+        self._app: FunctualizeApp | None = None
+        self._core: HttpServerCore | None = None
+
+    def __call__(self, app: FunctualizeApp) -> None:
+        """Register the 'serve' command on the app.
+
+        Args:
+            app: The FunctualizeApp kernel instance.
+        """
+        self._app = app
+        self._core = HttpServerCore(app)
+
+        app.register_plugin_command(
+            name="serve",
+            callback=self._serve_command,
+            help_text="Start an HTTP server exposing all jobs as endpoints",
+        )
+
+    def _serve_command(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8000,
+    ) -> None:
+        """Start the HTTP server (CLI command handler).
+
+        Args:
+            host: Host address to bind to.
+            port: Port number to listen on.
+        """
+        if self._core is None:
+            raise RuntimeError("HttpServerPlugin not initialized")
+        asyncio.run(self._core.start(host, port))
+
+
+__all__ = [
+    "HttpAdapter",
+    "HttpServerCore",
+    "HttpServerPlugin",
+    "PluginMetadata",
+]

functualize_http-0.1.0/tests/conftest.py

@@ -0,0 +1,73 @@
+"""Shared fixtures for functualize-http plugin tests."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import pytest
+
+
+@dataclass
+class FakeDescriptor:
+    name: str
+    group: str | None = None
+    docstring: str | None = None
+
+
+@dataclass
+class FakeJobResult:
+    status: str = "success"
+    return_value: Any = None
+    duration_ms: float = 5.0
+
+
+class FakeApp:
+    """Minimal FunctualizeApp fake for HTTP adapter tests."""
+
+    def __init__(
+        self,
+        descriptors: list[FakeDescriptor] | None = None,
+        execute_results: dict[str, FakeJobResult] | None = None,
+        execute_error: Exception | None = None,
+    ):
+        self._descriptors = descriptors or []
+        self._execute_results = execute_results or {}
+        self._execute_error = execute_error
+        self._commands: dict[str, Any] = {}
+
+    def get_jobs(self) -> list[FakeDescriptor]:
+        return self._descriptors
+
+    def get_job(self, name: str) -> FakeDescriptor | None:
+        for d in self._descriptors:
+            if d.name == name:
+                return d
+        return None
+
+    def execute(self, job_name: str, **kwargs: Any) -> FakeJobResult:
+        if self._execute_error:
+            raise self._execute_error
+        if job_name in self._execute_results:
+            return self._execute_results[job_name]
+        return FakeJobResult(return_value=f"executed {job_name}")
+
+    def register_plugin_command(
+        self, name: str, callback: Any, help_text: str = ""
+    ) -> None:
+        self._commands[name] = callback
+
+
+@pytest.fixture
+def fake_app() -> FakeApp:
+    return FakeApp(
+        descriptors=[
+            FakeDescriptor(name="greet", docstring="Greet user"),
+            FakeDescriptor(name="deploy", group="ops", docstring="Deploy"),
+        ]
+    )
+
+
+@pytest.fixture
+def empty_app() -> FakeApp:
+    return FakeApp(descriptors=[])

functualize_http-0.1.0/tests/test_plugin.py

@@ -0,0 +1,144 @@
+"""Unit tests for functualize-http plugin.
+
+Tests the HTTP server core logic: request routing, job execution,
+health endpoints, and error handling. Uses direct method calls on
+HttpServerCore.handle_request() to avoid needing a running server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import pytest
+from functualize_http import HttpAdapter, HttpServerCore, HttpServerPlugin
+
+from .conftest import FakeApp, FakeDescriptor
+
+
+class TestHealthEndpoint:
+    """Tests for GET /health."""
+
+    def test_health_returns_200(self, fake_app):
+        core = HttpServerCore(fake_app)
+        status, body = asyncio.run(core.handle_request("GET", "/health", b""))
+        assert status == 200
+        assert body == {"status": "healthy"}
+
+
+class TestJobListing:
+    """Tests for GET /jobs."""
+
+    def test_lists_all_jobs(self, fake_app):
+        core = HttpServerCore(fake_app)
+        status, body = asyncio.run(core.handle_request("GET", "/jobs", b""))
+        assert status == 200
+        assert len(body["jobs"]) == 2
+        names = [j["name"] for j in body["jobs"]]
+        assert "greet" in names
+        assert "deploy" in names
+
+    def test_empty_app_returns_empty_list(self, empty_app):
+        core = HttpServerCore(empty_app)
+        status, body = asyncio.run(core.handle_request("GET", "/jobs", b""))
+        assert status == 200
+        assert body == {"jobs": []}
+
+
+class TestJobExecution:
+    """Tests for POST /jobs/{name}/execute."""
+
+    def test_execute_job_success(self, fake_app):
+        core = HttpServerCore(fake_app)
+        payload = json.dumps({"name": "World"}).encode()
+        status, body = asyncio.run(
+            core.handle_request("POST", "/jobs/greet/execute", payload)
+        )
+        assert status == 200
+        assert body["return_value"] == "executed greet"
+
+    def test_execute_nonexistent_job_returns_404(self, fake_app):
+        core = HttpServerCore(fake_app)
+        status, body = asyncio.run(
+            core.handle_request("POST", "/jobs/nope/execute", b"")
+        )
+        assert status == 404
+        assert "not found" in body["error"].lower()
+
+    def test_execute_with_invalid_json_returns_400(self, fake_app):
+        core = HttpServerCore(fake_app)
+        status, body = asyncio.run(
+            core.handle_request("POST", "/jobs/greet/execute", b"not json")
+        )
+        assert status == 400
+        assert "Invalid JSON" in body["error"]
+
+    def test_execute_with_non_object_body_returns_400(self, fake_app):
+        core = HttpServerCore(fake_app)
+        payload = json.dumps([1, 2, 3]).encode()
+        status, body = asyncio.run(
+            core.handle_request("POST", "/jobs/greet/execute", payload)
+        )
+        assert status == 400
+        assert "must be a JSON object" in body["error"]
+
+    def test_execute_with_empty_body_succeeds(self, fake_app):
+        core = HttpServerCore(fake_app)
+        status, body = asyncio.run(
+            core.handle_request("POST", "/jobs/greet/execute", b"")
+        )
+        assert status == 200
+
+    def test_execution_error_returns_500(self):
+        app = FakeApp(
+            descriptors=[FakeDescriptor(name="broken", docstring="Broken")],
+            execute_error=RuntimeError("kaboom"),
+        )
+        core = HttpServerCore(app)
+        status, body = asyncio.run(
+            core.handle_request("POST", "/jobs/broken/execute", b"")
+        )
+        assert status == 500
+        assert "kaboom" in body["error"]
+
+
+class TestRouting:
+    """Tests for route matching."""
+
+    def test_unknown_path_returns_404(self, fake_app):
+        core = HttpServerCore(fake_app)
+        status, body = asyncio.run(core.handle_request("GET", "/unknown/path", b""))
+        assert status == 404
+
+    def test_build_routes_maps_jobs(self, fake_app):
+        core = HttpServerCore(fake_app)
+        routes = core.build_routes()
+        assert "/jobs/greet/execute" in routes
+        assert "/jobs/deploy/execute" in routes
+
+
+class TestHttpAdapter:
+    """Tests for HttpAdapter setup and metadata."""
+
+    def test_adapter_type(self):
+        adapter = HttpAdapter()
+        assert adapter.adapter_type == "http"
+
+    def test_run_before_setup_raises(self):
+        adapter = HttpAdapter()
+        with pytest.raises(RuntimeError, match="called before __call__"):
+            adapter.run()
+
+    def test_setup_creates_core(self, fake_app):
+        adapter = HttpAdapter()
+        adapter(fake_app)
+        assert adapter._core is not None
+
+
+class TestHttpServerPlugin:
+    """Tests for HttpServerPlugin command registration."""
+
+    def test_registers_serve_command(self, fake_app):
+        plugin = HttpServerPlugin()
+        plugin(fake_app)
+        assert "serve" in fake_app._commands