from __future__ import annotations

from enum import Enum
from typing import Any, Dict, List, Optional, Type

__version__: str
"""Package version string (semantic version)."""

DEFAULT_LOG_SOCKET: str
DEFAULT_CONTROL_SOCKET: str
PLUGIN_FILTER_LOG_MESSAGE: int
PLUGIN_FILTER_ACCESS_LOG: int
PLUGIN_FILTER_METRICS: int
PLUGIN_FILTER_ALL: int


class WorkerClass(Enum):
    """Worker execution model."""
    Sync: "WorkerClass"
    Async: "WorkerClass"

    def __init__(self, class_str: str) -> None: ...
    def __str__(self) -> str: ...
    def __repr__(self) -> str: ...


class ProtocolType(Enum):
    """Application protocol interface."""
    Wsgi: "ProtocolType"
    Asgi: "ProtocolType"

    def __init__(self, class_str: str) -> None: ...
    def __str__(self) -> str: ...
    def __repr__(self) -> str: ...


class ServerConfig:
    """Server configuration object (mirrors Rust core config)."""
    host: str
    port: int
    backlog: int
    workers: Optional[int]
    protocol: ProtocolType
    h2c_enabled: bool
    strict_http: bool
    worker_class: WorkerClass
    worker_timeout: int
    worker_mode: bool
    max_requests: Optional[int]
    max_requests_jitter: Optional[int]
    buffer_size: int
    keepalive_timeout: int
    max_connections: int
    sync_handler_threads: int
    sync_conn_queue_capacity: int
    async_worker_threads: int
    async_max_blocking_threads: int
    app_module: str
    app_callable: str
    pythonpath: List[str]
    log_stdout: bool
    log_level: str
    access_log_format: str
    access_log: Optional[str]
    error_log: Optional[str]
    asgi_event_loop: str
    asgi_event_loop_fallback: bool
    asgi_submit_timeout_ms: int
    asgi_scheduler: str
    asgi_max_inflight: int
    asgi_send_pool_size: int
    plugin_socket: Optional[str]
    plugin_auth_token: Optional[str]
    plugin_drop_policy: str
    plugin_max_lagged_events: int
    plugin_write_timeout_ms: int
    plugin_bus_capacity: int
    plugin_max_clients: int
    plugin_subscribe_timeout_ms: int
    plugin_auth_fail_window_secs: int
    plugin_auth_fail_max_attempts: int
    plugin_acl_mode: str
    plugin_socket_mode: int
    metrics_interval_ms: int
    metrics_workers_enabled: bool
    metrics_os_enabled: bool
    metrics_percentiles_enabled: bool
    metrics_top_errors_limit: int
    control_socket: Optional[str]
    control_auth_token: Optional[str]
    control_acl_mode: str
    control_socket_mode: int
    config_path: Optional[str]
    ssl_enabled: bool
    ssl_certfile: Optional[str]
    ssl_keyfile: Optional[str]

    def __init__(
        self,
        app_module: str,
        app_callable: str,
        host: Optional[str] = ...,
        port: Optional[int] = ...,
        backlog: Optional[int] = ...,
        workers: Optional[int] = ...,
        protocol: ProtocolType = ...,
        h2c_enabled: Optional[bool] = ...,
        strict_http: Optional[bool] = ...,
        worker_class: WorkerClass = ...,
        worker_timeout: Optional[int] = ...,
        worker_mode: Optional[bool] = ...,
        max_requests: Optional[int] = ...,
        max_requests_jitter: Optional[int] = ...,
        max_connections: Optional[int] = ...,
        buffer_size: Optional[int] = ...,
        keepalive_timeout: Optional[int] = ...,
        sync_handler_threads: Optional[int] = ...,
        sync_conn_queue_capacity: Optional[int] = ...,
        async_worker_threads: Optional[int] = ...,
        async_max_blocking_threads: Optional[int] = ...,
        pythonpath: Optional[List[str]] = ...,
        asgi_event_loop: Optional[str] = ...,
        asgi_event_loop_fallback: Optional[bool] = ...,
        asgi_submit_timeout_ms: Optional[int] = ...,
        asgi_scheduler: Optional[str] = ...,
        asgi_max_inflight: Optional[int] = ...,
        asgi_send_pool_size: Optional[int] = ...,
        log_stdout: Optional[bool] = ...,
        log_level: Optional[str] = ...,
        access_log_format: Optional[str] = ...,
        access_log: Optional[str] = ...,
        error_log: Optional[str] = ...,
        plugin_socket: Optional[str] = ...,
        plugin_auth_token: Optional[str] = ...,
        plugin_drop_policy: Optional[str] = ...,
        plugin_max_lagged_events: Optional[int] = ...,
        plugin_write_timeout_ms: Optional[int] = ...,
        plugin_bus_capacity: Optional[int] = ...,
        plugin_max_clients: Optional[int] = ...,
        plugin_subscribe_timeout_ms: Optional[int] = ...,
        plugin_auth_fail_window_secs: Optional[int] = ...,
        plugin_auth_fail_max_attempts: Optional[int] = ...,
        plugin_acl_mode: Optional[str] = ...,
        plugin_socket_mode: Optional[int] = ...,
        metrics_interval_ms: Optional[int] = ...,
        metrics_workers_enabled: Optional[bool] = ...,
        metrics_os_enabled: Optional[bool] = ...,
        metrics_percentiles_enabled: Optional[bool] = ...,
        metrics_top_errors_limit: Optional[int] = ...,
        control_socket: Optional[str] = ...,
        control_auth_token: Optional[str] = ...,
        control_acl_mode: Optional[str] = ...,
        control_socket_mode: Optional[int] = ...,
        ssl_enabled: Optional[bool] = ...,
        ssl_certfile: Optional[str] = ...,
        ssl_keyfile: Optional[str] = ...,
    ) -> None: ...

    @staticmethod
    def from_toml(path: str) -> "ServerConfig": ...
    """Load configuration from a TOML file."""

    def to_toml(self, path: str) -> None: ...
    """Write configuration to a TOML file."""

    def validate(self) -> None: ...
    """Validate configuration values."""

    def get_worker_count(self) -> int: ...
    """Return effective worker count (auto-detects CPU if unset)."""

    def __repr__(self) -> str: ...


class FalcornServer:
    """High-performance WSGI/ASGI server wrapper."""
    def __init__(
        self,
        app_module: str,
        app_callable: str,
        host: Optional[str] = ...,
        port: Optional[int] = ...,
        backlog: Optional[int] = ...,
        workers: Optional[int] = ...,
        protocol: ProtocolType = ...,
        h2c_enabled: Optional[bool] = ...,
        strict_http: Optional[bool] = ...,
        worker_class: WorkerClass = ...,
        worker_timeout: Optional[int] = ...,
        worker_mode: Optional[bool] = ...,
        max_requests: Optional[int] = ...,
        max_requests_jitter: Optional[int] = ...,
        max_connections: Optional[int] = ...,
        buffer_size: Optional[int] = ...,
        keepalive_timeout: Optional[int] = ...,
        sync_handler_threads: Optional[int] = ...,
        sync_conn_queue_capacity: Optional[int] = ...,
        async_worker_threads: Optional[int] = ...,
        async_max_blocking_threads: Optional[int] = ...,
        pythonpath: Optional[List[str]] = ...,
        asgi_event_loop: Optional[str] = ...,
        asgi_event_loop_fallback: Optional[bool] = ...,
        asgi_submit_timeout_ms: Optional[int] = ...,
        asgi_scheduler: Optional[str] = ...,
        asgi_max_inflight: Optional[int] = ...,
        asgi_send_pool_size: Optional[int] = ...,
        log_stdout: Optional[bool] = ...,
        log_level: Optional[str] = ...,
        access_log_format: Optional[str] = ...,
        access_log: Optional[str] = ...,
        error_log: Optional[str] = ...,
        plugin_socket: Optional[str] = ...,
        plugin_auth_token: Optional[str] = ...,
        plugin_drop_policy: Optional[str] = ...,
        plugin_max_lagged_events: Optional[int] = ...,
        plugin_write_timeout_ms: Optional[int] = ...,
        plugin_bus_capacity: Optional[int] = ...,
        plugin_max_clients: Optional[int] = ...,
        plugin_subscribe_timeout_ms: Optional[int] = ...,
        plugin_auth_fail_window_secs: Optional[int] = ...,
        plugin_auth_fail_max_attempts: Optional[int] = ...,
        plugin_acl_mode: Optional[str] = ...,
        plugin_socket_mode: Optional[int] = ...,
        metrics_interval_ms: Optional[int] = ...,
        metrics_workers_enabled: Optional[bool] = ...,
        metrics_os_enabled: Optional[bool] = ...,
        metrics_percentiles_enabled: Optional[bool] = ...,
        metrics_top_errors_limit: Optional[int] = ...,
        control_socket: Optional[str] = ...,
        control_auth_token: Optional[str] = ...,
        control_acl_mode: Optional[str] = ...,
        control_socket_mode: Optional[int] = ...,
        ssl_enabled: Optional[bool] = ...,
        ssl_certfile: Optional[str] = ...,
        ssl_keyfile: Optional[str] = ...,
    ) -> None: ...

    @staticmethod
    def from_config(config: ServerConfig) -> "FalcornServer": ...
    """Create a server from an existing ServerConfig."""

    def run(self) -> None: ...
    """Run the server (blocking)."""

    def start(self) -> None: ...
    """Start the server in background (non-blocking)."""

    def stop(self) -> None: ...
    """Stop the server if running."""

    def set_worker_class(self, class_str: str) -> None: ...
    """Set worker class by name ('sync' or 'async')."""

    def set_timeout(self, seconds: int) -> None: ...
    """Set worker timeout in seconds."""

    def set_keepalive(self, seconds: int) -> None: ...
    """Set keepalive timeout in seconds."""

    def set_log_level(self, level: str) -> None: ...
    """Set log level ('TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR')."""

    def add_pythonpath(self, path: str) -> None: ...
    """Append a path to the Python search path."""

    def get_config(self) -> ServerConfig: ...
    """Return a copy of the current configuration."""

    def status(self) -> str: ...
    """Return a human-readable server status."""
    def __repr__(self) -> str: ...
    def __enter__(self) -> "FalcornServer": ...
    def __exit__(self, exc_type, exc_value, traceback) -> bool: ...


class LoggingClient:
    """Logging & metrics plugin client (IPC)."""

    def __init__(
        self,
        socket: Optional[str] = ...,
        auth_token: Optional[str] = ...,
        client_name: Optional[str] = ...,
        filter_mask: Optional[int] = ...,
        read_timeout_ms: Optional[int] = ...,
        write_timeout_ms: Optional[int] = ...,
    ) -> None: ...

    def next_event(self) -> Dict[str, Any]: ...


class ControlClient:
    """Control plugin client (IPC)."""

    def __init__(
        self,
        socket: Optional[str] = ...,
        auth_token: Optional[str] = ...,
        client_name: Optional[str] = ...,
        read_timeout_ms: Optional[int] = ...,
        write_timeout_ms: Optional[int] = ...,
    ) -> None: ...

    def get_status(self) -> Dict[str, Any]: ...
    def get_workers(self) -> List[Dict[str, Any]]: ...
    def show_config(self) -> str: ...
    def scale_to(self, workers: int) -> str: ...
    def restart_worker(self, id: Optional[int] = ..., graceful: Optional[bool] = ...) -> str: ...
    def shutdown(self, graceful: Optional[bool] = ...) -> str: ...
    def reload_config(self, path: Optional[str] = ..., rolling: Optional[bool] = ...) -> str: ...


PyServerConfig: Type[ServerConfig]
"""Compatibility alias for ServerConfig."""

__all__: list[str]
