containers-network

Network routing utilities for Cloudflare Containers. Provides TCP and HTTP proxy classes that intercept outbound connections from containers and route them to other services.

Installation

npm install containers-network

Usage

Create proxy classes using makeTCPProxy or makeHTTPProxy, then route container traffic through them.

TCP Proxy

import {
  ContainerInNetwork,
  makeTCPProxy,
  VIRTUAL_HOST_IP,
} from "containers-network";

// Create proxy classes for your services
export const Database = makeTCPProxy(
  (env) => env.DATABASE.getByName("production"),  // returns a Container
  5432,
);

export const Validator = makeTCPProxy(
  (env) => env.VALIDATOR.getByName("production"), // returns a Container
  8080,
);

// Use in your container class
export class ComputeContainer extends ContainerInNetwork<Env> {
  async onStart() {
    // Route outbound connections to your proxies
    await this.route(this.ctx.exports.Database({}));
    await this.route(this.ctx.exports.Validator({}));
  }

  ...
}

Inside the container, connect to 10.0.0.2:5432 to reach the database or use VIRTUAL_HOST_IP which equals "10.0.0.2".

HTTP Proxy

import { makeHTTPProxy } from "containers-network";

export const MyAPI = makeHTTPProxy(
  (env) => env.API_SERVICE, // Returns a HTTP service (Fetcher)
  "api.example.com",
);

// Use in your container class
export class ComputeContainer extends ContainerInNetwork<Env> {
  async onStart() {
    // Route outbound connections to your proxies
    await this.route(this.ctx.exports.MyAPI({}));
  }

  ...
}

Inside the container, call api.example.com to reach the your API service.

API

makeTCPProxy<Env>(getTarget, port)

Creates a TCP proxy class that intercepts outbound TCP connections.

• getTarget: Function that returns a ContainerInNetwork instance from env
• port: Target port number
• Returns: Class extending WorkerEntrypoint for RPC routing

makeHTTPProxy<Env>(getTarget, hostname)

Creates an HTTP proxy class that intercepts outbound HTTP connections.

• getTarget: Function that returns a Fetcher instance from env
• hostname: Target hostname for routing
• Returns: Class extending WorkerEntrypoint for RPC routing

ContainerInNetwork<Env>

Base container class with network routing capabilities.

Methods

• route(proxy): Registers a proxy to intercept outbound connections