"""InstrumentationConfig and InitResult types for the OTel instrumentation pipeline.

InstrumentationConfig holds configuration for the tracing pipeline (exporter
endpoint, protocol, batch settings, retry settings).  All fields are optional
with sensible defaults; when omitted the SDK falls back to standard OTel
environment variables.

InitResult is the return type of ``OTelInitializer.initialize()``, bundling
the configured logging handler, an optional tracer, and a shutdown callable.

Requirements: 2.1, 2.5, 11.1
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Callable, Dict, Optional, TYPE_CHECKING

if TYPE_CHECKING:
    from .handler import OTelLoggingHandler


@dataclass
class InstrumentationConfig:
    """Configuration for the tracing / instrumentation pipeline.

    Attributes:
        endpoint:           OTLP span exporter endpoint.  Falls back to
                            ``OTEL_EXPORTER_OTLP_ENDPOINT`` env var when ``None``.
        protocol:           Transport protocol (``"grpc"`` or ``"http"``).  Falls
                            back to ``OTEL_EXPORTER_OTLP_PROTOCOL``, then ``"grpc"``.
        headers:            Auth / metadata headers.  Falls back to
                            ``OTEL_EXPORTER_OTLP_HEADERS`` env var when ``None``.
        tls_cert_path:      Path to a TLS certificate file.  Falls back to
                            ``OTEL_EXPORTER_OTLP_CERTIFICATE`` env var when ``None``.
        batch_size:         Maximum number of spans per batch (default 512).
        flush_interval_ms:  Flush interval in milliseconds (default 5000).
        max_retries:        Maximum retry attempts on transient failure (default 3).
        retry_backoff_ms:   Base backoff in milliseconds for exponential retry
                            (default 1000).
        shutdown_timeout_ms: Timeout in milliseconds for graceful shutdown flush
                            (default 5000).
    """

    endpoint: Optional[str] = None
    protocol: Optional[str] = None
    headers: Optional[Dict[str, str]] = None
    tls_cert_path: Optional[str] = None
    batch_size: int = 512
    flush_interval_ms: int = 5000
    max_retries: int = 3
    retry_backoff_ms: int = 1000
    shutdown_timeout_ms: int = 5000


@dataclass
class InitResult:
    """Result returned by ``OTelInitializer.initialize()``.

    Attributes:
        handler:  The configured :class:`OTelLoggingHandler`.
        tracer:   An OTel ``Tracer`` instance, or ``None`` when tracing is
                  disabled (no endpoint configured).
        shutdown: A callable that flushes and shuts down both the span and
                  log export pipelines.  Safe to call multiple times.
    """

    handler: "OTelLoggingHandler"
    tracer: Optional[Any] = None
    shutdown: Callable[[], None] = field(default=lambda: None)
