conduit-shared 0.0.1__tar.gz

conduit_shared-0.0.1/.gitignore

@@ -0,0 +1,111 @@
+# =============================================================================
+# Python
+# =============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.manifest
+pip-log.txt
+pip-delete-this-directory.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+*.mo
+*.pot
+.venv/
+venv/
+ENV/
+env/
+.pdm.toml
+.pdm-python
+.pdm-build/
+__pypackages__/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+cython_debug/
+.ruff_cache/
+.pypirc
+
+# =============================================================================
+# Node / Next.js
+# =============================================================================
+node_modules/
+.pnp
+.pnp.js
+.next/
+out/
+next-env.d.ts
+.source/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+*.tsbuildinfo
+.vercel
+
+# =============================================================================
+# Database
+# =============================================================================
+*.sqlite
+*.sqlite3
+*.sqlite3-journal
+db.sqlite
+db.sqlite3
+
+# =============================================================================
+# Environment & Secrets
+# =============================================================================
+.env
+.env*.local
+.env.prod
+
+# =============================================================================
+# IDE & OS
+# =============================================================================
+.DS_Store
+*.pem
+.idea/
+*.swp
+*.swo
+*~
+
+# =============================================================================
+# Testing & Coverage
+# =============================================================================
+coverage/
+coverage_html/
+test-results/
+playwright-report/
+blob-report/
+.vitest/
+
+# =============================================================================
+# tanstack start
+# =============================================================================
+.output/
+.tanstack/

conduit_shared-0.0.1/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: conduit-shared
+Version: 0.0.1
+Summary: Shared models for Conduit packages
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.10.0

conduit_shared-0.0.1/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "conduit-shared"
+version = "0.0.1"
+description = "Shared models for Conduit packages"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.10.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shared"]

conduit_shared-0.0.1/src/shared/__init__.py

@@ -0,0 +1,115 @@
+"""Shared models for Conduit packages."""
+
+from shared.api import API_PREFIX, HOURLY_BUCKET_TTL, MINUTE_BUCKET_TTL, REGISTRY_TTL
+from shared.artifacts import ArtifactType
+from shared.events import (
+    BatchEventItem,
+    BatchEventRequest,
+    EventRequest,
+    EventType,
+    HealthResponse,
+    JobCheckpointEvent,
+    JobCompletedEvent,
+    JobFailedEvent,
+    JobProgressEvent,
+    JobRetryingEvent,
+    JobStartedEvent,
+)
+from shared.models import Job, JobStatus, StateTransition
+from shared.patterns import get_matching_patterns, matches_event_pattern
+from shared.schemas import (
+    ApiDetailResponse,
+    ApiEndpoint,
+    ApiInfo,
+    ApiInstance,
+    ApisListResponse,
+    ApiStats,
+    ApiTrendHour,
+    ApiTrendsResponse,
+    ArtifactCreateResponse,
+    ArtifactListResponse,
+    ArtifactQueuedResponse,
+    ArtifactResponse,
+    CreateArtifactRequest,
+    DashboardStats,
+    EndpointsListResponse,
+    ErrorResponse,
+    FunctionDetailResponse,
+    FunctionInfo,
+    FunctionsListResponse,
+    FunctionType,
+    JobHistoryResponse,
+    JobListResponse,
+    JobStatsResponse,
+    JobTrendHour,
+    JobTrendsResponse,
+    Run,
+    RunStats,
+    WorkerInfo,
+    WorkerInstance,
+    WorkersListResponse,
+    WorkerStats,
+)
+
+__all__ = [
+    # API tracking constants
+    "API_PREFIX",
+    "MINUTE_BUCKET_TTL",
+    "HOURLY_BUCKET_TTL",
+    "REGISTRY_TTL",
+    # Core models
+    "Job",
+    "JobStatus",
+    "StateTransition",
+    # Events
+    "EventType",
+    "EventRequest",
+    "BatchEventItem",
+    "BatchEventRequest",
+    "JobStartedEvent",
+    "JobCompletedEvent",
+    "JobFailedEvent",
+    "JobRetryingEvent",
+    "JobProgressEvent",
+    "JobCheckpointEvent",
+    # Artifacts
+    "ArtifactType",
+    "ArtifactCreateResponse",
+    "ArtifactQueuedResponse",
+    "ArtifactResponse",
+    "ArtifactListResponse",
+    "CreateArtifactRequest",
+    "ErrorResponse",
+    # Health
+    "HealthResponse",
+    # Pattern matching
+    "matches_event_pattern",
+    "get_matching_patterns",
+    # API Schemas
+    "ApiInstance",
+    "ApiEndpoint",
+    "ApiInfo",
+    "ApisListResponse",
+    "EndpointsListResponse",
+    "ApiDetailResponse",
+    "ApiTrendHour",
+    "ApiTrendsResponse",
+    "FunctionType",
+    "Run",
+    "WorkerInstance",
+    "WorkerInfo",
+    "WorkersListResponse",
+    "WorkerStats",
+    "FunctionInfo",
+    "FunctionsListResponse",
+    "FunctionDetailResponse",
+    "RunStats",
+    "ApiStats",
+    "DashboardStats",
+    # Job History
+    "JobHistoryResponse",
+    "JobListResponse",
+    "JobStatsResponse",
+    "JobTrendHour",
+    "JobTrendsResponse",
+]

conduit_shared-0.0.1/src/shared/api.py

@@ -0,0 +1,26 @@
+"""API tracking constants shared between SDK middleware and server reader.
+
+Redis key structure:
+    conduit:api:registry                                    -> SET of api names
+    conduit:api:{api}:endpoints                             -> SET of "METHOD:path"
+    conduit:api:{api}:{method}:{path}:m:{YYYY-MM-DDTHH:MM} -> HASH (minute bucket)
+    conduit:api:{api}:{method}:{path}:h:{YYYY-MM-DDTHH}    -> HASH (hourly bucket)
+
+Each hash contains:
+    requests, errors, total_latency_ms, status_2xx, status_4xx, status_5xx
+"""
+
+# Key prefix for all API tracking keys
+API_PREFIX = "conduit:api"
+
+# Key prefix for API instance heartbeats
+API_INSTANCE_PREFIX = "conduit:api_instances"
+
+# TTLs (seconds)
+MINUTE_BUCKET_TTL = 600  # 10 minutes
+HOURLY_BUCKET_TTL = 2_592_000  # 30 days
+REGISTRY_TTL = 2_592_000  # 30 days
+
+# API instance TTL - must heartbeat within this time
+# With 10s heartbeat interval, this gives 3 missed heartbeats before expiry
+API_INSTANCE_TTL = 30

conduit_shared-0.0.1/src/shared/artifacts.py

@@ -0,0 +1,20 @@
+"""Artifact types for job outputs."""
+
+from enum import StrEnum
+
+
+class ArtifactType(StrEnum):
+    """Artifact types for job outputs."""
+
+    TEXT = "text"
+    JSON = "json"
+    PNG = "image/png"
+    JPEG = "image/jpeg"
+    WEBP = "image/webp"
+    GIF = "image/gif"
+    SVG = "image/svg"
+    PDF = "file/pdf"
+    CSV = "file/csv"
+    XML = "file/xml"
+    HTML = "file/html"
+    BINARY = "file/binary"

conduit_shared-0.0.1/src/shared/events.py

@@ -0,0 +1,173 @@
+"""Event schemas for job tracking between workers and API."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+EVENTS_STREAM = "conduit:status:events"
+API_REQUESTS_STREAM = "conduit:api:requests"
+EVENTS_PUBSUB_CHANNEL = "conduit:status:events:pubsub"
+
+
+class EventType(StrEnum):
+    """Event types sent from workers to API."""
+
+    JOB_STARTED = "job.started"
+    JOB_COMPLETED = "job.completed"
+    JOB_FAILED = "job.failed"
+    JOB_RETRYING = "job.retrying"
+    JOB_PROGRESS = "job.progress"
+    JOB_CHECKPOINT = "job.checkpoint"
+
+
+class JobStartedEvent(BaseModel):
+    """Event data for job.started."""
+
+    job_id: str
+    function: str
+    function_name: str
+    parent_id: str | None = None
+    root_id: str
+    kwargs: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    attempt: int = 1
+    max_retries: int = 0
+    worker_id: str | None = None
+    started_at: datetime
+
+
+class JobCompletedEvent(BaseModel):
+    """Event data for job.completed."""
+
+    job_id: str
+    function: str
+    function_name: str
+    parent_id: str | None = None
+    root_id: str
+    result: Any = None
+    duration_ms: float | None = None
+    attempt: int = 1
+    completed_at: datetime
+
+
+class JobFailedEvent(BaseModel):
+    """Event data for job.failed."""
+
+    job_id: str
+    function: str
+    function_name: str
+    parent_id: str | None = None
+    root_id: str
+    error: str
+    traceback: str | None = None
+    attempt: int = 1
+    max_retries: int = 0
+    will_retry: bool = False
+    failed_at: datetime
+
+
+class JobRetryingEvent(BaseModel):
+    """Event data for job.retrying."""
+
+    job_id: str
+    function: str
+    function_name: str
+    parent_id: str | None = None
+    root_id: str
+    error: str
+    delay_seconds: float
+    current_attempt: int
+    next_attempt: int
+    retry_at: datetime
+
+
+class JobProgressEvent(BaseModel):
+    """Event data for job.progress."""
+
+    job_id: str
+    parent_id: str | None = None
+    root_id: str
+    progress: float
+    message: str | None = None
+    updated_at: datetime
+
+
+class JobCheckpointEvent(BaseModel):
+    """Event data for job.checkpoint."""
+
+    job_id: str
+    parent_id: str | None = None
+    root_id: str
+    state: dict[str, Any]
+    checkpointed_at: datetime
+
+
+class SSEJobEvent(BaseModel):
+    """Event payload streamed to browser clients via SSE.
+
+    Only includes fields the dashboard needs — sensitive data like
+    kwargs, result, traceback, and checkpoint state are excluded.
+    Extra fields from the source event are silently dropped.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    type: str
+    job_id: str = ""
+    worker_id: str = ""
+    function: str | None = None
+    function_name: str | None = None
+    parent_id: str | None = None
+    root_id: str
+    # job.started / job.completed / job.failed
+    attempt: int | None = None
+    max_retries: int | None = None
+    started_at: datetime | None = None
+    # job.completed
+    duration_ms: float | None = None
+    completed_at: datetime | None = None
+    # job.failed
+    error: str | None = None
+    failed_at: datetime | None = None
+    # job.retrying
+    current_attempt: int | None = None
+    next_attempt: int | None = None
+    # job.progress
+    progress: float | None = None
+    message: str | None = None
+
+
+class EventRequest(BaseModel):
+    """Generic event request from workers."""
+
+    type: str
+    data: dict[str, Any]
+    worker_id: str | None = None
+
+
+class BatchEventItem(BaseModel):
+    """Single event in a batch."""
+
+    type: str
+    job_id: str
+    worker_id: str
+    timestamp: float
+    data: dict[str, Any] = Field(default_factory=dict)
+
+
+class BatchEventRequest(BaseModel):
+    """Batch of events from workers."""
+
+    events: list[BatchEventItem]
+    worker_id: str | None = None
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+
+    status: str = "ok"
+    version: str
+    tier: str = "free"
+    features: list[str] = Field(default_factory=list)

conduit_shared-0.0.1/src/shared/models.py

@@ -0,0 +1,335 @@
+"""Core data models for Conduit."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+
+@dataclass
+class StateTransition:
+    """
+    Records a state transition for a job.
+
+    Used to build timeline views showing job progression.
+    """
+
+    state: str  # JobStatus value
+    timestamp: datetime
+    message: str | None = None
+    worker_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "state": self.state,
+            "timestamp": self.timestamp.isoformat(),
+            "message": self.message,
+            "worker_id": self.worker_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> StateTransition:
+        """Deserialize from dictionary."""
+        return cls(
+            state=data["state"],
+            timestamp=datetime.fromisoformat(data["timestamp"]),
+            message=data.get("message"),
+            worker_id=data.get("worker_id"),
+        )
+
+
+class JobStatus(str, Enum):
+    """Job execution status."""
+
+    PENDING = "pending"
+    QUEUED = "queued"
+    ACTIVE = "active"
+    COMPLETE = "complete"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    RETRYING = "retrying"
+
+    def is_terminal(self) -> bool:
+        """Check if this is a terminal state."""
+        return self in (JobStatus.COMPLETE, JobStatus.FAILED, JobStatus.CANCELLED)
+
+    def can_transition_to(self, target: JobStatus) -> bool:
+        """Check if transition to target state is valid."""
+        valid_transitions: dict[JobStatus, set[JobStatus]] = {
+            JobStatus.PENDING: {JobStatus.QUEUED, JobStatus.CANCELLED},
+            JobStatus.QUEUED: {JobStatus.ACTIVE, JobStatus.CANCELLED},
+            JobStatus.ACTIVE: {
+                JobStatus.COMPLETE,
+                JobStatus.FAILED,
+                JobStatus.CANCELLED,
+                JobStatus.RETRYING,
+            },
+            JobStatus.RETRYING: {
+                JobStatus.QUEUED,
+                JobStatus.FAILED,
+                JobStatus.CANCELLED,
+            },
+            JobStatus.COMPLETE: set(),
+            JobStatus.FAILED: {JobStatus.QUEUED},  # Allow retry
+            JobStatus.CANCELLED: set(),
+        }
+        return target in valid_transitions.get(self, set())
+
+
+def _generate_job_id() -> str:
+    """Generate a unique job ID."""
+    return f"job_{uuid.uuid4().hex[:16]}"
+
+
+def _utc_now() -> datetime:
+    """Get current UTC time."""
+    return datetime.now(UTC)
+
+
+@dataclass
+class Job:
+    """
+    Represents a job to be executed.
+
+    Jobs are the fundamental unit of work in Conduit.
+    """
+
+    # Identity
+    function: str
+    function_name: str = ""
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=_generate_job_id)
+    key: str = ""  # Deduplication key (defaults to id if not set)
+
+    # Status
+    status: JobStatus = JobStatus.PENDING
+
+    # Timing
+    scheduled_at: datetime = field(default_factory=_utc_now)
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    timeout: float | None = None
+    lease_time: float | None = None
+
+    # Execution
+    # `attempts` is the number of times the job has been started (1-indexed when running).
+    # - 0 = not yet started
+    # - 1 = first attempt (initial execution)
+    # - 2 = second attempt (first retry)
+    # - N = Nth attempt (N-1 retries)
+    # Job can retry when: attempts <= max_retries + 1
+    # See also: can_retry() method
+    attempts: int = 0
+    max_retries: int = (
+        0  # Number of retry attempts (0 = no retries, just the initial attempt)
+    )
+    retry_delay: float = 1.0  # Base delay in seconds between retries
+    retry_backoff: float = 2.0  # Exponential backoff multiplier
+    worker_id: str | None = None
+    parent_id: str | None = None
+    root_id: str = ""
+
+    # Progress tracking
+    progress: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # Result
+    result: Any = None
+    error: str | None = None
+    error_traceback: str | None = None
+
+    # Cron scheduling
+    schedule: str | None = None
+
+    # State history
+    state_history: list[StateTransition] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        """Set defaults after initialization."""
+        if not self.key:
+            self.key = self.id
+        if not self.root_id:
+            self.root_id = self.id
+        if not self.function_name:
+            self.function_name = self.function
+
+    def _record_transition(
+        self,
+        state: JobStatus,
+        message: str | None = None,
+        worker_id: str | None = None,
+    ) -> None:
+        """Record a state transition to history."""
+        self.state_history.append(
+            StateTransition(
+                state=state.value,
+                timestamp=_utc_now(),
+                message=message,
+                worker_id=worker_id,
+            )
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize job to dictionary."""
+        return {
+            "id": self.id,
+            "key": self.key,
+            "function": self.function,
+            "function_name": self.function_name,
+            "kwargs": self.kwargs,
+            "status": self.status.value,
+            "scheduled_at": self.scheduled_at.isoformat(),
+            "started_at": self.started_at.isoformat() if self.started_at else None,
+            "completed_at": self.completed_at.isoformat()
+            if self.completed_at
+            else None,
+            "timeout": self.timeout,
+            "lease_time": self.lease_time,
+            "attempts": self.attempts,
+            "max_retries": self.max_retries,
+            "retry_delay": self.retry_delay,
+            "retry_backoff": self.retry_backoff,
+            "worker_id": self.worker_id,
+            "parent_id": self.parent_id,
+            "root_id": self.root_id,
+            "progress": self.progress,
+            "metadata": self.metadata,
+            "result": self.result,
+            "error": self.error,
+            "error_traceback": self.error_traceback,
+            "schedule": self.schedule,
+            "state_history": [t.to_dict() for t in self.state_history],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Job:
+        """Deserialize job from dictionary."""
+        return cls(
+            id=data["id"],
+            key=data["key"],
+            function=data["function"],
+            function_name=data.get("function_name", data["function"]),
+            kwargs=data.get("kwargs", {}),
+            status=JobStatus(data["status"]),
+            scheduled_at=datetime.fromisoformat(data["scheduled_at"]),
+            started_at=(
+                datetime.fromisoformat(data["started_at"])
+                if data.get("started_at")
+                else None
+            ),
+            completed_at=(
+                datetime.fromisoformat(data["completed_at"])
+                if data.get("completed_at")
+                else None
+            ),
+            timeout=data.get("timeout"),
+            lease_time=data.get("lease_time"),
+            attempts=data.get("attempts", 0),
+            max_retries=data.get("max_retries", 0),
+            retry_delay=data.get("retry_delay", 1.0),
+            retry_backoff=data.get("retry_backoff", 2.0),
+            worker_id=data.get("worker_id"),
+            parent_id=data.get("parent_id"),
+            root_id=data.get("root_id", data["id"]),
+            progress=data.get("progress", 0.0),
+            metadata=data.get("metadata", {}),
+            result=data.get("result"),
+            error=data.get("error"),
+            error_traceback=data.get("error_traceback"),
+            schedule=data.get("schedule"),
+            state_history=[
+                StateTransition.from_dict(t) for t in data.get("state_history", [])
+            ],
+        )
+
+    def to_json(self) -> str:
+        """Serialize job to JSON string."""
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Job:
+        """Deserialize job from JSON string."""
+        return cls.from_dict(json.loads(json_str))
+
+    def calculate_retry_delay(self) -> float:
+        """Calculate delay before next retry using exponential backoff."""
+        return self.retry_delay * (self.retry_backoff ** (self.attempts - 1))
+
+    def can_retry(self) -> bool:
+        """Check if job can be retried."""
+        return self.attempts <= self.max_retries
+
+    @property
+    def duration_ms(self) -> int | None:
+        """Calculate job duration in milliseconds."""
+        if self.started_at and self.completed_at:
+            delta = self.completed_at - self.started_at
+            return int(delta.total_seconds() * 1000)
+        return None
+
+    def mark_queued(self, message: str | None = None) -> None:
+        """Mark job as queued."""
+        self.status = JobStatus.QUEUED
+        self._record_transition(JobStatus.QUEUED, message or "Job enqueued")
+
+    def mark_started(self, worker_id: str) -> None:
+        """Mark job as started."""
+        self.status = JobStatus.ACTIVE
+        self.started_at = _utc_now()
+        self.worker_id = worker_id
+        self.attempts += 1
+        self._record_transition(
+            JobStatus.ACTIVE,
+            f"Started (attempt {self.attempts})",
+            worker_id=worker_id,
+        )
+
+    def mark_complete(self, result: Any = None) -> None:
+        """Mark job as complete."""
+        self.status = JobStatus.COMPLETE
+        self.completed_at = _utc_now()
+        self.result = result
+        self.progress = 1.0
+        self._record_transition(JobStatus.COMPLETE, "Completed successfully")
+
+    def mark_failed(self, error: str, traceback: str | None = None) -> None:
+        """Mark job as failed."""
+        self.status = JobStatus.FAILED
+        self.completed_at = _utc_now()
+        self.error = error
+        self.error_traceback = traceback
+        self._record_transition(JobStatus.FAILED, f"Failed: {error[:100]}")
+
+    def mark_cancelled(self) -> None:
+        """Mark job as cancelled."""
+        self.status = JobStatus.CANCELLED
+        self.completed_at = _utc_now()
+        self._record_transition(JobStatus.CANCELLED, "Cancelled")
+
+    def mark_retrying(self, delay: float) -> None:
+        """Mark job as retrying."""
+        self.status = JobStatus.RETRYING
+        self._record_transition(
+            JobStatus.RETRYING,
+            f"Scheduled for retry in {delay:.1f}s (attempt {self.attempts + 1})",
+        )
+
+    @property
+    def is_cron(self) -> bool:
+        """Check if this is a recurring cron job.
+
+        A job is a cron if it has a schedule AND was marked as cron in metadata.
+        This distinguishes cron jobs from regular delayed jobs.
+        """
+        if self.schedule is None:
+            return False
+        # Check metadata for explicit cron marker (set by seed_cron/reschedule_cron)
+        if self.metadata and self.metadata.get("cron"):
+            return True
+        # Fallback: if schedule is set, treat as cron for backward compatibility
+        return True

conduit_shared-0.0.1/src/shared/patterns.py

@@ -0,0 +1,88 @@
+"""Pattern matching utilities for event names.
+
+This module provides wildcard pattern matching for event routing.
+Both EventRouter and Registry use this shared implementation.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def _segment_regex(pattern: str) -> str:
+    """Compile one dot-delimited segment pattern into a regex fragment."""
+    out: list[str] = []
+    for char in pattern:
+        if char == "*":
+            # Single-segment wildcard: any chars except dot.
+            out.append("[^.]+")
+        else:
+            out.append(re.escape(char))
+    return "".join(out)
+
+
+def matches_event_pattern(event: str, pattern: str) -> bool:
+    """
+    Check if an event name matches a pattern.
+
+    Supports glob-style wildcards:
+    - Exact match: "user.signup" matches "user.signup"
+    - Single wildcard: "user.*" matches "user.signup" but not "user.signup.email"
+    - Multi-wildcard: "user.**" matches "user.signup" and "user.signup.email"
+
+    Args:
+        event: Event name to check (e.g., "user.signup")
+        pattern: Pattern to match against (e.g., "user.*")
+
+    Returns:
+        True if the event matches the pattern
+
+    Examples:
+        >>> matches_event_pattern("user.signup", "user.signup")
+        True
+        >>> matches_event_pattern("user.signup", "user.*")
+        True
+        >>> matches_event_pattern("user.signup.email", "user.*")
+        False
+        >>> matches_event_pattern("user.signup.email", "user.**")
+        True
+        >>> matches_event_pattern("order.item.added", "order.*.added")
+        True
+    """
+    if pattern == "**":
+        return True
+
+    event_parts = event.split(".")
+    pattern_parts = pattern.split(".")
+
+    i = 0
+    j = 0
+    while i < len(pattern_parts) and j < len(event_parts):
+        segment = pattern_parts[i]
+        if segment == "**":
+            # Multi-segment wildcard: consume any remaining segments.
+            return True
+        if not re.fullmatch(_segment_regex(segment), event_parts[j]):
+            return False
+        i += 1
+        j += 1
+
+    if i == len(pattern_parts) and j == len(event_parts):
+        return True
+    if i == len(pattern_parts) - 1 and pattern_parts[i] == "**":
+        return True
+    return False
+
+
+def get_matching_patterns(event: str, patterns: list[str]) -> list[str]:
+    """
+    Find all patterns that match an event name.
+
+    Args:
+        event: Event name to match
+        patterns: List of patterns to check
+
+    Returns:
+        List of matching patterns
+    """
+    return [p for p in patterns if matches_event_pattern(event, p)]

conduit_shared-0.0.1/src/shared/schemas.py

@@ -0,0 +1,366 @@
+"""Shared API schemas for Conduit."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from shared.artifacts import ArtifactType
+
+# =============================================================================
+# Common Types
+# =============================================================================
+
+
+class FunctionType(StrEnum):
+    TASK = "task"
+    CRON = "cron"
+    EVENT = "event"
+
+
+# =============================================================================
+# Job History Schemas
+# =============================================================================
+
+
+class JobHistoryResponse(BaseModel):
+    """Single job history response."""
+
+    id: str
+    function: str
+    function_name: str
+    status: str
+    created_at: datetime | None = None
+    scheduled_at: datetime | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    attempts: int = 1
+    max_retries: int = 0
+    timeout: float | None = None
+    worker_id: str | None = None
+    parent_id: str | None = None
+    root_id: str
+    progress: float = 0.0
+    kwargs: dict[str, Any] = {}
+    metadata: dict[str, Any] = {}
+    result: Any = None
+    error: str | None = None
+    duration_ms: float | None = None
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class JobListResponse(BaseModel):
+    """List of jobs response."""
+
+    jobs: list[JobHistoryResponse]
+    total: int
+    has_more: bool = False
+
+
+class JobStatsResponse(BaseModel):
+    """Job statistics response."""
+
+    total: int
+    success_count: int
+    failure_count: int
+    cancelled_count: int
+    success_rate: float
+    avg_duration_ms: float | None = None
+
+
+class JobTrendHour(BaseModel):
+    """Hourly job counts by status."""
+
+    hour: str  # ISO format: "2024-01-15T14:00:00Z"
+    complete: int = 0
+    failed: int = 0
+    retrying: int = 0
+    active: int = 0
+
+
+class JobTrendsResponse(BaseModel):
+    """Job trends response."""
+
+    hourly: list[JobTrendHour]
+
+
+# =============================================================================
+# Artifact Schemas
+# =============================================================================
+
+
+class ArtifactResponse(BaseModel):
+    """Single artifact response."""
+
+    id: int
+    job_id: str
+    name: str
+    type: str  # text, json, image/png, image/jpeg, file/pdf, etc.
+    size_bytes: int | None = None
+    data: Any = None
+    path: str | None = None
+    created_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class ArtifactListResponse(BaseModel):
+    """List of artifacts response."""
+
+    artifacts: list[ArtifactResponse]
+    total: int
+
+
+class CreateArtifactRequest(BaseModel):
+    """Request to create an artifact."""
+
+    name: str
+    type: ArtifactType
+    data: Any = None
+
+
+class ArtifactQueuedResponse(BaseModel):
+    """Artifact accepted but queued until the job row is available."""
+
+    status: Literal["queued"] = "queued"
+    job_id: str
+    pending_id: int
+
+
+ArtifactCreateResponse = ArtifactResponse | ArtifactQueuedResponse
+
+
+class ErrorResponse(BaseModel):
+    """Standard API error payload."""
+
+    detail: str
+
+
+# =============================================================================
+# Run/Job Schemas
+# =============================================================================
+
+
+class Run(BaseModel):
+    """Run model for job executions."""
+
+    id: str
+    function: str
+    function_name: str
+    status: str
+    started_at: str | None = None
+    completed_at: str | None = None
+    duration_ms: float | None = None
+    error: str | None = None
+    worker_id: str | None = None
+    attempts: int = 1
+    progress: float = 0.0
+
+
+# =============================================================================
+# Worker Schemas
+# =============================================================================
+
+
+class WorkerInstance(BaseModel):
+    """Worker instance model (registered via Redis heartbeat)."""
+
+    id: str
+    worker_name: str
+    started_at: str
+    last_heartbeat: str
+    functions: list[str] = []
+    function_names: dict[str, str] = {}
+    concurrency: int = 1
+    active_jobs: int = 0
+    jobs_processed: int = 0
+    jobs_failed: int = 0
+    hostname: str | None = None
+
+
+class WorkerInfo(BaseModel):
+    """Worker-level aggregate info (grouped by worker name)."""
+
+    name: str
+    active: bool = False
+    instance_count: int = 0
+    instances: list[WorkerInstance] = []
+    functions: list[str] = []
+    function_names: dict[str, str] = {}
+    concurrency: int = 0
+
+
+class WorkersListResponse(BaseModel):
+    """Workers list response."""
+
+    workers: list[WorkerInfo]
+    total: int
+
+
+class WorkerStats(BaseModel):
+    """Worker statistics."""
+
+    total: int
+
+
+# =============================================================================
+# API Instance Schemas
+# =============================================================================
+
+
+class ApiInstance(BaseModel):
+    """API instance model (registered via Redis heartbeat)."""
+
+    id: str
+    api_name: str
+    started_at: str
+    last_heartbeat: str
+    host: str = "0.0.0.0"
+    port: int = 8000
+    endpoints: list[str] = []
+    hostname: str | None = None
+
+
+HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
+
+
+class ApiEndpoint(BaseModel):
+    """API endpoint info."""
+
+    method: HttpMethod
+    path: str
+    requests_24h: int = 0
+    avg_latency_ms: float = 0.0
+    p50_latency_ms: float = 0.0
+    p95_latency_ms: float = 0.0
+    p99_latency_ms: float = 0.0
+    error_rate: float = 0.0
+    last_request_at: str | None = None
+
+
+class ApiInfo(BaseModel):
+    """API-level aggregate info (grouped by API name)."""
+
+    name: str
+    active: bool = False
+    instance_count: int = 0
+    instances: list[ApiInstance] = []
+    endpoint_count: int = 0
+    requests_24h: int = 0
+    avg_latency_ms: float = 0.0
+    error_rate: float = 0.0
+    requests_per_min: float = 0.0
+
+
+class ApisListResponse(BaseModel):
+    """APIs list response."""
+
+    apis: list[ApiInfo]
+    total: int
+
+
+class EndpointsListResponse(BaseModel):
+    """Endpoints list response (per-endpoint detail)."""
+
+    endpoints: list[ApiEndpoint]
+    total: int
+
+
+class ApiDetailResponse(ApiEndpoint):
+    """API endpoint detail response."""
+
+    hourly_stats: list = []
+    recent_errors: list = []
+
+
+class ApiTrendHour(BaseModel):
+    """Hourly API response counts by status category."""
+
+    hour: str
+    success_2xx: int = 0
+    client_4xx: int = 0
+    server_5xx: int = 0
+
+
+class ApiTrendsResponse(BaseModel):
+    """API trends response."""
+
+    hourly: list[ApiTrendHour]
+
+
+# =============================================================================
+# Function Schemas
+# =============================================================================
+
+
+class FunctionInfo(BaseModel):
+    """Function info."""
+
+    key: str
+    name: str
+    type: FunctionType
+    active: bool = False
+    # Task config
+    timeout: int | None = None
+    max_retries: int | None = None
+    retry_delay: int | None = None
+    # Cron config
+    schedule: str | None = None
+    next_run_at: str | None = None
+    # Event config
+    pattern: str | None = None
+    # Workers currently handling this function
+    workers: list[str] = []
+    # Stats
+    runs_24h: int = 0
+    success_rate: float = 100.0
+    avg_duration_ms: float = 0.0
+    p95_duration_ms: float | None = None
+    last_run_at: str | None = None
+    last_run_status: str | None = None
+
+
+class FunctionsListResponse(BaseModel):
+    """Functions list response."""
+
+    functions: list[FunctionInfo]
+    total: int
+
+
+class FunctionDetailResponse(FunctionInfo):
+    """Function detail response."""
+
+    recent_runs: list[Run] = []
+
+
+# =============================================================================
+# Dashboard Schemas
+# =============================================================================
+
+
+class RunStats(BaseModel):
+    """Run statistics."""
+
+    total_24h: int
+    success_rate: float
+    active_count: int
+
+
+class ApiStats(BaseModel):
+    """API statistics."""
+
+    requests_24h: int
+    avg_latency_ms: float
+    error_rate: float
+
+
+class DashboardStats(BaseModel):
+    """Dashboard stats response."""
+
+    runs: RunStats
+    workers: WorkerStats
+    apis: ApiStats
+    recent_runs: list[Run]
+    recent_failures: list[Run]

conduit_shared-0.0.1/src/shared/workers.py

@@ -0,0 +1,19 @@
+"""Worker constants shared between SDK and server."""
+
+# Key prefix for worker instance heartbeats
+WORKER_KEY_PREFIX = "conduit:workers"
+
+# Key prefix for persistent worker definitions (keyed by worker name)
+WORKER_DEF_PREFIX = "conduit:worker_defs"
+
+# Key prefix for function definitions
+FUNCTION_KEY_PREFIX = "conduit:functions"
+
+# Worker instance TTL - must heartbeat within this time
+# With 10s heartbeat interval, this gives 3 missed heartbeats before expiry
+WORKER_TTL = 30
+
+# Worker/function definition TTL - refreshed each time a worker starts
+# Matches API registry TTL so stale entries self-clean after 30 days
+WORKER_DEF_TTL = 2_592_000  # 30 days
+FUNCTION_DEF_TTL = 2_592_000  # 30 days