Implement support for specifying the protocol when exposing ports (#1068)

Author: technocidal

docs/features/containers.md

@@ -572,6 +572,31 @@ const container = await new GenericContainer("alpine")
 const httpPort = container.getFirstMappedPort();
 ```
 
+Specify a protocol for the exposed port:
+
+```javascript
+const container = await new GenericContainer("alpine")
+  .withExposedPorts({
+    container: 80,
+    protocol: "udp"
+  })
+  .start();
+
+const httpPort = container.getMappedPort(80, "udp");
+```
+
+Alternatively, specify the protocol using a string with the format `port/protocol`:
+
+```javascript
+const container = await new GenericContainer("alpine")
+  .withExposedPorts("80/udp")
+  .start();
+
+const httpPort = container.getMappedPort("80/udp");
+```
+
+If no protocol is specified, it defaults to `tcp`.
+
 Specify fixed host port bindings (**not recommended**):
 
 ```javascript
@@ -609,12 +634,12 @@ expect(response.status).toBe(200);
 expect(await response.text()).toBe("PONG");
 ```
 
-The example above starts a `testcontainers/helloworld` container and a `socat` container. 
+The example above starts a `testcontainers/helloworld` container and a `socat` container.
 The `socat` container is configured to forward traffic from port `8081` to the `testcontainers/helloworld` container on port `8080`.
 
 ## Running commands
 
-To run a command inside an already started container, use the exec method. 
+To run a command inside an already started container, use the exec method.
 The command will be run in the container's working directory,
 returning the combined output (`output`), standard output (`stdout`), standard error (`stderr`), and exit code (`exitCode`).
 

packages/modules/azurite/src/azurite-container.ts

@@ -1,6 +1,7 @@
 import {
   AbstractStartedContainer,
   GenericContainer,
+  getContainerPort,
   hasHostBinding,
   PortWithOptionalBinding,
   StartedTestContainer,
@@ -171,23 +172,26 @@ export class StartedAzuriteContainer extends AbstractStartedContainer {
     if (hasHostBinding(this.blobPort)) {
       return this.blobPort.host;
     } else {
-      return this.getMappedPort(this.blobPort);
+      const containerPort = getContainerPort(this.blobPort);
+      return this.getMappedPort(containerPort);
     }
   }
 
   public getQueuePort(): number {
     if (hasHostBinding(this.queuePort)) {
       return this.queuePort.host;
     } else {
-      return this.getMappedPort(this.queuePort);
+      const containerPort = getContainerPort(this.queuePort);
+      return this.getMappedPort(containerPort);
     }
   }
 
   public getTablePort(): number {
     if (hasHostBinding(this.tablePort)) {
       return this.tablePort.host;
     } else {
-      return this.getMappedPort(this.tablePort);
+      const containerPort = getContainerPort(this.tablePort);
+      return this.getMappedPort(containerPort);
     }
   }
 

packages/testcontainers/src/generic-container/abstract-started-container.ts

@@ -43,7 +43,12 @@ export class AbstractStartedContainer implements StartedTestContainer {
     return this.startedTestContainer.getFirstMappedPort();
   }
 
-  public getMappedPort(port: number): number {
+  public getMappedPort(port: number, protocol?: string): number;
+  public getMappedPort(portWithProtocol: `${number}/${"tcp" | "udp"}`): number;
+  public getMappedPort(port: number | `${number}/${"tcp" | "udp"}`, protocol?: string): number {
+    if (typeof port === "number") {
+      return this.startedTestContainer.getMappedPort(port, protocol);
+    }
     return this.startedTestContainer.getMappedPort(port);
   }
 

packages/testcontainers/src/generic-container/generic-container.test.ts

@@ -5,10 +5,12 @@ import { getContainerRuntimeClient } from "../container-runtime";
 import { PullPolicy } from "../utils/pull-policy";
 import {
   checkContainerIsHealthy,
+  checkContainerIsHealthyUdp,
   getDockerEventStream,
   getRunningContainerNames,
   waitForDockerEvent,
 } from "../utils/test-helper";
+import { Wait } from "../wait-strategies/wait";
 import { GenericContainer } from "./generic-container";
 
 describe("GenericContainer", { timeout: 180_000 }, () => {
@@ -22,6 +24,17 @@ describe("GenericContainer", { timeout: 180_000 }, () => {
     expect(container.getFirstMappedPort()).toBe(container.getMappedPort(8080));
   });
 
+  it("should return first mapped port with regardless of protocol", async () => {
+    await using container = await new GenericContainer("mendhak/udp-listener")
+      .withWaitStrategy(Wait.forLogMessage("Listening on UDP port 5005"))
+      .withExposedPorts("5005/udp")
+      .start();
+
+    await checkContainerIsHealthyUdp(container);
+    expect(container.getFirstMappedPort()).toBe(container.getMappedPort("5005/udp"));
+    expect(container.getFirstMappedPort()).toBe(container.getMappedPort(5005, "udp"));
+  });
+
   it("should bind to specified host port", async () => {
     const hostPort = await getPort();
     await using container = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
@@ -35,6 +48,22 @@ describe("GenericContainer", { timeout: 180_000 }, () => {
     expect(container.getMappedPort(8080)).toBe(hostPort);
   });
 
+  it("should bind to specified host port with a different protocol", async () => {
+    const hostPort = await getPort();
+    await using container = await new GenericContainer("mendhak/udp-listener")
+      .withWaitStrategy(Wait.forLogMessage("Listening on UDP port 5005"))
+      .withExposedPorts({
+        container: 5005,
+        host: hostPort,
+        protocol: "udp",
+      })
+      .start();
+
+    await checkContainerIsHealthyUdp(container);
+    expect(container.getMappedPort("5005/udp")).toBe(hostPort);
+    expect(container.getMappedPort(5005, "udp")).toBe(hostPort);
+  });
+
   it("should execute a command on a running container", async () => {
     await using container = await new GenericContainer("cristianrgreco/testcontainer:1.1.14")
       .withExposedPorts(8080)

packages/testcontainers/src/generic-container/generic-container.ts

@@ -27,7 +27,7 @@ import {
 import { BoundPorts } from "../utils/bound-ports";
 import { createLabels, LABEL_TESTCONTAINERS_CONTAINER_HASH, LABEL_TESTCONTAINERS_SESSION_ID } from "../utils/labels";
 import { mapInspectResult } from "../utils/map-inspect-result";
-import { getContainerPort, hasHostBinding, PortWithOptionalBinding } from "../utils/port";
+import { getContainerPort, getProtocol, hasHostBinding, PortWithOptionalBinding } from "../utils/port";
 import { ImagePullPolicy, PullPolicy } from "../utils/pull-policy";
 import { Wait } from "../wait-strategies/wait";
 import { waitForContainer } from "../wait-strategies/wait-for-container";
@@ -364,7 +364,9 @@ export class GenericContainer implements TestContainer {
   public withExposedPorts(...ports: PortWithOptionalBinding[]): this {
     const exposedPorts: { [port: string]: Record<string, never> } = {};
     for (const exposedPort of ports) {
-      exposedPorts[`${getContainerPort(exposedPort).toString()}/tcp`] = {};
+      const containerPort = getContainerPort(exposedPort);
+      const protocol = getProtocol(exposedPort);
+      exposedPorts[`${containerPort}/${protocol}`] = {};
     }
 
     this.exposedPorts = [...this.exposedPorts, ...ports];
@@ -375,10 +377,12 @@ export class GenericContainer implements TestContainer {
 
     const portBindings: Record<string, Array<Record<string, string>>> = {};
     for (const exposedPort of ports) {
+      const protocol = getProtocol(exposedPort);
       if (hasHostBinding(exposedPort)) {
-        portBindings[`${exposedPort.container}/tcp`] = [{ HostPort: exposedPort.host.toString() }];
+        portBindings[`${exposedPort.container}/${protocol}`] = [{ HostPort: exposedPort.host.toString() }];
       } else {
-        portBindings[`${exposedPort}/tcp`] = [{ HostPort: "0" }];
+        const containerPort = getContainerPort(exposedPort);
+        portBindings[`${containerPort}/${protocol}`] = [{ HostPort: "0" }];
       }
     }
 

packages/testcontainers/src/generic-container/inspect-container-util-ports-exposed.test.ts

@@ -17,7 +17,10 @@ function mockInspectResult(
 
 describe.sequential("inspectContainerUntilPortsExposed", () => {
   it("returns the inspect result when all ports are exposed", async () => {
-    const data = mockInspectResult({ "8080/tcp": [] }, { "8080/tcp": [{ HostIp: "0.0.0.0", HostPort: "45000" }] });
+    const data = mockInspectResult(
+      { "8080/tcp": [], "8081/udp": [] },
+      { "8080/tcp": [{ HostIp: "0.0.0.0", HostPort: "45000" }], "8081/udp": [{ HostIp: "0.0.0.0", HostPort: "45001" }] }
+    );
     const inspectFn = vi.fn().mockResolvedValueOnce(data);
 
     const result = await inspectContainerUntilPortsExposed(inspectFn, "container-id");

packages/testcontainers/src/generic-container/started-generic-container.ts

@@ -10,6 +10,7 @@ import { CommitOptions, ContentToCopy, DirectoryToCopy, ExecOptions, ExecResult,
 import { BoundPorts } from "../utils/bound-ports";
 import { LABEL_TESTCONTAINERS_SESSION_ID } from "../utils/labels";
 import { mapInspectResult } from "../utils/map-inspect-result";
+import { PortWithOptionalBinding } from "../utils/port";
 import { waitForContainer } from "../wait-strategies/wait-for-container";
 import { WaitStrategy } from "../wait-strategies/wait-strategy";
 import { inspectContainerUntilPortsExposed } from "./inspect-container-util-ports-exposed";
@@ -95,7 +96,10 @@ export class StartedGenericContainer implements StartedTestContainer {
     }
 
     this.boundPorts = BoundPorts.fromInspectResult(client.info.containerRuntime.hostIps, mappedInspectResult).filter(
-      Array.from(this.boundPorts.iterator()).map((port) => port[0])
+      Array.from(this.boundPorts.iterator()).map((port) => {
+        const [portNumber, protocol] = port[0].split("/");
+        return `${portNumber}/${protocol}` as PortWithOptionalBinding;
+      })
     );
 
     await waitForContainer(client, this.container, this.waitStrategy, this.boundPorts, startTime);
@@ -136,8 +140,8 @@ export class StartedGenericContainer implements StartedTestContainer {
     return this.boundPorts.getFirstBinding();
   }
 
-  public getMappedPort(port: number): number {
-    return this.boundPorts.getBinding(port);
+  public getMappedPort(port: string | number, protocol: string = "tcp"): number {
+    return this.boundPorts.getBinding(port, protocol);
   }
 
   public getId(): string {

packages/testcontainers/src/test-container.ts

@@ -71,7 +71,8 @@ export interface StartedTestContainer extends AsyncDisposable {
   getHost(): string;
   getHostname(): string;
   getFirstMappedPort(): number;
-  getMappedPort(port: number): number;
+  getMappedPort(port: number, protocol?: string): number;
+  getMappedPort(portWithProtocol: `${number}/${"tcp" | "udp"}`): number;
   getName(): string;
   getLabels(): Labels;
   getId(): string;

packages/testcontainers/src/types.ts

@@ -69,7 +69,7 @@ export type ExtraHost = {
 export type Labels = { [key: string]: string };
 
 export type HostPortBindings = Array<{ hostIp: string; hostPort: number }>;
-export type Ports = { [containerPort: number]: HostPortBindings };
+export type Ports = { [containerPortWithProtocol: string]: HostPortBindings };
 
 export type AuthConfig = {
   username: string;

packages/testcontainers/src/utils/bound-ports.test.ts

@@ -10,6 +10,27 @@ describe("BoundPorts", () => {
     expect(boundPorts.getBinding(1)).toBe(1000);
   });
 
+  it("should return a binding with protocol", () => {
+    const boundPorts = new BoundPorts();
+    boundPorts.setBinding(1, 1000, "tcp");
+    boundPorts.setBinding(1, 2000, "udp");
+
+    expect(boundPorts.getBinding(1)).toBe(1000);
+    expect(boundPorts.getBinding(1, "tcp")).toBe(1000);
+    expect(boundPorts.getBinding(1, "udp")).toBe(2000);
+  });
+
+  it("should accept string port keys", () => {
+    const boundPorts = new BoundPorts();
+    boundPorts.setBinding("8080/tcp", 1000);
+    boundPorts.setBinding("8080/udp", 2000);
+
+    expect(boundPorts.getBinding("8080/tcp")).toBe(1000);
+    expect(boundPorts.getBinding("8080/udp")).toBe(2000);
+    expect(boundPorts.getBinding(8080, "tcp")).toBe(1000);
+    expect(boundPorts.getBinding(8080, "udp")).toBe(2000);
+  });
+
   describe("BoundPorts", () => {
     it("should return a binding", () => {
       const boundPorts = new BoundPorts();
@@ -38,16 +59,17 @@ describe("BoundPorts", () => {
       boundPorts.setBinding(1, 1000);
 
       for (const [internalPort, hostPort] of boundPorts.iterator()) {
-        expect(internalPort).toBe(1);
+        expect(internalPort).toBe("1/tcp");
         expect(hostPort).toBe(1000);
       }
     });
 
     it("should instantiate from an inspect result", () => {
       const inspectResult: Partial<InspectResult> = {
         ports: {
-          8080: [{ hostIp: "0.0.0.0", hostPort: 10000 }],
-          8081: [{ hostIp: "0.0.0.0", hostPort: 10001 }],
+          "8080/tcp": [{ hostIp: "0.0.0.0", hostPort: 10000 }],
+          "8081/tcp": [{ hostIp: "0.0.0.0", hostPort: 10001 }],
+          "8080/udp": [{ hostIp: "0.0.0.0", hostPort: 10002 }],
         },
       };
       const hostIps: HostIp[] = [{ address: "127.0.0.1", family: 4 }];
@@ -56,6 +78,8 @@ describe("BoundPorts", () => {
 
       expect(boundPorts.getBinding(8080)).toBe(10000);
       expect(boundPorts.getBinding(8081)).toBe(10001);
+      expect(boundPorts.getBinding(8080, "tcp")).toBe(10000);
+      expect(boundPorts.getBinding(8080, "udp")).toBe(10002);
     });
 
     it("should filter port bindings", () => {
@@ -68,6 +92,32 @@ describe("BoundPorts", () => {
       expect(() => filtered.getBinding(1)).toThrowError("No port binding found for :1");
       expect(filtered.getBinding(2)).toBe(2000);
     });
+
+    it("should filter port bindings with protocols", () => {
+      const boundPorts = new BoundPorts();
+      boundPorts.setBinding(8080, 1000, "tcp");
+      boundPorts.setBinding(8080, 2000, "udp");
+      boundPorts.setBinding(9090, 3000, "tcp");
+
+      let filtered = boundPorts.filter([8080]);
+      expect(filtered.getBinding(8080)).toBe(1000);
+      expect(() => filtered.getBinding(8080, "udp")).toThrowError("No port binding found for :8080/udp");
+      expect(() => filtered.getBinding(9090)).toThrowError("No port binding found for :9090/tcp");
+
+      filtered = boundPorts.filter(["8080/udp"]);
+      expect(filtered.getBinding(8080, "udp")).toBe(2000);
+      expect(() => filtered.getBinding(8080, "tcp")).toThrowError("No port binding found for :8080/tcp");
+    });
+
+    it("should handle case-insensitive protocols", () => {
+      const boundPorts = new BoundPorts();
+      boundPorts.setBinding(8080, 1000, "tcp");
+      expect(boundPorts.getBinding(8080, "TCP")).toBe(1000);
+
+      boundPorts.setBinding("9090/TCP", 2000);
+      expect(boundPorts.getBinding(9090, "tcp")).toBe(2000);
+      expect(boundPorts.getBinding("9090/tcp")).toBe(2000);
+    });
   });
 
   describe("resolveHostPortBinding", () => {