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