"""
Metadata model for a registered Station handler.

Each ``FlowRootMetaData`` instance captures everything the ``Station``
needs to invoke a handler: the source it listens on, whether it is async,
the expected parameter type, and a reference to the callable itself.
"""

from collections.abc import Awaitable, Callable
from typing import Any

from pydantic import BaseModel

from .bus_types import BusType


class FlowRootMetaData(BaseModel):
    """Pydantic model describing a single registered handler."""

    source: str | BusType
    """The line name (str) or ``BusType`` this handler is bound to."""

    is_async: bool
    """Whether the handler is an ``async`` coroutine."""

    parameter_type: type | type[Any] | Any
    """The expected message type (used for deserialization and routing)."""

    function: Callable[[Any, ...], Awaitable[Any] | Any]
    """Reference to the handler callable."""

    event_type: str | None = None
    """Optional explicit event type key for CloudEvents-style routing."""
