fix(rivetkit): normalize endpoints before comparing them

Author: NathanFlurry

rivetkit-typescript/packages/rivetkit/src/client/config.ts

@@ -16,7 +16,7 @@ import { tryParseEndpoint } from "@/utils/endpoint-parser";
  *
  * In browser: uses current origin + /api/rivet
  *
- * Server-side: uses localhost:6420
+ * Server-side: uses 127.0.0.1:6420
  */
 function getDefaultEndpoint(): string {
 	if (typeof window !== "undefined" && window.location?.origin) {
@@ -38,7 +38,7 @@ export const ClientConfigSchemaBase = z.object({
 	 *
 	 * Can also be set via RIVET_ENDPOINT environment variables.
 	 *
-	 * Defaults to current origin + /api/rivet in browser, or localhost:6420 server-side.
+	 * Defaults to current origin + /api/rivet in browser, or 127.0.0.1:6420 server-side.
 	 */
 	endpoint: z
 		.string()
@@ -88,7 +88,8 @@ export const ClientConfigSchemaBase = z.object({
 		.default(
 			() =>
 				typeof window !== "undefined" &&
-				window?.location?.hostname === "localhost",
+				(window?.location?.hostname === "127.0.0.1" ||
+					window.location?.hostname === "localhost"),
 		),
 });
 
@@ -144,6 +145,7 @@ export function convertRegistryConfigToClientConfig(
 		disableMetadataLookup: true,
 		devtools:
 			typeof window !== "undefined" &&
-			window?.location?.hostname === "localhost",
+			(window?.location?.hostname === "127.0.0.1" ||
+				window?.location?.hostname === "localhost"),
 	};
 }

rivetkit-typescript/packages/rivetkit/src/engine-process/constants.ts

@@ -1,2 +1,2 @@
 export const ENGINE_PORT = 6420;
-export const ENGINE_ENDPOINT = `http://localhost:${ENGINE_PORT}`;
+export const ENGINE_ENDPOINT = `http://127.0.0.1:${ENGINE_PORT}`;

rivetkit-typescript/packages/rivetkit/src/engine-process/mod.ts

@@ -308,7 +308,7 @@ async function checkIfEngineAlreadyRunningOnPort(
 ): Promise<boolean> {
 	let response: Response;
 	try {
-		response = await fetch(`http://localhost:${port}/health`);
+		response = await fetch(`http://127.0.0.1:${port}/health`);
 	} catch (err) {
 		// Nothing is running on this port
 		return false;

rivetkit-typescript/packages/rivetkit/src/inspector/utils.ts

@@ -56,7 +56,7 @@ export function getInspectorUrl(
 	const endpoint =
 		config.inspector.defaultEndpoint ??
 		(config.managerPort !== 6420
-			? `http://localhost:${managerPort}`
+			? `http://127.0.0.1:${managerPort}`
 			: undefined);
 	if (endpoint) {
 		url.searchParams.set("u", endpoint);

rivetkit-typescript/packages/rivetkit/src/registry/config/index.ts

@@ -213,11 +213,11 @@ export const RegistryConfigSchema = z
 		// Determine serveManager: default to true in dev mode without endpoint, false otherwise
 		const serveManager = config.serveManager ?? (isDevEnv && !endpoint);
 
-		// In dev mode, fall back to localhost if serving manager
+		// In dev mode, fall back to 127.0.0.1 if serving manager
 		const publicEndpoint =
 			parsedPublicEndpoint?.endpoint ??
 			(isDevEnv && (serveManager || config.serverless.spawnEngine)
-				? `http://localhost:${config.managerPort}`
+				? `http://127.0.0.1:${config.managerPort}`
 				: undefined);
 		// We extract publicNamespace to validate that it matches the backend
 		// namespace (see validation above), not for functional use.

rivetkit-typescript/packages/rivetkit/src/serverless/router.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from "vitest";
+import { endpointsMatch, normalizeEndpointUrl } from "./router";
+
+describe("normalizeEndpointUrl", () => {
+	test("normalizes URL without trailing slash", () => {
+		expect(normalizeEndpointUrl("http://localhost:6420")).toBe(
+			"http://localhost:6420/",
+		);
+	});
+
+	test("normalizes URL with trailing slash", () => {
+		expect(normalizeEndpointUrl("http://localhost:6420/")).toBe(
+			"http://localhost:6420/",
+		);
+	});
+
+	test("normalizes 127.0.0.1 to localhost", () => {
+		expect(normalizeEndpointUrl("http://127.0.0.1:6420")).toBe(
+			"http://localhost:6420/",
+		);
+	});
+
+	test("normalizes 0.0.0.0 to localhost", () => {
+		expect(normalizeEndpointUrl("http://0.0.0.0:6420")).toBe(
+			"http://localhost:6420/",
+		);
+	});
+
+	test("preserves path without trailing slash", () => {
+		expect(normalizeEndpointUrl("http://example.com/api/v1")).toBe(
+			"http://example.com/api/v1",
+		);
+	});
+
+	test("removes trailing slash from path", () => {
+		expect(normalizeEndpointUrl("http://example.com/api/v1/")).toBe(
+			"http://example.com/api/v1",
+		);
+	});
+
+	test("removes multiple trailing slashes", () => {
+		expect(normalizeEndpointUrl("http://example.com/api///")).toBe(
+			"http://example.com/api",
+		);
+	});
+
+	test("preserves port", () => {
+		expect(normalizeEndpointUrl("https://localhost:3000/api")).toBe(
+			"https://localhost:3000/api",
+		);
+	});
+
+	test("strips query string", () => {
+		expect(normalizeEndpointUrl("http://example.com/api?foo=bar")).toBe(
+			"http://example.com/api",
+		);
+	});
+
+	test("strips fragment", () => {
+		expect(normalizeEndpointUrl("http://example.com/api#section")).toBe(
+			"http://example.com/api",
+		);
+	});
+
+	test("returns null for invalid URL", () => {
+		expect(normalizeEndpointUrl("not-a-url")).toBeNull();
+	});
+
+	test("returns null for empty string", () => {
+		expect(normalizeEndpointUrl("")).toBeNull();
+	});
+});
+
+describe("endpointsMatch", () => {
+	test("matches identical URLs", () => {
+		expect(
+			endpointsMatch("http://127.0.0.1:6420", "http://127.0.0.1:6420"),
+		).toBe(true);
+	});
+
+	test("matches URL with and without trailing slash", () => {
+		expect(
+			endpointsMatch("http://127.0.0.1:6420", "http://127.0.0.1:6420/"),
+		).toBe(true);
+	});
+
+	test("matches URLs with paths ignoring trailing slash", () => {
+		expect(
+			endpointsMatch("http://example.com/api/v1", "http://example.com/api/v1/"),
+		).toBe(true);
+	});
+
+	test("matches localhost and 127.0.0.1", () => {
+		expect(
+			endpointsMatch("http://localhost:6420", "http://127.0.0.1:6420"),
+		).toBe(true);
+	});
+
+	test("matches localhost and 0.0.0.0", () => {
+		expect(
+			endpointsMatch("http://localhost:6420", "http://0.0.0.0:6420"),
+		).toBe(true);
+	});
+
+	test("does not match different hosts", () => {
+		expect(
+			endpointsMatch("http://localhost:6420", "http://example.com:6420"),
+		).toBe(false);
+	});
+
+	test("does not match different ports", () => {
+		expect(
+			endpointsMatch("http://localhost:6420", "http://localhost:3000"),
+		).toBe(false);
+	});
+
+	test("does not match different protocols", () => {
+		expect(
+			endpointsMatch("http://localhost:6420", "https://localhost:6420"),
+		).toBe(false);
+	});
+
+	test("does not match different paths", () => {
+		expect(
+			endpointsMatch("http://example.com/api/v1", "http://example.com/api/v2"),
+		).toBe(false);
+	});
+
+	test("falls back to string comparison for invalid URLs", () => {
+		expect(endpointsMatch("not-a-url", "not-a-url")).toBe(true);
+		expect(endpointsMatch("not-a-url", "different")).toBe(false);
+	});
+});

rivetkit-typescript/packages/rivetkit/src/serverless/router.ts

@@ -59,7 +59,7 @@ export function buildServerlessRouter(
 			// configuring an endpoint indicates you want to assert the
 			// incoming serverless requests.
 			if (config.endpoint) {
-				if (endpoint !== config.endpoint) {
+				if (!endpointsMatch(endpoint, config.endpoint)) {
 					throw new EndpointMismatch(config.endpoint, endpoint);
 				}
 
@@ -121,3 +121,42 @@ export function buildServerlessRouter(
 		);
 	});
 }
+
+/**
+ * Normalizes a URL for comparison by extracting protocol, host, port, and pathname.
+ * Normalizes 127.0.0.1 and 0.0.0.0 to localhost for consistent comparison.
+ * Returns null if the URL is invalid.
+ */
+export function normalizeEndpointUrl(url: string): string | null {
+	try {
+		const parsed = new URL(url);
+		// Normalize pathname by removing trailing slash (except for root)
+		const pathname =
+			parsed.pathname === "/" ? "/" : parsed.pathname.replace(/\/+$/, "");
+		// Normalize loopback addresses to localhost
+		const hostname =
+			parsed.hostname === "127.0.0.1" || parsed.hostname === "0.0.0.0"
+				? "localhost"
+				: parsed.hostname;
+		// Reconstruct host with normalized hostname and port
+		const host = parsed.port ? `${hostname}:${parsed.port}` : hostname;
+		// Reconstruct normalized URL with protocol, host, and pathname
+		return `${parsed.protocol}//${host}${pathname}`;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Compares two endpoint URLs after normalization.
+ * Returns true if they match (same protocol, host, port, and path).
+ */
+export function endpointsMatch(a: string, b: string): boolean {
+	const normalizedA = normalizeEndpointUrl(a);
+	const normalizedB = normalizeEndpointUrl(b);
+	if (normalizedA === null || normalizedB === null) {
+		// If either URL is invalid, fall back to string comparison
+		return a === b;
+	}
+	return normalizedA === normalizedB;
+}