"""
HTTP request metadata model for request tracking.

This module provides ModelHttpRequestMetadata, a typed model for HTTP-specific
request metadata. It captures HTTP method, path, and content negotiation
headers for request processing and logging.

Note:
    This model is distinct from ModelRequestMetadata in the common module,
    which provides generic request metadata. This model is HTTP-specific.

Thread Safety:
    ModelHttpRequestMetadata is immutable (frozen=True) after creation, making it
    thread-safe for concurrent read access from multiple threads or async tasks.

See Also:
    - omnibase_core.models.context.model_session_context: Session context
    - omnibase_core.models.common.model_request_metadata: Generic request metadata
"""

from pydantic import BaseModel, ConfigDict, Field

__all__ = ["ModelHttpRequestMetadata"]


class ModelHttpRequestMetadata(BaseModel):
    """HTTP request metadata.

    Provides typed HTTP-specific metadata for request tracking and logging.
    All fields are optional as metadata may be partially populated depending
    on the request source and middleware configuration.

    Attributes:
        request_id: Unique request identifier for correlation and tracing.
            Usually generated by API gateway or load balancer.
        method: HTTP method (GET, POST, PUT, DELETE, PATCH, etc.).
        path: Request path including query parameters if applicable.
        content_type: Content-Type header value indicating request body format
            (e.g., "application/json", "multipart/form-data").
        accept: Accept header value indicating preferred response format
            (e.g., "application/json", "text/html").

    Thread Safety:
        This model is frozen and immutable after creation.
        Safe for concurrent read access across threads.

    Example:
        >>> from omnibase_core.models.context import ModelHttpRequestMetadata
        >>>
        >>> metadata = ModelHttpRequestMetadata(
        ...     request_id="req_xyz789",
        ...     method="POST",
        ...     path="/api/v1/nodes/execute",
        ...     content_type="application/json",
        ...     accept="application/json",
        ... )
        >>> metadata.method
        'POST'
    """

    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)

    request_id: str | None = Field(
        default=None,
        description="Request identifier",
    )
    method: str | None = Field(
        default=None,
        description="HTTP method",
    )
    path: str | None = Field(
        default=None,
        description="Request path",
    )
    content_type: str | None = Field(
        default=None,
        description="Content-Type header",
    )
    accept: str | None = Field(
        default=None,
        description="Accept header",
    )
