Add SocatContainer

docs/features/containers.md

@@ -583,6 +583,27 @@ const container = await new GenericContainer("alpine")
   .start();
 ```
 
+## SocatContainer as a TCP proxy
+
+`SocatContainer` enables any TCP port of another container to be exposed publicly.
+
+```javascript
+const network = await new Network().start();
+
+const helloworld = await new GenericContainer("testcontainers/helloworld:1.2.0")
+    .withExposedPorts(8080)
+    .withNetwork(network)
+    .withNetworkAliases("helloworld")
+    .start();
+
+const socat = await new SocatContainer().withNetwork(network).withTarget(8081, "helloworld", 8080).start();
+
+const socatUrl = `http://${socat.getHost()}:${socat.getMappedPort(8081)}`;
+```
+
+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. 

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

@@ -0,0 +1,51 @@
+import { fetch } from "undici";
+import { GenericContainer } from "../generic-container/generic-container";
+import { Network } from "../network/network";
+import { SocatContainer } from "./socat-container";
+
+describe("Socat", { timeout: 120_000 }, () => {
+  it("should forward requests to helloworld container", async () => {
+    const network = await new Network().start();
+
+    const helloworld = await new GenericContainer("testcontainers/helloworld:1.2.0")
+      .withExposedPorts(8080)
+      .withNetwork(network)
+      .withNetworkAliases("helloworld")
+      .start();
+
+    const socat = await new SocatContainer().withNetwork(network).withTarget(8080, "helloworld").start();
+
+    const socatUrl = `http://${socat.getHost()}:${socat.getMappedPort(8080)}`;
+
+    const response = await fetch(`${socatUrl}/ping`);
+
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe("PONG");
+
+    await socat.stop();
+    await helloworld.stop();
+    await network.stop();
+  });
+  it("should forward requests to helloworld container in a different port", async () => {
+    const network = await new Network().start();
+
+    const helloworld = await new GenericContainer("testcontainers/helloworld:1.2.0")
+      .withExposedPorts(8080)
+      .withNetwork(network)
+      .withNetworkAliases("helloworld")
+      .start();
+
+    const socat = await new SocatContainer().withNetwork(network).withTarget(8081, "helloworld", 8080).start();
+
+    const socatUrl = `http://${socat.getHost()}:${socat.getMappedPort(8081)}`;
+
+    const response = await fetch(`${socatUrl}/ping`);
+
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe("PONG");
+
+    await socat.stop();
+    await helloworld.stop();
+    await network.stop();
+  });
+});

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

@@ -0,0 +1,40 @@
+import { RandomUuid } from "../common";
+import { AbstractStartedContainer } from "../generic-container/abstract-started-container";
+import { GenericContainer } from "../generic-container/generic-container";
+import { StartedTestContainer } from "../test-container";
+
+export class SocatContainer extends GenericContainer {
+  private targets: { [key in number]: string } = {};
+
+  constructor(image = "alpine/socat:1.7.4.3-r0") {
+    super(image);
+    this.withEntrypoint(["/bin/sh"]);
+    this.withName(`testcontainers-socat-${new RandomUuid().nextUuid()}`);
+  }
+
+  public withTarget(exposePort: number, host: string): this;
+  public withTarget(exposePort: number, host: string, internalPort: number): this;
+  public withTarget(exposePort: number, host: string, internalPort?: number): this {
+    this.withExposedPorts(exposePort);
+    if (internalPort == null) {
+      internalPort = exposePort;
+    }
+    this.targets[exposePort] = `${host}:${internalPort}`;
+    return this;
+  }
+
+  public override async start(): Promise<StartedSocatContainer> {
+    const command = Object.entries(this.targets)
+      .map(([exposePort, target]) => `socat TCP-LISTEN:${exposePort},fork,reuseaddr TCP:${target}`)
+      .join(" & ");
+
+    this.withCommand(["-c", command]);
+    return new StartedSocatContainer(await super.start());
+  }
+}
+
+export class StartedSocatContainer extends AbstractStartedContainer {
+  constructor(startedTestcontainers: StartedTestContainer) {
+    super(startedTestcontainers);
+  }
+}

packages/testcontainers/src/types.ts

@@ -104,3 +104,5 @@ export type NetworkSettings = {
   networkId: string;
   ipAddress: string;
 };
+
+export { SocatContainer, StartedSocatContainer } from "./socat/socat-container";