@quenty/studio-bridge 0.7.1 → 0.9.0

package/src/server/pending-request-map.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { PendingRequestMap } from './pending-request-map.js';
+
+describe('PendingRequestMap', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('happy path', () => {
+    it('resolves the promise when resolveRequest is called', async () => {
+      const map = new PendingRequestMap<string>();
+      const promise = map.addRequestAsync('req-1', 5000);
+
+      map.resolveRequest('req-1', 'hello');
+
+      await expect(promise).resolves.toBe('hello');
+    });
+
+    it('resolves with an object value', async () => {
+      const map = new PendingRequestMap<{ status: number }>();
+      const promise = map.addRequestAsync('req-1', 5000);
+
+      map.resolveRequest('req-1', { status: 200 });
+
+      await expect(promise).resolves.toEqual({ status: 200 });
+    });
+  });
+
+  describe('rejection', () => {
+    it('rejects the promise when rejectRequest is called', async () => {
+      const map = new PendingRequestMap<string>();
+      const promise = map.addRequestAsync('req-1', 5000);
+
+      map.rejectRequest('req-1', new Error('Something failed'));
+
+      await expect(promise).rejects.toThrow('Something failed');
+    });
+  });
+
+  describe('timeout', () => {
+    it('rejects with timeout error after the specified duration', async () => {
+      const map = new PendingRequestMap<string>();
+      const promise = map.addRequestAsync('req-1', 1000);
+
+      vi.advanceTimersByTime(1000);
+
+      await expect(promise).rejects.toThrow(
+        'Request "req-1" timed out after 1000ms'
+      );
+    });
+
+    it('removes the entry from the map after timeout', async () => {
+      const map = new PendingRequestMap<string>();
+      const promise = map.addRequestAsync('req-1', 500);
+
+      expect(map.hasPendingRequest('req-1')).toBe(true);
+
+      vi.advanceTimersByTime(500);
+
+      // Let the rejection propagate
+      await promise.catch(() => {});
+
+      expect(map.hasPendingRequest('req-1')).toBe(false);
+      expect(map.pendingCount).toBe(0);
+    });
+  });
+
+  describe('cancelAll', () => {
+    it('rejects all pending requests', async () => {
+      const map = new PendingRequestMap<string>();
+      const p1 = map.addRequestAsync('req-1', 5000);
+      const p2 = map.addRequestAsync('req-2', 5000);
+      const p3 = map.addRequestAsync('req-3', 5000);
+
+      map.cancelAll('session closed');
+
+      await expect(p1).rejects.toThrow('session closed');
+      await expect(p2).rejects.toThrow('session closed');
+      await expect(p3).rejects.toThrow('session closed');
+    });
+
+    it('uses default message when no reason provided', async () => {
+      const map = new PendingRequestMap<string>();
+      const promise = map.addRequestAsync('req-1', 5000);
+
+      map.cancelAll();
+
+      await expect(promise).rejects.toThrow('All pending requests cancelled');
+    });
+
+    it('empties the map after cancellation', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+      map.addRequestAsync('req-2', 5000).catch(() => {});
+
+      map.cancelAll();
+
+      expect(map.pendingCount).toBe(0);
+      expect(map.hasPendingRequest('req-1')).toBe(false);
+      expect(map.hasPendingRequest('req-2')).toBe(false);
+    });
+  });
+
+  describe('unknown ID handling', () => {
+    it('resolveRequest with unknown ID does not throw', () => {
+      const map = new PendingRequestMap<string>();
+      expect(() => map.resolveRequest('nonexistent', 'value')).not.toThrow();
+    });
+
+    it('rejectRequest with unknown ID does not throw', () => {
+      const map = new PendingRequestMap<string>();
+      expect(() =>
+        map.rejectRequest('nonexistent', new Error('err'))
+      ).not.toThrow();
+    });
+  });
+
+  describe('duplicate ID', () => {
+    it('rejects the second addRequestAsync immediately without disturbing the first', async () => {
+      const map = new PendingRequestMap<string>();
+      const first = map.addRequestAsync('req-1', 5000);
+      const second = map.addRequestAsync('req-1', 5000);
+
+      await expect(second).rejects.toThrow(
+        'Request "req-1" is already pending'
+      );
+
+      // First should still be pending
+      expect(map.hasPendingRequest('req-1')).toBe(true);
+
+      // Resolve the first
+      map.resolveRequest('req-1', 'success');
+      await expect(first).resolves.toBe('success');
+    });
+  });
+
+  describe('pendingCount', () => {
+    it('starts at 0', () => {
+      const map = new PendingRequestMap<string>();
+      expect(map.pendingCount).toBe(0);
+    });
+
+    it('increments when requests are added', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+      expect(map.pendingCount).toBe(1);
+
+      map.addRequestAsync('req-2', 5000).catch(() => {});
+      expect(map.pendingCount).toBe(2);
+    });
+
+    it('decrements when requests are resolved', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+      map.addRequestAsync('req-2', 5000).catch(() => {});
+
+      map.resolveRequest('req-1', 'done');
+      expect(map.pendingCount).toBe(1);
+
+      map.resolveRequest('req-2', 'done');
+      expect(map.pendingCount).toBe(0);
+    });
+
+    it('decrements when requests are rejected', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+
+      map.rejectRequest('req-1', new Error('fail'));
+      expect(map.pendingCount).toBe(0);
+    });
+
+    it('decrements on timeout', async () => {
+      const map = new PendingRequestMap<string>();
+      const promise = map.addRequestAsync('req-1', 100);
+
+      expect(map.pendingCount).toBe(1);
+
+      vi.advanceTimersByTime(100);
+      await promise.catch(() => {});
+
+      expect(map.pendingCount).toBe(0);
+    });
+  });
+
+  describe('hasPendingRequest', () => {
+    it('returns true for a pending request', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+      expect(map.hasPendingRequest('req-1')).toBe(true);
+    });
+
+    it('returns false for an unknown request', () => {
+      const map = new PendingRequestMap<string>();
+      expect(map.hasPendingRequest('req-1')).toBe(false);
+    });
+
+    it('returns false after resolve', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+
+      map.resolveRequest('req-1', 'done');
+      expect(map.hasPendingRequest('req-1')).toBe(false);
+    });
+
+    it('returns false after reject', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+
+      map.rejectRequest('req-1', new Error('fail'));
+      expect(map.hasPendingRequest('req-1')).toBe(false);
+    });
+
+    it('returns false after timeout', async () => {
+      const map = new PendingRequestMap<string>();
+      const promise = map.addRequestAsync('req-1', 200);
+
+      vi.advanceTimersByTime(200);
+      await promise.catch(() => {});
+
+      expect(map.hasPendingRequest('req-1')).toBe(false);
+    });
+  });
+
+  describe('timer cleanup', () => {
+    it('clears the timeout when resolved before expiry', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+
+      map.resolveRequest('req-1', 'done');
+
+      // Advancing past the original timeout should not cause issues
+      vi.advanceTimersByTime(10000);
+      expect(map.pendingCount).toBe(0);
+    });
+
+    it('clears the timeout when rejected before expiry', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+
+      map.rejectRequest('req-1', new Error('early'));
+
+      vi.advanceTimersByTime(10000);
+      expect(map.pendingCount).toBe(0);
+    });
+
+    it('clears all timers on cancelAll', () => {
+      const map = new PendingRequestMap<string>();
+      map.addRequestAsync('req-1', 5000).catch(() => {});
+      map.addRequestAsync('req-2', 5000).catch(() => {});
+
+      map.cancelAll();
+
+      vi.advanceTimersByTime(10000);
+      expect(map.pendingCount).toBe(0);
+    });
+  });
+});

package/src/server/pending-request-map.ts

@@ -0,0 +1,87 @@
+/**
+ * Request/response correlation layer for matching outgoing server requests
+ * to incoming plugin responses by requestId.
+ */
+
+interface PendingEntry<T> {
+  resolve: (value: T) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class PendingRequestMap<T> {
+  private _pending = new Map<string, PendingEntry<T>>();
+
+  /**
+   * Register a pending request and return a promise that resolves when the
+   * response arrives or rejects on timeout/cancellation. If a request with
+   * the same ID is already pending, the new promise rejects immediately
+   * without disturbing the existing one.
+   */
+  addRequestAsync(requestId: string, timeoutMs: number): Promise<T> {
+    if (this._pending.has(requestId)) {
+      return Promise.reject(
+        new Error(`Request "${requestId}" is already pending`)
+      );
+    }
+
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(requestId);
+        reject(
+          new Error(`Request "${requestId}" timed out after ${timeoutMs}ms`)
+        );
+      }, timeoutMs);
+
+      this._pending.set(requestId, { resolve, reject, timer });
+    });
+  }
+
+  /**
+   * Resolve a pending request with the given result. Unknown IDs are
+   * silently ignored.
+   */
+  resolveRequest(requestId: string, result: T): void {
+    const entry = this._pending.get(requestId);
+    if (!entry) return;
+
+    clearTimeout(entry.timer);
+    this._pending.delete(requestId);
+    entry.resolve(result);
+  }
+
+  /**
+   * Reject a pending request with the given error. Unknown IDs are
+   * silently ignored.
+   */
+  rejectRequest(requestId: string, error: Error): void {
+    const entry = this._pending.get(requestId);
+    if (!entry) return;
+
+    clearTimeout(entry.timer);
+    this._pending.delete(requestId);
+    entry.reject(error);
+  }
+
+  /**
+   * Cancel all pending requests, rejecting each with a cancellation error.
+   */
+  cancelAll(reason?: string): void {
+    const message = reason ?? 'All pending requests cancelled';
+    for (const [, entry] of this._pending) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error(message));
+    }
+    this._pending.clear();
+  }
+
+  /** Number of currently pending requests. */
+  get pendingCount(): number {
+    return this._pending.size;
+  }
+
+  /** Whether a request with the given ID is currently pending. */
+  hasPendingRequest(requestId: string): boolean {
+    return this._pending.has(requestId);
+  }
+}

package/src/server/plugin-detection.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Tests for persistent plugin detection and fallback logic in
+ * StudioBridgeServer.startAsync(). Validates the grace period behavior,
+ * persistent plugin preference, and fallback to temp injection.
+ */
+
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import { WebSocket } from 'ws';
+import { StudioBridgeServer } from './studio-bridge-server.js';
+
+vi.mock('@quenty/nevermore-template-helpers', () => ({
+  BuildContext: {
+    createAsync: vi.fn(async () => ({
+      resolvePath: vi.fn((rel: string) => `/fake/tmp/${rel}`),
+      executeLuneTransformScriptAsync: vi.fn(async () => {}),
+      rojoBuildAsync: vi.fn(async () => undefined),
+      cleanupAsync: vi.fn(async () => {}),
+    })),
+  },
+  resolvePackagePath: vi.fn((..._args: any[]) => '/fake/transform-script.luau'),
+  resolveTemplatePath: vi.fn((..._args: any[]) => '/fake/default.project.json'),
+}));
+
+const mockInjectPluginAsync = vi.fn(async () => ({
+  pluginPath: '/fake/plugin.rbxmx',
+  cleanupAsync: vi.fn(async () => {}),
+}));
+
+vi.mock('../plugin/plugin-injector.js', () => ({
+  injectPluginAsync: (..._args: any[]) => mockInjectPluginAsync(),
+}));
+
+const mockIsPersistentPluginInstalled = vi.fn(() => false);
+
+vi.mock('../plugin/plugin-discovery.js', () => ({
+  isPersistentPluginInstalled: () => mockIsPersistentPluginInstalled(),
+}));
+
+vi.mock('../process/studio-process-manager.js', () => ({
+  launchStudioAsync: vi.fn(async () => ({
+    process: { pid: 12345 },
+    killAsync: vi.fn(async () => {}),
+  })),
+  findPluginsFolder: vi.fn(() => '/fake/plugins'),
+}));
+
+/**
+ * Connect a WebSocket client and send a register message.
+ */
+async function connectAndHandshake(
+  port: number,
+  sessionId: string
+): Promise<WebSocket> {
+  const ws = new WebSocket(`ws://localhost:${port}/${sessionId}`);
+
+  await new Promise<void>((resolve, reject) => {
+    ws.on('open', resolve);
+    ws.on('error', reject);
+  });
+
+  ws.send(
+    JSON.stringify({
+      type: 'register',
+      sessionId,
+      payload: {
+        pluginVersion: '1.0.0',
+        instanceId: 'inst-1',
+        placeName: 'TestPlace',
+        state: 'Edit',
+        capabilities: ['execute', 'queryState'],
+      },
+    })
+  );
+
+  // Allow server to process register
+  await new Promise((r) => setTimeout(r, 20));
+  return ws;
+}
+
+describe('persistent plugin detection', () => {
+  let server: StudioBridgeServer | undefined;
+  let client: WebSocket | undefined;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockIsPersistentPluginInstalled.mockReturnValue(false);
+  });
+
+  afterEach(async () => {
+    if (client && client.readyState === WebSocket.OPEN) {
+      client.close();
+    }
+    if (server) {
+      await server.stopAsync();
+    }
+    client = undefined;
+    server = undefined;
+  });
+
+  it('uses temp injection when persistent plugin is not installed', async () => {
+    mockIsPersistentPluginInstalled.mockReturnValue(false);
+
+    const sessionId = 'no-persistent';
+    server = new StudioBridgeServer({
+      placePath: '/fake/place.rbxl',
+      sessionId,
+      timeoutMs: 5_000,
+    });
+
+    const startPromise = server.startAsync();
+    await new Promise((r) => setTimeout(r, 50));
+    const port: number = (server as any)._port;
+
+    // Temp injection should have been called immediately
+    expect(mockInjectPluginAsync).toHaveBeenCalledTimes(1);
+
+    // Complete handshake so startAsync resolves
+    client = await connectAndHandshake(port, sessionId);
+    await startPromise;
+  });
+
+  it('uses temp injection when preferPersistentPlugin is false', async () => {
+    mockIsPersistentPluginInstalled.mockReturnValue(true);
+
+    const sessionId = 'prefer-false';
+    server = new StudioBridgeServer({
+      placePath: '/fake/place.rbxl',
+      sessionId,
+      timeoutMs: 5_000,
+      preferPersistentPlugin: false,
+    });
+
+    const startPromise = server.startAsync();
+    await new Promise((r) => setTimeout(r, 50));
+    const port: number = (server as any)._port;
+
+    // Temp injection should have been called immediately
+    expect(mockInjectPluginAsync).toHaveBeenCalledTimes(1);
+
+    // Complete handshake so startAsync resolves
+    client = await connectAndHandshake(port, sessionId);
+    await startPromise;
+  });
+
+  it('falls back to temp injection after grace period when persistent plugin does not connect', async () => {
+    mockIsPersistentPluginInstalled.mockReturnValue(true);
+
+    const sessionId = 'grace-expire';
+    server = new StudioBridgeServer({
+      placePath: '/fake/place.rbxl',
+      sessionId,
+      timeoutMs: 10_000,
+    });
+
+    const startPromise = server.startAsync();
+
+    // Wait for the grace period (3 seconds) to expire + some buffer
+    // The server should fall back to temp injection after 3 seconds
+    await new Promise((r) => setTimeout(r, 3_200));
+
+    // After grace period, temp injection should have been called
+    expect(mockInjectPluginAsync).toHaveBeenCalledTimes(1);
+
+    // Complete handshake so startAsync resolves
+    const port: number = (server as any)._port;
+    client = await connectAndHandshake(port, sessionId);
+    await startPromise;
+  }, 15_000);
+
+  it('skips temp injection when persistent plugin connects within grace period', async () => {
+    mockIsPersistentPluginInstalled.mockReturnValue(true);
+
+    const sessionId = 'plugin-connects';
+    server = new StudioBridgeServer({
+      placePath: '/fake/place.rbxl',
+      sessionId,
+      timeoutMs: 10_000,
+    });
+
+    const startPromise = server.startAsync();
+
+    // Wait for the server to be up
+    await new Promise((r) => setTimeout(r, 100));
+    const port: number = (server as any)._port;
+
+    // Connect a plugin within the grace period (simulating persistent plugin)
+    client = await connectAndHandshake(port, sessionId);
+
+    // Wait for startAsync to resolve
+    await startPromise;
+
+    // Temp injection should NOT have been called
+    expect(mockInjectPluginAsync).not.toHaveBeenCalled();
+  });
+});