class EsiLink:
    """Execute ESI request groups with schema validation and runtime services.

    This class must be used as an async context manager so request and auth
    backends are initialized and cleaned up correctly.
    """

    def __init__(
        self,
        auth_manager_db_path: Path,
        web_cache_path: Path,
        max_rate: float = 20.0,
        time_period: float = 1.0,
    ):
        """Configure an EsiLink instance.

        Args:
            auth_manager_db_path: Path to the SqliteAuthManager database.
            web_cache_path: Path to the HTTP response cache database.
            max_rate: Maximum number of requests per rate-limit window.
            time_period: Window duration in seconds for rate limiting.
        """
        self.api_requester: api_request.ApiRequester | None = None
        self.auth_manager: SqliteAuthManager | None = None
        self.auth_manager_db_path = auth_manager_db_path
        self.web_cache_path = web_cache_path
        self.max_rate = max_rate
        self.time_period = time_period

    async def __aenter__(self) -> Self:
        """Initialize API requester and auth manager resources.

        Returns:
            The initialized EsiLink instance.
        """
        web_cache_factory = SqliteCacheFactory(db_path=self.web_cache_path)
        rate_limiter_factory = AiolimiterRateLimiterFactory(
            max_rate=self.max_rate, time_period=self.time_period
        )
        self.api_requester = api_request.ApiRequester(
            cache_factory=web_cache_factory, rate_limiter_factory=rate_limiter_factory
        )
        self.auth_manager = SqliteAuthManager(db_path=self.auth_manager_db_path)
        await self.api_requester.__aenter__()
        self.auth_manager.__enter__()
        return self

    async def __aexit__(
        self,
        exc_type: type[BaseException] | None,
        exc_value: BaseException | None,
        traceback: TracebackType | None,
    ):
        """Release API requester and auth manager resources."""
        if self.api_requester is not None:
            await self.api_requester.__aexit__(exc_type, exc_value, traceback)
        if self.auth_manager is not None:
            self.auth_manager.__exit__(exc_type, exc_value, traceback)

    @classmethod
    def from_settings(cls, settings: EsiLinkSettings) -> Self:
        """Create an EsiLink instance from EsiLinkSettings.

        Args:
            settings: EsiLinkSettings object containing configuration parameters.

        Returns:
            EsiLink: An initialized EsiLink instance.
        """
        return cls(
            auth_manager_db_path=settings.eve_auth_manager_settings.authorization_database_path,
            web_cache_path=settings.api_request_settings.web_cache_path,
            max_rate=settings.max_rate,
            time_period=settings.time_period,
        )

    def _check_api_requester_initialized(self) -> api_request.ApiRequester:
        """Return initialized ApiRequester instance.

        Returns:
            Initialized ApiRequester.

        Raises:
            RuntimeError: If EsiLink is used outside async context manager scope.
        """
        if self.api_requester is None:
            raise RuntimeError("EsiLink must be used as an async context manager.")
        return self.api_requester

    def _check_auth_manager(self) -> SqliteAuthManager:
        """Return initialized SqliteAuthManager instance.

        Returns:
            Initialized SqliteAuthManager.

        Raises:
            RuntimeError: If EsiLink is used outside async context manager scope.
        """
        if self.auth_manager is None:
            raise RuntimeError("EsiLink must be used as an async context manager.")
        return self.auth_manager

    def _check_operation(
        self, operation_id: str, esi_schema: EsiSchema
    ) -> SchemaOperation:
        """Check if the operation_id exists in the schema.

        Args:
            operation_id (str): The operation ID to check.
            esi_schema (EsiSchema): The schema to check against.

        Returns:
            SchemaOperation: The schema operation corresponding to the operation ID.

        Raises:
            ValueError: If the operation ID is not found in the schema.
        """
        operation = esi_schema.operations.get(operation_id)
        if operation is None:
            raise ValueError(f"Operation ID '{operation_id}' not found in ESI schema.")
        return operation

    async def _attach_access_token_if_required(
        self,
        esi_request: EsiRequest,
        runtime_esi_request: RuntimeEsiRequest,
    ) -> None:
        """Attach access token to runtime request when authorization is required.

        Args:
            esi_request: The ESI request to check.
            runtime_esi_request: Runtime request to mutate with access token.

        Raises:
            ValueError: If authorization tuple is incomplete.
        """
        if not esi_request.has_authorization:
            return
        auth_manager = self._check_auth_manager()
        cred_id = esi_request.auth_credential_id
        character_id = esi_request.auth_character_id
        if cred_id is None or character_id is None:
            raise ValueError(
                "Credential ID and Character ID must be provided for authorized requests."
            )
        access_token = auth_manager.refresh_character(
            cred_id, character_id
        ).access_token
        runtime_esi_request.access_token = access_token

    async def make_request(
        self, esi_request: EsiRequest, schema: EsiSchema
    ) -> EsiResponse | FailedEsiResponse:
        """Validate, execute, and return a single ESI request response.

        Args:
            esi_request: The ESI request to execute.
            schema: Schema used for operation lookup and validation.

        Returns:
            EsiResponse | FailedEsiResponse: The response for the ESI request.

        Raises:
            RuntimeError: If EsiLink is used outside async context manager scope.
            EsiRequestValidationErrors: If the request fails schema validation.
            Exception: Any backend execution exception from request or auth layers.
        """
        request_group = EsiRequestGroup(
            name="single_request_group",
            description="A group containing a single ESI request.",
            requests={esi_request.request_id: esi_request},
        )
        response_group = await self.make_requests(request_group, schema)
        if esi_request.request_id in response_group.failed_responses:
            return response_group.failed_responses[esi_request.request_id]
        elif esi_request.request_id in response_group.successful_responses:
            return response_group.successful_responses[esi_request.request_id]
        else:
            raise RuntimeError(
                f"Response for request ID {esi_request.request_id} not found in response group."
            )

    async def make_requests(
        self,
        esi_requests: EsiRequestGroup,
        schema: EsiSchema,
    ) -> EsiResponseGroup:
        """Validate, execute, and group responses for an ESI request batch.

        Args:
            esi_requests: ESI requests to execute.
            schema: Schema used for operation lookup and validation.

        Returns:
            Grouped successful and failed responses keyed by runtime request key.

        Raises:
            RuntimeError: If EsiLink is used outside async context manager scope.
            EsiRequestValidationErrors: If any request fails schema validation.
            Exception: Any backend execution exception from request or auth layers.
        """
        requester = self._check_api_requester_initialized()

        runtime_requests: dict[UUID, RuntimeEsiRequest] = {}
        for _, request in esi_requests.requests.items():
            self.validate_request(request, schema)
            runtime_request = build_runtime_esi_request(request, schema)
            await self._attach_access_token_if_required(request, runtime_request)
            runtime_requests[runtime_request.request_key] = runtime_request

        request_objects = {
            key: _make_request_from_runtime_request(request)
            for key, request in runtime_requests.items()
        }
        responses: Responses = await requester.process_requests(request_objects)
        esi_responses = _make_esi_response_group(
            responses, esi_requests, runtime_requests
        )
        return esi_responses

    @staticmethod
    def validate_request(
        esi_request: EsiRequest,
        schema: EsiSchema,
    ) -> None:
        """Validate one ESI request against the provided schema.

        Args:
            esi_request: The ESI request to validate.
            schema: Schema used for validation rules.

        Raises:
            EsiRequestValidationErrors: If request data violates schema-derived rules.
        """
        try:
            validate_esi_request(esi_request, schema)
        except EsiRequestValidationErrors as e:
            logger.error("Validation failed for request %s: %s", esi_request, e)
            raise

@dataclass(slots=True, kw_only=True)
class EsiLinkSettings:
    """Configuration settings for the Eve ESI Link application."""

    application_directory: Path
    logging_directory: Path
    schema_cache_directory: Path
    # Eve Auth Manager settings
    eve_auth_manager_settings: EveAuthManagerSettings
    # API Request settings
    api_request_settings: ApiRequestSettings
    max_rate: float = 50.0
    time_period: float = 1.0

@dataclass(slots=True, kw_only=True)
class EsiRequest:
    """Represents a single ESI request to be executed.

    Can be loaded from a file or created programmatically. The request_id is used to
    identify the request.

    Requests can be be contained in a RequestGroup, and the request_id is used
    to link the Request to its RuntimeRequest, and to the final EsiResponse.
    """

    request_id: UUID = field(default_factory=uuid4)
    """The unique identifier for the request. This is used to link the request to various 
        objects during the request lifecycle."""
    name: str | None = None
    """An optional name for the request. This is used for documentation purposes, 
        and can be used to provide context for the request when viewing it in a UI or in 
        logs."""
    description: str | None = None
    """An optional description of the request. This is used for documentation purposes, 
        and can be used to provide context for the request when viewing it in a UI or in 
        logs."""
    operation_id: str
    """The operation ID of the request, corresponding to the operationId in the ESI 
        OpenAPI schema."""
    path_parameters: dict[str, str | int | float] = field(
        default_factory=dict[str, str | int | float]
    )
    """The path parameters for the request, if applicable. This is used to fill in the 
        path parameters in the URL template."""
    query_parameters: dict[str, str | int | float] = field(
        default_factory=dict[str, str | int | float]
    )
    """The query parameters for the request, if applicable.

    This is used to fill in the query parameters in the URL template.

    NOTE: The page parameter is handled automatically by eve-link, and should not 
        be set manually. If it is set, it will raise a validation error. This is to help 
        normalize cache keys, which rely on predictable parameters.
    """
    header_parameters: dict[str, str] = field(default_factory=dict[str, str])
    """The header parameters for the request, if applicable. 

        Acceptable headers are:
        - Accept-Language
        - X-Tenant
        - X-Compatibility-Date

        Do not use this to set:

        - If-None-Match
        - If-Modified-Since headers. 

        Those are set at runtime during HTTP execution."""
    request_body: Any | None = None
    """The JSON payload of the request, if applicable. This is used for POST, PUT, and PATCH 
        requests."""
    auth_character_id: int | None = None
    """The character ID used for authorization."""
    auth_credential_id: UUID | None = None
    """The credential ID for authorization. This is used to link the authorization
        to the credential that was used to obtain it. This UUID is obtained from the 
        credential manager that provides the access token."""

    @property
    def has_authorization(self) -> bool:
        """Check if the request has an authorization."""
        return (
            self.auth_character_id is not None and self.auth_credential_id is not None
        )

    @property
    def authorization_slug(self) -> UUID:
        """Get the authorization slug for the authorization.

        This is a UUID that is generated from the character ID and credential ID, and is
        used as part of the cache key to differentiate between different cached
        authorized requests.

        Returns:
            The authorization slug for the authorization.
        """
        if not self.has_authorization:
            raise ValueError(
                "Cannot generate authorization key without both character_id and credential_id."
            )
        return uuid5(self.auth_credential_id, str(self.auth_character_id))  # type: ignore

@dataclass(slots=True, kw_only=True)
class EsiRequestGroup:
    name: str | None = None
    """The name of this group of runtime ESI requests."""
    description: str | None = None
    """An optional description of this group of runtime ESI requests."""
    requests: dict[UUID, EsiRequest] = field(default_factory=dict[UUID, EsiRequest])
    """The dict of  ESI requests in this group."""

@dataclass(slots=True, kw_only=True, frozen=True)
class EsiResponse:
    esi_request: EsiRequest
    """The request that generated this response."""
    esi_runtime_request: RuntimeEsiRequest
    """The request that generated this response."""
    response: Response
    """The response associated with this EsiResponse."""

    def serialize(self, indent: int | None = None) -> str:
        """Serialize the EsiResponse."""
        return EsiResponseRoot(root=self).model_dump_json(indent=indent)

    @property
    def response_data(self) -> Any:
        """Return the JSON response data associated with this EsiResponse."""
        return self.response.json

    @property
    def received_at_instant(self) -> Instant:
        """Return the instant at which the response was received."""
        return self.response.metadata.received_at

    @property
    def expires_at_instant(self) -> Instant | None:
        """Return the instant at which the response expires, if any."""
        return (
            Instant.from_timestamp(self.response.metadata.expires_at)
            if self.response.metadata.expires_at
            else None
        )

    def simple_response(self) -> SimplifiedEsiResponse:
        """Return a simplified version of this EsiResponse.

        This is useful for serialization and deserialization, as it removes the
        response metadata and other details that are not needed for most use cases.
        """
        return SimplifiedEsiResponse(
            esi_request=self.esi_request,
            response_data=self.response_data,
            received_at_instant=self.received_at_instant,
            expires_at_instant=self.expires_at_instant,
        )

@dataclass(slots=True, kw_only=True)
class EsiResponseGroup:
    name: str | None = None
    """The name of this group of runtime ESI responses."""
    description: str | None = None
    """An optional description of this group of runtime ESI responses."""
    successful_responses: dict[UUID, EsiResponse] = field(
        default_factory=dict[UUID, EsiResponse]
    )
    """The dict of successful ESI responses in this group."""
    failed_responses: dict[UUID, FailedEsiResponse] = field(
        default_factory=dict[UUID, FailedEsiResponse]
    )
    """The dict of failed ESI responses in this group."""

    def serialize(self, indent: int | None = None) -> str:
        """Purge secrets and serialize the EsiResponseGroup to a JSON string."""
        return EsiResponseGroupRoot(root=self).model_dump_json(indent=indent)

@dataclass(slots=True, kw_only=True)
class EsiSchema:
    """Represents the schema payload used for operation-level lookups.

    Can have an optional timestamp associated with it, representing the timestamp when
    the schema was fetched in nanoseconds.

    The model builds operation and tag indexes during initialization.
    """

    dereferenced_schema: dict[str, Any]
    timestamp: str | None = None
    """The timestamp associated with the schema, representing the timestamp when the
        schema was fetched as an ISO 8601 string. This field is optional and can be None 
        if the timestamp is not available or not applicable."""
    _schema_operations: dict[str, SchemaOperation] = field(
        default_factory=dict[str, SchemaOperation], init=False, repr=False
    )
    _operations_id_by_tag: dict[str, list[str]] = field(
        default_factory=dict[str, list[str]], init=False, repr=False
    )

    @property
    def timestamp_instant(self) -> Instant | None:
        """Get the timestamp as an Instant object, if available."""
        if self.timestamp is not None:
            return Instant.parse_iso(self.timestamp)
        return None

    def __post_init__(self) -> None:
        """Ensure that the schema is valid."""
        if "openapi" not in self.dereferenced_schema:
            raise ValueError("Invalid schema: missing 'openapi' field")
        # fill the schema operations dictionary
        self._build_schema_operations()
        self._build_operation_id_by_tag()

    def serialize(self, indent: int | None = None) -> str:
        """Serialize as an EsiSchemaTD-compatible JSON string.

        Output keys:
        - dereferenced_schema
        - timestamp
        """
        return EsiSchemaRoot(root=self).model_dump_json(indent=indent)

    @classmethod
    def deserialize(cls, json_str: str) -> EsiSchema:
        """Deserialize an EsiSchema compatible JSON string into an EsiSchema instance."""
        model = EsiSchemaRoot.model_validate_json(json_str).root
        return model

    def _build_schema_operations(self) -> None:
        """Build the schema operations dictionary from the dereferenced schema."""
        paths = self.dereferenced_schema.get("paths", {})
        for path, methods in paths.items():
            for method, operation in methods.items():
                operation_id = operation.get("operationId")
                if operation_id:
                    self._schema_operations[operation_id] = SchemaOperation(
                        path=path,
                        method=HttpMethod(method.upper()),
                        operation_schema=deepcopy(operation),
                    )

    def _build_operation_id_by_tag(self) -> None:
        """Build the operation ID by tag mapping from the schema operations."""
        if not self._schema_operations:
            raise ValueError(
                "Schema operations must be built before building operation ID by tag mapping."
            )
        tag_mapping: dict[str, list[str]] = {}
        for operation in self._schema_operations.values():
            for tag in operation.tags:
                if tag not in tag_mapping:
                    tag_mapping[tag] = []
                tag_mapping[tag].append(operation.operation_id)
        # sort the tags alphabetically, and the operation IDs within each tag alphabetically as well
        self._operations_id_by_tag = {
            tag: sorted(operation_ids)
            for tag, operation_ids in sorted(tag_mapping.items())
        }

    @classmethod
    def from_raw_schema(
        cls, raw_schema: dict[str, Any], timestamp: str | None = None
    ) -> Self:
        """Factory method to create an EsiSchema instance from a raw OpenAPI schema.

        This method resolves internal ``$ref`` values before creating ``EsiSchema``.

        Args:
            raw_schema: The raw OpenAPI schema as a dictionary.
            timestamp: The timestamp associated with the schema, representing the timestamp when the
                schema was fetched as an ISO 8601 string. This field is optional and can be None if the
                timestamp is not available or not applicable.

        Returns:
            An instance of EsiSchema with the dereferenced schema.
        """
        dereferenced_schema = resolve_internal_refs(raw_schema, raw_schema)
        return cls(dereferenced_schema=dereferenced_schema, timestamp=timestamp)

    @property
    def operations(self) -> dict[str, SchemaOperation]:
        """Get a dictionary of all operations in the schema, keyed by operation ID."""
        return self._schema_operations

    @property
    def operations_id_by_tag(self) -> dict[str, list[str]]:
        """Get a dictionary mapping tags to lists of operation IDs."""
        return self._operations_id_by_tag

    @property
    def compatibility_date(self) -> str:
        """Get compatibility date, currently sourced from ``info.version``."""
        return self.version

    @property
    def version(self) -> str:
        """Get the version of the ESI schema based on the compatibility date."""
        version = cast(str, self.dereferenced_schema["info"]["version"])
        return version

    @property
    def base_url(self) -> str:
        """Get the base URL for the ESI API from the servers section of the schema."""
        return self.dereferenced_schema["servers"][0]["url"]

    def operation_url(self, operation_id: str) -> str:
        """Get full URL template for an operation ID.

        Raises:
            ValueError: If operation_id is not present in the schema.
        """
        operation = self.operations.get(operation_id)
        if operation is None:
            raise ValueError(f"Operation ID '{operation_id}' not found in ESI schema.")
        return f"{self.base_url}{operation.path}"

    @property
    def content_languages(self) -> set[str]:
        """Get the content languages supported by the ESI API from the schema."""
        return set(
            self.dereferenced_schema
            .get("components", {})
            .get("headers", {})
            .get("ContentLanguage", {})
            .get("schema", {})
            .get("enum", [])
        )

@dataclass(slots=True, kw_only=True, frozen=True)
class FailedEsiResponse:
    esi_request: EsiRequest
    """The request that generated this failed response."""
    esi_runtime_request: RuntimeEsiRequest
    """The request that generated this failed response."""
    failed_response: FailedResponse
    """The failed response associated with this FailedEsiResponse."""

    def serialize(self, indent: int | None = None) -> str:
        """Serialize the FailedEsiResponse."""
        return FailedEsiResponseRoot(root=self).model_dump_json(indent=indent)