Expose 'destination' on request data and avoid IPs in 'url' if possible

If you tunnel to a specific IP with a domain name specified, we'll use
the domain in the url property - this is normally clearer & preferable.
The IP is still available in the 'destination' property. It will still
be used in the URL if there's no hostname anywhere.

This also further deprecates the standalone 'hostname' field on
requests, which was not really used and functioned quite ambiguously.
You can now look at either the URL (best guess domain name), the
destination (the actual destination IP/domain name) or the Host/:Authority
header (the name the client is telling the server). In theory they
should probably match all the time, but they may not.

This mostly comes up when tunneling to one server, and sending a
different Host header, which mostly matters for weird edge cases and
testing of non-production deployments & similar.

Author: pimterry

src/admin/mockttp-schema.ts

@@ -117,6 +117,7 @@ export const MockttpSchema = gql`
         rawHeaders: Json
         remoteIpAddress: String
         remotePort: Int
+        destination: Destination
     }
 
     type RawPassthroughEvent {
@@ -158,7 +159,9 @@ export const MockttpSchema = gql`
         path: String!
         remoteIpAddress: String
         remotePort: Int
-        hostname: String
+
+        destination: Destination!
+        hostname: String # Deprecated
 
         headers: Json!
         rawHeaders: Json!
@@ -177,7 +180,9 @@ export const MockttpSchema = gql`
         path: String!
         remoteIpAddress: String
         remotePort: Int
-        hostname: String
+
+        destination: Destination!
+        hostname: String # Deprecated
 
         headers: Json!
         rawHeaders: Json!
@@ -199,7 +204,9 @@ export const MockttpSchema = gql`
         path: String!
         remoteIpAddress: String
         remotePort: Int
-        hostname: String
+
+        destination: Destination!
+        hostname: String # Deprecated
 
         headers: Json!
         rawHeaders: Json!
@@ -241,4 +248,9 @@ export const MockttpSchema = gql`
         timingEvents: Json!
         tags: [String!]!
     }
+
+    type Destination {
+        hostname: String!
+        port: Int!
+    }
 `;

src/client/mockttp-admin-request-builder.ts

@@ -233,7 +233,8 @@ export class MockttpAdminRequestBuilder {
                     path
                     ${this.schema.asOptionalField('InitiatedRequest', 'remoteIpAddress')}
                     ${this.schema.asOptionalField('InitiatedRequest', 'remotePort')}
-                    hostname
+
+                    ${this.schema.asOptionalField('InitiatedRequest', 'destination', 'destination { hostname, port }')}
 
                     ${this.schema.typeHasField('InitiatedRequest', 'rawHeaders')
                         ? 'rawHeaders'
@@ -254,7 +255,8 @@ export class MockttpAdminRequestBuilder {
                     path
                     ${this.schema.asOptionalField('Request', 'remoteIpAddress')}
                     ${this.schema.asOptionalField('Request', 'remotePort')}
-                    hostname
+
+                    ${this.schema.asOptionalField('Request', 'destination', 'destination { hostname, port }')}
 
                     ${this.schema.typeHasField('Request', 'rawHeaders')
                         ? 'rawHeaders'
@@ -297,7 +299,8 @@ export class MockttpAdminRequestBuilder {
                     path
                     remoteIpAddress
                     remotePort
-                    hostname
+
+                    ${this.schema.asOptionalField('Request', 'destination', 'destination { hostname, port }')}
 
                     rawHeaders
                     body
@@ -359,12 +362,13 @@ export class MockttpAdminRequestBuilder {
             }`,
             abort: gql`subscription OnAbort {
                 requestAborted {
-                    id,
-                    protocol,
-                    method,
-                    url,
-                    path,
-                    hostname,
+                    id
+                    protocol
+                    method
+                    url
+                    path
+
+                    ${this.schema.asOptionalField('AbortedRequest', 'destination', 'destination { hostname, port }')}
 
                     ${this.schema.typeHasField('Request', 'rawHeaders')
                         ? 'rawHeaders'
@@ -437,6 +441,7 @@ export class MockttpAdminRequestBuilder {
 
                         ${this.schema.asOptionalField('ClientErrorRequest', 'remoteIpAddress')}
                         ${this.schema.asOptionalField('ClientErrorRequest', 'remotePort')}
+                        ${this.schema.asOptionalField('ClientErrorRequest', 'destination', 'destination { hostname, port }')}
                     }
                     response {
                         id

src/client/schema-introspection.ts

@@ -20,14 +20,14 @@ export class SchemaIntrospector {
         return !!_.find(type.fields, { name: fieldName });
     }
 
-    public asOptionalField(typeName: string | string[], fieldName: string): string {
+    public asOptionalField(typeName: string | string[], fieldName: string, specifier: string = fieldName): string {
         const possibleNames = !Array.isArray(typeName) ? [typeName] : typeName;
 
         const firstAvailableName = possibleNames.find((name) => this.isTypeDefined(name));
         if (!firstAvailableName) return '';
 
         return (this.typeHasField(firstAvailableName, fieldName))
-            ? fieldName
+            ? specifier
             : '';
     }
 

src/rules/requests/request-handlers.ts

@@ -21,7 +21,7 @@ import {
 } from "../../types";
 
 import { MaybePromise, ErrorLike, isErrorLike } from '@httptoolkit/util';
-import { isAbsoluteUrl, getEffectivePort } from '../../util/url';
+import { isAbsoluteUrl, getEffectivePort, getDestination } from '../../util/url';
 import {
     waitForCompletedRequest,
     buildBodyReader,
@@ -413,8 +413,10 @@ export class PassThroughHandler extends PassThroughHandlerDefinition {
         dropDefaultHeaders(clientRes);
 
         // Capture raw request data:
-        let { method, url: reqUrl, rawHeaders } = clientReq as OngoingRequest;
-        let { protocol, hostname, port, path } = url.parse(reqUrl);
+        let { method, url: reqUrl, rawHeaders, destination } = clientReq as OngoingRequest;
+        let { protocol, path } = url.parse(reqUrl);
+        let hostname: string | null = destination.hostname;
+        let port: string | null = destination.port.toString();
 
         // Check if this request is a request loop:
         if (isSocketLoop(this.outgoingSockets, (clientReq as any).socket)) {
@@ -938,6 +940,10 @@ export class PassThroughHandler extends PassThroughHandlerDefinition {
                         protocol: protocol?.replace(':', '') ?? '',
                         method: method,
                         url: reqUrl,
+                        destination: {
+                            hostname: hostname || 'localhost',
+                            port: effectivePort
+                        },
                         path: path ?? '',
                         headers: reqHeader,
                         rawHeaders: rawHeaders,

src/server/http-combo-server.ts

@@ -17,9 +17,10 @@ import {
 } from 'read-tls-client-hello';
 import { URLPattern } from "urlpattern-polyfill";
 
-import { TlsHandshakeFailure } from '../types';
+import { Destination, TlsHandshakeFailure } from '../types';
 import { getCA } from '../util/tls';
 import { shouldPassThrough } from '../util/server-utils';
+import { getDestination } from '../util/url';
 import {
     getParentSocket,
     buildSocketTimingInfo,
@@ -32,9 +33,8 @@ import {
     LastHopEncrypted,
     TlsMetadata,
     TlsSetupCompleted,
-    getAddressAndPort,
-    resetOrDestroy,
-    SocketMetadata
+    SocketMetadata,
+    resetOrDestroy
 } from '../util/socket-util';
 import { MockttpHttpsOptions } from '../mockttp';
 import { buildSocksServer, SocksServerOptions, SocksTcpAddress } from './socks-server';
@@ -151,8 +151,8 @@ export interface ComboServerOptions {
 
     requestListener: (req: http.IncomingMessage, res: http.ServerResponse) => void;
     tlsClientErrorListener: (socket: tls.TLSSocket, req: TlsHandshakeFailure) => void;
-    tlsPassthroughListener: (socket: net.Socket, address: string, port?: number) => void;
-    rawPassthroughListener: (socket: net.Socket, address: string, port?: number) => void;
+    tlsPassthroughListener: (socket: net.Socket, hostname: string, port?: number) => void;
+    rawPassthroughListener: (socket: net.Socket, hostname: string, port?: number) => void;
 };
 
 // The low-level server that handles all the sockets & TLS. The server will correctly call the
@@ -249,19 +249,26 @@ export async function createComboServer(options: ComboServerOptions): Promise<De
 
     if (options.passthroughUnknownProtocols) {
         unknownProtocolServer = net.createServer((socket) => {
-            const destination = socket[LastTunnelAddress];
-            if (!destination) {
-                server.emit('clientError', new Error('Unknown protocol without destination'), socket);
-                return;
-            }
+            const tunnelAddress = socket[LastTunnelAddress];
 
-            const [host, port] = getAddressAndPort(destination);
-            if (!port) { // Both CONNECT & SOCKS require a port, so this shouldn't happen
-                server.emit('clientError', new Error('Unknown protocol without destination port'), socket);
-                return;
-            }
+            try {
+                if (!tunnelAddress) {
+                    server.emit('clientError', new Error('Unknown protocol without destination'), socket);
+                    return;
+                }
 
-            options.rawPassthroughListener(socket, host, port);
+                if (!tunnelAddress.includes(':')) {
+                    // Both CONNECT & SOCKS require a port, so this shouldn't happen
+                    server.emit('clientError', new Error('Unknown protocol without destination port'), socket);
+                    return;
+                }
+
+                const { hostname, port } = getDestination('unknown', tunnelAddress); // Has port, so no protocol required
+                options.rawPassthroughListener(socket, hostname, port);
+            } catch (e) {
+                console.error('Unknown protocol server error', e);
+                resetOrDestroy(socket);
+            }
         });
     }
 
@@ -432,7 +439,7 @@ function analyzeAndMaybePassThroughTls(
     server: tls.Server,
     passthroughList: Required<MockttpHttpsOptions>['tlsPassthrough'] | undefined,
     interceptOnlyList: Required<MockttpHttpsOptions>['tlsInterceptOnly'] | undefined,
-    passthroughListener: (socket: net.Socket, address: string, port?: number) => void
+    passthroughListener: (socket: net.Socket, hostname: string, port?: number) => void
 ) {
     if (passthroughList && interceptOnlyList){
         throw new Error('Cannot use both tlsPassthrough and tlsInterceptOnly options at the same time.');
@@ -450,23 +457,22 @@ function analyzeAndMaybePassThroughTls(
 
             // SNI is a good clue for where the request is headed, but an explicit proxy address (via
             // CONNECT or SOCKS) is even better. Note that this may be a hostname or IPv4/6 address:
-            let upstreamHostname: string | undefined;
-            let upstreamPort: number | undefined;
+            let upstreamDestination: Destination | undefined;
             if (socket[LastTunnelAddress]) {
-                ([upstreamHostname, upstreamPort] = getAddressAndPort(socket[LastTunnelAddress]));
+                upstreamDestination = getDestination('https', socket[LastTunnelAddress]);
             }
 
             socket[TlsMetadata] = {
                 sniHostname,
-                connectHostname: upstreamHostname,
-                connectPort: upstreamPort?.toString(),
+                connectHostname: upstreamDestination?.hostname,
+                connectPort: upstreamDestination?.port.toString(),
                 clientAlpn: helloData.alpnProtocols,
                 ja3Fingerprint: calculateJa3FromFingerprintData(helloData.fingerprintData),
                 ja4Fingerprint: calculateJa4FromHelloData(helloData)
             };
 
-            if (shouldPassThrough(upstreamHostname, passThroughPatterns, interceptOnlyPatterns)) {
-                passthroughListener(socket, upstreamHostname, upstreamPort);
+            if (shouldPassThrough(upstreamDestination?.hostname, passThroughPatterns, interceptOnlyPatterns)) {
+                passthroughListener(socket, upstreamDestination.hostname, upstreamDestination.port);
                 return; // Do not continue with TLS
             } else if (shouldPassThrough(sniHostname, passThroughPatterns, interceptOnlyPatterns)) {
                 passthroughListener(socket, sniHostname!); // Can't guess the port - not included in SNI