acrylblends 0.3.0 → 0.4.0

package/plugins/acryl-router/src/core/helper/accepts/accepts.test.ts

@@ -0,0 +1,344 @@
+import { App } from '../../index.ts'
+import { parseAccept } from '../../utils/accept.ts'
+import type { AcceptHeader } from '../../utils/headers.ts'
+import type { Accept, acceptsConfig, acceptsOptions } from './accepts.ts'
+import { accepts, defaultMatch } from './accepts.ts'
+
+describe('parseAccept', () => {
+  test('should parse accept header', () => {
+    const acceptHeader =
+      'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8;level=1;foo=bar'
+    const accepts = parseAccept(acceptHeader)
+    expect(accepts).toEqual([
+      { type: 'text/html', params: {}, q: 1 },
+      { type: 'application/xhtml+xml', params: {}, q: 1 },
+      { type: 'image/webp', params: {}, q: 1 },
+      { type: 'application/xml', params: { q: '0.9' }, q: 0.9 },
+      { type: '*/*', params: { q: '0.8', level: '1', foo: 'bar' }, q: 0.8 },
+    ])
+  })
+})
+
+describe('defaultMatch', () => {
+  test('should return default support', () => {
+    const accepts: Accept[] = [
+      { type: 'text/html', params: {}, q: 1 },
+      { type: 'application/xhtml+xml', params: {}, q: 1 },
+      { type: 'application/xml', params: { q: '0.9' }, q: 0.9 },
+      { type: 'image/webp', params: {}, q: 1 },
+      { type: '*/*', params: { q: '0.8' }, q: 0.8 },
+    ]
+    const config: acceptsConfig = {
+      header: 'Accept',
+      supports: ['text/html'],
+      default: 'text/html',
+    }
+    const result = defaultMatch(accepts, config)
+    expect(result).toBe('text/html')
+  })
+})
+
+describe('accepts', () => {
+  test('should return matched support', () => {
+    const c = {
+      req: {
+        header: () => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/xml', 'text/html'],
+      default: 'application/json',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('text/html')
+  })
+
+  test('should return default support if no matched support', () => {
+    const c = {
+      req: {
+        header: () => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/json'],
+      default: 'text/html',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('text/html')
+  })
+
+  test('should match wildcard subtype application/*', () => {
+    const c = {
+      req: {
+        header: () => 'application/*',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/json', 'text/html'],
+      default: 'text/html',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('application/json')
+  })
+
+  test('should return default support for global wildcard */*', () => {
+    const c = {
+      req: {
+        header: () => 'text/plain, */*;q=0.5',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/json'],
+      default: 'text/html',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('text/html')
+  })
+
+  test('should return default support for single asterisk wildcard *', () => {
+    const c = {
+      req: {
+        header: () => '*',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept-Encoding',
+      supports: ['gzip', 'deflate'],
+      default: 'identity',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('identity')
+  })
+
+  test('should prefer exact match over wildcard match at same quality factor', () => {
+    const c = {
+      req: {
+        header: () => '*/*, application/json',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['text/html', 'application/json'],
+      default: 'text/html',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('application/json')
+  })
+
+  test('should match subtype wildcard while global wildcard falls through to default', () => {
+    const c = {
+      req: {
+        header: () => '*/*, text/*',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/json', 'text/plain'],
+      default: 'application/json',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('text/plain')
+  })
+
+  test('should return default support if no accept header', () => {
+    const c = {
+      req: {
+        header: () => undefined,
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/json'],
+      default: 'text/html',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('text/html')
+  })
+
+  test('should return matched support with custom match function', () => {
+    const c = {
+      req: {
+        header: () => 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    // this match function will return the least q value
+    const match = (accepts: Accept[], config: acceptsConfig) => {
+      const { supports, default: defaultSupport } = config
+      const accept = accepts
+        .sort((a, b) => a.q - b.q)
+        .find((accept) => supports.includes(accept.type))
+      return accept ? accept.type : defaultSupport
+    }
+    const options: acceptsOptions = {
+      header: 'Accept',
+      supports: ['application/xml', 'text/html'],
+      default: 'application/json',
+      match,
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('application/xml')
+  })
+
+  test('should not match entries explicitly rejected with q=0', () => {
+    const c = {
+      req: {
+        header: () => 'application/json;q=0',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/json'],
+      default: 'text/html',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('text/html')
+  })
+
+  test('should skip q=0 entries and match the remaining ones', () => {
+    const c = {
+      req: {
+        header: () => 'text/html;q=0.5, application/json;q=0',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/json'],
+      default: 'application/octet-stream',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('application/octet-stream')
+  })
+
+  test('should not match a subtype wildcard the client rejected with q=0', () => {
+    const c = {
+      req: {
+        header: () => 'application/*;q=0',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any
+    const options: acceptsConfig = {
+      header: 'Accept',
+      supports: ['application/json'],
+      default: 'text/html',
+    }
+    const result = accepts(c, options)
+    expect(result).toBe('text/html')
+  })
+
+  describe('case insensitivity', () => {
+    const pick = (header: AcceptHeader, value: string, supports: string[]) => {
+      const c = {
+        req: { header: () => value },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any
+      return accepts(c, { header, supports, default: 'DEFAULT' })
+    }
+
+    // Media types are case-insensitive (RFC 9110 §8.3.1)
+    test.each(['text/html', 'TEXT/HTML', 'Text/Html', 'text/HTML'])(
+      'Accept: %s matches text/html',
+      (value) => {
+        expect(pick('Accept', value, ['text/html'])).toBe('text/html')
+      }
+    )
+
+    test('a case-different subtype wildcard still matches', () => {
+      expect(pick('Accept', 'TEXT/*', ['text/html'])).toBe('text/html')
+    })
+
+    // Language tags are case-insensitive (RFC 4647 §2.1)
+    test.each(['en-US', 'EN-US', 'en-us', 'En-Us'])(
+      'Accept-Language: %s matches en-US',
+      (value) => {
+        expect(pick('Accept-Language', value, ['en-US'])).toBe('en-US')
+      }
+    )
+
+    test('a case-different entry with q=0 is still not acceptable', () => {
+      expect(pick('Accept-Language', 'EN;q=0', ['en'])).toBe('DEFAULT')
+    })
+  })
+})
+
+describe('Usage', () => {
+  test('decide compression by Accept-Encoding header', async () => {
+    const app = new App()
+    app.get('/compressed', async (c) => {
+      const encoding = accepts(c, {
+        header: 'Accept-Encoding',
+        supports: ['gzip', 'deflate'],
+        default: 'identity',
+      })
+      const COMPRESS_DATA = 'COMPRESS_DATA'
+      const readable = new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(COMPRESS_DATA))
+          controller.close()
+        },
+      })
+
+      if (encoding === 'gzip') {
+        c.header('Content-Encoding', 'gzip')
+        return c.body(readable.pipeThrough(new CompressionStream('gzip')))
+      }
+      if (encoding === 'deflate') {
+        c.header('Content-Encoding', 'deflate')
+        return c.body(readable.pipeThrough(new CompressionStream('deflate')))
+      }
+
+      c.body(COMPRESS_DATA)
+    })
+
+    const req1 = await app.request('/compressed', { headers: { 'Accept-Encoding': 'deflate' } })
+    const req2 = await app.request('/compressed', { headers: { 'Accept-Encoding': 'gzip' } })
+    const req3 = await app.request('/compressed', {
+      headers: { 'Accept-Encoding': 'gzip;q=0.5,deflate' },
+    })
+    const req4 = await app.request('/compressed', { headers: { 'Accept-Encoding': 'br' } })
+
+    expect(req1.headers.get('Content-Encoding')).toBe('deflate')
+    expect(req2.headers.get('Content-Encoding')).toBe('gzip')
+    expect(req3.headers.get('Content-Encoding')).toBe('deflate')
+    expect(req4.headers.get('Content-Encoding')).toBeNull()
+  })
+
+  test('decide language by Accept-Language header', async () => {
+    const app = new App()
+    const SUPPORTED_LANGS = ['en', 'ja', 'zh']
+    app.get('/*', async (c) => {
+      const lang = accepts(c, {
+        header: 'Accept-Language',
+        supports: SUPPORTED_LANGS,
+        default: 'en',
+      })
+      const isLangedPath = SUPPORTED_LANGS.some((l) => c.req.path.startsWith(`/${l}`))
+      if (isLangedPath) {
+        return c.body(`lang: ${lang}`)
+      }
+
+      return c.redirect(`/${lang}${c.req.path}`)
+    })
+
+    const req1 = await app.request('/foo', { headers: { 'Accept-Language': 'en=0.8,ja' } })
+    const req2 = await app.request('/en/foo', { headers: { 'Accept-Language': 'en' } })
+
+    expect(req1.status).toBe(302)
+    expect(req1.headers.get('Location')).toBe('/ja/foo')
+    expect(await req2.text()).toBe('lang: en')
+  })
+})

package/plugins/acryl-router/src/core/helper/accepts/accepts.ts

@@ -0,0 +1,96 @@
+import type { Context } from '../../context.ts'
+import { parseAccept } from '../../utils/accept.ts'
+import type { AcceptHeader } from '../../utils/headers.ts'
+
+export interface Accept {
+  type: string
+  params: Record<string, string>
+  q: number
+}
+
+export interface acceptsConfig {
+  header: AcceptHeader
+  supports: string[]
+  default: string
+}
+
+export interface acceptsOptions extends acceptsConfig {
+  match?: (accepts: Accept[], config: acceptsConfig) => string
+}
+
+const matchType = (acceptType: string, supportedType: string): boolean => {
+  // Media types and language tags are both case-insensitive (RFC 9110 §8.3.1,
+  // RFC 4647 §2.1), so compare them case-folded. `defaultMatch` returns the
+  // caller's own `supports` entry, so its casing is preserved.
+  const accept = acceptType.toLowerCase()
+  const supported = supportedType.toLowerCase()
+
+  if (accept === supported) {
+    return true
+  }
+  if (accept === '*/*' || accept === '*') {
+    return false
+  }
+  if (accept.endsWith('/*')) {
+    const [acceptMain] = accept.split('/')
+    const [supportedMain] = supported.split('/')
+    return acceptMain === supportedMain
+  }
+  return false
+}
+
+const getSpecificity = (type: string): number => {
+  if (type === '*/*' || type === '*') {
+    return 1
+  }
+  if (type.endsWith('/*')) {
+    return 2
+  }
+  return 3
+}
+
+export const defaultMatch = (accepts: Accept[], config: acceptsConfig): string => {
+  const { supports, default: defaultSupport } = config
+  // A quality value of 0 means "not acceptable" (RFC 9110 §12.5.1), so such
+  // entries must never match, the same rule the compress middleware applies.
+  const sortedAccepts = accepts
+    .filter((accept) => accept.q > 0)
+    .sort((a, b) => {
+      if (b.q !== a.q) {
+        return b.q - a.q
+      }
+      return getSpecificity(b.type) - getSpecificity(a.type)
+    })
+
+  for (const accept of sortedAccepts) {
+    const matched = supports.find((supported) => matchType(accept.type, supported))
+    if (matched) {
+      return matched
+    }
+  }
+  return defaultSupport
+}
+
+/**
+ * Match the accept header with the given options.
+ * @example
+ * ```ts
+ * app.get('/users', (c) => {
+ *   const lang = accepts(c, {
+ *     header: 'Accept-Language',
+ *     supports: ['en', 'zh'],
+ *     default: 'en',
+ *   })
+ * })
+ * ```
+ */
+export const accepts = (c: Context, options: acceptsOptions): string => {
+  const acceptHeader = c.req.header(options.header)
+  if (!acceptHeader) {
+    return options.default
+  }
+  const accepts = parseAccept(acceptHeader)
+  const match = options.match || defaultMatch
+
+  return match(accepts, options)
+}

package/plugins/acryl-router/src/core/helper/accepts/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @module
+ * Accepts Helper for App.
+ */
+
+export { accepts } from './accepts.ts'

package/plugins/acryl-router/src/core/helper/adapter/index.test.ts

@@ -0,0 +1,55 @@
+import { env, getRuntimeKey } from './index.ts'
+import { App } from '../../app.ts'
+
+describe('getRuntimeKey', () => {
+  it('Should return the current runtime key', () => {
+    // Now, using the `bun run test` command.
+    // But `vitest` depending Node.js will run this test so the RuntimeKey will be `node`.
+    expect(getRuntimeKey()).toBe('node')
+  })
+})
+
+describe('env', () => {
+  describe('Types', () => {
+    type Env = {
+      Bindings: {
+        MY_VAR: string
+      }
+    }
+
+    it('Should not throw type errors with env has generics', () => {
+      const app = new App()
+      app.get('/var', (c) => {
+        const { MY_VAR } = env<{ MY_VAR: string }>(c)
+        expectTypeOf<string>(MY_VAR)
+        return c.json({
+          var: MY_VAR,
+        })
+      })
+    })
+
+    it('Should not throw type errors with App has generics', () => {
+      const app = new App<Env>()
+
+      app.get('/var', (c) => {
+        const { MY_VAR } = env(c)
+        expectTypeOf<string>(MY_VAR)
+        return c.json({
+          var: MY_VAR,
+        })
+      })
+    })
+
+    it('Should not throw type errors with env and App have generics', () => {
+      const app = new App<Env>()
+
+      app.get('/var', (c) => {
+        const { MY_VAR } = env<{ MY_VAR: string }>(c)
+        expectTypeOf<string>(MY_VAR)
+        return c.json({
+          var: MY_VAR,
+        })
+      })
+    })
+  })
+})

package/plugins/acryl-router/src/core/helper/adapter/index.ts

@@ -0,0 +1,90 @@
+/**
+ * @module
+ * Adapter Helper for App.
+ */
+
+import type { Context } from '../../context.ts'
+
+export type Runtime = 'node' | 'deno' | 'bun' | 'workerd' | 'fastly' | 'edge-light' | 'other'
+
+export const env = <
+  T extends Record<string, unknown>,
+  C extends Context = Context<{
+    Bindings: T
+  }>,
+>(
+  c: T extends Record<string, unknown> ? Context : C,
+  runtime?: Runtime
+): T & C['env'] => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const global = globalThis as any
+  const globalEnv = global?.process?.env as T
+
+  runtime ??= getRuntimeKey()
+
+  const runtimeEnvHandlers: Record<string, () => T> = {
+    bun: () => globalEnv,
+    node: () => globalEnv,
+    'edge-light': () => globalEnv,
+    deno: () => {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      return Deno.env.toObject() as T
+    },
+    workerd: () => c.env,
+    // On Fastly Compute, you can use the ConfigStore to manage user-defined data.
+    fastly: () => ({}) as T,
+    other: () => ({}) as T,
+  }
+
+  return runtimeEnvHandlers[runtime]()
+}
+
+export const knownUserAgents: Partial<Record<Runtime, string>> = {
+  deno: 'Deno',
+  bun: 'Bun',
+  workerd: 'Cloudflare-Workers',
+  node: 'Node.js',
+}
+
+export const getRuntimeKey = (): Runtime => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const global = globalThis as any
+
+  // check if the current runtime supports navigator.userAgent
+  const userAgentSupported =
+    typeof navigator !== 'undefined' && typeof navigator.userAgent === 'string'
+
+  // if supported, check the user agent
+  if (userAgentSupported) {
+    for (const [runtimeKey, userAgent] of Object.entries(knownUserAgents)) {
+      if (checkUserAgentEquals(userAgent)) {
+        return runtimeKey as Runtime
+      }
+    }
+  }
+
+  // check if running on Edge Runtime
+  if (typeof global?.EdgeRuntime === 'string') {
+    return 'edge-light'
+  }
+
+  // check if running on Fastly
+  if (global?.fastly !== undefined) {
+    return 'fastly'
+  }
+
+  // userAgent isn't supported before Node v21.1.0; so fallback to the old way
+  if (global?.process?.release?.name === 'node') {
+    return 'node'
+  }
+
+  // couldn't detect the runtime
+  return 'other'
+}
+
+export const checkUserAgentEquals = (platform: string): boolean => {
+  const userAgent = navigator.userAgent
+
+  return userAgent.startsWith(platform)
+}

package/plugins/acryl-router/src/core/helper/conninfo/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @module
+ * ConnInfo Helper for App.
+ */
+
+export type { AddressType, NetAddrInfo, ConnInfo, GetConnInfo } from './types.ts'

package/plugins/acryl-router/src/core/helper/conninfo/types.ts

@@ -0,0 +1,45 @@
+import type { Context } from '../../context.ts'
+
+export type AddressType = 'IPv6' | 'IPv4' | undefined
+
+export type NetAddrInfo = {
+  /**
+   * Transport protocol type
+   */
+  transport?: 'tcp' | 'udp'
+  /**
+   * Transport port number
+   */
+  port?: number
+
+  address?: string
+  addressType?: AddressType
+} & (
+  | {
+      /**
+       * Host name such as IP Addr
+       */
+      address: string
+
+      /**
+       * Host name type
+       */
+      addressType: AddressType
+    }
+  | {}
+)
+
+/**
+ * HTTP Connection information
+ */
+export interface ConnInfo {
+  /**
+   * Remote information
+   */
+  remote: NetAddrInfo
+}
+
+/**
+ * Helper type
+ */
+export type GetConnInfo = (c: Context) => ConnInfo