<?php

namespace App\Xapi;

use JumPHP\Async\Task;

/**
 * How HTTP requests reach a XAPI server (the toolstack of XCP-ng / XenServer): a real stream (StreamTransport: plain TCP, the
 * JumPHP runtime, an SSH tunnel, TLS on the desktop) or the demo pool in memory (FakeXapi). Never blocks: a Task of HttpReply.
 */
interface Transport
{
    /**
     * @param array<string, string> $headers
     * @param string $channel requests of one channel go one after the other on one connection (keep-alive); 'events' waits long
     */
    public function request(string $method, string $path, string $body = '', array $headers = [], string $channel = 'calls'): Task;

    /** Each frame: reads the streams, settles the tasks. */
    public function poll(float $dt): void;

    public function close(): void;

    /** A line for the status bar: "HTTP 10.0.0.2:80", "SSH tunnel root@pool.example.com"... */
    public function describe(): string;
}