feat(drivers): add overridable public asset mounting

- move h3 static asset handling into driver-h3
- make H3Driver mountPublicAssets optional with a built-in default
- add mountPublicAssets override support to ExpressDriver
- remove app-level h3 public asset registration
- add tests for default and override public asset behavior

Author: 3m1n3nc3

h3/src/app/http/middlewares/staticAssetHandler.ts

@@ -5,7 +5,6 @@ import { H3Driver, type H3Middleware } from '@arkstack/driver-h3'
 import { H3 } from 'h3'
 import { Router } from 'src/core/router'
 import ErrorHandler from './utils/request-handlers'
-import { staticAssetHandler } from '@app/http/middlewares/staticAssetHandler'
 
 export default class Application implements ArkstackRouterAwareCore<H3, unknown> {
   private app: H3
@@ -27,9 +26,6 @@ export default class Application implements ArkstackRouterAwareCore<H3, unknown>
       bindRouter: async (runtime) => {
         await Router.bind(runtime)
       },
-      mountPublicAssets: (runtime) => {
-        runtime.use(staticAssetHandler())
-      },
     })
 
     this.app = app ?? this.driver.createApp()

h3/src/core/app.ts

@@ -5,6 +5,7 @@ import { Logger } from '@arkstack/common'
 
 export interface ExpressDriverOptions {
     bindRouter: (app: Express) => PromiseOrValue<void>;
+    mountPublicAssets?: (app: Express, publicPath: string) => PromiseOrValue<void>;
     errorHandler?: ErrorRequestHandler | Handler;
 }
 
@@ -41,8 +42,20 @@ export class ExpressDriver extends ArkstackKitDriver<Express, Handler> {
      * @param app 
      * @param publicPath 
      */
-    mountPublicAssets (app: Express, publicPath: string): void {
-        app.use(express.static(publicPath))
+    mountPublicAssets (app: Express, publicPath: string): PromiseOrValue<void> {
+        if (this.options.mountPublicAssets) {
+            return this.options.mountPublicAssets(app, publicPath)
+        }
+
+        app.use(express.static(publicPath, {
+            maxAge: '1y',
+            immutable: true,
+            setHeaders: (res) => {
+                res.setHeader('Access-Control-Allow-Origin', '*')
+                res.setHeader('Access-Control-Allow-Methods', 'GET, HEAD, OPTIONS')
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization')
+            },
+        }))
     }
 
     /**

packages/driver-express/src/index.ts

@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import express, { type Express } from 'express'
+
+import { ExpressDriver } from '../src/index'
+
+describe('ExpressDriver', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks()
+    })
+
+    it('uses a custom mountPublicAssets override when provided', async () => {
+        const app = { use: vi.fn() } as unknown as Express
+        const mountPublicAssets = vi.fn().mockResolvedValue(undefined)
+        const staticSpy = vi.spyOn(express, 'static')
+        const driver = new ExpressDriver({
+            bindRouter: vi.fn(),
+            mountPublicAssets,
+        })
+
+        await driver.mountPublicAssets(app, '/tmp/public')
+
+        expect(mountPublicAssets).toHaveBeenCalledWith(app, '/tmp/public')
+        expect(staticSpy).not.toHaveBeenCalled()
+        expect(app.use).not.toHaveBeenCalled()
+    })
+
+    it('falls back to express.static with cache and cors headers', () => {
+        const app = { use: vi.fn() } as unknown as Express
+        const staticMiddleware = vi.fn() as ReturnType<typeof express.static>
+        const staticSpy = vi.spyOn(express, 'static').mockReturnValue(staticMiddleware)
+        const driver = new ExpressDriver({
+            bindRouter: vi.fn(),
+        })
+
+        driver.mountPublicAssets(app, '/tmp/public')
+
+        expect(staticSpy).toHaveBeenCalledTimes(1)
+        expect(staticSpy).toHaveBeenCalledWith('/tmp/public', expect.objectContaining({
+            maxAge: '1y',
+            immutable: true,
+            setHeaders: expect.any(Function),
+        }))
+        expect(app.use).toHaveBeenCalledWith(staticMiddleware)
+
+        const staticOptions = staticSpy.mock.calls[0][1] as {
+            setHeaders: (res: { setHeader: (name: string, value: string) => void }) => void;
+        }
+        const headers = new Map<string, string>()
+
+        staticOptions.setHeaders({
+            setHeader: (name, value) => {
+                headers.set(name, value)
+            },
+        })
+
+        expect(headers.get('Access-Control-Allow-Origin')).toBe('*')
+        expect(headers.get('Access-Control-Allow-Methods')).toBe('GET, HEAD, OPTIONS')
+        expect(headers.get('Access-Control-Allow-Headers')).toBe('Content-Type, Authorization')
+    })
+})

packages/driver-express/tests/index.test.ts

@@ -3,13 +3,14 @@ import { H3, serve, toResponse } from 'h3'
 
 import { Middleware as H3BaseMiddleware } from 'clear-router/types/h3'
 import { Logger } from '@arkstack/common'
+import { staticAssetHandler } from './middlewares'
 
 // oxlint-disable-next-line typescript/no-explicit-any
 export type H3Middleware = H3BaseMiddleware | [H3BaseMiddleware, Record<string, any>];
 
 export interface H3DriverOptions {
     bindRouter: (app: H3) => PromiseOrValue<void>;
-    mountPublicAssets: (app: H3, publicPath: string) => PromiseOrValue<void>;
+    mountPublicAssets?: (app: H3, publicPath: string) => PromiseOrValue<void>;
     createApp?: () => H3;
 }
 
@@ -60,7 +61,11 @@ export class H3Driver extends ArkstackKitDriver<H3, H3Middleware> {
      * @param publicPath 
      */
     mountPublicAssets (app: H3, publicPath: string): PromiseOrValue<void> {
-        return this.options.mountPublicAssets(app, publicPath)
+        if (this.options.mountPublicAssets) {
+            return this.options.mountPublicAssets(app, publicPath)
+        }
+
+        app.use(staticAssetHandler(publicPath))
     }
 
     /**

packages/driver-h3/src/index.ts

@@ -1 +1,2 @@
-export * from './request-logger'
+export * from './request-logger'
+export * from './static-asset-handler'

packages/driver-h3/src/middlewares/index.ts

@@ -0,0 +1,41 @@
+import { H3Event, serveStatic } from 'h3'
+import { readFile, stat } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+export const staticAssetHandler = (publicPath: string = 'public') => {
+    const rootPath = resolve(process.cwd(), publicPath)
+
+    return (event: H3Event) => {
+        const { pathname } = new URL(event.req.url)
+
+        if (!/\.[a-zA-Z0-9]+$/.test(pathname)) return
+        if (pathname.startsWith('/.') || pathname.includes('..')) return
+
+        event.res.headers.set('Cache-Control', 'public, max-age=31536000, immutable')
+        event.res.headers.set('Access-Control-Allow-Origin', '*')
+        event.res.headers.set('Access-Control-Allow-Methods', 'GET, HEAD, OPTIONS')
+        event.res.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization')
+
+        return serveStatic(event, {
+            indexNames: ['/index.html'],
+            getContents: (id) => {
+                const relativePath = id.replace(/^\/+/, '')
+                const file = join(rootPath, relativePath)
+
+                return readFile(file).catch(() => null) as never
+            },
+            getMeta: async (id) => {
+                const relativePath = id.replace(/^\/+/, '')
+                const file = join(rootPath, relativePath)
+                const stats = await stat(file).catch(() => undefined)
+
+                if (stats?.isFile()) {
+                    return {
+                        size: stats.size,
+                        mtime: stats.mtimeMs,
+                    }
+                }
+            },
+        })
+    }
+}

packages/driver-h3/src/middlewares/static-asset-handler.ts

@@ -0,0 +1,36 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { H3 } from 'h3'
+
+import { H3Driver } from '../src/index'
+
+describe('H3Driver', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+    })
+
+    it('uses a custom mountPublicAssets override when provided', async () => {
+        const app = { use: vi.fn() } as unknown as H3
+        const mountPublicAssets = vi.fn()
+        const driver = new H3Driver({
+            bindRouter: vi.fn(),
+            mountPublicAssets,
+        })
+
+        await driver.mountPublicAssets(app, 'public')
+
+        expect(mountPublicAssets).toHaveBeenCalledWith(app, 'public')
+        expect(app.use).not.toHaveBeenCalled()
+    })
+
+    it('registers the built-in static asset handler by default', () => {
+        const app = { use: vi.fn() } as unknown as H3
+        const driver = new H3Driver({
+            bindRouter: vi.fn(),
+        })
+
+        driver.mountPublicAssets(app, 'public')
+
+        expect(app.use).toHaveBeenCalledTimes(1)
+        expect(app.use).toHaveBeenCalledWith(expect.any(Function))
+    })
+})

packages/driver-h3/tests/index.test.ts

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { serveStatic } from 'h3'
+import { staticAssetHandler } from '../src/middlewares/static-asset-handler'
+
+vi.mock('h3', async () => {
+    const actual = await vi.importActual<typeof import('h3')>('h3')
+
+    return {
+        ...actual,
+        serveStatic: vi.fn(),
+    }
+})
+
+
+
+describe('staticAssetHandler', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+    })
+
+    it('ignores requests that do not target a static asset', () => {
+        const handler = staticAssetHandler('public')
+        const event = {
+            req: { url: 'http://localhost/posts' },
+            res: { headers: new Headers() },
+        }
+
+        const result = handler(event as never)
+
+        expect(result).toBeUndefined()
+        expect(serveStatic).not.toHaveBeenCalled()
+    })
+
+    it('blocks dotfile and traversal requests', () => {
+        const handler = staticAssetHandler('public')
+
+        handler({
+            req: { url: 'http://localhost/.env' },
+            res: { headers: new Headers() },
+        } as never)
+
+        handler({
+            req: { url: 'http://localhost/..%2Fsecret.txt' },
+            res: { headers: new Headers() },
+        } as never)
+
+        expect(serveStatic).not.toHaveBeenCalled()
+    })
+
+    it('serves asset requests and applies cache and cors headers', () => {
+        const handler = staticAssetHandler('public')
+        const event = {
+            req: { url: 'http://localhost/app.js' },
+            res: { headers: new Headers() },
+        }
+
+        vi.mocked(serveStatic).mockReturnValue('served' as never)
+
+        const result = handler(event as never)
+
+        expect(result).toBe('served')
+        expect(event.res.headers.get('Cache-Control')).toBe('public, max-age=31536000, immutable')
+        expect(event.res.headers.get('Access-Control-Allow-Origin')).toBe('*')
+        expect(event.res.headers.get('Access-Control-Allow-Methods')).toBe('GET, HEAD, OPTIONS')
+        expect(event.res.headers.get('Access-Control-Allow-Headers')).toBe('Content-Type, Authorization')
+        expect(serveStatic).toHaveBeenCalledTimes(1)
+        expect(serveStatic).toHaveBeenCalledWith(event, expect.objectContaining({
+            indexNames: ['/index.html'],
+            getContents: expect.any(Function),
+            getMeta: expect.any(Function),
+        }))
+    })
+})