Implementation:Microsoft Playwright SocksProxy

Knowledge Sources	Microsoft_Playwright
Domains	Network Proxy, SOCKS5 Protocol
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for implementing a SOCKS5 proxy server provided by the Playwright library.

Description

The `SocksProxy` class (extending `EventEmitter`) implements a SOCKS5 proxy server following RFC 1928. It handles the SOCKS5 handshake protocol including authentication negotiation, command processing (CONNECT), and address type parsing (IPv4, IPv6, FQDN). The module defines low-level protocol enums (`SocksAuth`, `SocksAddressType`, `SocksCommand`, `SocksReply`) and a `SocksConnection` class for managing individual SOCKS connections through a state machine. The proxy emits events for socket requests, data transfer, and socket closure, enabling external handlers (like the client certificates interceptor or remote browser connections) to process the proxied traffic. It supports direct connection mode and can optionally redirect connections to upstream hosts.

Usage

Use this class when you need a SOCKS5 proxy for browser traffic routing, such as for client certificate injection, remote browser connections through firewalls, or network traffic interception.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/server/utils/socksProxy.ts

Signature

export type SocksSocketRequestedPayload = { uid: string, host: string, port: number };
export type SocksSocketDataPayload = { uid: string, data: Buffer };
export type SocksSocketClosedPayload = { uid: string };

export class SocksProxy extends EventEmitter implements SocksConnectionClient {
  constructor();
  setPattern(pattern: string | undefined): void;
  async listen(port: number, hostname?: string): Promise<number>;
  async close(): Promise<void>;
  socketConnected(uid: string): void;
  socketFailed(uid: string): void;
  sendSocketData(uid: string, data: Buffer): void;
  sendSocketClose(uid: string): void;
  sendSocketEnd(uid: string): void;
}

Import

import { SocksProxy } from '../server/utils/socksProxy';
import type { SocksSocketRequestedPayload, SocksSocketDataPayload, SocksSocketClosedPayload } from '../server/utils/socksProxy';

I/O Contract

Inputs

Name	Type	Required	Description
port	number	Yes	TCP port to listen on
hostname	string	No	Hostname to bind to (defaults to localhost)
pattern	string	No	URL pattern for selective proxying
uid	string	Yes	Unique socket connection identifier
data	Buffer	Yes	Data to send through the proxy connection

Outputs

Name	Type	Description
port	number	Actual port the proxy is listening on
SocksSocketRequestedPayload	event	Emitted when a client requests a connection
SocksSocketDataPayload	event	Emitted when data arrives from a client
SocksSocketClosedPayload	event	Emitted when a client socket closes

Usage Examples

import { SocksProxy } from 'playwright-core/lib/server/utils/socksProxy';

const proxy = new SocksProxy();

proxy.on('socks-requested', ({ uid, host, port }) => {
  console.log(`Connection requested to ${host}:${port}`);
  proxy.socketConnected(uid);
});

proxy.on('socks-data', ({ uid, data }) => {
  // Forward data to the real server
});

proxy.on('socks-closed', ({ uid }) => {
  // Clean up connection
});

const actualPort = await proxy.listen(0);
console.log(`SOCKS proxy on port ${actualPort}`);

await proxy.close();

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment