acrylblends 0.2.0 → 0.4.0

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

@@ -0,0 +1,147 @@
+/**
+ * @module
+ * Method Override Middleware for App.
+ */
+
+import type { Context, ExecutionContext } from '../../context.ts'
+import type { App } from '../../app.ts'
+import type { MiddlewareHandler } from '../../types.ts'
+import { parseBody } from '../../utils/body.ts'
+
+type MethodOverrideOptions = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  app: App<any, any, any>
+} & (
+  | {
+      // Default is 'form' and the value is `_method`
+      form?: string
+      header?: never
+      query?: never
+    }
+  | {
+      form?: never
+      header: string
+      query?: never
+    }
+  | {
+      form?: never
+      header?: never
+      query: string
+    }
+)
+
+const DEFAULT_METHOD_FORM_NAME = '_method'
+
+/**
+ * Method Override Middleware for App.
+ *
+ *
+ * @param {MethodOverrideOptions} options - The options for the method override middleware.
+ * @param {App} options.app - The instance of App is used in your application.
+ * @param {string} [options.form=_method] - Form key with a value containing the method name.
+ * @param {string} [options.header] - Header name with a value containing the method name.
+ * @param {string} [options.query] - Query parameter key with a value containing the method name.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ *
+ * @example
+ * ```ts
+ * const app = new App()
+ *
+ * // If no options are specified, the value of `_method` in the form,
+ * // e.g. DELETE, is used as the method.
+ * app.use('/posts', methodOverride({ app }))
+ *
+ * app.delete('/posts', (c) => {
+ *   // ....
+ * })
+ * ```
+ */
+export const methodOverride = (options: MethodOverrideOptions): MiddlewareHandler =>
+  async function methodOverride(c, next) {
+    if (c.req.method === 'GET') {
+      return await next()
+    }
+
+    const app = options.app
+    // Method override by form
+    if (!(options.header || options.query)) {
+      const contentType = c.req.header('content-type')
+      const methodFormName = options.form || DEFAULT_METHOD_FORM_NAME
+      const clonedRequest = c.req.raw.clone()
+      const newRequest = clonedRequest.clone()
+      // Content-Type is `multipart/form-data`
+      if (contentType?.startsWith('multipart/form-data')) {
+        const form = await clonedRequest.formData()
+        const method = form.get(methodFormName)
+        if (method) {
+          const newForm = await newRequest.formData()
+          newForm.delete(methodFormName)
+          const newHeaders = new Headers(clonedRequest.headers)
+          newHeaders.delete('content-type')
+          newHeaders.delete('content-length')
+          const request = new Request(c.req.url, {
+            body: newForm,
+            headers: newHeaders,
+            method: method as string,
+          })
+          return app.fetch(request, c.env, getExecutionCtx(c))
+        }
+      }
+      // Content-Type is `application/x-www-form-urlencoded`
+      if (contentType?.startsWith('application/x-www-form-urlencoded')) {
+        const params = await parseBody<Record<string, string>>(clonedRequest)
+        const method = params[methodFormName]
+        if (method) {
+          delete params[methodFormName]
+          const newParams = new URLSearchParams(params)
+          const request = new Request(newRequest, {
+            body: newParams,
+            method: method as string,
+          })
+          return app.fetch(request, c.env, getExecutionCtx(c))
+        }
+      }
+    }
+    // Method override by header
+    else if (options.header) {
+      const headerName = options.header
+      const method = c.req.header(headerName)
+      if (method) {
+        const newHeaders = new Headers(c.req.raw.headers)
+        newHeaders.delete(headerName)
+        const request = new Request(c.req.raw, {
+          headers: newHeaders,
+          method,
+        })
+        return app.fetch(request, c.env, getExecutionCtx(c))
+      }
+    }
+    // Method override by query
+    else if (options.query) {
+      const queryName = options.query
+      const method = c.req.query(queryName)
+      if (method) {
+        const url = new URL(c.req.url)
+        url.searchParams.delete(queryName)
+        const requestInit: RequestInit & { duplex?: 'half' } = {
+          body: c.req.raw.body,
+          headers: c.req.raw.headers,
+          method,
+          duplex: c.req.raw.body ? 'half' : undefined,
+        }
+        const request = new Request(url.toString(), requestInit)
+        return app.fetch(request, c.env, getExecutionCtx(c))
+      }
+    }
+    await next()
+  }
+
+const getExecutionCtx = (c: Context) => {
+  let executionCtx: ExecutionContext | undefined
+  try {
+    executionCtx = c.executionCtx
+  } catch {
+    // Do nothing
+  }
+  return executionCtx
+}

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

@@ -0,0 +1,37 @@
+import { poweredBy } from './index.ts'
+import { App } from '../../app.ts'
+
+describe('Powered by Middleware', () => {
+  const app = new App()
+
+  app.use('/poweredBy/*', poweredBy())
+  app.get('/poweredBy', (c) => c.text('root'))
+
+  app.use('/poweredBy2/*', poweredBy())
+  app.use('/poweredBy2/*', poweredBy())
+  app.get('/poweredBy2', (c) => c.text('root'))
+
+  app.use('/poweredBy3/*', poweredBy({ serverName: 'Foo' }))
+  app.get('/poweredBy3', (c) => c.text('root'))
+
+  it('Should return with X-Powered-By header', async () => {
+    const res = await app.request('http://localhost/poweredBy')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Powered-By')).toBe('ACRYL')
+  })
+
+  it('Should not return duplicate values', async () => {
+    const res = await app.request('http://localhost/poweredBy2')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Powered-By')).toBe('ACRYL')
+  })
+
+  it('Should return custom serverName', async () => {
+    const res = await app.request('http://localhost/poweredBy3')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Powered-By')).toBe('Foo')
+  })
+})

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

@@ -0,0 +1,35 @@
+/**
+ * @module
+ * Powered By Middleware for App.
+ */
+import type { MiddlewareHandler } from '../../types.ts'
+
+type PoweredByOptions = {
+  /**
+   * The value for X-Powered-By header.
+   * @default App
+   */
+  serverName?: string
+}
+
+/**
+ * Powered By Middleware for App.
+ *
+ * @param options - The options for the Powered By Middleware.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ *
+ * @example
+ * ```ts
+ * import { poweredBy } from 'acryl-router/middleware'
+ *
+ * const app = new App()
+ *
+ * app.use(poweredBy()) // With options: poweredBy({ serverName: "My Server" })
+ * ```
+ */
+export const poweredBy = (options?: PoweredByOptions): MiddlewareHandler => {
+  return async function poweredBy(c, next) {
+    await next()
+    c.res.headers.set('X-Powered-By', options?.serverName ?? 'ACRYL')
+  }
+}

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

@@ -0,0 +1,218 @@
+import { prettyJSON } from './index.ts'
+import { App } from '../../app.ts'
+
+describe('JSON pretty by Middleware', () => {
+  it('Should return pretty JSON output', async () => {
+    const app = new App()
+    app.use('*', prettyJSON())
+    app.get('/', (c) => {
+      return c.json({ message: 'App!' })
+    })
+
+    const res = await app.request('http://localhost/?pretty')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe(`{
+  "message": "App!"
+}`)
+  })
+
+  it('Should return pretty JSON output with 4 spaces', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ space: 4 }))
+    app.get('/', (c) => {
+      return c.json({ message: 'App!' })
+    })
+
+    const res = await app.request('http://localhost/?pretty')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe(`{
+    "message": "App!"
+}`)
+  })
+
+  it('Should return pretty JSON output when middleware received custom query', async () => {
+    const targetQuery = 'format'
+
+    const app = new App()
+    app.use(
+      '*',
+      prettyJSON({
+        query: targetQuery,
+      })
+    )
+    app.get('/', (c) =>
+      c.json({
+        message: 'App!',
+      })
+    )
+
+    const prettyText = await (await app.request(`?${targetQuery}`)).text()
+    expect(prettyText).toBe(`{
+  "message": "App!"
+}`)
+    const nonPrettyText = await (await app.request('?pretty')).text()
+    expect(nonPrettyText).toBe('{"message":"App!"}')
+  })
+
+  it('Should force pretty JSON output when force option is true', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ force: true }))
+    app.get('/', (c) => {
+      return c.json({ message: 'App!' })
+    })
+
+    const resWithoutQuery = await (await app.request('http://localhost/')).text()
+    expect(resWithoutQuery).toBe(`{
+  "message": "App!"
+}`)
+
+    const resWithQuery = await (await app.request('http://localhost/?pretty')).text()
+    expect(resWithQuery).toBe(`{
+  "message": "App!"
+}`)
+  })
+
+  it('Should return pretty JSON output for structured JSON content-types (+json)', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ force: true }))
+    app.get('/problem', (c) => {
+      return c.newResponse(JSON.stringify({ type: 'about:blank', title: 'Bad Request' }), 400, {
+        'Content-Type': 'application/problem+json',
+      })
+    })
+    app.get('/jsonapi', (c) => {
+      return c.newResponse(JSON.stringify({ data: { id: '1', type: 'articles' } }), 200, {
+        'Content-Type': 'application/vnd.api+json',
+      })
+    })
+
+    const problemRes = await app.request('http://localhost/problem')
+    expect(await problemRes.text()).toBe(`{
+  "type": "about:blank",
+  "title": "Bad Request"
+}`)
+
+    const jsonApiRes = await app.request('http://localhost/jsonapi')
+    expect(await jsonApiRes.text()).toBe(`{
+  "data": {
+    "id": "1",
+    "type": "articles"
+  }
+}`)
+  })
+
+  it('Should not touch responses with non-JSON content-types', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ force: true }))
+    app.get('/text', (c) => c.text('{"message":"App!"}'))
+    app.get('/json-seq', (c) => {
+      return c.body('{"message":"App!"}', 200, {
+        'Content-Type': 'application/json-seq',
+      })
+    })
+
+    const textRes = await app.request('http://localhost/text')
+    expect(await textRes.text()).toBe('{"message":"App!"}')
+
+    const jsonSeqRes = await app.request('http://localhost/json-seq')
+    expect(await jsonSeqRes.text()).toBe('{"message":"App!"}')
+  })
+
+  it('Should not break 204 responses with a JSON content-type', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ force: true }))
+    app.delete('/x', (c) => {
+      c.header('Content-Type', 'application/json')
+      return c.body(null, 204)
+    })
+
+    const res = await app.request('http://localhost/x', { method: 'DELETE' })
+    expect(res.status).toBe(204)
+    expect(res.body).toBeNull()
+  })
+
+  it('Should not break 304 responses with a JSON content-type', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ force: true }))
+    app.get('/x', (c) => {
+      c.header('Content-Type', 'application/json')
+      return c.body(null, 304)
+    })
+
+    const res = await app.request('http://localhost/x')
+    expect(res.status).toBe(304)
+    expect(res.body).toBeNull()
+  })
+
+  it('Should not break empty responses with a JSON content-type', async () => {
+    const app = new App()
+    app.use('*', prettyJSON())
+    app.get('/x', () => new Response('', { headers: { 'Content-Type': 'application/json' } }))
+
+    const res = await app.request('http://localhost/x?pretty')
+    expect(res.status).toBe(200)
+    expect(await res.text()).toBe('')
+  })
+
+  it('Should pass through a response with an invalid JSON body unchanged', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ force: true }))
+    app.get(
+      '/x',
+      () =>
+        new Response('not json', {
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+            'X-Custom': 'custom',
+            ETag: '"abc"',
+            'Content-Length': '8',
+          },
+        })
+    )
+
+    const res = await app.request('http://localhost/x')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Custom')).toBe('custom')
+    expect(res.headers.get('ETag')).toBe('"abc"')
+    expect(res.headers.get('Content-Length')).toBe('8')
+    expect(await res.text()).toBe('not json')
+  })
+
+  it('Should pass through a response whose body was already consumed by another middleware', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ force: true }))
+    app.use('*', async (c, next) => {
+      await next()
+      await c.res.text()
+    })
+    app.get('/x', (c) => c.json({ message: 'App!' }))
+
+    // The other middleware has read the body, so the bytes are no longer available;
+    // pretty JSON must not turn this into a 500 and must leave the response as is.
+    const res = await app.request('http://localhost/x')
+    expect(res.status).toBe(200)
+    expect(res.bodyUsed).toBe(true)
+    await expect(res.text()).rejects.toThrow()
+  })
+
+  it('Should remove a stale Content-Length when the body is prettified', async () => {
+    const app = new App()
+    app.use('*', prettyJSON({ force: true }))
+    app.get(
+      '/x',
+      () =>
+        new Response('{"message":"App!"}', {
+          headers: { 'Content-Type': 'application/json', 'Content-Length': '19' },
+        })
+    )
+
+    const res = await app.request('http://localhost/x')
+    expect(await res.text()).toBe(`{
+  "message": "App!"
+}`)
+    expect(res.headers.get('Content-Length')).toBeNull()
+  })
+})

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

@@ -0,0 +1,67 @@
+/**
+ * @module
+ * Pretty JSON Middleware for App.
+ */
+
+import type { MiddlewareHandler } from '../../types.ts'
+
+interface PrettyOptions {
+  /**
+   * Number of spaces for indentation.
+   * @default 2
+   */
+  space?: number
+
+  /**
+   * Query conditions for when to Pretty.
+   * @default 'pretty'
+   */
+  query?: string
+
+  /**
+   * Force prettification of JSON responses regardless of query parameters.
+   * @default false
+   */
+  force?: boolean
+}
+
+const jsonContentTypeRegex = /^application\/(?:[a-z0-9._-]+\+)?json(?=$|[;\s])/i
+
+/**
+ * Pretty JSON Middleware for App.
+ *
+ *
+ * @param options - The options for the pretty JSON middleware.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ *
+ * @example
+ * ```ts
+ * const app = new App()
+ *
+ * app.use(prettyJSON()) // With options: prettyJSON({ space: 4 })
+ * app.get('/', (c) => {
+ *   return c.json({ message: 'App!' })
+ * })
+ * ```
+ */
+export const prettyJSON = (options?: PrettyOptions): MiddlewareHandler => {
+  const targetQuery = options?.query ?? 'pretty'
+  return async function prettyJSON(c, next) {
+    const pretty = options?.force || c.req.query(targetQuery) || c.req.query(targetQuery) === ''
+    await next()
+    const contentType = c.res.headers.get('Content-Type')
+    if (pretty && contentType && jsonContentTypeRegex.test(contentType)) {
+      // Read from a clone so that the response is kept intact when the body is not parseable as JSON
+      let obj: unknown
+      try {
+        obj = await c.res.clone().json()
+      } catch {
+        // e.g. an empty 204 response or a body that is not valid JSON
+        return
+      }
+      c.res = new Response(JSON.stringify(obj, null, options?.space ?? 2), c.res)
+      // The length of the body has changed, so remove the stale Content-Length
+      c.res.headers.delete('Content-Length')
+    }
+  }
+}

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

@@ -0,0 +1,168 @@
+import { requestId } from './index.ts'
+import type { Context } from '../../context.ts'
+import { App } from '../../app.ts'
+
+const regexUUIDv4 = /([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})/
+
+describe('Request ID Middleware', () => {
+  const app = new App()
+  app.use('*', requestId())
+  app.get('/requestId', (c) => c.text(c.get('requestId') ?? 'No Request ID'))
+
+  it('Should return random request id', async () => {
+    const res = await app.request('http://localhost/requestId')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toMatch(regexUUIDv4)
+    expect(await res.text()).match(regexUUIDv4)
+  })
+
+  it('Should return custom request id', async () => {
+    const res = await app.request('http://localhost/requestId', {
+      headers: {
+        'X-Request-Id': 'acryl-is-hot',
+      },
+    })
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toBe('acryl-is-hot')
+    expect(await res.text()).toBe('acryl-is-hot')
+  })
+
+  it('Should return custom request id with all valid characters', async () => {
+    const validRequestId = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_='
+    const res = await app.request('http://localhost/requestId', {
+      headers: {
+        'X-Request-Id': validRequestId,
+      },
+    })
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toBe(validRequestId)
+    expect(await res.text()).toBe(validRequestId)
+  })
+
+  it('Should return random request id without using request header', async () => {
+    const res = await app.request('http://localhost/requestId', {
+      headers: {
+        'X-Request-Id': 'Hello!12345-@*^',
+      },
+    })
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toMatch(regexUUIDv4)
+    expect(await res.text()).toMatch(regexUUIDv4)
+  })
+})
+
+describe('Request ID Middleware with custom generator', () => {
+  function generateWord() {
+    return 'AppIsWebFramework'
+  }
+  function generateDoubleRequestId(c: Context) {
+    const appId = c.req.header('App-Request-Id')
+    const ohnoId = c.req.header('Ohno-Request-Id')
+    if (appId && ohnoId) {
+      return appId + ohnoId
+    }
+    return crypto.randomUUID()
+  }
+  const app = new App()
+  app.use('/word', requestId({ generator: generateWord }))
+  app.use('/doubleRequestId', requestId({ generator: generateDoubleRequestId }))
+  app.get('/word', (c) => c.text(c.get('requestId') ?? 'No Request ID'))
+  app.get('/doubleRequestId', (c) => c.text(c.get('requestId') ?? 'No Request ID'))
+  it('Should return custom request id', async () => {
+    const res = await app.request('http://localhost/word')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toBe('AppIsWebFramework')
+    expect(await res.text()).toBe('AppIsWebFramework')
+  })
+
+  it('Should return complex request id', async () => {
+    const res = await app.request('http://localhost/doubleRequestId', {
+      headers: {
+        'App-Request-Id': 'Hello',
+        'Ohno-Request-Id': 'World',
+      },
+    })
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toBe('HelloWorld')
+    expect(await res.text()).toBe('HelloWorld')
+  })
+})
+
+describe('Request ID Middleware with limit length', () => {
+  const charactersOf255 = 'h'.repeat(255)
+  const charactersOf256 = 'h'.repeat(256)
+
+  const app = new App()
+  app.use('/requestId', requestId())
+  app.use('/limit256', requestId({ limitLength: 256 }))
+  app.get('/requestId', (c) => c.text(c.get('requestId') ?? 'No Request ID'))
+  app.get('/limit256', (c) => c.text(c.get('requestId') ?? 'No Request ID'))
+
+  it('Should return custom request id', async () => {
+    const res = await app.request('http://localhost/requestId', {
+      headers: {
+        'X-Request-Id': charactersOf255,
+      },
+    })
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toBe(charactersOf255)
+    expect(await res.text()).toBe(charactersOf255)
+  })
+  it('Should return random request id without using request header', async () => {
+    const res = await app.request('http://localhost/requestId', {
+      headers: {
+        'X-Request-Id': charactersOf256,
+      },
+    })
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toMatch(regexUUIDv4)
+    expect(await res.text()).toMatch(regexUUIDv4)
+  })
+  it('Should return custom request id with 256 characters', async () => {
+    const res = await app.request('http://localhost/limit256', {
+      headers: {
+        'X-Request-Id': charactersOf256,
+      },
+    })
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toBe(charactersOf256)
+    expect(await res.text()).toBe(charactersOf256)
+  })
+})
+
+describe('Request ID Middleware with custom header', () => {
+  const app = new App()
+  app.use('/requestId', requestId({ headerName: 'App-Request-Id' }))
+  app.get('/emptyId', requestId({ headerName: '' }))
+  app.get('/requestId', (c) => c.text(c.get('requestId') ?? 'No Request ID'))
+  app.get('/emptyId', (c) => c.text(c.get('requestId') ?? 'No Request ID'))
+
+  it('Should return custom request id', async () => {
+    const res = await app.request('http://localhost/requestId', {
+      headers: {
+        'App-Request-Id': 'acryl-is-hot',
+      },
+    })
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('App-Request-Id')).toBe('acryl-is-hot')
+    expect(await res.text()).toBe('acryl-is-hot')
+  })
+
+  it('Should not return request id', async () => {
+    const res = await app.request('http://localhost/emptyId')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Request-Id')).toBeNull()
+    expect(await res.text()).toMatch(regexUUIDv4)
+  })
+})

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

@@ -0,0 +1,7 @@
+import type { RequestIdVariables } from './request-id.ts'
+export type { RequestIdVariables }
+export { requestId } from './request-id.ts'
+
+declare module '../../context.ts' {
+  interface ContextVariableMap extends RequestIdVariables {}
+}