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

namespace Aiwend\Knowledge;

/**
 * The single rule set for an uploaded knowledge file, used by the first upload and by file replacement, over REST and in the
 * administrator forms. It decides in this order, and never reads a file that an earlier rule has already rejected:
 *   1. PHP's own rejection (upload_max_filesize / MAX_FILE_SIZE) is a size problem; any other upload error, or a file that was
 *      not really uploaded via HTTP, is a missing file;
 *   2. the extension (txt, md, markdown, pdf) decides the type; nothing else is accepted;
 *   3. the declared size and the real size on disk must be within Extractor::MAX_BYTES;
 *   4. at most MAX_BYTES + 1 bytes are read, and the content must be UTF-8 without NUL (text) or a PDF with header and %%EOF.
 * The result is the sanitized name, the storage type and the content, or one stable error code. Callers map the code to their
 * own surface (REST status or administrator notice); they add no rules of their own.
 */
final class UploadReader
{
    public const MISSING = 'upload_missing';
    public const TYPE = 'upload_type';
    public const SIZE = 'upload_size';
    public const BINARY = 'upload_binary';
    /** A .pdf file in an edition that does not contain PDF extraction (see PdfSupport). */
    public const PDF_UNAVAILABLE = 'upload_pdf_unavailable';

    /**
     * @param mixed $file one entry of $_FILES / WP_REST_Request::get_file_params()
     * @param (callable(string): string)|null $sanitizeName defaults to WordPress's sanitize_file_name()
     * @param (callable(string): bool)|null $isUploaded defaults to is_uploaded_file()
     * @return array{name:string, type:string, content:string}|string  error code (see constants)
     */
    public static function read(mixed $file, ?callable $sanitizeName = null, ?callable $isUploaded = null): array|string
    {
        $err = is_array($file) ? ($file['error'] ?? UPLOAD_ERR_NO_FILE) : UPLOAD_ERR_NO_FILE;
        if ($err === UPLOAD_ERR_INI_SIZE || $err === UPLOAD_ERR_FORM_SIZE) {
            return self::SIZE;
        }
        $isUploaded ??= 'is_uploaded_file';
        if (!is_array($file) || $err !== UPLOAD_ERR_OK || !is_string($file['tmp_name'] ?? null) || !$isUploaded($file['tmp_name'])) {
            return self::MISSING;
        }
        $sanitizeName ??= 'sanitize_file_name';
        $name = $sanitizeName((string) ($file['name'] ?? ''));
        $type = self::typeFor($name);
        if ($type === null) {
            return self::TYPE;
        }
        if ($type === 'pdf' && !PdfSupport::available()) {
            return self::PDF_UNAVAILABLE;
        }
        $declared =(int) ($file['size'] ?? 0);
        $onDisk = (int) @filesize($file['tmp_name']);
        if ($declared > Extractor::MAX_BYTES || $onDisk > Extractor::MAX_BYTES) {
            return self::SIZE;
        }
        // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- reads a local file (the key file or an uploaded text file), not a URL
        $content = (string) @file_get_contents($file['tmp_name'], false, null, 0, Extractor::MAX_BYTES + 1);
        if ($type !== 'pdf') {
            $content = self::normalizeText($content);
        }
        $checked = self::validateContent($type, $content);
        return $checked === null ? ['name' => $name, 'type' => $type, 'content' => $content] : $checked;
    }

    /** Pure check used by read() and by tests: name, declared size and content already in hand. @return array{type:string}|string */
    public static function validate(string $sanitizedName, int $declaredSize, string $content): array|string
    {
        $type = self::typeFor($sanitizedName);
        if ($type === null) {
            return self::TYPE;
        }
        if ($type === 'pdf' && !PdfSupport::available()) {
            return self::PDF_UNAVAILABLE;
        }
        if ($declaredSize > Extractor::MAX_BYTES) {
            return self::SIZE;
        }
        $error = self::validateContent($type, $content);
        return $error ?? ['type' => $type];
    }

    private static function typeFor(string $name): ?string
    {
        return match (strtolower(pathinfo($name, PATHINFO_EXTENSION))) {
            'txt' => 'text',
            'md', 'markdown' => 'markdown',
            'pdf' => 'pdf',
            default => null,
        };
    }

    /**
     * Text saved by common editors: a UTF-8 byte order mark is dropped, and UTF-16 with a byte order mark (Notepad's "Unicode" option) is
     * converted to UTF-8. Both are unambiguous. Other encodings are not guessed: a wrong guess would index unreadable text without a word.
     */
    private static function normalizeText(string $content): string
    {
        if (str_starts_with($content, "\xEF\xBB\xBF")) {
            return substr($content, 3);
        }
        $bom = substr($content, 0, 2);
        if (($bom === "\xFF\xFE" || $bom === "\xFE\xFF") && strlen($content) % 2 === 0) {
            $converted = mb_convert_encoding(substr($content, 2), 'UTF-8', $bom === "\xFF\xFE" ? 'UTF-16LE' : 'UTF-16BE');
            return is_string($converted) ? $converted : $content;
        }
        return $content;
    }

    private static function validateContent(string $type, string $content): ?string
    {
        if (strlen($content) > Extractor::MAX_BYTES) {
            return self::SIZE;
        }
        $valid = $type === 'pdf'
            ? str_starts_with($content, '%PDF-') && str_contains($content, '%%EOF')
            : !str_contains($content, "\0") && mb_check_encoding($content, 'UTF-8');
        return $valid ? null : self::BINARY;
    }
}