worker-lb 0.0.1

package/README.md

@@ -0,0 +1,17 @@
+# worker-lb
+
+> [!NOTE]
+> **WARNING:** I don't know if you should use this in production just yet, this is more of an experiment and by no means is battle-tested.
+
+worker-lb is a small and extensible load balancer built on Cloudflare Workers. It's basically a poor mans Cloudflare Load Balancer, but running on Cloudflare Workers, because why not.
+
+## Features
+
+- Failover between multiple HTTP endpoints
+- Health checks with customizable intervals and timeouts
+- "Dooms-day mode" to automatically dump traffic to a log file when all backends are down (not finished yet)
+
+## Use Cases
+
+- Simple load balancing for dirty small projects
+- Latency is not a concern but reliability is

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "worker-lb",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src/index.ts"
+  ],
+  "scripts": {
+    "publish": "bun publish"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241218.0",
+    "@types/bun": "^1.3.6"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/index.ts

@@ -0,0 +1,226 @@
+/**
+ * The process in which fall back is handled.
+ *
+ * `async-block` – One by one check and select the first available endpoint
+ *
+ * `promise.any` – Use Promise.any to select the first available endpoint that responds successfully
+ *
+ * `fail-forward` – Always use the first endpoint, fail over to the next only on specified failure conditions
+ *
+ */
+export type AvailabilityMethodType =
+  | "async-block"
+  | "promise.any"
+  | "fail-forward";
+
+export interface AvailabilityMethodOptions {
+  "async-block": {
+    /**
+     * async-block requires a health endpoint to check availability of the service
+     *
+     * @example "/health"
+     */
+    healthCheckPathname: `/${string}`;
+  };
+  "promise.any": {
+    /**
+     * promise.any requires a health endpoint to check availability of the service
+     *
+     * @example "/health"
+     *
+     */
+    healthEndpoint: `/${string}`;
+  };
+  "fail-forward": {
+    /**
+     * Statuses that should result in a failover
+     *
+     * @default [502, 503, 504]
+     */
+    failoverOnStatuses?: number[];
+  };
+}
+
+export type AvailabilityMethod = {
+  [K in AvailabilityMethodType]: {
+    type: K;
+    options?: AvailabilityMethodOptions[K];
+  };
+}[AvailabilityMethodType];
+
+export const DEFAULT_FAILOVER_STATUSES = [502, 503, 504];
+
+type RecoveryFn = (request: Request) => Promise<Response | undefined>;
+
+export interface LoadBalancerOptions {
+  /**
+   * The endpoints that you want to load balance against
+   *
+   * @example ["https://us-east-1.api.capy.lol/v1", "https://us-west-1.api.capy.lol/v1"]
+   */
+  endpoints: string[];
+  /**
+   * The availability method when failure happens.
+   *
+   * @default { type: "fail-forward"  }
+   */
+  availability?: AvailabilityMethod;
+  /**
+   * A recovery function that you can customize to dump data or notify on failures. This only runs when all endpoints are unavailable.
+   *
+   * Some ideas for ya bud:
+   * - Send a notification to a monitoring service
+   * - Dump the request data to an S3/R2 bucket for replaying later.
+   */
+  recoveryFn?: RecoveryFn;
+}
+
+export class LoadBalancer {
+  private endpoints: string[];
+  private availability: AvailabilityMethod;
+  private recoveryFn?: RecoveryFn;
+
+  constructor(options: LoadBalancerOptions) {
+    if (!options.endpoints || options.endpoints.length === 0) {
+      throw new Error("At least one endpoint is required");
+    }
+
+    this.endpoints = options.endpoints.map((url) => url.replace(/\/$/, "")); // remove trailing slash
+    this.availability = options.availability ?? {
+      type: "fail-forward",
+    };
+
+    if (
+      this.availability.type === "fail-forward" &&
+      !this.availability.options?.failoverOnStatuses
+    ) {
+      this.availability.options = {
+        failoverOnStatuses: DEFAULT_FAILOVER_STATUSES,
+      };
+    }
+
+    this.recoveryFn = options.recoveryFn;
+  }
+
+  async getAvailableEndpoint(): Promise<string> {
+    switch (this.availability.type) {
+      case "async-block":
+        return this.getEndpointAsyncBlock();
+      case "promise.any":
+        return this.getEndpointPromiseAny();
+      case "fail-forward":
+        return this.endpoints[0]!;
+    }
+  }
+
+  private async getEndpointAsyncBlock(): Promise<string> {
+    if (this.availability.type !== "async-block") {
+      throw new Error("Availability method is not async-block");
+    }
+
+    for (const endpoint of this.endpoints) {
+      try {
+        const response = await fetch(
+          endpoint + this.availability.options?.healthCheckPathname,
+          {
+            method: "GET",
+          },
+        );
+        if (response.ok) {
+          return endpoint;
+        }
+      } catch {
+        continue;
+      }
+    }
+    throw new Error("No available endpoints");
+  }
+
+  private async getEndpointPromiseAny(): Promise<string> {
+    if (this.availability.type !== "promise.any") {
+      throw new Error("Availability method is not promise.any");
+    }
+
+    const healthPathname = this.availability.options?.healthEndpoint;
+
+    const healthChecks = this.endpoints.map(async (endpoint) => {
+      const response = await fetch(endpoint + healthPathname, {
+        method: "GET",
+      });
+      if (!response.ok) {
+        throw new Error(`Endpoint ${endpoint} returned ${response.status}`);
+      }
+      return endpoint;
+    });
+
+    try {
+      return await Promise.any(healthChecks);
+    } catch {
+      throw new Error("No available endpoints");
+    }
+  }
+
+  private async getEndpointsToTry(): Promise<string[]> {
+    if (this.availability.type === "fail-forward") {
+      return this.endpoints;
+    }
+
+    return [await this.getAvailableEndpoint()];
+  }
+
+  async handleRequest(request: Request): Promise<Response> {
+    const startTime = Date.now();
+    const endpointsToTry = await this.getEndpointsToTry();
+    const gatherEndpointLatency = Date.now();
+    const url = new URL(request.url);
+
+    for (const endpoint of endpointsToTry) {
+      try {
+        const targetUrl = endpoint + url.pathname + url.search;
+        const response = await fetch(targetUrl, {
+          method: request.method,
+          headers: request.headers,
+          body: request.body,
+          redirect: "follow",
+        });
+
+        const shouldFailover =
+          this.availability.type === "fail-forward" &&
+          this.availability.options?.failoverOnStatuses?.includes(
+            response.status,
+          );
+
+        if (!shouldFailover) {
+          const endTime = Date.now();
+          const headers = new Headers(response.headers);
+          headers.set("X-Load-Balancer-Endpoint", endpoint);
+          headers.set(
+            "X-Load-Balancer-Latency",
+            (endTime - startTime).toString(),
+          );
+          headers.set(
+            "X-Load-Balancer-Endpoint-Gather-Latency",
+            (gatherEndpointLatency - startTime).toString(),
+          );
+
+          return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers,
+          });
+        }
+      } catch {
+        // Network error, try next endpoint
+        continue;
+      }
+    }
+
+    if (this.recoveryFn) {
+      await this.recoveryFn(request);
+    }
+
+    throw new Error("No available endpoints");
+  }
+}
+
+export default LoadBalancer;