@just-be/wildcard 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@just-be/wildcard",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Portable wildcard subdomain routing with pluggable storage backends",
   "type": "module",
   "main": "./src/index.ts",

package/src/handlers/index.ts

@@ -1,3 +1,4 @@
 export { handleStatic } from "./static";
 export { handleRedirect } from "./redirect";
 export { handleRewrite } from "./rewrite";
+export { handlePathRules } from "./path-rules";

package/src/handlers/path-rules.ts

@@ -0,0 +1,66 @@
+import type { StaticConfig } from "../schemas";
+import { matchPath, proxyRequest } from "../utils";
+
+/**
+ * Handles path-level redirects and rewrites for static handlers
+ * Returns a Response if a rule matches, or null to continue to static file serving
+ */
+export async function handlePathRules(
+  request: Request,
+  config: StaticConfig
+): Promise<Response | null> {
+  const url = new URL(request.url);
+  const pathname = url.pathname;
+
+  // Check redirects first (in array order)
+  if (config.redirects?.length) {
+    for (const rule of config.redirects) {
+      const match = matchPath(rule.path, pathname);
+      if (!match.matched) continue;
+
+      // Build target URL, appending suffix for wildcard patterns
+      let targetUrl = rule.url;
+      if (rule.path.endsWith("/*") && match.suffix && match.suffix !== "/") {
+        targetUrl = rule.url.replace(/\/$/, "") + match.suffix;
+      }
+
+      return Response.redirect(targetUrl, rule.permanent ? 301 : 302);
+    }
+  }
+
+  // Check rewrites (in array order)
+  if (config.rewrites?.length) {
+    for (const rule of config.rewrites) {
+      const match = matchPath(rule.path, pathname);
+      if (!match.matched) continue;
+
+      // Check HTTP method
+      if (!(rule.allowedMethods as string[]).includes(request.method)) {
+        return new Response("Method not allowed", {
+          status: 405,
+          headers: {
+            Allow: rule.allowedMethods.join(", "),
+          },
+        });
+      }
+
+      // Build target URL for rewrite
+      const targetUrl = new URL(rule.url);
+
+      // For wildcard patterns, use the suffix as the path
+      // For exact patterns, use the original pathname
+      if (rule.path.endsWith("/*") && match.suffix) {
+        targetUrl.pathname = match.suffix;
+      } else {
+        targetUrl.pathname = url.pathname;
+      }
+
+      targetUrl.search = url.search;
+
+      return proxyRequest(request, targetUrl);
+    }
+  }
+
+  // No path rule matched, continue to static file serving
+  return null;
+}

package/src/handlers/rewrite.ts

@@ -1,8 +1,6 @@
 import type { Handler } from "../types";
 import type { RewriteConfig } from "../schemas";
-import { filterSafeHeaders } from "../utils";
-
-const FETCH_TIMEOUT_MS = 5_000;
+import { proxyRequest } from "../utils";
 
 export const handleRewrite: Handler<RewriteConfig> = async (request, config) => {
   const originalUrl = new URL(request.url);
@@ -22,43 +20,5 @@ export const handleRewrite: Handler<RewriteConfig> = async (request, config) =>
   url.pathname = originalUrl.pathname;
   url.search = originalUrl.search;
 
-  // Filter headers to only include safe ones (prevents header injection)
-  const safeHeaders = filterSafeHeaders(request.headers);
-
-  // Create a new request with the target URL and filtered headers
-  const modifiedRequest = new Request(url.toString(), {
-    method: request.method,
-    headers: safeHeaders,
-    body: request.method !== "GET" && request.method !== "HEAD" ? request.body : undefined,
-  });
-
-  // Create abort controller for timeout
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-
-  try {
-    const response = await fetch(modifiedRequest, {
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    // Create a new response with the same body but potentially modified headers
-    const newResponse = new Response(response.body, response);
-
-    // Remove content-encoding header because the response body is already decoded
-    // by the fetch API, and if we forward this header, the browser will try to
-    // decode it again, causing corruption
-    newResponse.headers.delete("content-encoding");
-
-    return newResponse;
-  } catch (error) {
-    clearTimeout(timeoutId);
-
-    if (error instanceof Error && error.name === "AbortError") {
-      return new Response("Request timeout", { status: 504 });
-    }
-
-    return new Response("Bad gateway", { status: 502 });
-  }
+  return proxyRequest(request, url);
 };

package/src/handlers/static.ts

@@ -1,12 +1,17 @@
 import type { Handler, FileLoader, FileObject } from "../types";
 import type { StaticConfig } from "../schemas";
 import { getContentType, sanitizePath } from "../utils";
+import { handlePathRules } from "./path-rules";
 
 export const handleStatic: Handler<StaticConfig, { fileLoader: FileLoader }> = async (
   request,
   config,
   { fileLoader }
 ) => {
+  // Check path-level redirects and rewrites first
+  const pathResponse = await handlePathRules(request, config);
+  if (pathResponse) return pathResponse;
+
   const url = new URL(request.url);
   const { spa, fallback } = config;
 
@@ -17,30 +22,55 @@ export const handleStatic: Handler<StaticConfig, { fileLoader: FileLoader }> = a
   const basePath = subdomain;
 
   return spa
-    ? handleSpaMode(fileLoader, basePath)
+    ? handleSpaMode(fileLoader, basePath, url.pathname)
     : handleStaticMode(fileLoader, basePath, url.pathname, fallback);
 };
 
-async function handleSpaMode(fileLoader: FileLoader, basePath: string): Promise<Response> {
-  // Sanitize base path to prevent directory traversal
+async function handleSpaMode(
+  fileLoader: FileLoader,
+  basePath: string,
+  pathname: string
+): Promise<Response> {
+  // Sanitize paths to prevent directory traversal
   const sanitizedBase = sanitizePath(basePath);
+  const sanitizedPathname = sanitizePath(pathname);
+
   if (!sanitizedBase) {
     return new Response("Invalid path", { status: 400 });
   }
 
-  const key = sanitizedBase.endsWith("index.html")
+  // First, try to serve the requested file if it exists
+  // Only check files that likely exist (have extensions or end with /)
+  if (pathname !== "/" && (pathname.includes(".") || pathname.endsWith("/"))) {
+    const fullPath = `${sanitizedBase}/${sanitizedPathname}`;
+    let key = fullPath.replace(/\/+/g, "/"); // Normalize double slashes
+
+    // Append index.html for directories
+    if (key.endsWith("/")) {
+      key = `${key}index.html`;
+    }
+
+    const fileObject = await fileLoader.loadFile(key);
+
+    if (fileObject) {
+      return buildFileResponse(fileObject, key);
+    }
+  }
+
+  // Fall back to index.html for SPA routing
+  const indexKey = sanitizedBase.endsWith("index.html")
     ? sanitizedBase
     : sanitizedBase.endsWith("/")
       ? `${sanitizedBase}index.html`
       : `${sanitizedBase}/index.html`;
 
-  const fileObject = await fileLoader.loadFile(key);
+  const indexFile = await fileLoader.loadFile(indexKey);
 
-  if (!fileObject) {
+  if (!indexFile) {
     return new Response("File not found", { status: 404 });
   }
 
-  return buildFileResponse(fileObject, key);
+  return buildFileResponse(indexFile, indexKey);
 }
 
 async function handleStaticMode(

package/src/schemas.ts

@@ -13,12 +13,30 @@ export const subdomain = () =>
     message: "Invalid subdomain format. Must be alphanumeric with hyphens, 1-63 characters.",
   });
 
+const HttpMethod = z.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]);
+
+/** Path-level redirect schema */
+export const PathRedirectSchema = z.object({
+  path: z.string().min(1).startsWith("/"),
+  url: safeUrl(),
+  permanent: z.boolean().optional(),
+});
+
+/** Path-level rewrite schema */
+export const PathRewriteSchema = z.object({
+  path: z.string().min(1).startsWith("/"),
+  url: safeUrl(),
+  allowedMethods: z.array(HttpMethod).optional().default(["GET", "HEAD", "OPTIONS"]),
+});
+
 // Zod schemas for validation
 export const StaticConfigSchema = z
   .object({
     type: z.literal("static"),
     spa: z.boolean().optional(),
     fallback: z.string().optional(), // Fallback file path for non-SPA mode (e.g., "404.html")
+    redirects: z.array(PathRedirectSchema).optional(),
+    rewrites: z.array(PathRewriteSchema).optional(),
   })
   .refine((data) => (data.spa && data.fallback ? false : true), {
     message: "fallback cannot be used with spa mode (spa: true)",
@@ -30,8 +48,6 @@ export const RedirectConfigSchema = z.object({
   permanent: z.boolean().optional(),
 });
 
-const HttpMethod = z.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]);
-
 export const RewriteConfigSchema = z.object({
   type: z.literal("rewrite"),
   url: safeUrl(),
@@ -70,6 +86,8 @@ const json = <T extends z.ZodType>(schema: T) =>
  */
 export const RouteConfigCodec = json(RouteConfigSchema);
 
+export type PathRedirect = z.infer<typeof PathRedirectSchema>;
+export type PathRewrite = z.infer<typeof PathRewriteSchema>;
 export type StaticConfig = z.infer<typeof StaticConfigSchema>;
 export type RedirectConfig = z.infer<typeof RedirectConfigSchema>;
 export type RewriteConfig = z.infer<typeof RewriteConfigSchema>;

package/src/utils.test.ts

@@ -5,6 +5,7 @@ import {
   sanitizePath,
   filterSafeHeaders,
   isValidSubdomain,
+  matchPath,
   SAFE_REQUEST_HEADERS,
 } from "./utils";
 
@@ -341,3 +342,82 @@ describe("isValidSubdomain", () => {
     });
   });
 });
+
+describe("matchPath", () => {
+  describe("exact match patterns", () => {
+    it("should match exact paths", () => {
+      expect(matchPath("/github", "/github")).toEqual({ matched: true });
+      expect(matchPath("/about", "/about")).toEqual({ matched: true });
+      expect(matchPath("/foo/bar", "/foo/bar")).toEqual({ matched: true });
+    });
+
+    it("should not match different paths", () => {
+      expect(matchPath("/github", "/gitlab")).toEqual({ matched: false });
+      expect(matchPath("/about", "/about/team")).toEqual({ matched: false });
+      expect(matchPath("/foo", "/foo/bar")).toEqual({ matched: false });
+    });
+
+    it("should handle trailing slash normalization", () => {
+      expect(matchPath("/github", "/github/")).toEqual({ matched: true });
+      expect(matchPath("/github/", "/github")).toEqual({ matched: true });
+      expect(matchPath("/foo/bar/", "/foo/bar")).toEqual({ matched: true });
+    });
+
+    it("should handle root path", () => {
+      expect(matchPath("/", "/")).toEqual({ matched: true });
+    });
+  });
+
+  describe("wildcard patterns", () => {
+    it("should match prefix with wildcard", () => {
+      expect(matchPath("/api/*", "/api/users")).toEqual({ matched: true, suffix: "/users" });
+      expect(matchPath("/api/*", "/api/users/123")).toEqual({
+        matched: true,
+        suffix: "/users/123",
+      });
+      expect(matchPath("/v1/api/*", "/v1/api/test")).toEqual({ matched: true, suffix: "/test" });
+    });
+
+    it("should match just the prefix without trailing content", () => {
+      expect(matchPath("/api/*", "/api")).toEqual({ matched: true, suffix: "/" });
+      expect(matchPath("/api/*", "/api/")).toEqual({ matched: true, suffix: "/" });
+    });
+
+    it("should not match paths that do not start with prefix", () => {
+      expect(matchPath("/api/*", "/apiv2/users")).toEqual({ matched: false });
+      expect(matchPath("/api/*", "/other/api/users")).toEqual({ matched: false });
+      expect(matchPath("/foo/*", "/foobar")).toEqual({ matched: false });
+    });
+
+    it("should return correct suffix for nested paths", () => {
+      expect(matchPath("/old/*", "/old/page")).toEqual({ matched: true, suffix: "/page" });
+      expect(matchPath("/old/*", "/old/deep/nested/path")).toEqual({
+        matched: true,
+        suffix: "/deep/nested/path",
+      });
+    });
+
+    it("should handle wildcard at root", () => {
+      expect(matchPath("/*", "/anything")).toEqual({ matched: true, suffix: "/anything" });
+      expect(matchPath("/*", "/")).toEqual({ matched: true, suffix: "/" });
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle paths with query strings (pathname only)", () => {
+      // matchPath only receives pathname, not query strings
+      expect(matchPath("/api/*", "/api/users")).toEqual({ matched: true, suffix: "/users" });
+    });
+
+    it("should handle patterns with multiple segments", () => {
+      expect(matchPath("/a/b/c/*", "/a/b/c/d")).toEqual({ matched: true, suffix: "/d" });
+      expect(matchPath("/a/b/c/*", "/a/b/c")).toEqual({ matched: true, suffix: "/" });
+    });
+
+    it("should distinguish between similar paths", () => {
+      expect(matchPath("/api", "/api")).toEqual({ matched: true });
+      expect(matchPath("/api", "/api/")).toEqual({ matched: true });
+      expect(matchPath("/api", "/api/users")).toEqual({ matched: false });
+    });
+  });
+});

package/src/utils.ts

@@ -163,6 +163,45 @@ export function filterSafeHeaders(headers: Headers): Headers {
   return filtered;
 }
 
+/**
+ * Match result from matchPath function
+ */
+export interface PathMatchResult {
+  matched: boolean;
+  suffix?: string;
+}
+
+/**
+ * Matches a path pattern against a pathname
+ * Supports exact matches and wildcard suffix patterns (e.g., /api/*)
+ *
+ * @param pattern - The pattern to match (e.g., "/github" or "/api/*")
+ * @param pathname - The actual pathname to match against
+ * @returns Object with matched boolean and optional suffix for wildcard matches
+ */
+export function matchPath(pattern: string, pathname: string): PathMatchResult {
+  // Normalize paths by removing trailing slashes (except for root "/")
+  const normPattern =
+    pattern === "/" ? "/" : pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+  const normPathname =
+    pathname === "/" ? "/" : pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+
+  // Handle wildcard patterns: /api/*
+  if (normPattern.endsWith("/*")) {
+    const prefix = normPattern.slice(0, -2);
+
+    // Match prefix exactly or prefix + "/"
+    if (normPathname === prefix || normPathname.startsWith(prefix + "/")) {
+      const suffix = normPathname.slice(prefix.length) || "/";
+      return { matched: true, suffix };
+    }
+    return { matched: false };
+  }
+
+  // Exact match
+  return { matched: normPathname === normPattern };
+}
+
 /**
  * Validates subdomain name format and length
  * @param subdomain - The subdomain to validate
@@ -196,3 +235,60 @@ export function isValidSubdomain(subdomain: string): boolean {
 
   return true;
 }
+
+/**
+ * Timeout for proxy requests in milliseconds
+ */
+const FETCH_TIMEOUT_MS = 5_000;
+
+/**
+ * Proxies a request to a target URL with timeout and safe header filtering
+ *
+ * @param request - The original request
+ * @param targetUrl - The target URL to proxy to
+ * @returns Response from the proxied request
+ */
+export async function proxyRequest(
+  request: Request,
+  targetUrl: URL
+): Promise<Response> {
+  // Filter headers to only include safe ones (prevents header injection)
+  const safeHeaders = filterSafeHeaders(request.headers);
+
+  // Create a new request with the target URL and filtered headers
+  const modifiedRequest = new Request(targetUrl.toString(), {
+    method: request.method,
+    headers: safeHeaders,
+    body: request.method !== "GET" && request.method !== "HEAD" ? request.body : undefined,
+  });
+
+  // Create abort controller for timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const response = await fetch(modifiedRequest, {
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    // Create a new response with the same body but potentially modified headers
+    const newResponse = new Response(response.body, response);
+
+    // Remove content-encoding header because the response body is already decoded
+    // by the fetch API, and if we forward this header, the browser will try to
+    // decode it again, causing corruption
+    newResponse.headers.delete("content-encoding");
+
+    return newResponse;
+  } catch (error) {
+    clearTimeout(timeoutId);
+
+    if (error instanceof Error && error.name === "AbortError") {
+      return new Response("Request timeout", { status: 504 });
+    }
+
+    return new Response("Bad gateway", { status: 502 });
+  }
+}