Replace TLS event connectHostname/Port & 'hostname' with 'destination'

In most cases, you want event.destination.hostname to get the final
target of any given request/tunnel/etc. If you're looking for the SNI
hostname for a TLS connection, that's under
event.tlsMetadata.sniHostname. The previous 'hostname' field was
ambiguous and has been removed.

Author: pimterry

src/admin/mockttp-schema.ts

@@ -64,8 +64,7 @@ export const MockttpSchema = gql`
     type TlsPassthroughEvent {
         id: String!
 
-        upstreamHost: String
-        upstreamPort: Int!
+        destination: Destination!
 
         hostname: String
         remoteIpAddress: String!
@@ -123,8 +122,7 @@ export const MockttpSchema = gql`
     type RawPassthroughEvent {
         id: String!
 
-        upstreamHost: String!
-        upstreamPort: Int!
+        destination: Destination!
 
         remoteIpAddress: String!
         remotePort: Int!

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

@@ -384,8 +384,13 @@ export class MockttpAdminRequestBuilder {
                 tlsPassthroughOpened {
                     id
 
-                    ${this.schema.asOptionalField('TlsPassthroughEvent', 'upstreamHost')}
-                    upstreamPort
+                    ${this.schema.typeHasField('TlsPassthroughEvent', 'destination')
+                        ? 'destination { hostname, port }'
+                        : `
+                            upstreamHost
+                            upstreamPort
+                        `
+                    }
 
                     hostname
                     remoteIpAddress
@@ -399,8 +404,13 @@ export class MockttpAdminRequestBuilder {
                 tlsPassthroughClosed {
                     id
 
-                    ${this.schema.asOptionalField('TlsPassthroughEvent', 'upstreamHost')}
-                    upstreamPort
+                    ${this.schema.typeHasField('TlsPassthroughEvent', 'destination')
+                        ? 'destination { hostname, port }'
+                        : `
+                            upstreamHost
+                            upstreamPort
+                        `
+                    }
 
                     hostname
                     remoteIpAddress
@@ -464,8 +474,7 @@ export class MockttpAdminRequestBuilder {
                 rawPassthroughOpened {
                     id
 
-                    upstreamHost
-                    upstreamPort
+                    destination { hostname, port }
 
                     remoteIpAddress
                     remotePort
@@ -477,8 +486,7 @@ export class MockttpAdminRequestBuilder {
                 rawPassthroughClosed {
                     id
 
-                    upstreamHost
-                    upstreamPort
+                    destination { hostname, port }
 
                     remoteIpAddress
                     remotePort

src/server/http-combo-server.ts

@@ -474,8 +474,6 @@ function analyzeAndMaybePassThroughTls(
 
             socket[TlsMetadata] = {
                 sniHostname,
-                connectHostname: upstreamDestination?.hostname,
-                connectPort: upstreamDestination?.port.toString(),
                 clientAlpn: helloData.alpnProtocols,
                 ja3Fingerprint: calculateJa3FromFingerprintData(helloData.fingerprintData),
                 ja4Fingerprint: calculateJa4FromHelloData(helloData)

src/server/mockttp-server.ts

@@ -565,8 +565,6 @@ export class MockttpServer extends AbstractMockttp implements Mockttp {
         if (socket instanceof tls.TLSSocket && socket[TlsSetupCompleted]) return;
 
         setImmediate(() => {
-            // We can get falsey but set hostname values - drop them
-            if (!request.hostname) delete request.hostname;
             if (this.debug) console.warn(`TLS client error: ${JSON.stringify(request)}`);
             this.eventEmitter.emit('tls-client-error', request);
         });
@@ -1193,8 +1191,7 @@ ${await this.suggestRule(request)}`
             {
                 id: uuid(),
                 hostname: hostname, // Deprecated, but kept here for backward compat
-                upstreamHost: hostname,
-                upstreamPort: targetPort
+                destination: { hostname, port: targetPort }
             }
         );
 

src/types.ts

@@ -93,31 +93,24 @@ export interface Request {
 }
 
 export interface TlsConnectionEvent {
-    /**
-     * @deprecated - Use `tlsMetadata.sniHostname` or `tlsMetadata.connectHostname` for
-     * handshake/tunnel details, or `upstreamHost` in passthrough events for the
-     * upstream host of the passthrough tunnel.
-     */
-    hostname?: string;
-
     remoteIpAddress?: string; // Can be unavailable in some error cases
     remotePort?: number; // Can be unavailable in some error cases
     tags: string[];
     timingEvents: TlsTimingEvents;
+    destination?: Destination; // Set for tunnelled requests only
     tlsMetadata: TlsSocketMetadata;
 }
 
 export interface TlsSocketMetadata {
     sniHostname?: string;
-    connectHostname?: string;
-    connectPort?: string;
     clientAlpn?: string[];
     ja3Fingerprint?: string;
     ja4Fingerprint?: string;
 }
 
 export interface TlsPassthroughEvent extends RawPassthroughEvent, TlsConnectionEvent {
     // Removes ambiguity of the two parent interface fields
+    destination: Destination;
     remoteIpAddress: string;
     remotePort: number;
     timingEvents: TlsTimingEvents;
@@ -137,8 +130,7 @@ export interface TlsHandshakeFailure extends TlsConnectionEvent {
 export interface RawPassthroughEvent {
     id: string;
 
-    upstreamHost: string;
-    upstreamPort: number;
+    destination: Destination;
 
     /**
      * The IP address of the remote client that initiated the connection.

src/util/socket-util.ts

@@ -166,7 +166,7 @@ export function resetOrDestroy(requestOrSocket:
 
 export function buildRawSocketEventData(
     socket: net.Socket
-): Omit<RawPassthroughEvent, 'id' | 'upstreamHost' | 'upstreamPort'> {
+): Omit<RawPassthroughEvent, 'id' | 'destination'> {
     const timingInfo = socket[SocketTimingInfo] ||
         socket._parent?.[SocketTimingInfo] ||
         buildSocketTimingInfo();
@@ -190,7 +190,7 @@ export function buildRawSocketEventData(
 
 export function buildTlsSocketEventData(
     socket: net.Socket & Partial<tls.TLSSocket>
-): Omit<RawPassthroughEvent, 'id' | 'upstreamHost' | 'upstreamPort'> & TlsConnectionEvent {
+): Omit<RawPassthroughEvent, 'id' | 'destination'> & TlsConnectionEvent {
     const rawSocketData = buildRawSocketEventData(socket) as Partial<TlsConnectionEvent>;
 
     const timingInfo = socket[SocketTimingInfo] ||
@@ -203,8 +203,6 @@ export function buildTlsSocketEventData(
         socket._parent?.[TlsMetadata] ||
         {};
 
-    rawSocketData.hostname = socket.servername;
-
     return rawSocketData as any;
 }
 

test/integration/subscriptions/raw-passthrough-events.spec.ts

@@ -48,7 +48,7 @@ nodeOnly(() => {
         });
 
         it("should fire for raw sockets that are passed through SOCKS", async () => {
-            const events: any[] = [];
+            const events: Array<RawPassthroughEvent> = [];
             await server.on('raw-passthrough-opened', (e) => events.push(e));
             await server.on('raw-passthrough-closed', (e) => events.push(e));
 
@@ -62,8 +62,8 @@ nodeOnly(() => {
             const [openEvent, closeEvent] = events;
             expect(openEvent.id).to.equal(closeEvent.id);
 
-            expect(openEvent.upstreamHost).to.equal('localhost');
-            expect(openEvent.upstreamPort).to.equal(remotePort);
+            expect(openEvent.destination.hostname).to.equal('localhost');
+            expect(openEvent.destination.port).to.equal(remotePort);
         });
 
         it("should expose sent & received data", async () => {
@@ -144,8 +144,8 @@ nodeOnly(() => {
                 expect(sentEvent.id).to.equal(openEvent.id);
                 expect(openEvent.id).to.equal(closeEvent.id);
 
-                expect(openEvent.upstreamHost).to.equal('localhost');
-                expect(openEvent.upstreamPort).to.equal(remotePort);
+                expect(openEvent.destination.hostname).to.equal('localhost');
+                expect(openEvent.destination.port).to.equal(remotePort);
 
                 expect(receivedEvent.content.toString()).to.equal('123456789');
                 expect(receivedEvent.direction).to.equal('received');

test/integration/subscriptions/tls-error-events.spec.ts

@@ -93,7 +93,6 @@ describe("TLS error subscriptions", () => {
             'reset', // Node 12+
             'cert-rejected' // Chrome
         ]);
-        expect(tlsError.hostname).to.equal('localhost');
         expect(tlsError.remoteIpAddress).to.be.oneOf([
             '::ffff:127.0.0.1', // IPv4 localhost
             '::1' // IPv6 localhost
@@ -133,7 +132,6 @@ describe("TLS error subscriptions", () => {
             const tlsError = await seenTlsErrorPromise;
 
             expect(tlsError.failureCause).to.be.equal('reset');
-            expect(tlsError.hostname).to.equal('localhost');
             expect(tlsError.remoteIpAddress).to.be.oneOf([
                 '::ffff:127.0.0.1', // IPv4 localhost
                 '::1' // IPv6 localhost

test/integration/subscriptions/tls-passthrough-events.spec.ts

@@ -41,13 +41,11 @@ describe("TLS passthrough subscriptions", () => {
         const [openEvent, closeEvent] = events;
         expect(openEvent.id).to.equal(closeEvent.id);
 
-        expect(openEvent.hostname).to.equal('bypass.localhost');
-        expect(openEvent.upstreamPort).to.equal(443);
+        expect(openEvent.destination.hostname).to.equal('bypass.localhost');
+        expect(openEvent.destination.port).to.equal(443);
 
         const { tlsMetadata } = openEvent;
         expect(tlsMetadata.sniHostname).to.equal('bypass.localhost');
-        expect(tlsMetadata.connectHostname).to.equal(undefined);
-        expect(tlsMetadata.connectPort).to.equal(undefined);
         expect(tlsMetadata.clientAlpn).to.deep.equal(isNode
             ? undefined
             : ['h2', 'http/1.1']