Skip to content

endpoints.md

Latest commit

 

History

History
173 lines (118 loc) · 4.39 KB

endpoints.md

File metadata and controls

173 lines (118 loc) · 4.39 KB

Endpoints

Endpoints represent backend servers that receive load-balanced traffic. There are two types:

  • Endpoint - Standard endpoint for basic load balancing
  • GeoEndpoint - Endpoint with geographic targeting for geo steering

Endpoint

Basic Usage

import { Endpoint } from "worker-lb";

const endpoint = new Endpoint("https://api.example.com");

The trailing slash is automatically removed from URLs.

With Custom Health Check Path

const endpoint = new Endpoint("https://api.example.com", {
  healthCheckPathname: "/health", // the default is "/"
});

The health check performs a GET request to the specified path and considers the endpoint healthy if it returns a 2xx status code.

Options

Option Type Default Description
healthCheckPathname `/${string}` "/" Path for health check requests (e.g., "/health")

Methods

commitRequest(request: Request): Promise<Response>

Forwards a request to this endpoint. Used internally by the LoadBalancer.

const endpoint = new Endpoint("https://api.example.com");
const response = await endpoint.commitRequest(request);

healthCheck(): Promise<boolean>

Performs a health check against this endpoint. Returns true if healthy.

const endpoint = new Endpoint("https://api.example.com", {
  healthCheckPathname: "/health",
});

const isHealthy = await endpoint.healthCheck();

GeoEndpoint

GeoEndpoint extends Endpoint with geographic targeting configuration. Used with geo steering to route requests based on client location.

Basic Usage

import { GeoEndpoint } from "worker-lb";

const endpoint = new GeoEndpoint("https://eu.api.example.com", {
  geo: { type: "continent", continents: ["EU"] },
});

Options

GeoEndpoint accepts all Endpoint options plus a required geo configuration:

Option Type Default Description
healthCheckPathname `/${string}` "/" Path for health check requests (e.g., "/health")
geo GeoConfig — Geographic targeting configuration (required)

Geo Configuration Types

Continent

new GeoEndpoint("https://eu.api.example.com", {
  geo: { type: "continent", continents: ["EU", "AF"] },
});

Continent codes: AF, AN, AS, EU, NA, OC, SA

Country

new GeoEndpoint("https://de.api.example.com", {
  geo: { type: "country", countries: ["DE", "AT", "CH"] },
});

Uses ISO 3166-1 alpha-2 codes. Use "T1" for TOR requests.

Region

new GeoEndpoint("https://west.api.example.com", {
  geo: { type: "region", regions: ["CA", "WA", "OR"] },
});

Uses ISO 3166-2 region/subdivision codes.

Colo

new GeoEndpoint("https://dfw.api.example.com", {
  geo: { type: "colo", colos: ["DFW", "IAH", "AUS"] },
});

Uses Cloudflare data center codes (IATA airport codes).

Methods

GeoEndpoint inherits all Endpoint methods plus:

matchesRequest(request: Request): boolean

Checks if this endpoint matches the request's geographic location.

const endpoint = new GeoEndpoint("https://eu.api.example.com", {
  geo: { type: "continent", continents: ["EU"] },
});

const matches = endpoint.matchesRequest(request);

Using Endpoints with LoadBalancer

Standard Load Balancing

import { Endpoint, LoadBalancer } from "worker-lb";

const lb = new LoadBalancer({
  endpoints: [
    new Endpoint("https://api1.example.com"),
    new Endpoint("https://api2.example.com"),
  ],
});

Geo Steering

import { GeoEndpoint, LoadBalancer } from "worker-lb";

const lb = new LoadBalancer({
  endpoints: [
    new GeoEndpoint("https://us.api.example.com", {
      geo: { type: "continent", continents: ["NA"] },
    }),
    new GeoEndpoint("https://eu.api.example.com", {
      geo: { type: "continent", continents: ["EU"] },
    }),
  ],
  steering: { type: "geo" },
});

See Geo Steering for detailed geo steering documentation.