xnano.requests

def on_get_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``GET`` request."""
    return _register_request_hook("GET", handler_or_path, path)

def on_head_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``HEAD`` request."""
    return _register_request_hook("HEAD", handler_or_path, path)

def on_post_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``POST`` request."""
    return _register_request_hook("POST", handler_or_path, path)

def on_put_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``PUT`` request."""
    return _register_request_hook("PUT", handler_or_path, path)

def on_delete_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``DELETE`` request."""
    return _register_request_hook("DELETE", handler_or_path, path)

def on_connect_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``CONNECT`` request."""
    return _register_request_hook("CONNECT", handler_or_path, path)

def on_options_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``OPTIONS`` request."""
    return _register_request_hook("OPTIONS", handler_or_path, path)

def on_trace_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``TRACE`` request."""
    return _register_request_hook("TRACE", handler_or_path, path)

def on_patch_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``PATCH`` request."""
    return _register_request_hook("PATCH", handler_or_path, path)

def on_query_request(
    handler_or_path: EventHookFunction | str | None = None,
    /,
    *,
    path: str | None = None,
) -> RequestDecorator:
    """Decorate a handler for an HTTP ``QUERY`` request."""
    return _register_request_hook("QUERY", handler_or_path, path)

def has_request_hooks(grid_or_class: Any) -> bool:
    """Return whether a grid (instance or class) declares any request hook."""
    grid_class = (
        grid_or_class
        if isinstance(grid_or_class, type)
        else type(grid_or_class)
    )
    return bool(
        _RequestHooksRegistry.from_component_class(grid_class).all_hooks()
    )

def collect_request_routes(grid_class: type) -> list[_OnRequestHookEntry]:
    """Collect ``@on_*_request`` route entries declared on a grid class."""
    return _RequestHooksRegistry.from_component_class(grid_class).all_hooks()

def request(
    method: str,
    path: str = "/",
) -> Callable[[EventHookFunction], EventHookFunction]:
    """Register an HTTP request hook for an arbitrary method.

    Args:
        method: HTTP method name.
        path: URL path (normalized to a leading slash).

    Returns:
        A decorator that marks the function as a request hook.
    """
    method_upper = method.upper()
    factories: dict[str, Callable[..., Any]] = {
        "GET": on_get_request,
        "HEAD": on_head_request,
        "POST": on_post_request,
        "PUT": on_put_request,
        "DELETE": on_delete_request,
        "CONNECT": on_connect_request,
        "OPTIONS": on_options_request,
        "TRACE": on_trace_request,
        "PATCH": on_patch_request,
        "QUERY": on_query_request,
    }
    factory = factories.get(method_upper)
    if factory is None:
        raise ValueError(f"Unsupported HTTP method: {method!r}")
    return factory(path)

def dispatch_request(
    grid: Any,
    method: str,
    path: str,
    *,
    request_obj: Request | None = None,
    runtime: Any | None = None,
) -> Response | bool:
    """Run the request hook matching ``method`` and ``path``.

    Pass a runtime to make it available through the handler's ``Context``.
    A handler that returns ``None`` produces an empty successful response.

    Args:
        grid: Grid instance declaring request hooks.
        method: HTTP method.
        path: Request path.
        request_obj: Optional parsed request for ``ctx.request``.
        runtime: Optional runtime exposed through the hook context.

    Returns:
        The handler response, or whether a route matched when no runtime was
        supplied.
    """
    from xnano.context import Context
    from xnano.events import AbstractEventData, Event
    from xnano.utils.dispatch import invoke_hook

    method = method.upper()
    cleaned = _normalize_request_path(path)
    routes: Sequence[_OnRequestHookEntry] = collect_request_routes(type(grid))
    matched = False
    last_response: Response | None = None

    facade = runtime if runtime is not None else grid
    ctx = Context(
        event=Event.from_data(AbstractEventData()),
        terminal=facade,
        state=_resolve_context_state(runtime, grid),
        request=request_obj,
    )

    for entry in routes:
        if entry["method"] != method or entry["path"] != cleaned:
            continue
        name = getattr(entry["handler"], "__name__", "")
        handler = getattr(grid, name, None)
        if handler is None:
            continue
        result = invoke_hook(handler, grid, ctx)
        matched = True
        if isinstance(result, Response):
            last_response = result
        elif result is not None and not isinstance(result, bool):
            last_response = Response(body=str(result))

    if runtime is not None:
        if last_response is not None:
            return last_response
        if matched:
            return Response()
        return Response(status=404, body=b"Not Found")
    return matched