<?php

declare(strict_types=1);

namespace KTXM\ProviderImap\Client\Protocol;

use Generator;
use IteratorAggregate;
use KTXM\ProviderImap\Client\ImapException;
use Traversable;

final class ResponseStream implements IteratorAggregate
{
    /** @var \Closure():Generator */
    private readonly \Closure $generatorFactory;

    /** @var (\Closure(string):void)|null */
    private readonly ?\Closure $continuationWriter;

    /**
     * @param \Closure():Generator        $generatorFactory
     * @param (\Closure(string):void)|null $continuationWriter writes raw bytes
     *        back to the server in response to a command continuation request
     */
    public function __construct(\Closure $generatorFactory, ?\Closure $continuationWriter = null)
    {
        $this->generatorFactory = $generatorFactory;
        $this->continuationWriter = $continuationWriter;
    }

    public function getIterator(): Traversable
    {
        return ($this->generatorFactory)();
    }

    /**
     * Send raw bytes to the server after a command continuation request (a "+"
     * response) — e.g. the literal payload of an APPEND.
     *
     * Must only be called while iterating this stream, in response to a
     * {@see \KTXM\ProviderImap\Client\Protocol\Response\ContinuationResponse};
     * the next pulled response then reflects the server's reaction to the data.
     */
    public function respond(string $payload): void
    {
        if ($this->continuationWriter === null) {
            throw new ImapException('This response stream does not support continuation replies.');
        }

        ($this->continuationWriter)($payload);
    }
}