<?php
// SPDX-License-Identifier: GPL-3.0-or-later
declare(strict_types=1);

namespace Aiwend\Provider;

/**
 * The two bounds on a provider request, kept apart on purpose, and the one JSON encoding every transport sends.
 *
 *  1. LOGICAL limit (the "configured local byte limit"): the UTF-8 size of what is being sent as input (instruction, conversation, reference
 *     material), measured exactly like the budget reservation (InputEstimate). It does not depend on how the text is escaped, so a Persian,
 *     Chinese or emoji conversation is limited by its real size, not by the size of its \uXXXX escapes.
 *  2. SERIALIZED payload limit: the size of the JSON body that actually goes on the wire. This is a hard transport bound; it also covers
 *     what the logical measure cannot see (a request that is small as text but expands when quoted: quotes, backslashes, control characters,
 *     reference material that is JSON inside a JSON string).
 *
 * Before Phase 97D the adapters compared the escaped JSON size with the logical limit and the transports serialized with PHP's default
 * escaping, so non-ASCII text counted (and was sent) at up to three times its UTF-8 size: Persian conversations hit the limit about three
 * times sooner than English ones and uploaded three times the bytes. Characters are now sent as UTF-8 characters, which every provider accepts.
 * Everything that fails here fails BEFORE dispatch (never dispatched, settled at zero), with a fixed message and no request text.
 */
final class RequestPayload
{
    /** Hard cap on the serialized body a transport will send. */
    public const MAX_PAYLOAD_BYTES = 262144;
    private const FLAGS = JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES;

    /**
     * The wire encoding: compact UTF-8 JSON, characters unescaped. Refuses (before dispatch) text that is not valid UTF-8 and a body above the hard cap.
     *
     * @param array<string, mixed> $body
     */
    public static function encode(array $body): string
    {
        try {
            // phpcs:ignore WordPress.WP.AlternativeFunctions.json_encode_json_encode -- wp_json_encode() does not throw on invalid UTF-8; the strict, exception-based encoding is required here and this class must work without WordPress loaded
            $json = json_encode($body, self::FLAGS);
        } catch (\JsonException) {
            // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- exception messages go to logs and callers, never echoed; public errors are fixed codes
            throw new ProviderException(ProviderException::INVALID_REQUEST, false, 'The request contains text that cannot be sent (not valid UTF-8).');
        }
        if (strlen($json) > self::MAX_PAYLOAD_BYTES) {
            // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- exception messages go to logs and callers, never echoed; public errors are fixed codes
            throw new ProviderException(ProviderException::INVALID_REQUEST, false, 'Request exceeds the local input limit.');
        }
        return $json;
    }

    /**
     * The reference material as the text placed in the data message (same encoding as before Phase 97D). Text that is not valid UTF-8 is refused
     * before dispatch instead of surfacing as an unclassified error.
     *
     * @param list<array<string, mixed>> $context
     */
    public static function contextJson(array $context): string
    {
        try {
            // phpcs:ignore WordPress.WP.AlternativeFunctions.json_encode_json_encode -- strict, exception-based encoding (see encode())
            return json_encode($context, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
        } catch (\JsonException) {
            // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- exception messages go to logs and callers, never echoed; public errors are fixed codes
            throw new ProviderException(ProviderException::INVALID_REQUEST, false, 'The request contains text that cannot be sent (not valid UTF-8).');
        }
    }

    /**
     * Both bounds, for an adapter, before anything is handed to a transport. $configured is the site's byte limit (clamped to 1,024..131,072).
     *
     * @param array<string, mixed> $body the provider-shaped body the adapter is about to send
     */
    public static function assertWithinLimits(ModelRequest $request, array $body, int $configured): void
    {
        try {
            $logical = InputEstimate::bytes($request);
        } catch (\JsonException) {
            // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- exception messages go to logs and callers, never echoed; public errors are fixed codes
            throw new ProviderException(ProviderException::INVALID_REQUEST, false, 'The request contains text that cannot be sent (not valid UTF-8).');
        }
        if ($logical > max(1024, min(131072, $configured))) {
            // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- exception messages go to logs and callers, never echoed; public errors are fixed codes
            throw new ProviderException(ProviderException::INVALID_REQUEST, false, 'Context exceeds the configured local byte limit.');
        }
        self::encode($body); // the serialized bound (and the UTF-8 check) on the body that will really be sent
    }
}