sillydev 1.0.0

data/lib/sillydev/console.rb

@@ -0,0 +1,1131 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require_relative "websocket"
+
+module SillyDev
+  # One message from (or to) the console, as the websocket carries it. event is such as
+  # "console output", "status", "stats", "daemon message" or "auth success"; args are strings
+  # ("console output" has the line as args[0]).
+  ConsoleMessage = Struct.new(:event, :args)
+
+  # A server's live console: its output, state and resource use as they happen, and commands and
+  # power actions sent back.
+  #
+  # There are four ways to reach it, tried in this order by transport "auto" (the default):
+  #
+  # - websocket: a websocket to the server's node. The quickest, and what the panel uses.
+  # - stream: the same messages from a session on the node, streamed over plain HTTPS
+  #   (server-sent events), for networks that block websockets.
+  # - poll: the same session read by long polling, for proxies that hold streams back.
+  # - relay: the panel reads a session on the node for you, for networks that can't reach the
+  #   node at all. Output arrives a second or two late.
+  #
+  # Every way carries the same messages. The connection renews its 10-minute token by itself, and
+  # reconnects (trying each way again) if it drops. It runs on background threads, which is where
+  # listeners added with #on are called.
+  #
+  #   client.panel.console.connect("1a7ce997") do |console|
+  #     console.on("console output") { |message| puts message.args[0] }
+  #     console.command("say Hello")
+  #     sleep 10
+  #   end
+  class Console
+    TRANSPORTS = %w[websocket stream poll relay].freeze
+    CONNECT_TIMEOUTS = { "websocket" => 6.0, "stream" => 8.0, "poll" => 10.0, "relay" => 10.0 }.freeze
+    TOKEN_AGE = 5 * 60.0 # A token older than this is swapped before connecting again; they last 10 minutes.
+    QUEUE_LIMIT = 1000 # Messages kept for a reader that isn't reading; the oldest go first.
+    MAX_FAILURES = 3 # Failed reads in a row before a session or relay is taken as lost.
+    HEALTHY_STREAM = 30.0 # A stream that lasted this long ended normally (the node ends them every 5 minutes).
+    ENDED = "The session has ended."
+
+    # How long things may take; replaceable in tests.
+    Timings = Struct.new(:first_byte, :stream_idle, :request, :poll_pause, keyword_init: true)
+    DEFAULT_TIMINGS = Timings.new(first_byte: 8.0, stream_idle: 40.0, request: 30.0, poll_pause: 1.0).freeze
+
+    # Reads {event, args} from a websocket frame or a queued message.
+    def self.parse_message(value)
+      return nil unless value.is_a?(Hash)
+
+      event = value["event"]
+      return nil unless event.is_a?(String) && !event.empty?
+
+      args = if value["args"].is_a?(Array)
+               value["args"].map { |a| a.is_a?(String) ? a : a.to_s }
+             else
+               []
+             end
+      ConsoleMessage.new(event, args)
+    end
+
+    # The origin of a URL: https://sillydev.co.uk/panel/api/client gives https://sillydev.co.uk.
+    def self.origin_of(url)
+      uri = URI(url)
+      return url if uri.scheme.nil? || uri.host.nil?
+
+      default = uri.scheme == "https" ? 443 : 80
+      uri.port == default ? "#{uri.scheme}://#{uri.host}" : "#{uri.scheme}://#{uri.host}:#{uri.port}"
+    rescue URI::InvalidURIError
+      url
+    end
+
+    def self.monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # A one-shot signal a thread can wait on, with a timeout and an optional error.
+    class Latch
+      def initialize
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @done = false
+        @error = nil
+      end
+
+      def set(error = nil)
+        @mutex.synchronize do
+          next if @done
+
+          @done = true
+          @error = error
+          @cond.broadcast
+        end
+      end
+
+      def done?
+        @done
+      end
+
+      # True once set (raising its error, if any), false when the timeout passed first.
+      def wait(timeout = nil) # rubocop:disable Naming/PredicateMethod
+        deadline = timeout ? Console.monotonic + timeout : nil
+        @mutex.synchronize do
+          until @done
+            remaining = deadline ? deadline - Console.monotonic : nil
+            return false if remaining && remaining <= 0
+
+            @cond.wait(@mutex, remaining)
+          end
+        end
+        raise @error if @error
+
+        true
+      end
+    end
+
+    # What a transport calls: message(ConsoleMessage) for each message, closed(ConsoleError) once
+    # it drops after starting.
+    Handlers = Struct.new(:message, :closed)
+
+    # A websocket to the node.
+    class WebsocketTransport
+      attr_reader :kind
+
+      def initialize(url, origin, token, handlers)
+        @kind = "websocket"
+        @url = url
+        @origin = origin
+        @token = token
+        @handlers = handlers
+        @closed = false
+      end
+
+      def start(timeout)
+        begin
+          @ws = WebSocket.connect(@url, origin: @origin, timeout: timeout,
+                                        headers: { "User-Agent" => "sillydev-ruby/#{VERSION}" })
+        rescue WebSocket::Closed => e
+          raise ConsoleError.new("Could not open the websocket: #{e.message}", "network", transport: kind)
+        end
+        started = Latch.new
+        @reader = Thread.new { read_loop(started) }
+        @reader.name = "sillydev-console-websocket" if @reader.respond_to?(:name=)
+        begin
+          @ws.send_text(JSON.generate({ event: "auth", args: [@token] }))
+        rescue WebSocket::Closed
+          nil # The reader sees why (4409 for a suspended server).
+        end
+        return if started.wait(timeout)
+
+        close
+        raise ConsoleError.new("Connecting took longer than #{timeout} s.", "timeout", transport: kind)
+      end
+
+      def send_message(message)
+        raise ConsoleError.new("The websocket is closed.", "network", transport: kind) if @closed || @ws.nil?
+
+        @ws.send_text(JSON.generate({ event: message.event, args: message.args }))
+      rescue WebSocket::Closed => e
+        raise ConsoleError.new("Could not send on the websocket: #{e.message}", "network", transport: kind)
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @ws&.close
+      end
+
+      private
+
+      def read_loop(started)
+        error = nil
+        loop do
+          raw = @ws.read
+          return if @closed
+
+          message = begin
+            Console.parse_message(JSON.parse(raw))
+          rescue JSON::ParserError
+            nil
+          end
+          next if message.nil?
+
+          unless started.done?
+            if message.event == "auth success"
+              started.set
+              @handlers.message.call(message)
+            elsif message.event == "jwt error"
+              error = ConsoleError.new("The node refused the token: #{message.args.first}".strip, "token",
+                                       transport: kind)
+              break
+            end
+            next
+          end
+          @handlers.message.call(message)
+        end
+      rescue WebSocket::Closed => e
+        error ||= close_error(e.code, e.reason)
+      rescue StandardError => e
+        error ||= ConsoleError.new("The websocket failed: #{e.message}", "network", transport: kind)
+      ensure
+        finish(started, error) unless @closed && error.nil?
+      end
+
+      def finish(started, error)
+        return if @closed && started.done?
+
+        was_closed = @closed
+        @closed = true
+        @ws&.close
+        error ||= ConsoleError.new("The websocket closed.", "network", transport: kind)
+        if started.done?
+          @handlers.closed.call(error) unless was_closed
+        else
+          started.set(error)
+        end
+      end
+
+      def close_error(code, reason)
+        case code
+        when 4409 then ConsoleError.new("The server is suspended.", "suspended", transport: kind)
+        when 4410 then ConsoleError.new("The node is still loading the server.", "booting", transport: kind)
+        else
+          why = reason.nil? || reason.empty? ? "" : ": #{reason}"
+          ConsoleError.new("The websocket closed (code #{code || 'none'})#{why}.", "network", transport: kind)
+        end
+      end
+    end
+
+    # A session on the node, read by streaming ("stream") or long polling ("poll").
+    class SessionTransport
+      attr_reader :kind
+
+      def initialize(kind, base, token, handlers, poll_wait, timings)
+        @kind = kind
+        @base = base.chomp("/")
+        @token = token
+        @handlers = handlers
+        @poll_wait = poll_wait
+        @timings = timings
+        @session = nil
+        @cursor = 0
+        @started = false
+        @closed = false
+        @lock = Mutex.new
+        @http = nil
+      end
+
+      def start(timeout)
+        status, body = request("POST", @base, headers: { "Authorization" => "Bearer #{@token}" },
+                                              timeout: [timeout, @timings.request].min)
+        session = body["session"]
+        raise refusal(status, body) unless status == 201 && session.is_a?(String)
+
+        @session = session
+        if @closed
+          end_session
+          raise ConsoleError.new("Closed while connecting.", "network", transport: kind)
+        end
+
+        # The session is already authenticated, so its first message is "auth success".
+        @ready = Latch.new
+        @runner = Thread.new { run }
+        return if @ready.wait(timeout)
+
+        close
+        raise ConsoleError.new("Connecting took longer than #{timeout} s.", "timeout", transport: kind)
+      end
+
+      def send_message(message)
+        raise ConsoleError.new("The session is closed.", "network", transport: kind) if @session.nil? || @closed
+
+        status, body = request("POST", "#{@base}/#{@session}/send",
+                               headers: { "Content-Type" => "text/plain" },
+                               body: JSON.generate({ event: message.event, args: message.args }))
+        return if status == 202
+
+        if status == 410
+          error = gone(body)
+          unless @closed
+            close
+            @handlers.closed.call(error)
+          end
+          raise error
+        end
+        raise ConsoleError.new("Too many messages; the node is dropping them.", "throttled", transport: kind) if status == 429
+
+        detail = body["error"]
+        raise ConsoleError.new(detail.is_a?(String) ? detail : "The node refused the message (#{status}).", "network",
+                               transport: kind)
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        stream = @lock.synchronize { @http }
+        begin
+          stream&.finish
+        rescue StandardError
+          nil
+        end
+        @runner&.kill unless @runner == Thread.current
+        end_session if @session
+      end
+
+      private
+
+      def run
+        kind == "stream" ? stream_loop : poll_loop
+      rescue StandardError => e
+        return if @closed
+
+        error = e.is_a?(ConsoleError) ? e : ConsoleError.new(e.message, "network", transport: kind)
+        was_started = @started
+        close
+        if was_started
+          @handlers.closed.call(error)
+        else
+          @ready&.set(error)
+        end
+      end
+
+      # Tells the node the session is no longer wanted. It would end by itself within a minute.
+      def end_session
+        session = @session
+        Thread.new do
+          request("DELETE", "#{@base}/#{session}", timeout: 5)
+        rescue StandardError
+          nil
+        end
+      end
+
+      def gone(body)
+        ConsoleError.new(ENDED, body["suspended"] ? "suspended" : "network", transport: kind)
+      end
+
+      def refusal(status, body)
+        error = body["error"]
+        message = error.is_a?(String) && !error.empty? ? error : "The node refused the session (#{status})."
+        reason = if body["booting"] then "booting"
+                 elsif body["suspended"] then "suspended"
+                 elsif status == 401 || body["jwt"] then "token"
+                 else "network"
+                 end
+        ConsoleError.new(message, reason, transport: kind)
+      end
+
+      def http_for(uri, read_timeout)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = [@timings.request, 10].min
+        http.read_timeout = read_timeout
+        http.write_timeout = @timings.request
+        http
+      end
+
+      # One request to the node, without the API key: [status, parsed JSON body (or {})].
+      def request(method, url, headers: {}, body: nil, params: nil, timeout: nil)
+        uri = URI(url)
+        uri.query = URI.encode_www_form(params) if params
+        http = http_for(uri, timeout || @timings.request)
+        req = Net::HTTPGenericRequest.new(method, !body.nil?, method != "HEAD", uri.request_uri)
+        req["User-Agent"] = "sillydev-ruby/#{VERSION}"
+        req["Accept"] = "application/json"
+        headers.each { |k, v| req[k] = v }
+        req.body = body if body
+        res = http.start { |h| h.request(req) }
+        [res.code.to_i, parse_json(res.body)]
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+        raise ConsoleError.new("The node took too long to answer.", "timeout", transport: kind)
+      rescue SystemCallError, SocketError, IOError, OpenSSL::SSL::SSLError => e
+        raise ConsoleError.new("Could not reach the node: #{e.message}", "network", transport: kind)
+      end
+
+      def parse_json(text)
+        value = JSON.parse(text.to_s)
+        value.is_a?(Hash) ? value : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def deliver(items)
+        items.each do |m|
+          break if @closed
+          next unless m.is_a?(Hash)
+
+          ident = m["id"]
+          next unless ident.is_a?(Integer) && ident > @cursor
+
+          @cursor = ident
+          message = Console.parse_message(m)
+          next if message.nil?
+
+          unless @started
+            next unless message.event == "auth success"
+
+            @started = true
+            @handlers.message.call(message)
+            @ready.set
+            next
+          end
+          @handlers.message.call(message)
+        end
+      end
+
+      def poll_loop
+        failures = 0
+        until @closed
+          asked = Console.monotonic
+          begin
+            status, body = request("GET", "#{@base}/#{@session}/poll", params: { after: @cursor, wait: @poll_wait },
+                                                                       timeout: @timings.request + @poll_wait)
+            raise gone(body) if status == 410
+            raise ConsoleError.new("Polling failed (#{status}).", "network", transport: kind) unless status.between?(200, 299)
+
+            before = @cursor
+            deliver(body["events"].is_a?(Array) ? body["events"] : [])
+            failures = 0
+            fresh = @cursor != before
+            # Back early with nothing new: a proxy cutting long polls short. Don't ask without end.
+            sleep(@timings.poll_pause) if !body["more"] && !fresh && Console.monotonic - asked < @timings.poll_pause
+          rescue ConsoleError => e
+            return if @closed
+
+            failures += 1
+            raise if e.message == ENDED || !@started || failures >= MAX_FAILURES
+
+            sleep(failures)
+          end
+        end
+      end
+
+      def stream_loop
+        failures = 0
+        until @closed
+          opened = Console.monotonic
+          begin
+            read_stream
+            failures = Console.monotonic - opened > HEALTHY_STREAM ? 0 : failures + 1
+          rescue ConsoleError => e
+            return if @closed
+            raise if e.message == ENDED || !@started
+
+            failures += 1
+          end
+          raise ConsoleError.new("The stream keeps dropping.", "network", transport: kind) if failures >= MAX_FAILURES
+
+          sleep(failures) if failures.positive? && !@closed
+        end
+      end
+
+      # Reads one stream until it ends.
+      def read_stream
+        uri = URI("#{@base}/#{@session}/stream")
+        uri.query = URI.encode_www_form(after: @cursor)
+        # A stream a proxy is holding back looks like a slow one until its first bytes arrive.
+        # The node sends some at once, so waiting long means held back.
+        http = http_for(uri, @timings.first_byte)
+        http.open_timeout = @timings.first_byte
+        @lock.synchronize { @http = http }
+        req = Net::HTTP::Get.new(uri)
+        req["Accept"] = "text/event-stream"
+        req["User-Agent"] = "sillydev-ruby/#{VERSION}"
+        buffer = +""
+        http.start do |h|
+          h.request(req) do |res|
+            status = res.code.to_i
+            raise gone(parse_json(res.read_body)) if status == 410
+            raise ConsoleError.new("Streaming failed (#{status}).", "network", transport: kind) unless status.between?(200, 299)
+
+            res.read_body do |chunk|
+              h.read_timeout = @timings.stream_idle
+              buffer << chunk.to_s.force_encoding(Encoding::UTF_8).gsub("\r\n", "\n").tr("\r", "\n")
+              while (index = buffer.index("\n\n"))
+                block = buffer.slice!(0, index + 2)
+                deliver_event(block)
+              end
+            end
+          end
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise ConsoleError.new(@started ? "The stream went quiet." : "The stream was held back.", "timeout", transport: kind)
+      rescue SystemCallError, SocketError, IOError, OpenSSL::SSL::SSLError => e
+        raise ConsoleError.new("The stream failed: #{e.message}", "network", transport: kind)
+      ensure
+        @lock.synchronize { @http = nil }
+      end
+
+      # Delivers one server-sent event: "id: <n>" and "data: <message>" lines.
+      def deliver_event(block)
+        ident = 0
+        data = []
+        block.split("\n").each do |line|
+          if line.start_with?("id:")
+            ident = Integer(line[3..].strip, exception: false) || 0
+          elsif line.start_with?("data:")
+            value = line[5..]
+            data << (value.start_with?(" ") ? value[1..] : value)
+          end
+        end
+        return if ident.zero? || data.empty?
+
+        body = begin
+          JSON.parse(data.join("\n"))
+        rescue JSON::ParserError
+          nil
+        end
+        deliver([body.merge("id" => ident)]) if body.is_a?(Hash)
+      end
+    end
+
+    # A session on the node that the panel reads for us.
+    class RelayTransport
+      attr_reader :kind
+
+      def initialize(client, server, handlers, interval)
+        @kind = "relay"
+        @client = client
+        @server = server
+        @handlers = handlers
+        @interval = interval
+        @session = nil
+        @cursor = 0
+        @started = false
+        @closed = false
+      end
+
+      def start(timeout)
+        begin
+          session = @client.panel.servers.open_relay(@server)
+        rescue Error => e
+          raise Console.relay_error(e)
+        end
+        raise ConsoleError.new("The panel did not open a session.", "network", transport: kind) if session.to_s.empty?
+
+        @session = session
+        if @closed
+          end_session
+          raise ConsoleError.new("Closed while connecting.", "network", transport: kind)
+        end
+        @ready = Latch.new
+        @runner = Thread.new { run }
+        return if @ready.wait(timeout)
+
+        close
+        raise ConsoleError.new("Connecting took longer than #{timeout} s.", "timeout", transport: kind)
+      end
+
+      def send_message(message)
+        raise ConsoleError.new("The relay is closed.", "network", transport: kind) if @session.nil? || @closed
+
+        @client.panel.servers.send_relay(@server, @session, message.event, *message.args)
+      rescue APIStatusError => e
+        converted = Console.relay_error(e)
+        if e.status_code == 410 && !@closed && converted.is_a?(ConsoleError)
+          close
+          @handlers.closed.call(converted)
+        elsif e.status_code == 429
+          raise ConsoleError.new("Too many messages; the node is dropping them.", "throttled", transport: kind)
+        end
+        raise converted
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @runner&.kill unless @runner == Thread.current
+        end_session if @session
+      end
+
+      private
+
+      def end_session
+        session = @session
+        Thread.new do
+          @client.panel.servers.close_relay(@server, session)
+        rescue StandardError
+          nil
+        end
+      end
+
+      def run
+        relay_loop
+      rescue StandardError => e
+        return if @closed
+
+        converted = e.is_a?(Error) ? Console.relay_error(e) : e
+        was_started = @started
+        close
+        if was_started
+          error = converted.is_a?(ConsoleError) ? converted : ConsoleError.new(converted.message, "network", transport: kind)
+          @handlers.closed.call(error)
+        else
+          @ready.set(converted)
+        end
+      end
+
+      def relay_loop
+        failures = 0
+        until @closed
+          more = false
+          begin
+            data = @client.panel.servers.poll_relay(@server, @session, after: @cursor)
+            events = data.is_a?(Hash) && data["events"].is_a?(Array) ? data["events"] : []
+            more = data.is_a?(Hash) && data["more"] ? true : false
+            failures = 0
+            deliver(events)
+          rescue StandardError => e
+            return if @closed
+
+            failures += 1
+            status = e.is_a?(APIStatusError) ? e.status_code : nil
+            raise if status == 410 || !@started || failures >= MAX_FAILURES
+          end
+          next if more || @closed
+
+          sleep(@interval * [1, failures].max)
+        end
+      end
+
+      def deliver(events)
+        events.each do |m|
+          break if @closed
+          next unless m.is_a?(Hash)
+
+          ident = m["id"]
+          next unless ident.is_a?(Integer) && ident > @cursor
+
+          @cursor = ident
+          message = Console.parse_message(m)
+          next if message.nil?
+
+          unless @started
+            next unless message.event == "auth success"
+
+            @started = true
+            @handlers.message.call(message)
+            @ready.set
+            next
+          end
+          @handlers.message.call(message)
+        end
+      end
+    end
+
+    # Turns an error from the relay's panel endpoints into a ConsoleError, or returns it unchanged.
+    def self.relay_error(error)
+      return error if error.is_a?(ConsoleError)
+      return ConsoleError.new(error.message, "network", transport: "relay") if error.is_a?(APIConnectionError) || error.is_a?(ServerError)
+
+      if error.is_a?(APIStatusError)
+        meta = (error.errors.first || {})["meta"] || {}
+        return ConsoleError.new(error.message, "suspended", transport: "relay") if meta["suspended"]
+        return ConsoleError.new(error.message, "booting", transport: "relay") if meta["booting"]
+        return ConsoleError.new(error.message, "token", transport: "relay") if meta["jwt"]
+        return ConsoleError.new(ENDED, "network", transport: "relay") if error.status_code == 410
+      end
+      # The API key, a missing permission or a missing server: no other way would do better.
+      error
+    end
+
+    # The way in use (or last used): "websocket", "stream", "poll" or "relay".
+    attr_reader :transport
+    # Why the console ended, if it ended with an error.
+    attr_reader :close_reason
+    attr_reader :server
+
+    # Made by client.panel.console.connect.
+    def initialize(client, server, transport: "auto", transports: nil, origin: nil, connect_timeout: nil,
+                   reconnect: true, max_reconnect_attempts: 5, poll_wait: 20, relay_interval: 2.0,
+                   timings: DEFAULT_TIMINGS, buffer: true)
+      transport = transport.to_s
+      unless transport == "auto" || TRANSPORTS.include?(transport)
+        raise ArgumentError, "transport must be \"auto\" or one of #{TRANSPORTS.join(', ')}"
+      end
+
+      @client = client
+      @server = server
+      @kinds = transport == "auto" ? (transports || TRANSPORTS).map(&:to_s) : [transport]
+      @origin = origin || Console.origin_of(client.base_url)
+      @connect_timeout = connect_timeout
+      @reconnect = reconnect
+      @max_reconnects = [max_reconnect_attempts.to_i, 1].max
+      @poll_wait = poll_wait.to_i.clamp(0, 25)
+      @relay_interval = relay_interval
+      @timings = timings
+      @buffer = buffer
+
+      @transport = nil
+      @close_reason = nil
+      @current = nil
+      @credentials = nil
+      @credentials_at = 0.0
+      @last_jwt_renewal = -60.0
+      @ended = false
+      @listeners = Hash.new { |h, k| h[k] = [] }
+      @close_listeners = []
+      @queue = Queue.new
+      @state_lock = Mutex.new
+      # Set once a connection is in use, so a message sent meanwhile waits for it.
+      @ready = Latch.new
+    end
+
+    def inspect
+      "#<#{self.class.name} server=#{@server.inspect} transport=#{@transport.inspect} closed=#{@ended}>"
+    end
+
+    # Whether the console has been closed, or has ended.
+    def closed?
+      @ended
+    end
+
+    # Connects (called by client.panel.console.connect). Returns self.
+    def open
+      connect_once
+      @ready.set
+      self
+    rescue StandardError => e
+      @ended = true
+      @ready.set(e)
+      raise
+    end
+
+    # Calls the block with every message whose event is event ("*" for every one), on the
+    # console's thread. Returns a proc that removes the listener.
+    def on(event, &listener)
+      raise ArgumentError, "on needs a block" unless listener
+
+      @state_lock.synchronize { @listeners[event.to_s] << listener }
+      -> { @state_lock.synchronize { @listeners[event.to_s].delete(listener) } }
+    end
+
+    # Calls the block once the console ends: with the ConsoleError, or nil after #close.
+    def on_close(&listener)
+      raise ArgumentError, "on_close needs a block" unless listener
+
+      @state_lock.synchronize { @close_listeners << listener }
+      -> { @state_lock.synchronize { @close_listeners.delete(listener) } }
+    end
+
+    # Sends a websocket message, such as send_message("send command", "say hi"). Waits while
+    # reconnecting.
+    def send_message(event, *args)
+      raise(@close_reason || ConsoleError.new("The console is closed.", "network")) if @ended
+
+      @ready.wait
+      current = @current
+      raise(@close_reason || ConsoleError.new("The console is closed.", "network")) if current.nil? || @ended
+
+      current.send_message(ConsoleMessage.new(event.to_s, args.map(&:to_s)))
+      nil
+    end
+
+    # Types a command into the console (needs control.console; ignored while the server is offline).
+    def command(command)
+      send_message("send command", command)
+    end
+
+    # "start", "stop", "restart" or "kill" the server (needs the matching control.* permission).
+    def power(signal)
+      send_message("set state", signal)
+    end
+
+    # Asks for the recent console history; it arrives as "console output" messages.
+    def request_logs
+      send_message("send logs")
+    end
+
+    # Asks for a "stats" message straight away.
+    def request_stats
+      send_message("send stats")
+    end
+
+    # The messages as they arrive, until the console ends (raising its close_reason, if any) or,
+    # with a timeout, until timeout seconds pass without one. Without a block, an Enumerator.
+    def each(timeout: nil)
+      return enum_for(:each, timeout: timeout) unless block_given?
+
+      loop do
+        item = pop(timeout)
+        return if item == :timeout
+
+        if item == :done
+          @queue << :done
+          raise @close_reason if @close_reason
+
+          return
+        end
+        yield item
+      end
+    end
+    alias messages each
+
+    # Closes the console, telling the node (or the panel) it is done with.
+    def close
+      finish(nil)
+      nil
+    end
+
+    # -- used by the transports and the threads ---------------------------------------------------
+
+    private
+
+    def pop(timeout)
+      return @queue.pop if timeout.nil?
+      return @queue.pop(timeout: timeout) || :timeout if RUBY_VERSION >= "3.2"
+
+      deadline = Console.monotonic + timeout
+      loop do
+        begin
+          return @queue.pop(true)
+        rescue ThreadError
+          nil
+        end
+        return :timeout if Console.monotonic >= deadline
+
+        sleep(0.02)
+      end
+    end
+
+    def timeout_for(kind)
+      case @connect_timeout
+      when Numeric then @connect_timeout.to_f
+      when Hash then (@connect_timeout[kind] || @connect_timeout[kind.to_sym] || CONNECT_TIMEOUTS[kind]).to_f
+      else CONNECT_TIMEOUTS[kind]
+      end
+    end
+
+    def creds(force: false)
+      return @credentials if !force && @credentials && Console.monotonic - @credentials_at < TOKEN_AGE
+
+      @credentials = @client.panel.servers.websocket(@server).to_h
+      @credentials_at = Console.monotonic
+      @credentials
+    end
+
+    def build(kind, handlers)
+      case kind
+      when "websocket"
+        c = creds
+        WebsocketTransport.new(c["socket"].to_s, @origin, c["token"].to_s, handlers)
+      when "stream", "poll"
+        c = creds
+        raise ConsoleError.new("The panel did not give a sessions address.", "unavailable", transport: kind) if c["sessions"].to_s.empty?
+
+        SessionTransport.new(kind, c["sessions"].to_s, c["token"].to_s, handlers, @poll_wait, @timings)
+      when "relay"
+        RelayTransport.new(@client, @server, handlers, @relay_interval)
+      else
+        raise ConsoleError.new("Unknown transport #{kind}.", "unavailable")
+      end
+    end
+
+    # Connects with the first way that works.
+    def connect_once
+      failures = []
+      @kinds.each do |kind|
+        tries = 0
+        loop do
+          raise ConsoleError.new("The console was closed while connecting.", "network") if @ended
+
+          holder = {}
+          closed = lambda do |error|
+            lost(error) if !@current.nil? && holder[:transport].equal?(@current)
+          end
+          transport = nil
+          error = nil
+          begin
+            transport = build(kind, Handlers.new(method(:dispatch), closed))
+            holder[:transport] = transport
+            transport.start(timeout_for(kind))
+          rescue ConsoleError => e
+            transport&.close
+            error = e
+          rescue StandardError
+            transport&.close
+            raise
+          end
+          if error.nil?
+            if @ended
+              transport.close
+              raise ConsoleError.new("The console was closed while connecting.", "network")
+            end
+            @current = transport
+            @transport = kind
+            return # rubocop:disable Lint/NonLocalExitFromIterator
+          end
+          if error.reason == "token" && tries.zero? && kind != "relay"
+            # The token may have been too old: one more go with a new one.
+            tries += 1
+            @credentials = nil
+            next
+          end
+          raise error if @kinds.length == 1 || %w[suspended booting].include?(error.reason)
+
+          failures << error
+          break
+        end
+      end
+      summary = failures.map { |f| "#{f.transport}: #{f.message}" }.join("; ")
+      reason = failures.empty? ? "unavailable" : failures.last.reason
+      raise ConsoleError.new("Could not connect to the console (#{summary}).", reason, attempts: failures)
+    end
+
+    def dispatch(message)
+      return if @ended
+
+      if ["token expiring", "token expired"].include?(message.event)
+        renew
+      elsif message.event == "jwt error" && Console.monotonic - @last_jwt_renewal > 30
+        @last_jwt_renewal = Console.monotonic
+        renew
+      end
+
+      listeners = @state_lock.synchronize { @listeners[message.event].dup + @listeners["*"].dup }
+      listeners.each do |listener|
+        listener.call(message)
+      rescue StandardError => e
+        warn "sillydev: a console listener failed: #{e.class}: #{e.message}"
+      end
+      if @buffer
+        @queue << message
+        @queue.pop(true) while @queue.size > QUEUE_LIMIT
+      end
+
+      finish(ConsoleError.new("The server has been deleted.", "deleted", transport: @transport)) if message.event == "deleted"
+    rescue ThreadError
+      nil
+    end
+
+    # Sends a fresh token on the connection in use.
+    def renew
+      return if @renewing&.alive?
+
+      @renewing = Thread.new do
+        c = creds(force: true)
+        @current&.send_message(ConsoleMessage.new("auth", [c["token"].to_s]))
+      rescue StandardError
+        nil # The node ends a connection whose token expires; reconnecting gets a new one.
+      end
+    end
+
+    # The connection in use dropped: connect again, or end.
+    def lost(error)
+      @current = nil
+      return if @ended
+
+      if !@reconnect || %w[suspended deleted].include?(error.reason)
+        finish(error)
+        return
+      end
+
+      @ready = Latch.new
+      ready = @ready
+      @reconnector = Thread.new do
+        last = error
+        @max_reconnects.times do |attempt|
+          break if @ended
+
+          sleep([2.0**attempt, 30.0].min)
+          break if @ended
+
+          begin
+            connect_once
+            last = nil
+            break
+          rescue ConsoleError => e
+            last = e
+            break if %w[suspended deleted].include?(e.reason)
+          rescue APIConnectionError, ServerError => e
+            last = e
+          rescue StandardError => e
+            last = e # The key or a permission: no use trying again.
+            break
+          end
+        end
+        if last.nil?
+          ready.set
+        else
+          reason = last.is_a?(ConsoleError) ? last : ConsoleError.new("Could not reconnect: #{last.message}", "network")
+          finish(reason)
+          ready.set(reason)
+        end
+      end
+    end
+
+    def finish(error)
+      listeners = @state_lock.synchronize do
+        return if @ended
+
+        @ended = true
+        @close_reason = error
+        @close_listeners.dup
+      end
+      current = @current
+      @current = nil
+      current&.close
+      @reconnector&.kill unless @reconnector.nil? || @reconnector == Thread.current
+      @ready.set(error || ConsoleError.new("The console is closed.", "network")) unless @ready.done?
+      @queue << :done
+      listeners.each do |listener|
+        listener.call(error)
+      rescue StandardError => e
+        warn "sillydev: a console close listener failed: #{e.class}: #{e.message}"
+      end
+    end
+  end
+
+  # client.panel.console: connect to a server's live console, or read its recent output.
+  class ConsoleApi
+    def initialize(client)
+      @client = client
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    # Connects to a server's console, trying the websocket, then a streamed, then a polled session
+    # on the node, then the panel's relay, unless transport: names one.
+    #
+    # origin: is the Origin sent with the websocket (default: the origin of the client's base_url);
+    # connect_timeout: the seconds each way may take (a number, or a hash per way; default
+    # websocket 6, stream 8, poll and relay 10); reconnect: whether to connect again when the
+    # connection drops (up to max_reconnect_attempts: in a row); poll_wait: the seconds a poll
+    # waits on the node (at most 25); relay_interval: the seconds between reads of the relay.
+    #
+    # With a block, yields the console and closes it afterwards. Uses operationIds
+    # getWebsocketCredentials and openConsoleRelay.
+    def connect(server, **options)
+      console = Console.new(@client, server, **options).open
+      return console unless block_given?
+
+      begin
+        yield console
+      ensure
+        console.close
+      end
+    end
+
+    # The server's recent console output, oldest line first (the node keeps the last 150 or so).
+    #
+    # An empty array while the server is offline, since the node only has the output of a running
+    # server. Connects as connect does and closes again; timeout: is the seconds to wait in all,
+    # and quiet: the seconds without a new line after which the history is taken as complete
+    # (default 0.5, or 2.5 through the relay).
+    def history(server, timeout: 15.0, quiet: nil, **options)
+      relay = options[:transport].to_s == "relay"
+      quiet ||= relay ? (options[:relay_interval] || 2.0) + 0.5 : 0.5
+      console = Console.new(@client, server, **options, reconnect: false, buffer: false)
+      History.new(console, timeout, quiet).run
+    end
+
+    # Collects the history: waits for the first "status", asks for the logs and then the stats
+    # (the node answers in order, so the stats come after every line), and stops once no new line
+    # has come for a while after the stats.
+    class History
+      def initialize(console, timeout, quiet)
+        @console = console
+        @timeout = timeout
+        @quiet = quiet
+        @lines = []
+        @asked = false
+        @stats = false
+        @last = nil
+        @done = Console::Latch.new
+        @lock = Mutex.new
+      end
+
+      def run
+        @console.on("*") { |message| receive(message) }
+        @console.on_close { |error| @done.set(error) }
+        deadline = Console.monotonic + @timeout
+        @console.open
+        loop do
+          remaining = deadline - Console.monotonic
+          if remaining <= 0
+            unless @asked
+              raise ConsoleError.new("No status from the server within #{@timeout} s.", "timeout",
+                                     transport: @console.transport)
+            end
+
+            break
+          end
+          break if @done.wait([remaining, 0.05].min)
+
+          quiet_since = @lock.synchronize { @stats ? @last : nil }
+          break if quiet_since && Console.monotonic - quiet_since >= @quiet
+        end
+        @lock.synchronize { @lines.dup }
+      ensure
+        @console.close
+      end
+
+      private
+
+      def receive(message)
+        unless @asked
+          return unless message.event == "status"
+
+          if message.args.first == "offline"
+            @done.set
+            return
+          end
+          @asked = true
+          Thread.new do
+            @console.request_logs
+            @console.request_stats
+          rescue StandardError => e
+            @done.set(e)
+          end
+          return
+        end
+        @lock.synchronize do
+          case message.event
+          when "console output"
+            @lines << (message.args.first || "")
+            @last = Console.monotonic if @stats
+          when "stats"
+            @stats = true
+            @last = Console.monotonic
+          end
+        end
+      end
+    end
+  end
+end