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

namespace Aiwend\Provider;

/**
 * A write-only PHP stream wrapper that hands every chunk of an HTTP response body to a callback AS IT ARRIVES.
 *
 * The WordPress HTTP API cannot deliver a response incrementally, but when a request is made with 'stream' => true it writes the body
 * to the 'filename' piece by piece as the transport receives it. Pointing 'filename' at this wrapper turns that into a live feed, so
 * server-sent events can be read through wp_remote_post() without any direct cURL call. Nothing is ever written to disk.
 *
 * The callback may throw (a StreamAbort) to stop the transfer: the exception propagates out of the transport's write, which makes the
 * underlying transport abort the connection.
 */
final class StreamSink
{
    public const SCHEME = 'aiwendstream';

    /** @var array<string, callable(string): void> */
    private static array $sinks = [];
    private static bool $registered = false;

    /** @var resource|null set by PHP */
    public $context;
    private ?string $id = null;

    /** Registers a sink and returns the URL-like name to pass as the request's 'filename'. */
    public static function open(callable $onChunk): string
    {
        if (!self::$registered) {
            self::$registered = in_array(self::SCHEME, stream_get_wrappers(), true) || stream_wrapper_register(self::SCHEME, self::class);
        }
        $id = bin2hex(random_bytes(8));
        self::$sinks[$id] = $onChunk;
        return self::SCHEME . '://' . $id . '/body';
    }

    public static function close(string $name): void
    {
        unset(self::$sinks[self::idOf($name)]);
    }

    private static function idOf(string $path): string
    {
        return (string) (preg_match('~^' . self::SCHEME . '://([0-9a-f]{16})(/|$)~', $path, $m) === 1 ? $m[1] : '');
    }

    // ---- stream wrapper protocol (called by PHP) ------------------------------------------------------------------------------

    public function stream_open(string $path, string $mode, int $options, ?string &$openedPath): bool
    {
        $this->id = self::idOf($path);
        return str_contains($mode, 'w') || str_contains($mode, 'a') || str_contains($mode, 'x');
    }

    public function stream_write(string $data): int
    {
        if ($this->id !== null && isset(self::$sinks[$this->id])) {
            (self::$sinks[$this->id])($data);
        }
        return strlen($data); // anything else the WordPress writability probe may write (Windows) is accepted and dropped
    }

    public function stream_close(): void
    {
    }

    public function stream_flush(): bool
    {
        return true;
    }

    public function stream_eof(): bool
    {
        return true;
    }

    /** @return array<string, int> */
    public function stream_stat(): array
    {
        return ['mode' => 0100666, 'size' => 0];
    }

    /** @return array<string, int>|false the "directory" WordPress checks for writability before streaming */
    public function url_stat(string $path, int $flags): array|false
    {
        return ['mode' => 040777, 'size' => 0, 'uid' => 0, 'gid' => 0, 'nlink' => 1];
    }

    public function unlink(string $path): bool
    {
        return true;
    }
}