<?php declare(strict_types=1);
/**
 * @package messenger
 * @author kputyr
 * @date 20.04.2026
 */

namespace IMATHUZH\Messenger\Rest;

/**
 * An interface of a REST request exposed to request handlers.
 */
interface RequestInterface
{
    /**
     * Returns the request path.
     * 
     * @return string
     */
    public function getPath(): string;

    /**
     * Returns the request method.
     * 
     * @return string
     */
    public function getMethod(): string;

    /**
     * Returns as many arguments as provided regexp patterns and asserts
     * that the patterns are matched.
     * 
     * Returns all arguments if no pattern is provided.
     */
    public function getParams(string ...$patterns): array;

    /**
     * Returns the request body or null if empty
     */
    public function getBody(array $patterns = []): null|object|array;

    /**
     * Returns the query parameters or an empty array if none
     */
    public function getQuery(array $patterns = []): array;

    /**
     * Asserts that the given value matches the provided pattern and rejects otherwise.
     */
    public function assertMatches(string $value, string $pattern): void;

    /**
     * Rejects the request by throwing an exception that is handled
     * by the main request processing code.
     */
    public function reject(string $message, int $code=403): void;
}
