acrylblends 0.3.0 → 0.4.1

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

@@ -0,0 +1,70 @@
+import type { HTTPExceptionFunction } from './index.ts'
+import { timeout } from './index.ts'
+import type { Context } from '../../context.ts'
+import { App } from '../../app.ts'
+import { HTTPException } from '../../http-exception.ts'
+
+describe('Timeout API', () => {
+  const app = new App()
+
+  app.use('/slow-endpoint', timeout(1000))
+  app.use(
+    '/slow-endpoint/custom',
+    timeout(
+      1100,
+      () => new HTTPException(408, { message: 'Request timeout. Please try again later.' })
+    )
+  )
+  const exception500: HTTPExceptionFunction = (context: Context) =>
+    new HTTPException(500, { message: `Internal Server Error at ${context.req.path}` })
+  app.use('/slow-endpoint/error', timeout(1200, exception500))
+  app.use('/normal-endpoint', timeout(1000))
+
+  app.get('/slow-endpoint', async (c) => {
+    await new Promise((resolve) => setTimeout(resolve, 1100))
+    return c.text('This should not show up')
+  })
+
+  app.get('/slow-endpoint/custom', async (c) => {
+    await new Promise((resolve) => setTimeout(resolve, 1200))
+    return c.text('This should not show up')
+  })
+
+  app.get('/slow-endpoint/error', async (c) => {
+    await new Promise((resolve) => setTimeout(resolve, 1300))
+    return c.text('This should not show up')
+  })
+
+  app.get('/normal-endpoint', async (c) => {
+    await new Promise((resolve) => setTimeout(resolve, 900))
+    return c.text('This should not show up')
+  })
+
+  it('Should trigger default timeout exception', async () => {
+    const res = await app.request('http://localhost/slow-endpoint')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(504)
+    expect(await res.text()).toContain('Gateway Timeout')
+  })
+
+  it('Should apply custom exception with function', async () => {
+    const res = await app.request('http://localhost/slow-endpoint/custom')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(408)
+    expect(await res.text()).toContain('Request timeout. Please try again later.')
+  })
+
+  it('Error timeout with custom status code and message', async () => {
+    const res = await app.request('http://localhost/slow-endpoint/error')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(500)
+    expect(await res.text()).toContain('Internal Server Error at /slow-endpoint/error')
+  })
+
+  it('No Timeout should pass', async () => {
+    const res = await app.request('http://localhost/normal-endpoint')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(await res.text()).toContain('This should not show up')
+  })
+})

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

@@ -0,0 +1,58 @@
+/**
+ * @module
+ * Timeout Middleware for App.
+ */
+
+import type { Context } from '../../context.ts'
+import { HTTPException } from '../../http-exception.ts'
+import type { MiddlewareHandler } from '../../types.ts'
+
+export type HTTPExceptionFunction = (context: Context) => HTTPException
+
+const defaultTimeoutException = new HTTPException(504, {
+  message: 'Gateway Timeout',
+})
+
+/**
+ * Timeout Middleware for App.
+ *
+ * @param {number} duration - The timeout duration in milliseconds.
+ * @param {HTTPExceptionFunction | HTTPException} [exception=defaultTimeoutException] - The exception to throw when the timeout occurs. Can be a function that returns an HTTPException or an HTTPException object.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ *
+ * @example
+ * ```ts
+ * const app = new App()
+ *
+ * app.use(
+ *   '/long-request',
+ *   timeout(5000) // Set timeout to 5 seconds
+ * )
+ *
+ * app.get('/long-request', async (c) => {
+ *   await someLongRunningFunction()
+ *   return c.text('Completed within time limit')
+ * })
+ * ```
+ */
+export const timeout = (
+  duration: number,
+  exception: HTTPExceptionFunction | HTTPException = defaultTimeoutException
+): MiddlewareHandler => {
+  return async function timeout(context, next) {
+    let timer: number | undefined
+    const timeoutPromise = new Promise<void>((_, reject) => {
+      timer = setTimeout(() => {
+        reject(typeof exception === 'function' ? exception(context) : exception)
+      }, duration) as unknown as number
+    })
+
+    try {
+      await Promise.race([next(), timeoutPromise])
+    } finally {
+      if (timer !== undefined) {
+        clearTimeout(timer)
+      }
+    }
+  }
+}

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

@@ -0,0 +1,310 @@
+import { endTime, setMetric, startTime, timing, wrapTime } from './index.ts'
+import { App } from '../../app.ts'
+
+describe('Server-Timing API', () => {
+  const app = new App()
+
+  const totalDescription = 'my total DescRipTion!'
+  const name = 'sleep'
+  const region = 'region'
+  const regionDesc = 'europe-west3'
+
+  app.use(
+    '*',
+    timing({
+      totalDescription,
+    })
+  )
+  app.get('/', (c) => c.text('/'))
+  app.get('/api', async (c) => {
+    startTime(c, name)
+    await new Promise((r) => setTimeout(r, 30))
+    endTime(c, name)
+
+    return c.text('api!')
+  })
+  app.get('/api-wrap', async (c) => {
+    await wrapTime(c, name, new Promise((r) => setTimeout(r, 30)))
+
+    return c.text('api!')
+  })
+  app.get('/api-wrap-throw', async (c) => {
+    try {
+      await wrapTime(c, name, new Promise((_, r) => setTimeout(r, 30)))
+    } catch (e) {
+      return c.text(`error :( ${e}`, 500)
+    }
+
+    return c.text('api!')
+  })
+  app.get('/cache', async (c) => {
+    setMetric(c, region, regionDesc)
+
+    return c.text('cache!')
+  })
+
+  const sub = new App()
+
+  sub.use(timing())
+  sub.get('/', (c) => c.text('sub'))
+  app.route('/sub', sub)
+
+  it('Should contain total duration', async () => {
+    const res = await app.request('http://localhost/')
+    expect(res).not.toBeNull()
+    expect(res.headers.has('server-timing')).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes('total;dur=')).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(totalDescription)).toBeTruthy()
+  })
+
+  it('Should contain value metrics', async () => {
+    const res = await app.request('http://localhost/api')
+    expect(res).not.toBeNull()
+    expect(res.headers.has('server-timing')).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(`${name};dur=`)).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(name)).toBeTruthy()
+  })
+
+  it('Should contain value metrics, wrapped', async () => {
+    const res = await app.request('http://localhost/api-wrap')
+    expect(res).not.toBeNull()
+    expect(res.headers.has('server-timing')).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(`${name};dur=`)).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(name)).toBeTruthy()
+  })
+
+  it('Should contain value metrics, wrapped throw', async () => {
+    const res = await app.request('http://localhost/api-wrap-throw')
+    expect(res).not.toBeNull()
+    expect(res.headers.has('server-timing')).toBeTruthy()
+    expect(res.status).toBeGreaterThanOrEqual(500)
+    expect(res.headers.get('server-timing')?.includes(`${name};dur=`)).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(name)).toBeTruthy()
+  })
+
+  it('Should contain value-less metrics', async () => {
+    const res = await app.request('http://localhost/cache')
+    expect(res).not.toBeNull()
+    expect(res.headers.has('server-timing')).toBeTruthy()
+    expect(
+      res.headers.get('server-timing')?.includes(`${region};desc="${regionDesc}"`)
+    ).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(region)).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(regionDesc)).toBeTruthy()
+  })
+
+  it('Should not be enabled if the main app has the timing middleware', async () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn')
+    const res = await app.request('/sub')
+    expect(res.status).toBe(200)
+    expect(res.headers.has('server-timing')).toBeTruthy()
+    expect(res.headers.get('server-timing')?.includes(totalDescription)).toBeTruthy()
+    expect(consoleWarnSpy).not.toHaveBeenCalled()
+    consoleWarnSpy.mockRestore()
+  })
+
+  describe('Should handle timing options', async () => {
+    it('Should handle autoEnd option', async () => {
+      const autoEndApp = new App()
+
+      autoEndApp.use('*', timing())
+      autoEndApp.get('/', (c) => {
+        startTime(c, 'test')
+        return c.text('/')
+      })
+
+      const res = await autoEndApp.request('/')
+
+      expect(res.status).toBe(200)
+      expect(res.headers.get('server-timing')).toContain('test;dur=')
+
+      const disabledAutoEndApp = new App()
+
+      disabledAutoEndApp.use('*', timing({ autoEnd: false }))
+      disabledAutoEndApp.get('/', (c) => {
+        startTime(c, 'test')
+        return c.text('/')
+      })
+
+      const disabledRes = await disabledAutoEndApp.request('/')
+
+      expect(disabledRes.status).toBe(200)
+      expect(disabledRes.headers.get('server-timing')).not.toContain('test;dur=')
+    })
+
+    it('Should use enabled function return value', async () => {
+      const enabledApp = new App()
+      const enabled = vi.fn(() => false)
+
+      enabledApp.use('*', timing({ enabled }))
+      enabledApp.get('/', (c) => c.text('/'))
+
+      const res = await enabledApp.request('/')
+
+      expect(res.status).toBe(200)
+      expect(enabled).toHaveBeenCalled()
+      expect(res.headers.has('server-timing')).toBeFalsy()
+    })
+
+    it('Should handle total false and value-less metrics without description', async () => {
+      const metricApp = new App()
+
+      metricApp.use('*', timing({ total: false }))
+      metricApp.get('/', (c) => {
+        setMetric(c, 'test')
+        return c.text('/')
+      })
+
+      const res = await metricApp.request('/')
+
+      expect(res.status).toBe(200)
+      expect(res.headers.get('server-timing')).toBe('test')
+    })
+  })
+
+  describe('Should handle crossOrigin setting', async () => {
+    it('Should do nothing when crossOrigin is falsy', async () => {
+      const crossOriginApp = new App()
+
+      crossOriginApp.use(
+        '*',
+        timing({
+          crossOrigin: false,
+        })
+      )
+
+      crossOriginApp.get('/', (c) => c.text('/'))
+
+      const res = await crossOriginApp.request('http://localhost/')
+
+      expect(res).not.toBeNull()
+      expect(res.headers.has('server-timing')).toBeTruthy()
+      expect(res.headers.has('timing-allow-origin')).toBeFalsy()
+    })
+
+    it('Should set Timing-Allow-Origin to * when crossOrigin is true', async () => {
+      const crossOriginApp = new App()
+
+      crossOriginApp.use(
+        '*',
+        timing({
+          crossOrigin: true,
+        })
+      )
+
+      crossOriginApp.get('/', (c) => c.text('/'))
+
+      const res = await crossOriginApp.request('http://localhost/')
+
+      expect(res).not.toBeNull()
+      expect(res.headers.has('server-timing')).toBeTruthy()
+      expect(res.headers.has('timing-allow-origin')).toBeTruthy()
+      expect(res.headers.get('timing-allow-origin')).toBe('*')
+    })
+
+    it('Should set Timing-Allow-Origin to the value of crossOrigin when it is a string', async () => {
+      const crossOriginApp = new App()
+
+      crossOriginApp.use(
+        '*',
+        timing({
+          crossOrigin: 'https://example.com',
+        })
+      )
+
+      crossOriginApp.get('/', (c) => c.text('/'))
+
+      const res = await crossOriginApp.request('http://localhost/')
+
+      expect(res).not.toBeNull()
+      expect(res.headers.has('server-timing')).toBeTruthy()
+      expect(res.headers.has('timing-allow-origin')).toBeTruthy()
+      expect(res.headers.get('timing-allow-origin')).toBe('https://example.com')
+    })
+
+    it('Should set Timing-Allow-Origin to the return value of crossOrigin when it is a function', async () => {
+      const crossOriginApp = new App()
+
+      crossOriginApp.use(
+        '*',
+        timing({
+          crossOrigin: (c) => c.req.header('origin') ?? '*',
+        })
+      )
+
+      crossOriginApp.get('/', (c) => c.text('/'))
+
+      const res = await crossOriginApp.request('http://localhost/', {
+        headers: {
+          origin: 'https://example.com',
+        },
+      })
+
+      expect(res).not.toBeNull()
+      expect(res.headers.has('server-timing')).toBeTruthy()
+      expect(res.headers.has('timing-allow-origin')).toBeTruthy()
+      expect(res.headers.get('timing-allow-origin')).toBe('https://example.com')
+    })
+
+    it("Should use Date.now as backup if performance API isn't available", async () => {
+      const originalPerformance = globalThis.performance
+      // @ts-expect-error disable performance API for testing
+      delete globalThis.performance
+      const DateNowSpy = vi.spyOn(Date, 'now').mockReturnValue(123456789)
+
+      const app = new App().use(timing()).get('/', (c) => {
+        startTime(c, 'test')
+        endTime(c, 'test')
+        return c.text('hello')
+      })
+
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+
+      expect(DateNowSpy).toHaveBeenCalled()
+
+      DateNowSpy.mockRestore()
+      globalThis.performance = originalPerformance
+    })
+  })
+
+  describe('Configuration validation', async () => {
+    it('Should silently warn when no timing metrics are available', async () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      const app = new App().get('/', (c) => {
+        setMetric(c, 'test', 123)
+        startTime(c, 'test')
+        endTime(c, 'test')
+        return c.text('hello')
+      })
+
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+
+      expect(consoleWarnSpy).toHaveBeenNthCalledWith(
+        2,
+        'Metrics not initialized! Please add the `timing()` middleware to this route!'
+      )
+
+      consoleWarnSpy.mockRestore()
+    })
+
+    it('Should silently warn when trying to end a non-existent timer', async () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      const app = new App().use(timing()).get('/', (c) => {
+        setMetric(c, 'region', 'europe-west3')
+        endTime(c, 'nonExistentTimer')
+        return c.text('hello')
+      })
+
+      const res = await app.request('/')
+      expect(res.status).toBe(200)
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith('Timer "nonExistentTimer" does not exist!')
+
+      consoleWarnSpy.mockRestore()
+    })
+  })
+})

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

@@ -0,0 +1,8 @@
+import type { TimingVariables } from './timing.ts'
+
+export type { TimingVariables }
+export { timing, setMetric, startTime, endTime, wrapTime } from './timing.ts'
+
+declare module '../../context.ts' {
+  interface ContextVariableMap extends TimingVariables {}
+}

package/plugins/acryl-router/src/core/middleware/timing/timing.ts

@@ -0,0 +1,256 @@
+/**
+ * @module
+ * Server-Timing Middleware for App.
+ */
+
+import type { Context } from '../../context.ts'
+import type { MiddlewareHandler } from '../../types.ts'
+import '../../context.ts'
+
+export type TimingVariables = {
+  metric?: {
+    headers: string[]
+    timers: Map<string, Timer>
+  }
+}
+
+interface Timer {
+  description?: string
+  start: number
+}
+
+interface TimingOptions {
+  total?: boolean
+  enabled?: boolean | ((c: Context) => boolean)
+  totalDescription?: string
+  autoEnd?: boolean
+  crossOrigin?: boolean | string | ((c: Context) => boolean | string)
+}
+
+const getTime = (): number => {
+  try {
+    return performance.now()
+  } catch {}
+  return Date.now()
+}
+
+/**
+ * Server-Timing Middleware for App.
+ *
+ *
+ * @param {TimingOptions} [config] - The options for the timing middleware.
+ * @param {boolean} [config.total=true] - Show the total response time.
+ * @param {boolean | ((c: Context) => boolean)} [config.enabled=true] - Whether timings should be added to the headers or not.
+ * @param {string} [config.totalDescription=Total Response Time] - Description for the total response time.
+ * @param {boolean} [config.autoEnd=true] - If `startTime()` should end automatically at the end of the request.
+ * @param {boolean | string | ((c: Context) => boolean | string)} [config.crossOrigin=false] - The origin this timings header should be readable.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ *
+ * @example
+ * ```ts
+ * const app = new App()
+ *
+ * // add the middleware to your router
+ * app.use(timing());
+ *
+ * app.get('/', async (c) => {
+ *   // add custom metrics
+ *   setMetric(c, 'region', 'europe-west3')
+ *
+ *   // add custom metrics with timing, must be in milliseconds
+ *   setMetric(c, 'custom', 23.8, 'My custom Metric')
+ *
+ *   // start a new timer
+ *   startTime(c, 'db');
+ *
+ *   const data = await db.findMany(...);
+ *
+ *   // end the timer
+ *   endTime(c, 'db');
+ *
+ *   return c.json({ response: data });
+ * });
+ * ```
+ */
+export const timing = (config?: TimingOptions): MiddlewareHandler => {
+  const options: TimingOptions = {
+    total: true,
+    enabled: true,
+    totalDescription: 'Total Response Time',
+    autoEnd: true,
+    crossOrigin: false,
+    ...config,
+  }
+  return async function timing(c, next) {
+    const headers: string[] = []
+    const timers = new Map<string, Timer>()
+
+    if (c.get('metric')) {
+      return await next()
+    }
+
+    c.set('metric', { headers, timers })
+
+    if (options.total) {
+      startTime(c, 'total', options.totalDescription)
+    }
+    await next()
+
+    if (options.total) {
+      endTime(c, 'total')
+    }
+
+    if (options.autoEnd) {
+      timers.forEach((_, key) => {
+        endTime(c, key)
+      })
+    }
+
+    const enabled = typeof options.enabled === 'function' ? options.enabled(c) : options.enabled
+
+    if (enabled) {
+      c.res.headers.append('Server-Timing', headers.join(','))
+
+      const crossOrigin =
+        typeof options.crossOrigin === 'function' ? options.crossOrigin(c) : options.crossOrigin
+
+      if (crossOrigin) {
+        c.res.headers.append(
+          'Timing-Allow-Origin',
+          typeof crossOrigin === 'string' ? crossOrigin : '*'
+        )
+      }
+    }
+  }
+}
+
+interface SetMetric {
+  (c: Context, name: string, value: number, description?: string, precision?: number): void
+
+  (c: Context, name: string, description?: string): void
+}
+
+/**
+ * Set a metric for the timing middleware.
+ *
+ * @param {Context} c - The context of the request.
+ * @param {string} name - The name of the metric.
+ * @param {number | string} [valueDescription] - The value or description of the metric.
+ * @param {string} [description] - The description of the metric.
+ * @param {number} [precision] - The precision of the metric value.
+ *
+ * @example
+ * ```ts
+ * setMetric(c, 'region', 'europe-west3')
+ * setMetric(c, 'custom', 23.8, 'My custom Metric')
+ * ```
+ */
+export const setMetric: SetMetric = (
+  c: Context,
+  name: string,
+  valueDescription: number | string | undefined,
+  description?: string,
+  precision?: number
+) => {
+  const metrics = c.get('metric')
+  if (!metrics) {
+    console.warn('Metrics not initialized! Please add the `timing()` middleware to this route!')
+    return
+  }
+  if (typeof valueDescription === 'number') {
+    const dur = valueDescription.toFixed(precision || 1)
+
+    const metric = description ? `${name};dur=${dur};desc="${description}"` : `${name};dur=${dur}`
+
+    metrics.headers.push(metric)
+  } else {
+    // Value-less metric
+    const metric = valueDescription ? `${name};desc="${valueDescription}"` : `${name}`
+
+    metrics.headers.push(metric)
+  }
+}
+
+/**
+ * Start a timer for the timing middleware.
+ *
+ * @param {Context} c - The context of the request.
+ * @param {string} name - The name of the timer.
+ * @param {string} [description] - The description of the timer.
+ *
+ * @example
+ * ```ts
+ * startTime(c, 'db')
+ * ```
+ */
+export const startTime = (c: Context, name: string, description?: string) => {
+  const metrics = c.get('metric')
+  if (!metrics) {
+    console.warn('Metrics not initialized! Please add the `timing()` middleware to this route!')
+    return
+  }
+  metrics.timers.set(name, { description, start: getTime() })
+}
+
+/**
+ * End a timer for the timing middleware.
+ *
+ * @param {Context} c - The context of the request.
+ * @param {string} name - The name of the timer.
+ * @param {number} [precision] - The precision of the timer value.
+ *
+ * @example
+ * ```ts
+ * endTime(c, 'db')
+ * ```
+ */
+export const endTime = (c: Context, name: string, precision?: number) => {
+  const metrics = c.get('metric')
+  if (!metrics) {
+    console.warn('Metrics not initialized! Please add the `timing()` middleware to this route!')
+    return
+  }
+  const timer = metrics.timers.get(name)
+  if (!timer) {
+    console.warn(`Timer "${name}" does not exist!`)
+    return
+  }
+  const { description, start } = timer
+
+  const duration = getTime() - start
+
+  setMetric(c, name, duration, description, precision)
+  metrics.timers.delete(name)
+}
+
+/**
+ * Wrap a Promise to capture its duration.
+ * @param {Context} c - The context of the request.
+ * @param {string} name - The name of the timer.
+ * @param {Promise<T>} callable - The Promise to time.
+ * @param {string} [description] - The description of the timer.
+ * @param {number} [precision] - The precision of the timer value.
+ *
+ * @example
+ * ```ts
+ *   // Instead of this:
+ *   const data = await db.findMany(...);
+ *
+ *   // do this:
+ *   const data = await wrapTime(c, 'query', db.findMany(...));
+ * ```
+ * */
+export async function wrapTime<T>(
+  c: Context,
+  name: string,
+  callable: Promise<T>,
+  description?: string,
+  precision?: number
+): Promise<T> {
+  startTime(c, name, description)
+  try {
+    return await callable
+  } finally {
+    endTime(c, name, precision)
+  }
+}