falcon-interface 0.1.0__tar.gz

falcon_interface-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: falcon-interface
+Version: 0.1.0
+Summary: Stable external contracts and protocol definitions for Falcon.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: grpcio>=1.78.0
+
+# falcon-interface
+
+`falcon-interface` is the stable external contract package for Falcon.
+
+It is intended to hold only versioned, backward-compatible protocol definitions and
+cross-boundary data contracts shared by:
+
+- `falcon-master`
+- `falcon-worker`
+- future Falcon SDKs
+- third-party workers and adapters
+
+This package should not depend on internal ORM models, service-layer logic, or
+platform-only implementation details.
+
+## Stability policy
+
+`falcon-interface` is divided into two categories:
+
+- Stable core: fields and contracts that are expected to remain backward compatible
+  across master, worker, SDK, and third-party adapters.
+- Experimental surface: fields kept for current implementation compatibility but not
+  yet considered frozen.
+
+### Stable first candidates
+
+- Worker core identity and capacity:
+  - `worker_id`
+  - `host`
+  - `port`
+  - `address`
+  - `status`
+  - `capacity`
+  - `running_tasks`
+- Protocol and worker status enums
+- Minimal command acknowledgement fields
+- Common metrics envelope fields
+
+### Protocol typing rule
+
+`ProtocolType` is intentionally kept coarse and stable:
+
+- `http`
+- `rpc`
+- `stream`
+- `message`
+- `database`
+- `transport`
+- `custom`
+
+Concrete protocol or engine names should be expressed through explicit fields such as:
+
+- `protocol_name`
+- `engine_name`
+- `adapter_name`
+
+This avoids expanding the stable enum every time a new protocol, adapter, or engine is added.
+
+### Naming examples
+
+- HTTP builtin worker
+  - `protocol = "http"`
+  - `protocol_name = "http"`
+  - `engine_name = "builtin"`
+
+- gRPC builtin worker
+  - `protocol = "rpc"`
+  - `protocol_name = "grpc"`
+  - `engine_name = "builtin"`
+
+- MQTT adapter
+  - `protocol = "message"`
+  - `protocol_name = "mqtt"`
+  - `engine_name = "builtin"`
+  - `adapter_name = "falcon-adapter-mqtt"`
+
+- Locust-based HTTP worker
+  - `protocol = "http"`
+  - `protocol_name = "http"`
+  - `engine_name = "locust"`
+  - `adapter_name = "falcon-adapter-locust"`
+
+- MySQL pressure worker
+  - `protocol = "database"`
+  - `protocol_name = "mysql"`
+  - `engine_name = "builtin"`
+
+### Experimental fields
+
+- Worker capability details
+- Worker runtime snapshot structure
+- Task execution plan structure
+- Protocol-specific metric extension payloads
+- Event summary payload shape
+
+## Package boundary
+
+`falcon-interface` should be the only shared dependency between:
+
+- `falcon-master`
+- `falcon-worker`
+- future Falcon SDK packages
+- third-party workers and protocol adapters
+
+It should not depend on, or expose, any of the following:
+
+- ORM models
+- database identifiers and audit fields
+- service-layer exceptions
+- platform-specific scheduler internals
+- UI/report DTOs
+
+## Public surface
+
+Preferred public imports:
+
+- `falcon_interface.enums`
+- `falcon_interface.contracts`
+- `falcon_interface.grpc.generated`
+
+Compatibility-only modules kept during migration:
+
+- `falcon_interface.runtime_enums`
+- `falcon_interface.task_contracts`
+
+These compatibility modules exist to let the current built-in master/worker run
+without forcing a one-shot refactor. They should not be treated as the long-term
+SDK surface for external integrators.
+
+## Proto source of truth
+
+- `proto/worker_runtime.proto` is the source of truth for the current runtime gRPC contract
+- `falcon_interface/grpc/generated/` contains generated Python bindings
+- Generated files should be replaced from proto, not edited by hand during normal evolution
+
+## Current freezing strategy
+
+Freeze first:
+
+- `WorkerInfo` stable identity and capacity fields
+- `WorkerStatus`
+- `ProtocolType`
+- minimal command acknowledgement shape
+- metrics common envelope core
+
+Keep experimental for now:
+
+- task execution plan details
+- protocol-specific metrics extensions
+- event summary payload structure
+- capability and runtime snapshot detail payloads
+
+### Design rules
+
+- Only add fields, never rename or remove stable fields in-place
+- Do not leak ORM, database, or service-layer implementation concepts
+- Keep protocol-neutral contracts in the stable core
+- Move protocol-specific or engine-specific details into explicit extension blocks

falcon_interface-0.1.0/README.md

@@ -0,0 +1,158 @@
+# falcon-interface
+
+`falcon-interface` is the stable external contract package for Falcon.
+
+It is intended to hold only versioned, backward-compatible protocol definitions and
+cross-boundary data contracts shared by:
+
+- `falcon-master`
+- `falcon-worker`
+- future Falcon SDKs
+- third-party workers and adapters
+
+This package should not depend on internal ORM models, service-layer logic, or
+platform-only implementation details.
+
+## Stability policy
+
+`falcon-interface` is divided into two categories:
+
+- Stable core: fields and contracts that are expected to remain backward compatible
+  across master, worker, SDK, and third-party adapters.
+- Experimental surface: fields kept for current implementation compatibility but not
+  yet considered frozen.
+
+### Stable first candidates
+
+- Worker core identity and capacity:
+  - `worker_id`
+  - `host`
+  - `port`
+  - `address`
+  - `status`
+  - `capacity`
+  - `running_tasks`
+- Protocol and worker status enums
+- Minimal command acknowledgement fields
+- Common metrics envelope fields
+
+### Protocol typing rule
+
+`ProtocolType` is intentionally kept coarse and stable:
+
+- `http`
+- `rpc`
+- `stream`
+- `message`
+- `database`
+- `transport`
+- `custom`
+
+Concrete protocol or engine names should be expressed through explicit fields such as:
+
+- `protocol_name`
+- `engine_name`
+- `adapter_name`
+
+This avoids expanding the stable enum every time a new protocol, adapter, or engine is added.
+
+### Naming examples
+
+- HTTP builtin worker
+  - `protocol = "http"`
+  - `protocol_name = "http"`
+  - `engine_name = "builtin"`
+
+- gRPC builtin worker
+  - `protocol = "rpc"`
+  - `protocol_name = "grpc"`
+  - `engine_name = "builtin"`
+
+- MQTT adapter
+  - `protocol = "message"`
+  - `protocol_name = "mqtt"`
+  - `engine_name = "builtin"`
+  - `adapter_name = "falcon-adapter-mqtt"`
+
+- Locust-based HTTP worker
+  - `protocol = "http"`
+  - `protocol_name = "http"`
+  - `engine_name = "locust"`
+  - `adapter_name = "falcon-adapter-locust"`
+
+- MySQL pressure worker
+  - `protocol = "database"`
+  - `protocol_name = "mysql"`
+  - `engine_name = "builtin"`
+
+### Experimental fields
+
+- Worker capability details
+- Worker runtime snapshot structure
+- Task execution plan structure
+- Protocol-specific metric extension payloads
+- Event summary payload shape
+
+## Package boundary
+
+`falcon-interface` should be the only shared dependency between:
+
+- `falcon-master`
+- `falcon-worker`
+- future Falcon SDK packages
+- third-party workers and protocol adapters
+
+It should not depend on, or expose, any of the following:
+
+- ORM models
+- database identifiers and audit fields
+- service-layer exceptions
+- platform-specific scheduler internals
+- UI/report DTOs
+
+## Public surface
+
+Preferred public imports:
+
+- `falcon_interface.enums`
+- `falcon_interface.contracts`
+- `falcon_interface.grpc.generated`
+
+Compatibility-only modules kept during migration:
+
+- `falcon_interface.runtime_enums`
+- `falcon_interface.task_contracts`
+
+These compatibility modules exist to let the current built-in master/worker run
+without forcing a one-shot refactor. They should not be treated as the long-term
+SDK surface for external integrators.
+
+## Proto source of truth
+
+- `proto/worker_runtime.proto` is the source of truth for the current runtime gRPC contract
+- `falcon_interface/grpc/generated/` contains generated Python bindings
+- Generated files should be replaced from proto, not edited by hand during normal evolution
+
+## Current freezing strategy
+
+Freeze first:
+
+- `WorkerInfo` stable identity and capacity fields
+- `WorkerStatus`
+- `ProtocolType`
+- minimal command acknowledgement shape
+- metrics common envelope core
+
+Keep experimental for now:
+
+- task execution plan details
+- protocol-specific metrics extensions
+- event summary payload structure
+- capability and runtime snapshot detail payloads
+
+### Design rules
+
+- Only add fields, never rename or remove stable fields in-place
+- Do not leak ORM, database, or service-layer implementation concepts
+- Keep protocol-neutral contracts in the stable core
+- Move protocol-specific or engine-specific details into explicit extension blocks

falcon_interface-0.1.0/falcon_interface/__init__.py

@@ -0,0 +1,43 @@
+from falcon_interface.contracts import (
+    CommandAck,
+    CommonMetrics,
+    ExecutionPlanItem,
+    HeartbeatWorkerCommand,
+    MetricEnvelope,
+    ProtocolMetricsExtension,
+    RegisterWorkerCommand,
+    ReportTaskEventCommand,
+    StartTaskCommand,
+    StopTaskCommand,
+    TaskContext,
+    TaskDefinition,
+    WorkerCapability,
+    WorkerInfo,
+    WorkerRuntimeSnapshot,
+)
+from falcon_interface.enums import CommandType, ProtocolType, TaskLifecycleStatus, WorkerStatus
+from falcon_interface.version import INTERFACE_VERSION, PROTO_VERSION
+
+__all__ = [
+    "CommandAck",
+    "CommandType",
+    "CommonMetrics",
+    "ExecutionPlanItem",
+    "HeartbeatWorkerCommand",
+    "INTERFACE_VERSION",
+    "MetricEnvelope",
+    "ProtocolMetricsExtension",
+    "PROTO_VERSION",
+    "ProtocolType",
+    "RegisterWorkerCommand",
+    "ReportTaskEventCommand",
+    "StartTaskCommand",
+    "StopTaskCommand",
+    "TaskContext",
+    "TaskDefinition",
+    "TaskLifecycleStatus",
+    "WorkerCapability",
+    "WorkerInfo",
+    "WorkerRuntimeSnapshot",
+    "WorkerStatus",
+]

falcon_interface-0.1.0/falcon_interface/contracts/__init__.py

@@ -0,0 +1,29 @@
+from falcon_interface.contracts.command import (
+    CommandAck,
+    RegisterWorkerCommand,
+    HeartbeatWorkerCommand,
+    ReportTaskEventCommand,
+    StartTaskCommand,
+    StopTaskCommand,
+)
+from falcon_interface.contracts.metrics import CommonMetrics, MetricEnvelope, ProtocolMetricsExtension
+from falcon_interface.contracts.task import ExecutionPlanItem, TaskContext, TaskDefinition
+from falcon_interface.contracts.worker import WorkerCapability, WorkerInfo, WorkerRuntimeSnapshot
+
+__all__ = [
+    "CommandAck",
+    "CommonMetrics",
+    "ExecutionPlanItem",
+    "HeartbeatWorkerCommand",
+    "MetricEnvelope",
+    "ProtocolMetricsExtension",
+    "RegisterWorkerCommand",
+    "ReportTaskEventCommand",
+    "StartTaskCommand",
+    "StopTaskCommand",
+    "TaskContext",
+    "TaskDefinition",
+    "WorkerCapability",
+    "WorkerInfo",
+    "WorkerRuntimeSnapshot",
+]

falcon_interface-0.1.0/falcon_interface/contracts/command.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from falcon_interface.contracts.metrics import MetricEnvelope
+from falcon_interface.contracts.task import TaskDefinition
+from falcon_interface.contracts.worker import WorkerInfo
+from falcon_interface.enums import CommandType
+from falcon_interface.version import INTERFACE_VERSION
+
+
+class CommandAck(BaseModel):
+    """Stable minimal acknowledgement contract."""
+
+    version: str = INTERFACE_VERSION
+    accepted: bool
+    message: str = ""
+    worker_id: str = ""
+    worker_task_id: str = ""
+
+
+class RegisterWorkerCommand(BaseModel):
+    """Register command.
+
+    The command frame is stable. Nested worker capability details are still evolving.
+    """
+
+    version: str = INTERFACE_VERSION
+    command: CommandType = CommandType.REGISTER
+    token: str
+    worker: WorkerInfo
+
+
+class HeartbeatWorkerCommand(BaseModel):
+    """Heartbeat command with an experimental snapshot payload."""
+
+    version: str = INTERFACE_VERSION
+    command: CommandType = CommandType.HEARTBEAT
+    token: str
+    worker_id: str
+    running_tasks: int = 0
+    capacity: int = 1
+    tags: list[str] = Field(default_factory=list)
+    version_name: str | None = None
+    last_seen_error: str | None = None
+    snapshot: dict = Field(default_factory=dict)
+
+
+class StartTaskCommand(BaseModel):
+    """Stable start-task command frame around an evolving task contract."""
+
+    version: str = INTERFACE_VERSION
+    command: CommandType = CommandType.START_TASK
+    worker_task_id: str
+    task: TaskDefinition
+
+
+class StopTaskCommand(BaseModel):
+    """Stable stop-task command frame."""
+
+    version: str = INTERFACE_VERSION
+    command: CommandType = CommandType.STOP_TASK
+    task_id: int
+    task_run_id: int
+    worker_task_id: str
+
+
+class ReportTaskEventCommand(BaseModel):
+    """Task event command.
+
+    Stable core:
+    - worker_id
+    - worker_task_id
+    - task_id
+    - task_run_id
+    - event_type
+    - status
+
+    Experimental surface:
+    - metrics
+    - summary
+    """
+
+    version: str = INTERFACE_VERSION
+    command: CommandType = CommandType.REPORT_EVENT
+    worker_id: str
+    worker_task_id: str
+    task_id: int
+    task_run_id: int
+    event_type: str
+    status: str
+    metrics: MetricEnvelope | None = None
+    summary: dict = Field(default_factory=dict)

falcon_interface-0.1.0/falcon_interface/contracts/metrics.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from falcon_interface.enums import ProtocolType
+from falcon_interface.version import INTERFACE_VERSION
+
+
+class CommonMetrics(BaseModel):
+    """Stable protocol-neutral metrics core."""
+
+    timestamp: datetime | None = None
+    concurrency: int = 0
+    total_ops: int = 0
+    success_ops: int = 0
+    failed_ops: int = 0
+    ops_per_sec: float = 0.0
+    avg_latency_ms: float = 0.0
+    p95_latency_ms: float = 0.0
+    p99_latency_ms: float = 0.0
+    error_rate: float = 0.0
+    last_error: str | None = None
+
+
+class ProtocolMetricsExtension(BaseModel):
+    """Experimental protocol-specific metrics payload."""
+
+    values: dict[str, Any] = Field(default_factory=dict)
+
+
+class MetricEnvelope(BaseModel):
+    """Metrics contract.
+
+    Stable core:
+    - protocol
+    - task_id
+    - task_run_id
+    - worker_id
+    - target
+    - common
+
+    Experimental surface:
+    - extensions
+    """
+
+    version: str = INTERFACE_VERSION
+    protocol: ProtocolType
+    task_id: int
+    task_run_id: int
+    worker_id: str
+    target: str | None = None
+    common: CommonMetrics = Field(default_factory=CommonMetrics)
+    extensions: dict[str, ProtocolMetricsExtension] = Field(default_factory=dict)

falcon_interface-0.1.0/falcon_interface/contracts/task.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from falcon_interface.enums import ProtocolType
+from falcon_interface.version import INTERFACE_VERSION
+
+
+class TaskContext(BaseModel):
+    """Experimental task context envelope.
+
+    Field meanings:
+    - protocol: stable coarse-grained category
+    - protocol_name: concrete protocol name, such as http, grpc, mqtt, mysql
+    - engine_name: concrete execution engine, such as builtin, locust, jmeter, k6
+    - adapter_name: optional adapter/plugin identity chosen for execution
+    """
+
+    version: str = INTERFACE_VERSION
+    protocol: ProtocolType = ProtocolType.HTTP
+    protocol_name: str = "http"
+    engine_name: str | None = None
+    adapter_name: str | None = None
+    project_id: int | None = None
+    project_name: str | None = None
+    owner_id: int | None = None
+    owner_name: str | None = None
+    labels: dict[str, str] = Field(default_factory=dict)
+
+
+class ExecutionPlanItem(BaseModel):
+    """Experimental execution item.
+
+    The stable interface should eventually move protocol-specific execution details
+    into well-defined extension objects rather than an open config dict.
+    """
+
+    name: str
+    weight: int = 0
+    target_users: int | None = None
+    config: dict[str, Any] = Field(default_factory=dict)
+
+
+class TaskDefinition(BaseModel):
+    """Task contract with a stable core and an experimental execution surface.
+
+    Stable core fields:
+    - task_id
+    - task_run_id
+    - task_name
+    - users
+    - spawn_rate
+    - duration
+
+    Experimental fields:
+    - host
+    - execution_strategy
+    - completion_policy
+    - context
+    - execution_plan
+    - control_plane_addr
+    """
+
+    version: str = INTERFACE_VERSION
+    task_id: int
+    task_run_id: int
+    task_name: str
+    host: str
+    users: int
+    spawn_rate: int
+    duration: int
+    execution_strategy: str
+    completion_policy: str = "graceful"
+    context: TaskContext = Field(default_factory=TaskContext)
+    execution_plan: list[ExecutionPlanItem] = Field(default_factory=list)
+    control_plane_addr: str | None = None

falcon_interface-0.1.0/falcon_interface/contracts/worker.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from falcon_interface.enums import ProtocolType, WorkerStatus
+from falcon_interface.version import INTERFACE_VERSION
+
+
+class WorkerCapability(BaseModel):
+    """Experimental worker capability descriptor.
+
+    Field meanings:
+    - protocol: stable coarse-grained category
+    - protocol_name: concrete protocol name, such as grpc, mqtt, mysql, kafka
+    - engine_name: concrete execution engine, such as builtin, locust, jmeter, k6
+    - adapter_name: optional adapter/plugin identity
+    """
+
+    protocol: ProtocolType
+    protocol_name: str
+    engine_name: str
+    adapter_name: str | None = None
+    language: str | None = None
+    tags: list[str] = Field(default_factory=list)
+
+
+class WorkerRuntimeSnapshot(BaseModel):
+    """Experimental runtime snapshot payload. Shape may evolve by protocol and engine."""
+
+    sampled_at: datetime | None = None
+    system: dict[str, Any] = Field(default_factory=dict)
+    resources: dict[str, Any] = Field(default_factory=dict)
+    process: dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkerInfo(BaseModel):
+    """Stable core worker contract.
+
+    Stable core fields:
+    - worker_id
+    - host
+    - port
+    - address
+    - status
+    - capacity
+    - running_tasks
+
+    Experimental fields:
+    - capabilities
+    - snapshot
+    """
+
+    version: str = INTERFACE_VERSION
+    worker_id: str
+    host: str
+    port: int
+    address: str
+    status: WorkerStatus = WorkerStatus.ONLINE
+    capacity: int = 1
+    running_tasks: int = 0
+    capabilities: list[WorkerCapability] = Field(default_factory=list)
+    snapshot: WorkerRuntimeSnapshot | None = None