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
