feat(serve-static): initial check-in

packages/serve-static/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

packages/serve-static/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kitojs/serve-static",
+  "version": "0.1.0",
+  "description": "Static file-server middleware for the Kito framework",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "readme.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "ex:run": "pnpm build && tsx"
+  },
+  "keywords": [
+    "kito",
+    "plugin"
+  ],
+  "author": "Rasmus Schultz <github.com/mindplay-dk>",
+  "license": "MIT",
+  "dependencies": {
+    "kitojs": "latest"
+  },
+  "devDependencies": {
+    "tsdown": "latest",
+    "typescript": "latest",
+    "tsx": "latest",
+    "vitest": "latest"
+  }
+}

packages/serve-static/readme.md

@@ -0,0 +1,19 @@
+# @kitojs/serve-static
+
+Static file-server middleware for the Kito framework
+
+## Installation
+
+```bash
+pnpm add @kitojs/serve-static
+```
+
+## Usage
+
+TODO add docs
+
+```ts
+import { serveStatic } from "@kitojs/serve-static";
+
+app.use(serveStatic());
+```

packages/serve-static/src/index.ts

@@ -0,0 +1,153 @@
+import type { Stats } from "node:fs";
+import fs from "node:fs";
+import path from "node:path";
+import { URL } from "node:url";
+
+import {
+  middleware,
+  type KitoContext,
+  type KitoResponse,
+  type SendFileOptions,
+} from "kitojs";
+
+export interface ServeStaticOptions {
+  /**
+   * Root directory path from which static files will be served.
+   */
+  root: string;
+
+  /**
+   * Optional list of file extension fallbacks.
+   *
+   * If specified, when a requested file is not found, this middleware
+   * will try these file extensions, in order.
+   *
+   * Example: `['html', 'htm']`
+   */
+  extensions?: string[] | boolean;
+
+  /**
+   * If `true` (the default) this middleware will delegate unhandled
+   * requests to the next middleware.
+   *
+   * If `false`, this middleware will abort the middleware stack and
+   * return a 404 response.
+   */
+  fallthrough?: boolean;
+
+  /**
+   * If `true` (the default) this middleware will serve `index.html`
+   * when a directory is requested.
+   *
+   * Alternatively, you may specify an array of index filenames, for
+   * example `["index.html", "index.htm"]` and these will be tried
+   * in the order they're provided.
+   */
+  index?: string[] | boolean;
+
+  /**
+   * If `true` (the default) when a directory is requested *without*
+   * a trailing slash, this middleware will redirect to the same
+   * path *with* a trailing slash.
+   *
+   * This works better in browsers when using relative paths.
+   *
+   * Redirecting to a canonical URL avoids serving the same resource
+   * under two different URLs.
+   */
+  redirect?: boolean;
+
+  /**
+   * Optional function to set custom response headers.
+   */
+  setHeaders?: (
+    res: KitoResponse,
+    path: string,
+    stat: Stats,
+  ) => void | Promise<void>;
+}
+
+export const serveStatic = (
+  options: ServeStaticOptions,
+  sendFileOptions?: SendFileOptions,
+) =>
+  middleware(async (ctx, next) => {
+    const { method } = ctx.req;
+
+    const { root, fallthrough = true, redirect = true } = options;
+
+    const indexFiles =
+      typeof options.index === "boolean" && options.index === true
+        ? ["index.html"]
+        : options.index || [];
+
+    const extensions =
+      typeof options.extensions === "boolean" && options.extensions === true
+        ? ["html", "htm"]
+        : options.extensions || [];
+
+    if (method !== "GET" && method !== "HEAD") {
+      if (fallthrough) {
+        return next();
+      }
+
+      return ctx.res
+        .status(405)
+        .header("Allow", "GET, HEAD")
+        .send("Method Not Allowed");
+    }
+
+    const isRoot = ctx.req.url === "/";
+
+    const hasTrailingSlash = !isRoot && ctx.req.url.endsWith("/");
+
+    const baseURL = `http${ctx.req.secure ? "s" : ""}://${ctx.req.hostname}/`;
+
+    const url = new URL(ctx.req.url.replace(/\/$/, ""), baseURL);
+
+    const pathname = decodeURIComponent(url.pathname);
+
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: required for input sanitization
+    if (/(^|\/)\.+(\/|$)|\\|[\x00-\x1f]/.test(pathname)) {
+      return ctx.res.status(400).send("Bad Request");
+    }
+
+    const pathsToTry = isRoot ? [] : [path.join(root, pathname)];
+
+    for (const indexFile of indexFiles) {
+      pathsToTry.push(path.join(root, pathname, indexFile));
+    }
+
+    if (!isRoot && !hasTrailingSlash) {
+      for (const extension of extensions) {
+        pathsToTry.push(path.join(root, `${pathname}.${extension}`));
+      }
+    }
+
+    for (const resourcePath of pathsToTry) {
+      const stat = await fs.promises.stat(resourcePath).catch(() => null);
+
+      if (stat) {
+        if (stat.isDirectory()) {
+          if (redirect && !hasTrailingSlash) {
+            return ctx.res
+              .status(301)
+              .header("Location", `${url.pathname}/${url.search}`)
+              .send("Moved Permanently");
+          }
+        } else if (stat.isFile()) {
+          if (options.setHeaders) {
+            await options.setHeaders(ctx.res, resourcePath, stat);
+          }
+
+          return ctx.res.sendFile(resourcePath, sendFileOptions);
+        }
+      }
+    }
+
+    if (fallthrough) {
+      return next();
+    }
+
+    ctx.res.status(404).send("Not Found");
+  });

packages/serve-static/tests/resources/index.html

@@ -0,0 +1 @@
+<!DOCTYPE html>HELLO!

packages/serve-static/tests/serve-static.test.ts

@@ -0,0 +1,23 @@
+import path from "node:path";
+
+import { test, expect } from "vitest";
+
+import { server as createServer } from "kitojs";
+import { serveStatic } from "../src";
+
+const host = "0.0.0.0";
+const port = 8088;
+
+const root = path.resolve(import.meta.dirname, "./resources");
+
+test("Can serve index.html from root", async () => {
+  const app = createServer();
+
+  app.use(serveStatic({ root }));
+
+  const server = await app.listen({ host, port }, () => {
+    console.log("this runs");
+  });
+
+  console.log(`this never runs??`);
+});

packages/serve-static/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src", "tests"]
+}

packages/serve-static/tsdown.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: "src/index.ts",
+  outDir: "dist",
+  minify: true,
+  dts: true,
+  tsconfig: "tsconfig.json",
+});

packages/serve-static/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+  },
+});