Proxy Server

Connect handlers allow extensions to intercept and modify connections as they are initiated through the proxy. When a client connects, powhttp invokes all registered handlers sequentially. Each handler can modify the connection target, override proxy settings, control TLS interception or reject the connection entirely.

Handlers have a 10-second timeout. If a handler does not respond in time, it is skipped and the next handler is invoked.

proxy_server/add_connect_handler

Registers a connect handler with the given ID. The ID is used to route incoming handler calls to the correct implementation.

Parameters:

{
  handlerId: string;
}

Result: null

proxy_server/remove_connect_handler

Unregisters a previously registered connect handler.

Parameters:

{
  handlerId: string;
}

Result: null

Handler Callbacks

These methods are called by powhttp on the extension when a new connection is initiated through the proxy. The extension must implement these handlers to return a ConnectResult for each registered handler ID.

proxy_server/call_connect_handler

Called when powhttp invokes a connect handler for a new connection. The handler receives details about the connection and must return a ConnectResult indicating how to proceed.

Parameters:

type CallConnectHandlerParams = {
  handlerId: string;
  context: ConnectContext;
};

type ConnectContext = {
  sessionId: string;
  targetAddr: TargetAddress;
  clientAddr: string;            // "IP:port"
  process: Option<ProcessInfo>;
  request: ConnectRequest;
};

type TargetAddress = {
  host: string;
  port: number;
};

type ProcessInfo = {
  pid: number;
  name: Option<string>;
};

type ConnectRequest =
  | { type: "socks4"; userId: string }
  | { type: "socks5" }
  | { type: "http_connect";
      target: string;
      httpVersion: string;
      headers: Array<[string, string]>; }
  | { type: "tls_sni" }
  | { type: "http_direct";
      method: string;
      path: string;
      httpVersion: string;
      headers: Array<[string, string]>; }
  | { type: "http_proxy";
      method: string;
      url: string;
      httpVersion: string;
      headers: Array<[string, string]>; };

Result:

type ConnectResult =
  | { type: "accept";
      targetAddr?: TargetAddress;
      proxy?: Proxy;
      record?: boolean;
      interceptTls?: boolean; }
  | { type: "reject" };

type Proxy = {
  proxyType: "http" | "https" | "socks4"
    | "socks4a" | "socks5" | "socks5h";
  host: string;
  port: number;
  username: Option<string>;
  password: Option<string>;
};

Handler Chaining

When multiple connect handlers are registered across extensions, they are invoked sequentially. Each handler receives the connection parameters as modified by previous handlers. If any handler returns "reject", the connection is immediately rejected and no further handlers are called.

Only fields that are explicitly set in the response will override the current values. Fields set to null or omitted are left unchanged from the previous handler's result or the original connection parameters.