ECO-4787: Add interception proxy prototype

- start-interception-proxy adapted from https://github.com/ably/sdk-test-proxy at 82e93a7

Some TODOs which aren’t really important right now because this is just
a prototype:

- TODO fix type checking for interception proxy — `npm run build` does
  it properly, but tried to reproduce the way we do it for modulereport
  and it didn’t work

- TODO fix linting for interception proxy — doesn’t seem to be catching
  lint errors

- TODO linting / type checking etc for Python code

Also:

> Add test:playwright:open-browser script
>
> Lets you open a headed browser which is configured to use the
> interception proxy. Useful for local debugging of browser tests.

.github/workflows/test-browser.yml

@@ -25,11 +25,69 @@ jobs:
         with:
           node-version: 20.x
       - run: npm ci
+
+      # Set up Python (for pipx)
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12' 
+
+      # Install pipx (for mitmproxy)
+      # See https://pipx.pypa.io/stable/installation/
+      - name: Install pipx
+        run: |
+          python3 -m pip install --user pipx
+          sudo pipx --global ensurepath
+
+      # https://docs.mitmproxy.org/stable/overview-installation/#installation-from-the-python-package-index-pypi
+      - name: Install mitmproxy
+        run: |
+          pipx install mitmproxy
+          # We use this library in our addon
+          pipx inject mitmproxy websockets
+
+      - name: Generate mitmproxy SSL certs
+        run: mitmdump -s test/mitmproxy_addon_generate_certs_and_exit.py
+
+      - name: Start interception proxy server
+        run: ./start-interception-proxy
+
       - name: Install Playwright browsers and dependencies
         run: npx playwright install --with-deps
-      - env:
+
+        # For certutil
+      - name: Install NSS tools
+        run: sudo apt install libnss3-tools
+
+      # This is for Chromium (see https://chromium.googlesource.com/chromium/src/+/master/docs/linux/cert_management.md)
+      # Note this is the same command that we use for adding it to the Firefox profile (see playwrightHelpers.js)
+      - name: Install mitmproxy root CA in NSS shared DB
+        run: |
+          mkdir -p ~/.pki/nssdb
+          certutil -A -d sql:$HOME/.pki/nssdb -t "C" -n "Mitmproxy Root Cert" -i ~/.mitmproxy/mitmproxy-ca-cert.pem
+          certutil -L -d sql:$HOME/.pki/nssdb
+
+      # This is for WebKit (I think because it uses OpenSSL)
+      - name: Install mitmproxy root CA in /usr/local/share/ca-certificates
+        run: |
+          sudo cp ~/.mitmproxy/mitmproxy-ca-cert.cer /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt
+          sudo update-ca-certificates
+
+      - name: Run the tests
+        env:
           PLAYWRIGHT_BROWSER: ${{ matrix.browser }}
         run: npm run test:playwright
+
+      - name: Save interception proxy server logs
+        if: always()
+        run: sudo journalctl -u ably-sdk-test-proxy.service > interception-proxy-logs.txt
+
+      - name: Upload interception proxy server logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: interception-proxy-logs-${{ matrix.browser }}
+          path: interception-proxy-logs.txt
+
       - name: Generate private API usage reports
         run: npm run process-private-api-data private-api-usage/*.json
       - name: Save private API usage data

.github/workflows/test-node.yml

@@ -25,9 +25,120 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm ci
-      - run: npm run test:node
+
+      # Set up Python (for pipx)
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12' 
+
+      # Install pipx (for mitmproxy)
+      # See https://pipx.pypa.io/stable/installation/
+      - name: Install pipx
+        run: |
+          python3 -m pip install --user pipx
+          sudo pipx --global ensurepath
+
+      # https://docs.mitmproxy.org/stable/overview-installation/#installation-from-the-python-package-index-pypi
+      - name: Install mitmproxy
+        run: |
+          pipx install mitmproxy
+          # We use this library in our addon
+          pipx inject mitmproxy websockets
+
+      - name: Create a user to run the tests
+        run: sudo useradd --create-home ably-test-user
+
+      - name: Create a group for sharing the working directory
+        run: |
+          sudo groupadd ably-test-users
+          # Add relevant users to the group
+          sudo usermod --append --groups ably-test-users $USER
+          sudo usermod --append --groups ably-test-users ably-test-user
+          # Give the group ownership of the working directory and everything under it...
+          sudo chown -R :ably-test-users .
+          # ...and give group members full read/write access to its contents (i.e. rw access to files, rwx access to directories)
+          # (We use xargs because `find` does not fail if an `exec` command fails; see https://serverfault.com/a/905039)
+          find . -type f -print0 | xargs -n1 -0 chmod g+rw
+          find . -type d -print0 | xargs -n1 -0 chmod g+rwx
+          # TODO understand better
+          #
+          # This is to make `npm run` work when run as ably-test-user; else it fails because of a `statx()` call on package.json:
+          #
+          # > 2024-04-17T13:08:09.1302251Z [pid  2051] statx(AT_FDCWD, `"/home/runner/work/ably-js/ably-js/package.json"`, AT_STATX_SYNC_AS_STAT, STATX_ALL, 0x7f4875ffcb40) = -1 EACCES (Permission denied)
+          #
+          # statx documentation says:
+          #
+          # > in the case of **statx**() with a pathname, execute (search) permission is required on all of the directories in _pathname_ that lead to the file.
+          #
+          # The fact that I’m having to do this probably means that I’m doing something inappropriate elsewhere. (And I don’t know what the other consequences of doing this might be.)
+          chmod o+x ~
+
+      # TODO set umask appropriately, so that new files created are readable/writable by the group
+
+      - name: Generate mitmproxy SSL certs
+        run: mitmdump -s test/mitmproxy_addon_generate_certs_and_exit.py
+
+      - name: Set up iptables rules
+        run: |
+          # The rules suggested by mitmproxy etc are aimed at intercepting _all_ the outgoing traffic on a machine. I don’t want that, given that we want to be able to run this test suite on developers’ machines in a non-invasive manner. Instead we just want to target traffic generated by the process that contains the Ably SDK, which we’ll make identifable by iptables by running that process as a specific user created for that purpose (ably-test-user).
+          #
+          # Relevant parts of iptables documentation:
+          #
+          # nat:
+          # > This table is consulted when a packet that creates a new connection is encountered. It consists of three built-ins: PREROUTING (for altering packets as soon as they come in), OUTPUT (for altering locally-generated packets before routing), and POSTROUTING (for altering packets as they are about to go out).
+          #
+          # owner:
+          # > This module attempts to match various characteristics of the packet creator, for locally-generated packets. It is only valid in the OUTPUT chain, and even this some packets (such as ICMP ping responses) may have no owner, and hence never match.
+          #
+          # REDIRECT:
+          # > This target is only valid in the nat table, in the PREROUTING and OUTPUT chains, and user-defined chains which are only called from those chains. It redirects the packet to the machine itself by changing the destination IP to the primary address of the incoming interface (locally-generated packets are mapped to the 127.0.0.1 address). It takes one option:
+          # >
+          # > --to-ports port[-port]
+          # > This specifies a destination port or range of ports to use: without this, the destination port is never altered. This is only valid if the rule also specifies -p tcp or -p udp.
+          #
+          # I don’t exactly understand what the nat table means; I assume its rules apply to all _subsequent_ packets in the connection, too?
+          #
+          # So, what I expect to happen:
+          #
+          # 1. iptables rule causes default-port HTTP(S) datagram from test process to get its destination IP rewritten to 127.0.0.1, and rewrites the TCP header’s destination port to 8080
+          # 2. 127.0.0.1 destination causes OS’s routing to send this datagram on the loopback interface
+          # 3. nature of the loopback interface means that this datagram is then received on the loopback interface
+          # 4. mitmproxy, listening on port 8080 (not sure how or why it uses a single port for both non-TLS and TLS traffic) receives these datagrams, and uses Host header or SNI to figure out where they were originally destined.
+          #
+          # TODO (how) do we achieve the below on macOS? I have a feeling that it’s currently just working by accident; e.g. it's because the TCP connection to the control server exists before we start mitmproxy and hence the connection doesn’t get passed to its NETransparentProxyProvider or something. To be on the safe side, though, I’ve added a check in the mitmproxy addon so that we only mess with stuff for ports 80 or 443
+          #
+          # Note that in the current setup with ably-js, the test suite and the Ably SDK run in the same process. We want to make sure that we don’t intercept the test suite’s WebSocket communications with the interception proxy’s control API  (which it serves at 127.0.0.1:8001), hence only targeting the default HTTP(S) ports. (TODO consider that Realtime team also run a Realtime on non-default ports when testing locally)
+          sudo iptables  --table nat --append OUTPUT --match owner --uid-owner ably-test-user --protocol tcp --destination-port 80  --jump REDIRECT --to-ports 8080
+          sudo iptables  --table nat --append OUTPUT --match owner --uid-owner ably-test-user --protocol tcp --destination-port 443 --jump REDIRECT --to-ports 8080
+          sudo ip6tables --table nat --append OUTPUT --match owner --uid-owner ably-test-user --protocol tcp --destination-port 80  --jump REDIRECT --to-ports 8080
+          sudo ip6tables --table nat --append OUTPUT --match owner --uid-owner ably-test-user --protocol tcp --destination-port 443 --jump REDIRECT --to-ports 8080
+
+        # TODO how will this behave with:
+        #
+        # 1. the WebSocket connection from test suite to control API (see above note; not a problem in this CI setup, think about it on macOS)
+        # 2. the WebSocket connection from mitmproxy to control API (not an issue on Linux or macOS with our current setup since we don’t intercept any traffic from mitmproxy)
+        # 3. the WebSocket connections that mitmproxy proxies to the interception proxy (which it sends to localhost:8002) (ditto 2)
+        # 4. the WebSocket connections for which interception proxy is a client (not an issue for Linux or macOS with our current setup since we don’t intercept any traffic from interception proxy)
+
+      - name: Start interception proxy server
+        run: ./start-interception-proxy
+
+      - name: Run the tests
+        run: sudo -u ably-test-user NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem npm run test:node
         env:
           CI: true
+
+      - name: Save interception proxy server logs
+        if: always()
+        run: sudo journalctl -u ably-sdk-test-proxy.service > interception-proxy-logs.txt
+
+      - name: Upload interception proxy server logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: interception-proxy-logs-${{ matrix.node-version }}
+          path: interception-proxy-logs.txt
+
       - name: Generate private API usage reports
         run: npm run process-private-api-data private-api-usage/*.json
       - name: Save private API usage data

.gitignore

@@ -11,6 +11,7 @@ junit/
 private-api-usage/
 private-api-usage-reports/
 test/support/mocha_junit_reporter/build/
+tmp/
 
 # Python stuff (for interception proxy)
 __pycache__

package.json

@@ -142,8 +142,10 @@
     "test:node:skip-build": "mocha",
     "test:webserver": "grunt test:webserver",
     "test:playwright": "node test/support/runPlaywrightTests.js",
+    "test:playwright:open-browser": "node test/support/openPlaywrightBrowser.js",
     "test:react": "vitest run",
     "test:package": "grunt test:package",
+    "test:proxy": "npm run build && esr test/interception-proxy/server.ts",
     "concat": "grunt concat",
     "build": "grunt build:all && npm run build:react",
     "build:node": "grunt build:node",

start-interception-proxy

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+
+# Runs the server as a background service, exiting once the server is ready to receive requests.
+#
+# Intended for use in SDKs’ CI jobs. Must be run from the root of this repository.
+
+set -e
+
+# We run as the current user so that we can access the generated server certificate (in ~/.mitmproxy) without having to worry about permissions. TODO consider instead generating our own cert and telling mitmproxy to use it, then we also won’t have to have that step where we run mitmproxy once just to generate the certs
+start_systemd_service () {
+  systemd_service=$(cat <<SYSTEMD_SERVICE
+[Unit]
+Description=Ably SDK Test Proxy
+
+[Service]
+WorkingDirectory=$(pwd)
+ExecStart=npm run test:proxy
+User=$USER
+
+[Install]
+WantedBy=multi-user.target
+SYSTEMD_SERVICE
+)
+
+  # https://stackoverflow.com/questions/84882/sudo-echo-something-etc-privilegedfile-doesnt-work
+  echo "${systemd_service}" | sudo tee /etc/systemd/system/ably-sdk-test-proxy.service 1>/dev/null
+
+  echo "Starting ably-sdk-test-proxy systemd service..." 1>&2
+  sudo systemctl start ably-sdk-test-proxy.service
+  echo "Started ably-sdk-test-proxy systemd service." 1>&2
+}
+
+start_launchd_daemon () {
+  launchd_daemon=$(cat <<LAUNCHD_DAEMON
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.ably.test.proxy</string>
+    <key>WorkingDirectory</key>
+    <string>$(pwd)</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>npm</string>
+        <string>run</string>
+        <string>test:proxy</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+LAUNCHD_DAEMON
+)
+
+  # https://stackoverflow.com/questions/84882/sudo-echo-something-etc-privilegedfile-doesnt-work
+  echo "${launchd_daemon}" | sudo tee /Library/LaunchDaemons/com.ably.test.proxy.plist
+
+  echo "Loading ably-sdk-test-proxy launchd daemon..." 1>&2
+  sudo launchctl load /Library/LaunchDaemons/com.ably.test.proxy.plist
+  echo "Loaded ably-sdk-test-proxy launchd daemon." 1>&2
+}
+
+check_daemon_still_running () {
+  if uname | grep Linux 1>/dev/null
+  then
+    systemctl is-active --quiet ably-sdk-test-proxy.service
+  elif uname | grep Darwin 1>/dev/null
+  then
+    launchctl print system/com.ably.test.proxy 1>/dev/null
+  fi
+}
+
+if uname | grep Linux 1>/dev/null
+then
+  start_systemd_service
+elif uname | grep Darwin 1>/dev/null
+then
+  start_launchd_daemon
+else
+  echo "Unsupported system $(uname); exiting" 1>&2
+  exit 1
+fi
+
+echo "Waiting for sdk-test-proxy server to start on port 8001..." 1>&2
+
+# https://stackoverflow.com/questions/27599839/how-to-wait-for-an-open-port-with-netcat
+while ! nc -z localhost 8001; do
+  # Check that the service hasn’t failed (else we’ll be waiting forever)
+  check_daemon_still_running
+  sleep 0.5
+done
+
+echo "sdk-test-proxy server is now listening on port 8001." 1>&2

test/common/globals/named_dependencies.js

@@ -18,6 +18,10 @@ define(function () {
     async: { browser: 'node_modules/async/lib/async' },
     chai: { browser: 'node_modules/chai/chai', node: 'node_modules/chai/chai' },
     ulid: { browser: 'node_modules/ulid/dist/index.umd', node: 'node_modules/ulid/dist/index.umd' },
+    interception_proxy_client: {
+      browser: 'test/common/modules/interception_proxy_client',
+      node: 'test/common/modules/interception_proxy_client',
+    },
     private_api_recorder: {
       browser: 'test/common/modules/private_api_recorder',
       node: 'test/common/modules/private_api_recorder',