ravensight-playtest 0.1.0

package/src/run/drivers/godot-rpc.js

@@ -0,0 +1,225 @@
+// Client for the Godot driver's wire protocol: newline delimited JSON-RPC 2.0
+// over a loopback TCP socket (addons/ravensight_driver/driver.gd, spec 07).
+//
+// This is the Node replacement for the proof of concept's client.py. It keeps
+// the same shape (one JSON object per line, ids matched to pending calls) and
+// adds the parts a long persona run needs: per-call timeouts, a queue for the
+// server's interleaved "event" notifications, a hard cap on response size, and
+// a single rejection path so a dead game never leaves a call hanging forever.
+import { EventEmitter } from 'node:events';
+import net from 'node:net';
+
+const NEWLINE = 0x0a;
+
+export const DEFAULT_PORT = 47800;
+// Screenshots travel as base64 inside a single line, so responses are allowed
+// to be much larger than requests.
+export const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+
+/** A JSON-RPC error returned by the driver, with its spec 07 numeric code. */
+export class DriverRpcError extends Error {
+  constructor(method, { code, message, data }) {
+    super(`${method}: ${code} ${message}`);
+    this.name = 'DriverRpcError';
+    this.code = code;
+    this.rpcMessage = message;
+    this.data = data;
+  }
+}
+
+/** Raised when the socket goes away, which usually means the game exited. */
+export class DriverClosedError extends Error {
+  constructor(message = 'driver connection closed') {
+    super(message);
+    this.name = 'DriverClosedError';
+  }
+}
+
+export class DriverTimeoutError extends Error {
+  constructor(method, timeoutMs) {
+    super(`${method}: no response within ${timeoutMs}ms`);
+    this.name = 'DriverTimeoutError';
+    this.method = method;
+  }
+}
+
+export class GodotRpcClient extends EventEmitter {
+  constructor({
+    host = '127.0.0.1',
+    port = DEFAULT_PORT,
+    timeoutMs = 15000,
+    maxResponseBytes = MAX_RESPONSE_BYTES,
+  } = {}) {
+    super();
+    this.host = host;
+    this.port = port;
+    this.timeoutMs = timeoutMs;
+    this.maxResponseBytes = maxResponseBytes;
+    this.socket = null;
+    this.closed = false;
+    this.events = [];
+    this._nextId = 1;
+    this._pending = new Map();
+    this._buffer = Buffer.alloc(0);
+  }
+
+  /**
+   * Dials the driver, retrying while the game boots. The driver only ever
+   * listens on loopback, so a non loopback host is refused here too rather
+   * than being attempted and failing obscurely.
+   */
+  async connect({ attempts = 240, delayMs = 250 } = {}) {
+    if (!isLoopbackHost(this.host)) {
+      throw new Error(`refusing to dial non loopback host ${this.host}`);
+    }
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      try {
+        this.socket = await openSocket(this.host, this.port);
+        this._attach(this.socket);
+        this.closed = false;
+        return this;
+      } catch (error) {
+        lastError = error;
+        await sleep(delayMs);
+      }
+    }
+    throw new Error(
+      `could not connect to the Godot driver at ${this.host}:${this.port}: ${lastError?.message ?? 'unknown error'}`,
+    );
+  }
+
+  _attach(socket) {
+    socket.setNoDelay(true);
+    socket.on('data', (chunk) => this._onData(chunk));
+    socket.on('error', (error) => this._fail(new DriverClosedError(error.message)));
+    socket.on('close', () => this._fail(new DriverClosedError()));
+  }
+
+  _onData(chunk) {
+    this._buffer = Buffer.concat([this._buffer, chunk]);
+    for (;;) {
+      const index = this._buffer.indexOf(NEWLINE);
+      if (index === -1) {
+        if (this._buffer.length > this.maxResponseBytes) {
+          this._fail(
+            new DriverClosedError(`driver response exceeded ${this.maxResponseBytes} bytes`),
+          );
+        }
+        return;
+      }
+      const line = this._buffer.subarray(0, index).toString('utf8').trim();
+      this._buffer = this._buffer.subarray(index + 1);
+      if (line) this._onLine(line);
+    }
+  }
+
+  _onLine(line) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      this.emit('protocolError', new Error(`driver sent invalid JSON: ${line.slice(0, 200)}`));
+      return;
+    }
+    if (message.method === 'event') {
+      const params = message.params ?? {};
+      this.events.push(params);
+      this.emit('event', params);
+      return;
+    }
+    const pending = this._pending.get(message.id);
+    if (!pending) {
+      // An id we are not waiting for: a late reply after a timeout, or the
+      // unsolicited busy error the driver sends to a second client.
+      this.emit('orphan', message);
+      return;
+    }
+    this._pending.delete(message.id);
+    clearTimeout(pending.timer);
+    if (message.error) {
+      pending.reject(new DriverRpcError(pending.method, message.error));
+      return;
+    }
+    pending.resolve(message.result ?? {});
+  }
+
+  _fail(error) {
+    if (this.closed) return;
+    this.closed = true;
+    for (const [id, pending] of this._pending) {
+      clearTimeout(pending.timer);
+      this._pending.delete(id);
+      pending.reject(error);
+    }
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+    this.emit('closed', error);
+  }
+
+  async call(method, params = {}, { timeoutMs = this.timeoutMs } = {}) {
+    if (this.closed || !this.socket) throw new DriverClosedError();
+    const id = this._nextId;
+    this._nextId += 1;
+    const line = `${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        reject(new DriverTimeoutError(method, timeoutMs));
+      }, timeoutMs);
+      if (typeof timer.unref === 'function') timer.unref();
+      this._pending.set(id, { method, resolve, reject, timer });
+      this.socket.write(line, (error) => {
+        if (!error) return;
+        this._pending.delete(id);
+        clearTimeout(timer);
+        reject(new DriverClosedError(error.message));
+      });
+    });
+  }
+
+  /** Returns the notifications received since the previous drain. */
+  drainEvents() {
+    const drained = this.events;
+    this.events = [];
+    return drained;
+  }
+
+  close() {
+    this._fail(new DriverClosedError('closed by client'));
+  }
+}
+
+/**
+ * Only the two literal loopback addresses. "localhost" is deliberately not
+ * accepted: what it resolves to is up to /etc/hosts and the resolver, so it is
+ * not a guarantee that the connection stays on the machine, and the driver's
+ * one hard promise is that it never leaves it.
+ */
+export function isLoopbackHost(host) {
+  return host === '127.0.0.1' || host === '::1';
+}
+
+function openSocket(host, port) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection({ host, port });
+    const onError = (error) => {
+      socket.destroy();
+      reject(error);
+    };
+    socket.once('error', onError);
+    socket.once('connect', () => {
+      socket.removeListener('error', onError);
+      resolve(socket);
+    });
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    if (typeof timer.unref === 'function') timer.unref();
+  });
+}