lynkeus-client 0.2.0

package/README.md

@@ -0,0 +1,18 @@
+# lynkeus-client
+
+Node driver for apps running [lynkeus-agent](../agent).
+
+```ts
+import { AgentServer } from 'lynkeus-client';
+
+const agent = new AgentServer({ port: 8123 });
+await agent.listen();
+await agent.waitForApp();
+
+await agent.call('press', { testId: 'get-started-button' });
+await agent.call('waitFor', { route: 'Auth.Login' });
+console.log((await agent.call('screen')).elements.length);
+```
+
+`call` is typed for the core methods and open for app commands
+(`agent.call('reset')`). See [docs/PROTOCOL.md](../../docs/PROTOCOL.md).

package/lib/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The driver end of the link. The app dials in and keeps redialing, so the
+ * server is the stable side: start it once, and every app launch reattaches.
+ */
+import { EventEmitter } from 'node:events';
+import type { CoreMethods, HelloEvent } from 'lynkeus-protocol';
+export type { AgentEvent, CoreMethods, Element, HelloEvent, Screen, Target, RequestRecord } from 'lynkeus-protocol';
+export type AgentServerOptions = {
+    port?: number;
+    host?: string;
+    /** Must match the app's `token`; sent as the first message. */
+    token?: string;
+    /** How long in-flight calls wait for the app to reconnect before failing (default 2500 ms). */
+    reconnectGraceMs?: number;
+};
+export declare class AgentError extends Error {
+    code?: string;
+    constructor(message: string, code?: string);
+}
+export declare class AgentServer extends EventEmitter {
+    #private;
+    readonly port: number;
+    readonly host: string;
+    constructor(options?: AgentServerOptions);
+    get connected(): boolean;
+    /** What the app said about itself when it attached. */
+    get hello(): HelloEvent | null;
+    listen(): Promise<void>;
+    close(): Promise<void>;
+    waitForApp(timeoutMs?: number): Promise<HelloEvent>;
+    /** A core method, typed. */
+    call<M extends keyof CoreMethods>(method: M, params?: CoreMethods[M]['params'], timeoutMs?: number): Promise<CoreMethods[M]['result']>;
+    /** An app command registered with `qa.register`. */
+    call<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
+}

package/lib/index.js

@@ -0,0 +1,157 @@
+/**
+ * The driver end of the link. The app dials in and keeps redialing, so the
+ * server is the stable side: start it once, and every app launch reattaches.
+ */
+import { EventEmitter } from 'node:events';
+import { WebSocket, WebSocketServer } from 'ws';
+export class AgentError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+export class AgentServer extends EventEmitter {
+    port;
+    host;
+    #token;
+    #session = Math.random().toString(36).slice(2) + Date.now().toString(36);
+    #server = null;
+    #socket = null;
+    #pending = new Map();
+    #nextId = 1;
+    #hello = null;
+    #graceTimer = null;
+    #reconnectGraceMs;
+    constructor(options = {}) {
+        super();
+        this.port = options.port ?? 8123;
+        this.host = options.host ?? '127.0.0.1';
+        this.#token = options.token;
+        this.#reconnectGraceMs = options.reconnectGraceMs ?? 2500;
+    }
+    get connected() {
+        return this.#socket?.readyState === WebSocket.OPEN && this.#hello !== null;
+    }
+    /** What the app said about itself when it attached. */
+    get hello() {
+        return this.#hello;
+    }
+    async listen() {
+        if (this.#server)
+            return;
+        const server = new WebSocketServer({ port: this.port, host: this.host });
+        this.#server = server;
+        server.on('connection', (socket) => this.#attach(socket));
+        await new Promise((resolve, reject) => {
+            server.once('listening', () => resolve());
+            server.once('error', reject);
+        });
+    }
+    async close() {
+        this.#cancelGrace();
+        this.#failPending(new AgentError('Agent server closed'));
+        this.#socket?.close();
+        this.#socket = null;
+        this.#hello = null;
+        await new Promise((resolve) => (this.#server ? this.#server.close(() => resolve()) : resolve()));
+        this.#server = null;
+    }
+    async waitForApp(timeoutMs = 15_000) {
+        if (this.connected && this.#hello)
+            return this.#hello;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.off('hello', onHello);
+                reject(new AgentError(`No app attached on ${this.host}:${this.port} within ${timeoutMs}ms. Is a dev build running with <Lynkeus>?`));
+            }, timeoutMs);
+            const onHello = (hello) => {
+                clearTimeout(timer);
+                resolve(hello);
+            };
+            this.once('hello', onHello);
+        });
+    }
+    // The deadline keeps running across a reconnect: a resent request gets only the time that is left.
+    async call(method, params, timeoutMs = 20_000) {
+        const socket = this.#socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            throw new AgentError('No app attached');
+        const id = this.#nextId++;
+        const request = JSON.stringify({ id, method, params });
+        const result = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new AgentError(`${method} timed out after ${timeoutMs}ms`, 'timeout'));
+            }, timeoutMs);
+            this.#pending.set(id, { resolve, reject, timer, request });
+        });
+        socket.send(request);
+        return result;
+    }
+    #cancelGrace() {
+        if (this.#graceTimer)
+            clearTimeout(this.#graceTimer);
+        this.#graceTimer = null;
+    }
+    #failPending(error) {
+        for (const pending of this.#pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+    #attach(socket) {
+        // A relaunch reconnects before the old socket notices; the newest wins.
+        this.#socket?.close();
+        this.#socket = socket;
+        this.#hello = null;
+        this.#cancelGrace();
+        socket.send(JSON.stringify({ event: 'auth', session: this.#session, token: this.#token }));
+        socket.on('message', (data) => {
+            let message;
+            try {
+                message = JSON.parse(String(data));
+            }
+            catch {
+                return;
+            }
+            if ('event' in message) {
+                if (message.event === 'hello') {
+                    this.#hello = message;
+                    // Resend what the previous socket may have dropped, but only once this one has spoken the
+                    // protocol: a bare local connection could be any process.
+                    if (socket.readyState === WebSocket.OPEN) {
+                        for (const pending of this.#pending.values())
+                            socket.send(pending.request);
+                    }
+                }
+                this.emit(message.event, message);
+                return;
+            }
+            const pending = this.#pending.get(message.id);
+            if (!pending)
+                return;
+            this.#pending.delete(message.id);
+            clearTimeout(pending.timer);
+            if ('error' in message)
+                pending.reject(new AgentError(message.error.message, message.error.code));
+            else
+                pending.resolve(message.result);
+        });
+        socket.on('close', () => {
+            if (this.#socket !== socket)
+                return;
+            this.#socket = null;
+            this.#hello = null;
+            this.emit('disconnected');
+            // Dev builds redial within moments: hold in-flight calls for the next hello to resend.
+            if (this.#pending.size === 0)
+                return;
+            this.#graceTimer = setTimeout(() => {
+                this.#graceTimer = null;
+                this.#failPending(new AgentError('App disconnected mid-call', 'disconnected'));
+            }, this.#reconnectGraceMs);
+        });
+    }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "lynkeus-client",
+  "version": "0.2.0",
+  "description": "Node driver for apps running lynkeus-agent: attach, read the screen, press, type, wait.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test src/__tests__/*.test.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonamischener/lynkeus.git",
+    "directory": "packages/client"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "lynkeus-protocol": "^0.2.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.19.2",
+    "typescript": "^6.0.3"
+  },
+  "homepage": "https://github.com/jonamischener/lynkeus#readme"
+}

package/src/__tests__/server.test.ts

@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import { after, test } from 'node:test';
+
+import { WebSocket } from 'ws';
+
+import { AgentError, AgentServer } from '../index.js';
+
+let port = 18_500;
+const servers: AgentServer[] = [];
+after(async () => {
+  for (const s of servers) await s.close();
+});
+
+const serve = async (options: ConstructorParameters<typeof AgentServer>[0] = {}) => {
+  const server = new AgentServer({ port: port++, ...options });
+  servers.push(server);
+  await server.listen();
+  return server;
+};
+
+type Message = { event?: string; token?: string; id?: number; method?: string };
+
+const fakeApp = async (server: AgentServer, answer: (m: Message) => unknown = () => ({ ok: true })) => {
+  const socket = new WebSocket(`ws://127.0.0.1:${server.port}`);
+  const seen: Message[] = [];
+  socket.on('message', (data) => {
+    const m = JSON.parse(String(data)) as Message;
+    seen.push(m);
+    if (m.event === 'auth') socket.send(JSON.stringify({ event: 'hello', protocolVersion: 1, platform: 'ios', native: false, commands: [] }));
+    else if (m.id !== undefined) {
+      const reply = answer(m);
+      if (reply !== undefined) socket.send(JSON.stringify({ id: m.id, ...(reply as object) }));
+    }
+  });
+  await new Promise((r) => socket.once('open', r));
+  return { socket, seen };
+};
+
+test('an app that dials in is sent the token first and is ready once it says hello', async () => {
+  const server = await serve({ token: 'secret' });
+  const app = await fakeApp(server);
+  const hello = await server.waitForApp(2000);
+  assert.equal(hello.platform, 'ios');
+  assert.equal(server.connected, true);
+  assert.equal(app.seen[0]?.event, 'auth');
+  assert.equal(app.seen[0]?.token, 'secret');
+  app.socket.close();
+});
+
+test('a call gets the result the app sends back, and an error as an AgentError with its code', async () => {
+  const server = await serve();
+  const app = await fakeApp(server, (m) => (m.method === 'ping' ? { result: { pong: true } } : { error: { message: 'Unknown method', code: 'unknown' } }));
+  await server.waitForApp(2000);
+  assert.deepEqual(await server.call('ping'), { pong: true });
+  await assert.rejects(server.call('nope'), (e: unknown) => e instanceof AgentError && e.code === 'unknown');
+  app.socket.close();
+});
+
+test('a call the app never answers times out with the timeout code', async () => {
+  const server = await serve();
+  const app = await fakeApp(server, () => undefined);
+  await server.waitForApp(2000);
+  await assert.rejects(server.call('screen', undefined, 100), (e: unknown) => e instanceof AgentError && e.code === 'timeout');
+  app.socket.close();
+});
+
+test('with no app attached, waiting says so and a call refuses at once', async () => {
+  const server = await serve();
+  await assert.rejects(server.waitForApp(50), /No app attached/);
+  await assert.rejects(server.call('ping'), /No app attached/);
+});
+
+test('a call in flight when the app drops is resent to the app that comes back', async () => {
+  const server = await serve({ reconnectGraceMs: 1000 });
+  const first = await fakeApp(server, () => undefined);
+  await server.waitForApp(2000);
+  const pending = server.call('screen', undefined, 3000);
+  await new Promise((r) => setTimeout(r, 50));
+  first.socket.close();
+  const second = await fakeApp(server, () => ({ result: { route: 'Settings.Main' } }));
+  assert.deepEqual(await pending, { route: 'Settings.Main' });
+  second.socket.close();
+});
+
+test('a call in flight fails as disconnected when the app does not come back in time', async () => {
+  const server = await serve({ reconnectGraceMs: 100 });
+  const app = await fakeApp(server, () => undefined);
+  await server.waitForApp(2000);
+  const pending = server.call('screen', undefined, 3000);
+  await new Promise((r) => setTimeout(r, 50));
+  app.socket.close();
+  await assert.rejects(pending, (e: unknown) => e instanceof AgentError && e.code === 'disconnected');
+});

package/src/index.ts

@@ -0,0 +1,186 @@
+/**
+ * The driver end of the link. The app dials in and keeps redialing, so the
+ * server is the stable side: start it once, and every app launch reattaches.
+ */
+import { EventEmitter } from 'node:events';
+
+import { WebSocket, WebSocketServer } from 'ws';
+
+import type { AgentEvent, CoreMethods, HelloEvent, Response } from 'lynkeus-protocol';
+
+export type { AgentEvent, CoreMethods, Element, HelloEvent, Screen, Target, RequestRecord } from 'lynkeus-protocol';
+
+export type AgentServerOptions = {
+  port?: number;
+  host?: string;
+  /** Must match the app's `token`; sent as the first message. */
+  token?: string;
+  /** How long in-flight calls wait for the app to reconnect before failing (default 2500 ms). */
+  reconnectGraceMs?: number;
+};
+
+type Pending = {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+  request: string;
+};
+
+export class AgentError extends Error {
+  code?: string;
+  constructor(message: string, code?: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export class AgentServer extends EventEmitter {
+  readonly port: number;
+  readonly host: string;
+
+  #token?: string;
+  #session = Math.random().toString(36).slice(2) + Date.now().toString(36);
+  #server: WebSocketServer | null = null;
+  #socket: WebSocket | null = null;
+  #pending = new Map<number, Pending>();
+  #nextId = 1;
+  #hello: HelloEvent | null = null;
+  #graceTimer: ReturnType<typeof setTimeout> | null = null;
+  #reconnectGraceMs: number;
+
+  constructor(options: AgentServerOptions = {}) {
+    super();
+    this.port = options.port ?? 8123;
+    this.host = options.host ?? '127.0.0.1';
+    this.#token = options.token;
+    this.#reconnectGraceMs = options.reconnectGraceMs ?? 2500;
+  }
+
+  get connected(): boolean {
+    return this.#socket?.readyState === WebSocket.OPEN && this.#hello !== null;
+  }
+
+  /** What the app said about itself when it attached. */
+  get hello(): HelloEvent | null {
+    return this.#hello;
+  }
+
+  async listen(): Promise<void> {
+    if (this.#server) return;
+    const server = new WebSocketServer({ port: this.port, host: this.host });
+    this.#server = server;
+    server.on('connection', (socket) => this.#attach(socket));
+    await new Promise<void>((resolve, reject) => {
+      server.once('listening', () => resolve());
+      server.once('error', reject);
+    });
+  }
+
+  async close(): Promise<void> {
+    this.#cancelGrace();
+    this.#failPending(new AgentError('Agent server closed'));
+    this.#socket?.close();
+    this.#socket = null;
+    this.#hello = null;
+    await new Promise<void>((resolve) => (this.#server ? this.#server.close(() => resolve()) : resolve()));
+    this.#server = null;
+  }
+
+  async waitForApp(timeoutMs = 15_000): Promise<HelloEvent> {
+    if (this.connected && this.#hello) return this.#hello;
+    return new Promise<HelloEvent>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.off('hello', onHello);
+        reject(new AgentError(`No app attached on ${this.host}:${this.port} within ${timeoutMs}ms. Is a dev build running with <Lynkeus>?`));
+      }, timeoutMs);
+      const onHello = (hello: HelloEvent) => {
+        clearTimeout(timer);
+        resolve(hello);
+      };
+      this.once('hello', onHello);
+    });
+  }
+
+  /** A core method, typed. */
+  async call<M extends keyof CoreMethods>(method: M, params?: CoreMethods[M]['params'], timeoutMs?: number): Promise<CoreMethods[M]['result']>;
+  /** An app command registered with `qa.register`. */
+  async call<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
+  // The deadline keeps running across a reconnect: a resent request gets only the time that is left.
+  async call(method: string, params?: unknown, timeoutMs = 20_000): Promise<unknown> {
+    const socket = this.#socket;
+    if (!socket || socket.readyState !== WebSocket.OPEN) throw new AgentError('No app attached');
+    const id = this.#nextId++;
+    const request = JSON.stringify({ id, method, params });
+    const result = new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new AgentError(`${method} timed out after ${timeoutMs}ms`, 'timeout'));
+      }, timeoutMs);
+      this.#pending.set(id, { resolve, reject, timer, request });
+    });
+    socket.send(request);
+    return result;
+  }
+
+  #cancelGrace(): void {
+    if (this.#graceTimer) clearTimeout(this.#graceTimer);
+    this.#graceTimer = null;
+  }
+
+  #failPending(error: AgentError): void {
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.#pending.clear();
+  }
+
+  #attach(socket: WebSocket): void {
+    // A relaunch reconnects before the old socket notices; the newest wins.
+    this.#socket?.close();
+    this.#socket = socket;
+    this.#hello = null;
+    this.#cancelGrace();
+    socket.send(JSON.stringify({ event: 'auth', session: this.#session, token: this.#token }));
+
+    socket.on('message', (data) => {
+      let message: Response | AgentEvent;
+      try {
+        message = JSON.parse(String(data));
+      } catch {
+        return;
+      }
+      if ('event' in message) {
+        if (message.event === 'hello') {
+          this.#hello = message;
+          // Resend what the previous socket may have dropped, but only once this one has spoken the
+          // protocol: a bare local connection could be any process.
+          if (socket.readyState === WebSocket.OPEN) {
+            for (const pending of this.#pending.values()) socket.send(pending.request);
+          }
+        }
+        this.emit(message.event, message);
+        return;
+      }
+      const pending = this.#pending.get(message.id);
+      if (!pending) return;
+      this.#pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if ('error' in message) pending.reject(new AgentError(message.error.message, message.error.code));
+      else pending.resolve(message.result);
+    });
+
+    socket.on('close', () => {
+      if (this.#socket !== socket) return;
+      this.#socket = null;
+      this.#hello = null;
+      this.emit('disconnected');
+      // Dev builds redial within moments: hold in-flight calls for the next hello to resend.
+      if (this.#pending.size === 0) return;
+      this.#graceTimer = setTimeout(() => {
+        this.#graceTimer = null;
+        this.#failPending(new AgentError('App disconnected mid-call', 'disconnected'));
+      }, this.#reconnectGraceMs);
+    });
+  }
+}