[ECO-5260] feat: initial local proxy implementation

Core functionality includes:

- Spying on HTTP Requests and Responses
  - Inspect outgoing HTTP requests from the client.
  - Inspect and modify incoming HTTP responses.

- Spying on WebSocket Messages
  - Observe outgoing WebSocket messages from the client.
  - Inspect and modify incoming WebSocket messages.

- Injecting WebSocket Messages
  - Simulate server messages by injecting WebSocket frames into the client session.

- Breaking WebSocket and HTTP Connections
  - Force WebSocket disconnections to test reconnection behavior.
  - Simulate slow or broken HTTP responses to test timeout handling.

Author: ttypic

.github/workflows/check.yml

@@ -0,0 +1,21 @@
+name: Check
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+
+      - name: Run test
+        run: npm run test

README.md

@@ -22,14 +22,92 @@ During SDK testing, it’s often useful to simulate real-world conditions or ins
 - Replay server messages for automated or regression testing.
 - Monitor raw protocol-level activity to catch subtle bugs or race conditions.
 
-🚀 Getting Started
+### 🚀 Getting Started
 
 Install npm dependency:
 
 ```bash
-npm i -D @ably-labs/local-proxy
+npm install --save-dev @ably-labs/local-proxy
 ```
 
+### 🧪 Basic Usage
 
+```ts
+import { createInterceptingProxy } from '@ably-labs/local-proxy';
 
+// 1. Create and start the proxy
+const proxy = createInterceptingProxy({
+  // options here realtimeHost, restHost
+});
+await proxy.start();
 
+// 2. Configure your SDK to use proxy.options
+const client = new Ably.Realtime({
+  ...proxy.options
+  // aditonal option
+});
+
+// 3. Observe an outgoing HTTP request
+const request = await proxy.observeNextRequest(req =>
+  req.url.includes('/channels')
+);
+
+// 4. Observe an incoming protocol message
+proxy.observeNextIncomingProtocolMessage(msg =>
+  msg.action === 15 // Presence message
+)
+
+// 5. Inject a fake message into the client
+proxy.injectProtocolMessage(client.connection.id, {
+    action: 9, // Example: SYNC
+    channel: 'room:test',
+    connectionId: client.connection.id,
+    msgSerial: 0,
+    connectionSerial: -1,
+    data: { custom: 'data' },
+});
+```
+
+### 🧩 Replace a Server Message
+
+You can also simulate faulty server responses:
+
+```ts
+proxy.replaceNextIncomingProtocolMessage(
+  {
+    action: 9, // Fake SYNC
+    channel: 'room:test',
+    data: [],
+  },
+  msg => msg.action === 9 // Replace only SYNC messages
+);
+```
+
+
+### 🔌 Drop or Pause a Connection
+
+```ts
+// Drop connection by ID (force disconnect)
+proxy.dropConnection(client.connection.id);
+
+// Pause and resume connection manually
+const resume = proxy.pauseConnection();
+// simulate a pause...
+setTimeout(() => resume(), 5000);
+```
+
+
+### 🔧 Register Middleware
+
+For more advanced use cases, register middlewares to continuously inspect or modify traffic:
+
+```ts
+const unregister = proxy.registerRestMiddleware(req => {
+  if (req.url.includes('/channels')) {
+    console.log('Intercepted REST request:', req);
+    // You can modify headers, body, or response here
+  }
+});
+// Later...
+unregister();
+```

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ably-labs/local-proxy",
-  "version": "0.0.6",
-  "description": "Unified Test Suite for Chat SDKs. An executable npm package designed to provide a consistent testing environment for different Ably Chat SDKs",
+  "version": "0.1.0",
+  "description": "Local proxy for SDK testing",
   "scripts": {
     "build": "tsc",
     "prepare": "npm run build",

src/async-queue.ts

@@ -0,0 +1,36 @@
+import { CompletableDeferred } from './completable-deferred';
+
+type AsyncTask = () => Promise<void>;
+
+export class AsyncQueue {
+  private readonly queue: AsyncTask[] = [];
+  private processing: boolean = false;
+
+  enqueue(task: AsyncTask): Promise<void> {
+    const deferredValue = CompletableDeferred<void>();
+    this.queue.push(async () => {
+      try {
+        await task();
+      } finally {
+        deferredValue.complete();
+      }
+    });
+    this.processNext();
+    return deferredValue.get()
+  }
+
+  private async processNext() {
+    if (this.processing || this.queue.length === 0) return;
+
+    this.processing = true;
+
+    const task = this.queue.shift();
+
+    try {
+      await task!!();
+    } finally {
+      this.processing = false;
+      this.processNext();
+    }
+  }
+}

src/completable-deferred.ts

@@ -0,0 +1,22 @@
+type CompletionHandler<T = void> = (value: T) => void
+
+class DefaultCompletableDeferred<T = void> {
+  private _completeWith!: CompletionHandler<T>;
+  private value: T | undefined
+
+  private valuePromise = new Promise<T>(resolve => {
+    this._completeWith = resolve;
+  });
+
+  public complete(value: T): void {
+    this._completeWith(value);
+  }
+
+  public async get(): Promise<T> {
+    return this.value ?? this.valuePromise;
+  }
+}
+
+export function CompletableDeferred<T>() {
+  return new DefaultCompletableDeferred<T>()
+}

src/index.ts

@@ -0,0 +1 @@
+export * from './proxy.js';