acrylblends 0.6.1 → 0.6.3

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

@@ -0,0 +1,323 @@
+/**
+ * @module
+ * Cache Middleware for Acryl.
+ */
+
+import type { Context } from '../../context.ts'
+import { cloneRawRequest } from '../../request.ts'
+import type { MiddlewareHandler } from '../../types.ts'
+import { sha256 } from '../../utils/crypto.ts'
+import type { StatusCode } from '../../utils/http-status.ts'
+
+/**
+ * status codes that can be cached by default.
+ */
+const defaultCacheableStatusCodes: ReadonlyArray<StatusCode> = [200]
+
+const defaultMaxQueryBodySize = 64 * 1024
+
+const cacheKeyPath = '/.acryl-router/cache'
+const cacheKeyParameter = '__hono_cache_key'
+const cacheMethodKeyParameter = '__hono_cache_method'
+const queryDigestKeyParameter = '__hono_query_digest'
+const cacheVaryKeyParameter = '__hono_cache_vary'
+
+type CacheKeyRequest =
+  | { method: 'GET' }
+  | {
+      method: 'QUERY'
+      digest: string
+    }
+
+const queryRepresentationMetadataHeaders = [
+  'content-type',
+  'content-encoding',
+  'content-language',
+  'content-location',
+] as const
+
+const shouldSkipCacheControl = (cacheControl: string | null): boolean =>
+  !!cacheControl && /(?:^|,\s*)(?:private|no-(?:store|cache))(?:\s*(?:=|,|$))/i.test(cacheControl)
+
+const parseVaryDirectives = (vary: string | string[] | null | undefined): string[] => {
+  if (vary == null) {
+    return []
+  }
+  return (Array.isArray(vary) ? vary : vary.split(','))
+    .map((directive) => directive.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+const createCacheKey = (
+  key: string,
+  requestUrl: string,
+  request: CacheKeyRequest,
+  varyHeaders: [string, string][]
+): string => {
+  const url = new URL(cacheKeyPath, requestUrl)
+  url.searchParams.append(cacheKeyParameter, key)
+  url.searchParams.append(cacheMethodKeyParameter, request.method)
+
+  if (request.method === 'QUERY') {
+    url.searchParams.append(queryDigestKeyParameter, request.digest)
+  }
+
+  for (const header of varyHeaders) {
+    url.searchParams.append(cacheVaryKeyParameter, JSON.stringify(header))
+  }
+
+  return url.href
+}
+
+const shouldSkipCache = (
+  res: Response,
+  optionsVaryDirectives: Set<string> | undefined,
+  responseVary: string[]
+): boolean =>
+  (responseVary.length &&
+    (!optionsVaryDirectives || responseVary.some((name) => !optionsVaryDirectives.has(name)))) ||
+  shouldSkipCacheControl(res.headers.get('Cache-Control')) ||
+  res.headers.has('Set-Cookie')
+
+const reportCacheNotAvailable = (
+  onCacheNotAvailable: ((reason: string) => void) | false | undefined,
+  reason: string
+): void => {
+  if (onCacheNotAvailable === false) {
+    // suppress log
+  } else if (onCacheNotAvailable) {
+    onCacheNotAvailable(reason)
+  } else {
+    console.log(reason)
+  }
+}
+
+const createQueryDigest = async (
+  c: Context,
+  maxQueryBodySize: number
+): Promise<string | undefined> => {
+  if (!globalThis.crypto?.subtle) {
+    return undefined
+  }
+
+  if (c.req.raw.bodyUsed && Object.keys(c.req.bodyCache)[0] === 'formData') {
+    // FormData cannot be reserialized with a stable multipart boundary after
+    // the original request body has been consumed.
+    return undefined
+  }
+
+  try {
+    // RFC 10008 Section 2.7 requires QUERY cache keys to incorporate the
+    // request content and its related representation metadata.
+    const requestHeaders = c.req.raw.headers
+    const metadata = new TextEncoder().encode(
+      JSON.stringify(
+        queryRepresentationMetadataHeaders.map((header) => [header, requestHeaders.get(header)])
+      )
+    )
+    const body = (await cloneRawRequest(c.req)).body
+    const chunks: Uint8Array[] = []
+    let bodySize = 0
+
+    if (body) {
+      const reader = body.getReader()
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) {
+          break
+        }
+        bodySize += value.byteLength
+        if (bodySize > maxQueryBodySize) {
+          // Do not await cancellation because a cloned stream's cancellation
+          // can wait for the original request stream to finish.
+          void reader.cancel().catch(() => {})
+          return undefined
+        }
+        chunks.push(value)
+      }
+    }
+
+    const data = new Uint8Array(metadata.byteLength + bodySize)
+    data.set(metadata)
+    let offset = metadata.byteLength
+    for (const chunk of chunks) {
+      data.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+
+    return (await sha256(data)) ?? undefined
+  } catch {
+    // A QUERY response cannot be cached safely if its content cannot be read.
+    return undefined
+  }
+}
+
+/**
+ * Cache Middleware for Acryl.
+ *
+ *
+ * @param {Object} options - The options for the cache middleware.
+ * @param {string | Function} options.cacheName - The name of the cache. Can be used to store multiple caches with different identifiers.
+ * @param {boolean} [options.wait=false] - A boolean indicating if Acryl should wait for the Promise of the `cache.put` function to resolve before continuing with the request. Required to be true for the Deno environment.
+ * @param {string} [options.cacheControl] - A string of directives for the `Cache-Control` header.
+ * @param {string | string[]} [options.vary] - Adds the configured request headers to the cache key variants and sets the `Vary` header in the response. If the original response header already contains a `Vary` header, the values are merged, removing any duplicates.
+ * @param {Function} [options.keyGenerator] - Generates keys for every request in the `cacheName` store. This can be used to cache data based on request parameters or context parameters. QUERY keys additionally include a digest of the request content and its representation metadata.
+ * @param {number} [options.maxQueryBodySize=65536] - The maximum QUERY request body size in bytes that can be cached. Larger QUERY requests bypass the cache.
+ * @param {number[]} [options.cacheableStatusCodes=[200]] - An array of status codes that can be cached.
+ * @param {Function | false} [options.onCacheNotAvailable] - A callback invoked with the reason when `globalThis.caches` is not available or QUERY caching cannot use Web Crypto. By default, the reason is logged to the console. Set to `false` to suppress the log, or provide a custom function.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ * @throws {Error} If the `vary` option includes "*".
+ *
+ * @example
+ * ```ts
+ * app.use(
+ *   '*',
+ *   cache({
+ *     cacheName: 'my-app',
+ *     cacheControl: 'max-age=3600',
+ *   })
+ * )
+ * ```
+ */
+export const cache = (options: {
+  cacheName: string | ((c: Context) => Promise<string> | string)
+  wait?: boolean
+  cacheControl?: string
+  vary?: string | string[]
+  keyGenerator?: (c: Context) => Promise<string> | string
+  maxQueryBodySize?: number
+  cacheableStatusCodes?: StatusCode[]
+  onCacheNotAvailable?: ((reason: string) => void) | false
+}): MiddlewareHandler => {
+  if (!globalThis.caches) {
+    reportCacheNotAvailable(
+      options.onCacheNotAvailable,
+      'Cache Middleware is not enabled because caches is not defined.'
+    )
+    return async (_c, next) => await next()
+  }
+
+  if (!globalThis.crypto?.subtle) {
+    reportCacheNotAvailable(
+      options.onCacheNotAvailable,
+      'Cache Middleware cannot cache QUERY requests because Web Crypto is not available.'
+    )
+  }
+
+  if (options.wait === undefined) {
+    options.wait = false
+  }
+
+  const cacheControlDirectives = options.cacheControl
+    ?.split(',')
+    .map((directive) => directive.toLowerCase())
+  const optionsVaryList = parseVaryDirectives(options.vary)
+  const varyDirectives = optionsVaryList.length ? new Set(optionsVaryList) : undefined
+  // RFC 7231 Section 7.1.4 specifies that "*" is not allowed in Vary header.
+  // See: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.4
+  if (varyDirectives?.has('*')) {
+    throw new Error(
+      'Middleware vary configuration cannot include "*", as it disallows effective caching.'
+    )
+  }
+
+  const cacheableStatusCodes = new Set<number>(
+    options.cacheableStatusCodes ?? defaultCacheableStatusCodes
+  )
+  const maxQueryBodySize = options.maxQueryBodySize ?? defaultMaxQueryBodySize
+
+  const addHeader = (c: Context, responseVary: string[]) => {
+    if (cacheControlDirectives) {
+      const existingDirectives =
+        c.res.headers
+          .get('Cache-Control')
+          ?.split(',')
+          // Directive names are case-insensitive (RFC 7234 §5.2); lower-case so
+          // the case-insensitive de-dup check below matches handler-set names
+          // like `Max-Age`.
+          .map((d) => d.trim().split('=', 1)[0].toLowerCase()) ?? []
+      for (const directive of cacheControlDirectives) {
+        let [name, value] = directive.trim().split('=', 2)
+        name = name.toLowerCase()
+        if (!existingDirectives.includes(name)) {
+          c.header('Cache-Control', `${name}${value ? `=${value}` : ''}`, { append: true })
+        }
+      }
+    }
+
+    if (varyDirectives) {
+      if (responseVary.length === 0) {
+        c.header('Vary', Array.from(varyDirectives).join(', '))
+      } else {
+        const merged = new Set(varyDirectives)
+        for (const directive of responseVary) {
+          merged.add(directive)
+        }
+        if (merged.has('*')) {
+          c.header('Vary', '*')
+        } else {
+          c.header('Vary', Array.from(merged).join(', '))
+        }
+      }
+    }
+  }
+
+  return async function cache(c, next) {
+    if (
+      (c.req.method !== 'GET' && c.req.method !== 'QUERY') ||
+      c.req.raw.headers.has('Authorization')
+    ) {
+      await next()
+      return
+    }
+
+    let cacheKeyRequest: CacheKeyRequest = { method: 'GET' }
+    if (c.req.method === 'QUERY') {
+      const digest = await createQueryDigest(c, maxQueryBodySize)
+      if (digest === undefined) {
+        await next()
+        return
+      }
+      cacheKeyRequest = { method: 'QUERY', digest }
+    }
+
+    let key = c.req.url
+    if (options.keyGenerator) {
+      key = await options.keyGenerator(c)
+    }
+    const varyHeaders: [string, string][] = []
+    if (varyDirectives) {
+      for (const directive of varyDirectives) {
+        const value = c.req.raw.headers.get(directive) ?? ''
+        varyHeaders.push([directive, value])
+      }
+    }
+    key = createCacheKey(key, c.req.url, cacheKeyRequest, varyHeaders)
+
+    const cacheName =
+      typeof options.cacheName === 'function' ? await options.cacheName(c) : options.cacheName
+    const cache = await caches.open(cacheName)
+    const response = await cache.match(key)
+    if (response) {
+      return new Response(response.body, response)
+    }
+
+    await next()
+    if (!cacheableStatusCodes.has(c.res.status)) {
+      return
+    }
+    const responseVary = parseVaryDirectives(c.res.headers.get('Vary'))
+    addHeader(c, responseVary)
+
+    if (shouldSkipCache(c.res, varyDirectives, responseVary)) {
+      return
+    }
+
+    const res = c.res.clone()
+    if (options.wait) {
+      await cache.put(key, res)
+    } else {
+      c.executionCtx.waitUntil(cache.put(key, res))
+    }
+  }
+}

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

@@ -0,0 +1,334 @@
+import { mount } from './index.ts'
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+import type { ExecutionContext } from '../../context.ts'
+import { Acryl } from '../../app.ts'
+import { getPath } from '../../utils/url.ts'
+
+describe('mount()', () => {
+  describe('Basic', () => {
+    const anotherApp = (req: Request, ...params: unknown[]) => {
+      const path = getPath(req)
+      if (path === '/') {
+        return new Response('AnotherApp')
+      }
+      if (path === '/hello') {
+        return new Response('Hello from AnotherApp')
+      }
+      if (path === '/header') {
+        const message = req.headers.get('x-message')
+        return new Response(message)
+      }
+      if (path === '/with-query') {
+        const queryStrings = new URL(req.url).searchParams.toString()
+        return new Response(queryStrings)
+      }
+      if (path == '/with-params') {
+        return new Response(
+          JSON.stringify({
+            params,
+          }),
+          {
+            headers: {
+              'Content-Type': 'application.json',
+            },
+          }
+        )
+      }
+      if (path === '/undefined') {
+        return undefined as unknown as Response
+      }
+      return new Response('Not Found from AnotherApp', {
+        status: 404,
+      })
+    }
+
+    const app = new Acryl()
+    app.use('*', async (c, next) => {
+      await next()
+      c.header('x-message', 'Foo')
+    })
+    app.get('/', (c) => c.text('Acryl'))
+    app.notFound((c) => {
+      return c.text('Not Found from App', 404)
+    })
+
+    app.all(
+      '/another-app/*',
+      mount(anotherApp, () => {
+        return 'params'
+      })
+    )
+    app.all(
+      '/another-app-with-array-option/*',
+      mount(anotherApp, () => {
+        return ['param1', 'param2']
+      })
+    )
+    app.all('/another-app2/sub-slash/*', mount(anotherApp))
+
+    const api = new Acryl().basePath('/api')
+    api.all('/another-app/*', mount(anotherApp))
+
+    it('Should return responses from Acryl app', async () => {
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+      expect(res.headers.get('x-message')).toBe('Foo')
+      expect(await res.text()).toBe('Acryl')
+    })
+
+    it('Should return responses from AnotherApp', async () => {
+      let res = await app.request('/another-app')
+      expect(res.status).toBe(200)
+      expect(res.headers.get('x-message')).toBe('Foo')
+      expect(await res.text()).toBe('AnotherApp')
+
+      res = await app.request('/another-app/hello')
+      expect(res.status).toBe(200)
+      expect(res.headers.get('x-message')).toBe('Foo')
+      expect(await res.text()).toBe('Hello from AnotherApp')
+
+      const req = new Request('http://localhost/another-app/header', {
+        headers: {
+          'x-message': 'Message Foo!',
+        },
+      })
+      res = await app.request(req)
+      expect(res.status).toBe(200)
+      expect(res.headers.get('x-message')).toBe('Foo')
+      expect(await res.text()).toBe('Message Foo!')
+
+      res = await app.request('/another-app/not-found')
+      expect(res.status).toBe(404)
+      expect(res.headers.get('x-message')).toBe('Foo')
+      expect(await res.text()).toBe('Not Found from AnotherApp')
+
+      res = await app.request('/another-app/with-query?foo=bar&baz=qux')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('foo=bar&baz=qux')
+
+      res = await app.request('/another-app/with-params')
+      expect(res.status).toBe(200)
+      expect(await res.json()).toEqual({
+        params: ['params'],
+      })
+
+      res = await app.request('/another-app/undefined')
+      expect(res.status).toBe(404)
+      expect(await res.text()).toBe('Not Found from App')
+    })
+
+    it('Should return response from Another app with an array option', async () => {
+      const res = await app.request('/another-app-with-array-option/with-params')
+      expect(res.status).toBe(200)
+      expect(await res.json()).toEqual({
+        params: ['param1', 'param2'],
+      })
+    })
+
+    it('Should return responses from AnotherApp - sub + slash', async () => {
+      const res = await app.request('/another-app2/sub-slash')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('AnotherApp')
+    })
+
+    it('Should return responses from AnotherApp - with `basePath()`', async () => {
+      const res = await api.request('/api/another-app')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('AnotherApp')
+    })
+  })
+
+  describe('With encoded paths', () => {
+    const anotherApp = (req: Request) => new Response(getPath(req))
+
+    it('Should strip a decoded non-ASCII mount prefix', async () => {
+      const app = new Acryl()
+      app.all('/api/é/*', mount(anotherApp))
+
+      const res = await app.request('/api/%C3%A9/hello')
+
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('/hello')
+    })
+
+    it('Should preserve an encoded slash as a literal path segment after stripping the prefix', async () => {
+      const app = new Acryl()
+      app.all('/api/v1/*', mount(anotherApp))
+
+      const res = await app.request('/api/v1/admin%2Fsecret')
+
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('/admin%2Fsecret')
+    })
+
+    it('Should preserve encoded percent characters after stripping the prefix', async () => {
+      const app = new Acryl()
+      app.all('/api/*', mount(anotherApp))
+
+      const res = await app.request('/api/foo%252Fbar')
+
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('/foo%252Fbar')
+    })
+  })
+
+  describe('With fetch', () => {
+    const anotherApp = async (req: Request, env: {}, executionContext: ExecutionContext) => {
+      const path = getPath(req)
+      if (path === '/') {
+        return new Response(
+          JSON.stringify({
+            env,
+            executionContext,
+          }),
+          {
+            headers: {
+              'Content-Type': 'application/json',
+            },
+          }
+        )
+      }
+      return new Response('Not Found from AnotherApp', {
+        status: 404,
+      })
+    }
+
+    const app = new Acryl()
+    app.all('/another-app/*', mount(anotherApp))
+
+    it('Should handle Env and ExecuteContext', async () => {
+      const request = new Request('http://localhost/another-app')
+      const res = await app.fetch(
+        request,
+        {
+          TOKEN: 'foo',
+        },
+        {
+          // Force mocking!
+
+          // @ts-ignore
+          waitUntil: 'waitUntil',
+
+          // @ts-ignore
+          passThroughOnException: 'passThroughOnException',
+        }
+      )
+      expect(res.status).toBe(200)
+      expect(await res.json()).toEqual({
+        env: {
+          TOKEN: 'foo',
+        },
+        executionContext: {
+          waitUntil: 'waitUntil',
+          passThroughOnException: 'passThroughOnException',
+        },
+      })
+    })
+  })
+
+  describe('Mount on `/`', () => {
+    const anotherApp = (req: Request, _params: unknown) => {
+      const path = getPath(req)
+      if (path === '/') {
+        return new Response('AnotherApp')
+      }
+      if (path === '/hello') {
+        return new Response('Hello from AnotherApp')
+      }
+      if (path === '/good/night') {
+        return new Response('Good Night from AnotherApp')
+      }
+      return new Response('Not Found from AnotherApp', {
+        status: 404,
+      })
+    }
+
+    const app = new Acryl()
+    app.all('/*', mount(anotherApp))
+
+    it('Should return responses from AnotherApp - mount on `/`', async () => {
+      let res = await app.request('/')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('AnotherApp')
+      res = await app.request('/hello')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('Hello from AnotherApp')
+      res = await app.request('/good/night')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('Good Night from AnotherApp')
+      res = await app.request('/not-found')
+      expect(res.status).toBe(404)
+      expect(await res.text()).toBe('Not Found from AnotherApp')
+    })
+  })
+
+  describe('With replaceRequest option', () => {
+    const anotherApp = (req: Request) => {
+      const path = getPath(req)
+      if (path === '/app') {
+        return new Response(getPath(req))
+      }
+      return new Response(null, { status: 404 })
+    }
+
+    const app = new Acryl()
+    app.all(
+      '/app/*',
+      mount(anotherApp, {
+        replaceRequest: (req) => req,
+      })
+    )
+
+    it('Should return 200 response with the correct path', async () => {
+      const res = await app.request('/app')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('/app')
+    })
+  })
+
+  describe('With replaceRequest: false', () => {
+    const anotherApp = (req: Request) => {
+      const path = getPath(req)
+      if (path === '/app') {
+        return new Response(getPath(req))
+      }
+      return new Response(null, { status: 404 })
+    }
+
+    const app = new Acryl()
+    app.all('/app/*', mount(anotherApp, { replaceRequest: false }))
+
+    it('Should return 200 response with the correct path', async () => {
+      const res = await app.request('/app')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('/app')
+    })
+  })
+
+  describe('Used as `app.use()` middleware', () => {
+    const anotherApp = (req: Request) => {
+      const path = getPath(req)
+      if (path === '/hello') {
+        return new Response('Hello from AnotherApp')
+      }
+      // Fall through to the Acryl app
+      return undefined as unknown as Response
+    }
+
+    const app = new Acryl()
+    app.use('/another-app/*', mount(anotherApp))
+    app.get('/another-app/fallback', (c) => c.text('Fallback from App'))
+
+    it('Should return responses from AnotherApp', async () => {
+      const res = await app.request('/another-app/hello')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('Hello from AnotherApp')
+    })
+
+    it('Should fall through to the Acryl app if AnotherApp returns nothing', async () => {
+      const res = await app.request('/another-app/fallback')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('Fallback from App')
+    })
+  })
+})