feat(wobe): add html hook (#55)

coratgerl · web-flow · commit 2f09b57b2fdc · 2025-12-06T15:50:22.000+01:00
* feat(wobe): add html hook

* fix: tests

* fix: tests and improve security

* fix: lint
diff --git a/.gitignore b/.gitignore
@@ -14,3 +14,4 @@ lib
 dist
 
 .DS_Store
+test_static_files/
diff --git a/biome.json b/biome.json
@@ -20,7 +20,8 @@
 				"noExplicitAny": "off"
 			},
 			"style": {
-				"useTemplate": "off"
+				"useTemplate": "off",
+				"useNodejsImportProtocol": "error"
 			}
 		}
 	},
diff --git a/packages/wobe-documentation/doc/ecosystem/hooks/html.md b/packages/wobe-documentation/doc/ecosystem/hooks/html.md
@@ -0,0 +1,44 @@
+# html (static files)
+
+`html` serves static files (HTML, JS, CSS, images, etc.) from a directory with guardrails similar to `express.static`: traversal blocking, dotfiles ignored by default, symlink checks, and SPA fallback support.
+
+## Quick usage
+
+```ts
+import { Wobe, html } from 'wobe'
+import { join } from 'node:path'
+
+const staticRoot = join(__dirname, '../fixtures')
+
+new Wobe()
+	// Serve under /tata while stripping that prefix for file resolution
+	.get(
+		'/tata/*',
+		html({
+			rootPath: staticRoot,
+			fallbackFile: 'index.html', // optional for SPA
+			stripPrefix: '/tata',
+		})
+	)
+	.listen(3000)
+
+// http://localhost:3000/tata/test.html -> serves fixtures/test.html
+// http://localhost:3000/tata/unknown -> serves fixtures/index.html (fallback)
+```
+
+## Options
+
+-   `rootPath` (string, required): root directory of static files.
+-   `fallbackFile` (string, optional): file served on 404, useful for SPAs (`text/html`).
+-   `stripPrefix` (string, optional): prefix to strip from the pathname when mounted under a sub-path (e.g. `/static` or `/tata`).
+-   `allowDotfiles` (boolean, default `false`): serve dotfiles; otherwise they return 404.
+-   `allowSymlinks` (boolean, default `false`): allow symlinks pointing outside `rootPath`; otherwise realpath must stay inside root or 403.
+
+## Behavior and safety
+
+-   **Methods**: only `GET` and `HEAD` are accepted (`405` otherwise). HEAD returns headers only.
+-   **Dotfiles**: ignored by default (404).
+-   **Traversal / symlinks**: path is normalized + realpathed and must stay under `rootPath` unless `allowSymlinks` is true; otherwise 403.
+-   **Content-Type**: inferred from extension (built-in MIME table); text read via `.text()`, binary via `arrayBuffer()`.
+-   **SPA fallback**: served only if it resolves inside root (same symlink rule); otherwise 403.
+-   **Mounted prefixes**: use `stripPrefix` to exclude the mount prefix from file resolution.
diff --git a/packages/wobe-documentation/doc/ecosystem/hooks/index.md b/packages/wobe-documentation/doc/ecosystem/hooks/index.md
@@ -54,8 +54,12 @@ export const authorizationHook = (schema: TSchema): WobeHandler => {
 			throw new HttpException(
 				new Response('You are not authorized to access to this route', {
 					status: 403,
-				}),
+				})
 			)
 	}
 }
 ```
+
+## Available hooks
+
+-   [html](./html.md) — serve static files with SPA fallback, traversal/dotfile guards, GET/HEAD only.
diff --git a/packages/wobe/dev/index.ts b/packages/wobe/dev/index.ts
@@ -1,11 +1,21 @@
 process.env.NODE_TEST = 'test'
 import { join } from 'node:path'
-import { Wobe, uploadDirectory } from '../src'
+import { Wobe, uploadDirectory, html } from '../src'
+
+const staticRoot = join(__dirname, '../fixtures')
 
 new Wobe()
-	.get('/', (ctx) => ctx.res.send('Hi'))
+	// Sample API route
+	.get('/api', (ctx) => ctx.res.send('Hi'))
+	// Example of using the uploadDirectory hook
+	.get('/bucket/:filename', uploadDirectory({ directory: staticRoot }))
+	// Serve static assets and fallback to testFile.html for SPA-style routing
 	.get(
-		'/bucket/:filename',
-		uploadDirectory({ directory: join(__dirname, '../fixtures') }),
+		'/tata/*',
+		html({
+			rootPath: staticRoot,
+			fallbackFile: 'testFile.html',
+			stripPrefix: '/tata',
+		}),
 	)
 	.listen(3000)
diff --git a/packages/wobe/fixtures/test.html b/packages/wobe/fixtures/test.html
@@ -0,0 +1,5 @@
+<html>
+	<body>
+		<h1>Hello World</h1>
+	</body>
+</html>
diff --git a/packages/wobe/src/hooks/html.test.ts b/packages/wobe/src/hooks/html.test.ts
diff --git a/packages/wobe/src/hooks/html.ts b/packages/wobe/src/hooks/html.ts
diff --git a/packages/wobe/src/hooks/index.ts b/packages/wobe/src/hooks/index.ts

Original file line number	Diff line number	Diff line change
`@@ -14,3 +14,4 @@ lib`
`14`	`14`	`dist`
`15`	`15`
`16`	`16`	`.DS_Store`
	`17`	`+test_static_files/`
Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,8 @@`
`20`	`20`	`"noExplicitAny": "off"`
`21`	`21`	`},`
`22`	`22`	`"style": {`
`23`		`- "useTemplate": "off"`
	`23`	`+ "useTemplate": "off",`
	`24`	`+ "useNodejsImportProtocol": "error"`
`24`	`25`	`}`
`25`	`26`	`}`
`26`	`27`	`},`
Original file line number	Diff line number	Diff line change
`@@ -54,8 +54,12 @@ export const authorizationHook = (schema: TSchema): WobeHandler => {`
`54`	`54`	`throw new HttpException(`
`55`	`55`	`new Response('You are not authorized to access to this route', {`
`56`	`56`	`status: 403,`
`57`		`- }),`
	`57`	`+ })`
`58`	`58`	`)`
`59`	`59`	`}`
`60`	`60`	`}`
`61`	`61`	```
	`62`	`+`
	`63`	`+## Available hooks`
	`64`	`+`
	`65`	`+- [html](./html.md) — serve static files with SPA fallback, traversal/dotfile guards, GET/HEAD only.`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +<html>
 +	<body>
 +		<h1>Hello World</h1>
 +	</body>
 +</html>