acrylblends 0.3.0 → 0.4.0

package/plugins/acryl-router/src/core/middleware/serve-static/index.test.ts

@@ -0,0 +1,450 @@
+import { serveStatic as baseServeStatic } from './index.ts'
+import { App } from '../../app.ts'
+
+describe('Serve Static Middleware with a Blob body', () => {
+  it('Should serve content returned as a Blob', async () => {
+    const app = new App()
+    app.use(
+      '/static/*',
+      baseServeStatic({
+        getContent: async (path) => new Blob([`Hello in ${path}`]),
+      })
+    )
+    const res = await app.request('http://localhost/static/hello.txt')
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('Hello in static/hello.txt')
+  })
+})
+
+describe('Serve Static Middleware', () => {
+  const app = new App()
+  const getContent = vi.fn(async (path) => {
+    if (path.endsWith('not-found.txt')) {
+      return null
+    }
+    return `Hello in ${path}`
+  })
+
+  const serveStatic = baseServeStatic({
+    getContent,
+    isDir: (path) => {
+      if (path === 'static/sub' || path === 'static/hello.world') {
+        return true
+      }
+    },
+    onFound: (path, c) => {
+      if (path.endsWith('hello.html')) {
+        c.header('X-Custom', `Found the file at ${path}`)
+      }
+    },
+  })
+
+  app.get('/static/*', serveStatic)
+
+  beforeEach(() => {
+    getContent.mockClear()
+  })
+
+  it.each(['GET', 'HEAD'])(
+    'Should serve files for %s requests registered with use()',
+    async (method) => {
+      const app = new App().use('/static/*', serveStatic)
+
+      const res = await app.request('/static/hello.html', { method })
+
+      expect(res.status).toBe(200)
+      expect(res.headers.get('Content-Type')).toMatch(/^text\/html/)
+      expect(await res.text()).toBe(method === 'HEAD' ? '' : 'Hello in static/hello.html')
+      expect(getContent).toBeCalledTimes(1)
+    }
+  )
+
+  it.each(['POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'PROPFIND'])(
+    'Should pass %s requests to the next handler without accessing files',
+    async (method) => {
+      const isDir = vi.fn(() => false)
+      const rewriteRequestPath = vi.fn((path: string) => path)
+      const onFound = vi.fn()
+      const onNotFound = vi.fn()
+      const app = new App().use(
+        '/static/*',
+        baseServeStatic({ getContent, isDir, rewriteRequestPath, onFound, onNotFound })
+      )
+      app.on(method, '/static/hello.html', (c) => c.text('Handled downstream', 202))
+
+      const res = await app.request('/static/hello.html', { method })
+
+      expect(res.status).toBe(202)
+      expect(await res.text()).toBe('Handled downstream')
+      expect(rewriteRequestPath).not.toBeCalled()
+      expect(isDir).not.toBeCalled()
+      expect(getContent).not.toBeCalled()
+      expect(onFound).not.toBeCalled()
+      expect(onNotFound).not.toBeCalled()
+    }
+  )
+
+  it.each(['/static/hello.html', '/static/not-found.txt'])(
+    'Should return 404 for an unhandled POST request regardless of file existence - %s',
+    async (path) => {
+      const app = new App().use('/static/*', serveStatic)
+
+      const res = await app.request(path, { method: 'POST' })
+
+      expect(res.status).toBe(404)
+      expect(await res.text()).toBe('404 Not Found')
+      expect(getContent).not.toBeCalled()
+    }
+  )
+
+  it('Should return 200 response - /static/hello.html', async () => {
+    const res = await app.request('/static/hello.html')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Encoding')).toBeNull()
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/html/)
+    expect(await res.text()).toBe('Hello in static/hello.html')
+    expect(res.headers.get('X-Custom')).toBe('Found the file at static/hello.html')
+  })
+
+  it('Should return 200 response - /static/sub', async () => {
+    const res = await app.request('/static/sub')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/html/)
+    expect(await res.text()).toBe('Hello in static/sub/index.html')
+  })
+
+  it('Should return 200 response - /static/hello.world', async () => {
+    const res = await app.request('/static/hello.world')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/html/)
+    expect(await res.text()).toBe('Hello in static/hello.world/index.html')
+  })
+
+  it.each([
+    ['/static/%E7%82%8E.txt', 'static/炎.txt'],
+    ['/static/hello%20world.txt', 'static/hello world.txt'],
+  ])('Should decode URI strings - %s', async (url, path) => {
+    const res = await app.request(url)
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/plain/)
+    expect(await res.text()).toBe(`Hello in ${path}`)
+  })
+
+  it.each(['/static/100%25.txt', '/static/100%25/hello.txt', '/static/%2Fadmin/secret.txt'])(
+    'Should skip paths containing percent signs by default - %s',
+    async (path) => {
+      const onNotFound = vi.fn()
+      const app = new App().use('*', baseServeStatic({ getContent, onNotFound }))
+
+      const res = await app.request(path)
+
+      expect(res.status).toBe(404)
+      expect(getContent).not.toBeCalled()
+      expect(onNotFound).toHaveBeenCalledWith(path, expect.anything())
+    }
+  )
+
+  it.each([
+    ['/static/100%25.txt', 'static/100%.txt'],
+    ['/static/100%25/hello.txt', 'static/100%/hello.txt'],
+    ['/static/%2Fadmin/secret.txt', 'static/%2Fadmin/secret.txt'],
+  ])('Should allow percent signs when opted in - %s', async (url, path) => {
+    const app = new App().use('*', baseServeStatic({ getContent, allowPercentInPath: true }))
+
+    const res = await app.request(url)
+
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe(`Hello in ${path}`)
+  })
+
+  it('Should not bypass authentication through a second decode', async () => {
+    const app = new App()
+    app.get('/static/admin/*', (c) => c.text('Unauthorized', 401))
+    app.use('/static/*', baseServeStatic({ getContent }))
+
+    const protectedRes = await app.request('/static/admin/secret.txt')
+    expect(protectedRes.status).toBe(401)
+
+    const res = await app.request('/static/%%36%31dmin/secret.txt')
+    expect(res.status).toBe(404)
+    expect(getContent).not.toBeCalled()
+  })
+
+  it('Should return 404 response - /static/not-found.txt', async () => {
+    const res = await app.request('/static/not-found.txt')
+    expect(res.status).toBe(404)
+    expect(res.headers.get('Content-Encoding')).toBeNull()
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/plain/)
+    expect(await res.text()).toBe('404 Not Found')
+    expect(getContent).toBeCalledTimes(1)
+  })
+
+  it('Should return 200 response for empty string content - /static/empty.txt', async () => {
+    const onNotFound = vi.fn()
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent: async () => '',
+        onNotFound,
+      })
+    )
+    const res = await app.request('/static/empty.txt')
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('')
+    expect(onNotFound).not.toBeCalled()
+  })
+
+  it('Should not allow a directory traversal - /static/%2e%2e/static/hello.html', async () => {
+    const res = await app.fetch({
+      method: 'GET',
+      url: 'http://localhost/static/%2e%2e/static/hello.html',
+    } as Request)
+    expect(res.status).toBe(404)
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/plain/)
+    expect(await res.text()).toBe('404 Not Found')
+  })
+
+  it('Should not allow a backslash separator injection - /static/admin%5Csecret.txt', async () => {
+    const res = await app.fetch({
+      method: 'GET',
+      url: 'http://localhost/static/admin%5Csecret.txt',
+    } as Request)
+    expect(res.status).toBe(404)
+    expect(await res.text()).toBe('404 Not Found')
+  })
+
+  it('Should return a pre-compressed zstd response - /static/hello.html', async () => {
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent,
+        precompressed: true,
+      })
+    )
+
+    const res = await app.request('/static/hello.html', {
+      headers: { 'Accept-Encoding': 'zstd' },
+    })
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Encoding')).toBe('zstd')
+    expect(res.headers.get('Vary')).toBe('Accept-Encoding')
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/html/)
+    expect(await res.text()).toBe('Hello in static/hello.html.zst')
+  })
+
+  it('Should return a pre-compressed brotli response - /static/hello.html', async () => {
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent,
+        precompressed: true,
+      })
+    )
+
+    const res = await app.request('/static/hello.html', {
+      headers: { 'Accept-Encoding': 'wompwomp, gzip, br, deflate, zstd' },
+    })
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Encoding')).toBe('br')
+    expect(res.headers.get('Vary')).toBe('Accept-Encoding')
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/html/)
+    expect(await res.text()).toBe('Hello in static/hello.html.br')
+  })
+
+  it('Should return a pre-compressed brotli response - /static/hello.unknown', async () => {
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent,
+        precompressed: true,
+      })
+    )
+
+    const res = await app.request('/static/hello.unknown', {
+      headers: { 'Accept-Encoding': 'wompwomp, gzip, br, deflate, zstd' },
+    })
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Encoding')).toBe('br')
+    expect(res.headers.get('Vary')).toBe('Accept-Encoding')
+    expect(res.headers.get('Content-Type')).toBe('application/octet-stream')
+    expect(await res.text()).toBe('Hello in static/hello.unknown.br')
+  })
+
+  it('Should return a pre-compressed response when Accept-Encoding has q-values', async () => {
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent,
+        precompressed: true,
+      })
+    )
+
+    const res = await app.request('/static/hello.html', {
+      headers: { 'Accept-Encoding': 'br;q=0, zstd;q=1.0, gzip;q=0.5' },
+    })
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Encoding')).toBe('zstd')
+    expect(res.headers.get('Vary')).toBe('Accept-Encoding')
+    expect(await res.text()).toBe('Hello in static/hello.html.zst')
+  })
+
+  it('Should not return a pre-compressed response - /static/not-found.txt', async () => {
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent,
+        precompressed: true,
+      })
+    )
+
+    const res = await app.request('/static/not-found.txt', {
+      headers: { 'Accept-Encoding': 'gzip, zstd, br' },
+    })
+
+    expect(res.status).toBe(404)
+    expect(res.headers.get('Content-Encoding')).toBeNull()
+    expect(res.headers.get('Vary')).toBeNull()
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/plain/)
+    expect(await res.text()).toBe('404 Not Found')
+  })
+
+  it('Should not return a pre-compressed response - /static/hello.html', async () => {
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent,
+        precompressed: true,
+      })
+    )
+
+    const res = await app.request('/static/hello.html', {
+      headers: { 'Accept-Encoding': 'wompwomp, unknown' },
+    })
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Encoding')).toBeNull()
+    expect(res.headers.get('Vary')).toBeNull()
+    expect(res.headers.get('Content-Type')).toMatch(/^text\/html/)
+    expect(await res.text()).toBe('Hello in static/hello.html')
+  })
+
+  it('Should not find pre-compressed files - /static/hello.jpg', async () => {
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent,
+        precompressed: true,
+      })
+    )
+
+    const res = await app.request('/static/hello.jpg', {
+      headers: { 'Accept-Encoding': 'gzip, br, deflate, zstd' },
+    })
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('Content-Encoding')).toBeNull()
+    expect(res.headers.get('Vary')).toBeNull()
+    expect(res.headers.get('Content-Type')).toMatch(/^image\/jpeg/)
+    expect(await res.text()).toBe('Hello in static/hello.jpg')
+  })
+
+  it('Should return response object content as-is', async () => {
+    const body = new ReadableStream()
+    const response = new Response(body)
+    const app = new App().use(
+      '*',
+      baseServeStatic({
+        getContent: async () => {
+          return response
+        },
+      })
+    )
+
+    const res = await app.fetch({
+      method: 'GET',
+      url: 'http://localhost',
+    } as Request)
+    expect(res.status).toBe(200)
+    expect(res.body).toBe(body)
+  })
+
+  describe('Changing root path', () => {
+    it('Should return the content with absolute root path', async () => {
+      const app = new App()
+      const serveStatic = baseServeStatic({
+        getContent,
+        root: '/home/acryl/child',
+      })
+      app.get('/static/*', serveStatic)
+
+      const res = await app.request('/static/html/hello.html')
+      expect(await res.text()).toBe('Hello in /home/acryl/child/static/html/hello.html')
+    })
+
+    it('Should traverse the directories with absolute root path', async () => {
+      const app = new App()
+      const serveStatic = baseServeStatic({
+        getContent,
+        root: '/home/acryl/../parent',
+      })
+      app.get('/static/*', serveStatic)
+
+      const res = await app.request('/static/html/hello.html')
+      expect(await res.text()).toBe('Hello in /home/parent/static/html/hello.html')
+    })
+
+    it('Should treat the root path includes .. as relative path', async () => {
+      const app = new App()
+      const serveStatic = baseServeStatic({
+        getContent,
+        root: '../home/acryl',
+      })
+      app.get('/static/*', serveStatic)
+
+      const res = await app.request('/static/html/hello.html')
+      expect(await res.text()).toBe('Hello in ../home/acryl/static/html/hello.html')
+    })
+
+    it('Should not allow directory traversal with . as relative path', async () => {
+      const app = new App()
+      const serveStatic = baseServeStatic({
+        getContent,
+        root: '.',
+      })
+      app.get('*', serveStatic)
+
+      const res = await app.request('/etc/passwd')
+      expect(await res.text()).toBe('Hello in etc/passwd')
+    })
+
+    it('Should not allow bypass via path mismatch between middleware and serveStatic', async () => {
+      const app = new App()
+
+      app.use('/admin/*', async (c, next) => {
+        c.header('X-Authorized', 'true')
+        await next()
+      })
+
+      const serveStatic = baseServeStatic({
+        getContent,
+        root: '.',
+      })
+      app.use('/*', serveStatic)
+
+      const res = await app.request('/admin/secret.txt')
+      expect(res.headers.get('X-Authorized')).toBe('true')
+      expect(await res.text()).toBe('Hello in admin/secret.txt')
+
+      const res2 = await app.request('/admin%2Fsecret.txt')
+      expect(res2.headers.get('X-Authorized')).toBeNull()
+      expect(res2.status).toBe(404)
+
+      const res3 = await app.request('//admin/secret.txt')
+      expect(res3.status).toBe(404)
+    })
+  })
+})

package/plugins/acryl-router/src/core/middleware/serve-static/index.ts

@@ -0,0 +1,135 @@
+/**
+ * @module
+ * Serve Static Middleware for App.
+ */
+
+import type { Context, Data } from '../../context.ts'
+import type { Env, MiddlewareHandler } from '../../types.ts'
+import { parseAccept } from '../../utils/accept.ts'
+import { COMPRESSIBLE_CONTENT_TYPE_REGEX } from '../../utils/compress.ts'
+import { getMimeType } from '../../utils/mime.ts'
+import { tryDecodeURI } from '../../utils/url.ts'
+import { defaultJoin } from './path.ts'
+
+export type ServeStaticOptions<E extends Env = Env> = {
+  root?: string
+  path?: string
+  precompressed?: boolean
+  /** Allow percent signs in the routed request path. Defaults to false. */
+  allowPercentInPath?: boolean
+  mimes?: Record<string, string>
+  rewriteRequestPath?: (path: string) => string
+  onFound?: (path: string, c: Context<E>) => void | Promise<void>
+  onNotFound?: (path: string, c: Context<E>) => void | Promise<void>
+}
+
+const ENCODINGS = {
+  br: '.br',
+  zstd: '.zst',
+  gzip: '.gz',
+} as const
+const ENCODINGS_ORDERED_KEYS = Object.keys(ENCODINGS) as (keyof typeof ENCODINGS)[]
+
+const DEFAULT_DOCUMENT = 'index.html'
+
+/**
+ * This middleware is not directly used by the user. Create a wrapper specifying `getContent()` by the environment such as Deno or Bun.
+ */
+export const serveStatic = <E extends Env = Env>(
+  options: ServeStaticOptions<E> & {
+    getContent: (path: string, c: Context<E>) => Promise<Data | Response | null>
+    /**
+     *
+     * `join` option according to the runtime. Example `import { join } from 'node:path`. If not specified, it will fall back to the default join function.`
+     */
+    join?: (...paths: string[]) => string
+    /**
+     * @deprecated Currently, `pathResolve` is no longer used.
+     */
+    pathResolve?: (path: string) => string
+    isDir?: (path: string) => boolean | undefined | Promise<boolean | undefined>
+  }
+): MiddlewareHandler => {
+  const root = options.root ?? './'
+  const optionPath = options.path
+  const join = options.join ?? defaultJoin
+
+  return async (c, next) => {
+    // Do nothing if Response is already set
+    if (c.finalized) {
+      return next()
+    }
+
+    if (c.req.method !== 'GET' && c.req.method !== 'HEAD') {
+      return next()
+    }
+
+    let filename: string
+
+    if (options.path) {
+      filename = options.path
+    } else {
+      try {
+        if (!options.allowPercentInPath && c.req.path.includes('%')) {
+          throw new Error()
+        }
+        filename = tryDecodeURI(c.req.path)
+        if (/(?:^|[\/\\])\.{1,2}(?:$|[\/\\])|[\/\\]{2,}|\\/.test(filename)) {
+          throw new Error()
+        }
+      } catch {
+        await options.onNotFound?.(c.req.path, c)
+        return next()
+      }
+    }
+
+    let path = join(
+      root,
+      !optionPath && options.rewriteRequestPath ? options.rewriteRequestPath(filename) : filename
+    )
+
+    if (options.isDir && (await options.isDir(path))) {
+      path = join(path, DEFAULT_DOCUMENT)
+    }
+
+    const getContent = options.getContent
+    let content = await getContent(path, c)
+
+    if (content instanceof Response) {
+      return c.newResponse(content.body, content)
+    }
+
+    if (content != null) {
+      const mimeType = (options.mimes && getMimeType(path, options.mimes)) || getMimeType(path)
+      c.header('Content-Type', mimeType || 'application/octet-stream')
+
+      if (options.precompressed && (!mimeType || COMPRESSIBLE_CONTENT_TYPE_REGEX.test(mimeType))) {
+        const acceptEncodingSet = new Set(
+          parseAccept(c.req.header('Accept-Encoding') ?? '')
+            .filter((encoding) => encoding.q > 0)
+            .map((encoding) => encoding.type)
+        )
+
+        for (const encoding of ENCODINGS_ORDERED_KEYS) {
+          if (!acceptEncodingSet.has(encoding)) {
+            continue
+          }
+          const compressedContent = (await getContent(path + ENCODINGS[encoding], c)) as Data | null
+
+          if (compressedContent) {
+            content = compressedContent
+            c.header('Content-Encoding', encoding)
+            c.header('Vary', 'Accept-Encoding', { append: true })
+            break
+          }
+        }
+      }
+      await options.onFound?.(path, c)
+      return c.body(content)
+    }
+
+    await options.onNotFound?.(path, c)
+    await next()
+    return
+  }
+}

package/plugins/acryl-router/src/core/middleware/serve-static/path.test.ts

@@ -0,0 +1,50 @@
+import { join as posixJoin } from 'node:path/posix'
+import { defaultJoin } from './path.ts'
+
+describe('defaultJoin', () => {
+  describe('Comparison with node:path/posix.join', () => {
+    it('Should behave like path.posix.join for all path operations', () => {
+      const testCases = [
+        // Basic path joining
+        ['/home/yusuke/work/app/public', 'static/main.html'],
+        ['public', 'sub/', 'file.html'],
+        ['', 'file.html'],
+        ['public', ''],
+        ['public/', 'file.html'],
+        ['public', 'static', 'main.html'],
+        ['assets', 'images', 'logo.png'],
+
+        // Parent directory references
+        ['public', '../parent/file.html'],
+        ['public', '../../grandparent/file.html'],
+        ['/abs/path', '../relative.html'],
+        ['a/b', '../c'],
+        ['a/b/c', '../../d'],
+
+        // Current directory references
+        ['./public', 'static/main.html'],
+        ['public', './file.html'],
+        ['./public', '/absolute/path.html'],
+        ['.', 'file.html'],
+        ['public/.', 'file.html'],
+
+        // Edge cases
+        [],
+        ['.'],
+        [''],
+        ['/'],
+        ['a', 'b', 'c'],
+
+        // Backslash handling (security)
+        ['static', 'test\\file.txt'],
+        ['public', 'path\\with\\backslash'],
+      ]
+
+      testCases.forEach(([...args]) => {
+        const expected = posixJoin(...args)
+        const actual = defaultJoin(...args)
+        expect(actual).toBe(expected)
+      })
+    })
+  })
+})

package/plugins/acryl-router/src/core/middleware/serve-static/path.ts

@@ -0,0 +1,25 @@
+/**
+ * `defaultJoin` does not support Windows paths and always uses `/` separators.
+ * If you need Windows path support, please use `join` exported from `node:path` etc. instead.
+ */
+export const defaultJoin = (...paths: string[]): string => {
+  // Join non-empty paths with '/'
+  let result = paths.filter((p) => p !== '').join('/')
+
+  // Normalize multiple slashes to single slash
+  result = result.replace(/(?<=\/)\/+/g, '')
+
+  // Handle path resolution (. and ..)
+  const segments = result.split('/')
+  const resolved = []
+
+  for (const segment of segments) {
+    if (segment === '..' && resolved.length > 0 && resolved.at(-1) !== '..') {
+      resolved.pop()
+    } else if (segment !== '.') {
+      resolved.push(segment)
+    }
+  }
+
+  return resolved.join('/') || '.'
+}