acrylblends 0.6.2 → 0.6.4

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

@@ -0,0 +1,72 @@
+import { html } from '../html/index.ts'
+import type { SSGPlugin } from './ssg.ts'
+
+/**
+ * The default plugin that defines the recommended behavior.
+ *
+ * @experimental
+ * `defaultPlugin` is an experimental feature.
+ * The API might be changed.
+ */
+export const defaultPlugin = (): SSGPlugin => {
+  return {
+    afterResponseHook: (res) => {
+      if (res.status !== 200) {
+        return false
+      }
+      return res
+    },
+  }
+}
+
+const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308])
+
+const generateRedirectHtml = (location: string) => {
+  // prettier-ignore
+  const content = html`<!DOCTYPE html>
+<title>Redirecting to: ${location}</title>
+<meta http-equiv="refresh" content="0;url=${location}" />
+<meta name="robots" content="noindex" />
+<link rel="canonical" href="${location}" />
+<body>
+<a href="${location}">Redirecting to <code>${location}</code></a>
+</body>
+`
+  return content.toString().replace(/\n/g, '')
+}
+
+/**
+ * The redirect plugin that generates HTML redirect pages for HTTP redirect responses for status codes 301, 302, 303, 307 and 308.
+ *
+ * When used with `defaultPlugin`, place `redirectPlugin` before it, because `defaultPlugin` skips non-200 responses.
+ *
+ * ```ts
+ * // ✅ Will work as expected
+ * toSSG(app, fs, { plugins: [redirectPlugin(), defaultPlugin()] })
+ *
+ * // ❌ Will not work as expected
+ * toSSG(app, fs, { plugins: [defaultPlugin(), redirectPlugin()] })
+ * ```
+ *
+ * @experimental
+ * `redirectPlugin` is an experimental feature.
+ * The API might be changed.
+ */
+export const redirectPlugin = (): SSGPlugin => {
+  return {
+    afterResponseHook: (res) => {
+      if (REDIRECT_STATUS_CODES.has(res.status)) {
+        const location = res.headers.get('Location')
+        if (!location) {
+          return false
+        }
+        const htmlBody = generateRedirectHtml(location)
+        return new Response(htmlBody, {
+          status: 200,
+          headers: { 'Content-Type': 'text/html; charset=utf-8' },
+        })
+      }
+      return res
+    },
+  }
+}

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

@@ -0,0 +1,471 @@
+import { replaceUrlParam } from '../../client/utils.ts'
+import type { Acryl } from '../../app.ts'
+import type { Env, Schema } from '../../types.ts'
+import { createPool } from '../../utils/concurrent.ts'
+import { getExtension } from '../../utils/mime.ts'
+import type { AddedSSGDataRequest, SSGParams } from './middleware.ts'
+import { SSG_CONTEXT, X_ACRYL_DISABLE_SSG_HEADER_KEY } from './middleware.ts'
+import { defaultPlugin } from './plugins.ts'
+import {
+  dirname,
+  ensureWithinOutDir,
+  filterStaticGenerateRoutes,
+  isDynamicRoute,
+  joinPaths,
+} from './utils.ts'
+
+const DEFAULT_CONCURRENCY = 2 // default concurrency for ssg
+
+// 'default_content_type' is designed according to Bun's performance optimization,
+//  which omits Content-Type by default for text responses.
+//  This is based on benchmarks showing performance gains without Content-Type.
+//  In Acryl, using `c.text()` without a Content-Type implicitly assumes 'text/plain; charset=UTF-8'.
+//  This approach maintains performance consistency across different environments.
+//  For details, see GitHub issues: oven-sh/bun#8530
+const DEFAULT_CONTENT_TYPE = 'text/plain'
+
+export const DEFAULT_OUTPUT_DIR = './static'
+
+/**
+ * @experimental
+ * `FileSystemModule` is an experimental feature.
+ * The API might be changed.
+ */
+export interface FileSystemModule {
+  writeFile(path: string, data: string | Uint8Array): Promise<void>
+  mkdir(path: string, options: { recursive: boolean }): Promise<void | string>
+}
+
+/**
+ * @experimental
+ * `ToSSGResult` is an experimental feature.
+ * The API might be changed.
+ */
+export interface ToSSGResult {
+  success: boolean
+  files: string[]
+  error?: Error
+}
+
+const generateFilePath = (
+  routePath: string,
+  outDir: string,
+  mimeType: string,
+  extensionMap?: Record<string, string>
+): string => {
+  const extension = determineExtension(mimeType, extensionMap)
+
+  let filePath: string
+  if (routePath.endsWith(`.${extension}`)) {
+    filePath = joinPaths(outDir, routePath)
+  } else if (routePath === '/') {
+    filePath = joinPaths(outDir, `index.${extension}`)
+  } else if (routePath.endsWith('/')) {
+    filePath = joinPaths(outDir, routePath, `index.${extension}`)
+  } else {
+    filePath = joinPaths(outDir, `${routePath}.${extension}`)
+  }
+
+  ensureWithinOutDir(outDir, filePath)
+
+  return filePath
+}
+
+const parseResponseContent = async (response: Response): Promise<string | ArrayBuffer> => {
+  const contentType = response.headers.get('Content-Type')
+
+  try {
+    if (contentType?.includes('text') || contentType?.includes('json')) {
+      return await response.text()
+    } else {
+      return await response.arrayBuffer()
+    }
+  } catch (error) {
+    throw new Error(
+      `Error processing response: ${error instanceof Error ? error.message : 'Unknown error'}`
+    )
+  }
+}
+
+export const defaultExtensionMap: Record<string, string> = {
+  'text/html': 'html',
+  'text/xml': 'xml',
+  'application/xml': 'xml',
+  'application/atom+xml': 'xml',
+  'application/rss+xml': 'xml',
+  'application/yaml': 'yaml',
+}
+
+const determineExtension = (
+  mimeType: string,
+  userExtensionMap?: Record<string, string>
+): string => {
+  const extensionMap = userExtensionMap || defaultExtensionMap
+  if (mimeType in extensionMap) {
+    return extensionMap[mimeType]
+  }
+  return getExtension(mimeType) || 'html'
+}
+
+export type BeforeRequestHook = (req: Request) => Request | false | Promise<Request | false>
+export type AfterResponseHook = (res: Response) => Response | false | Promise<Response | false>
+export type AfterGenerateHook = (
+  result: ToSSGResult,
+  fsModule: FileSystemModule,
+  options?: ToSSGOptions
+) => void | Promise<void>
+
+export const combineBeforeRequestHooks = (
+  hooks: BeforeRequestHook | BeforeRequestHook[]
+): BeforeRequestHook => {
+  if (!Array.isArray(hooks)) {
+    return hooks
+  }
+  return async (req: Request): Promise<Request | false> => {
+    let currentReq = req
+    for (const hook of hooks) {
+      const result = await hook(currentReq)
+      if (result === false) {
+        return false
+      }
+      if (result instanceof Request) {
+        currentReq = result
+      }
+    }
+    return currentReq
+  }
+}
+
+export const combineAfterResponseHooks = (
+  hooks: AfterResponseHook | AfterResponseHook[]
+): AfterResponseHook => {
+  if (!Array.isArray(hooks)) {
+    return hooks
+  }
+  return async (res: Response): Promise<Response | false> => {
+    let currentRes = res
+    for (const hook of hooks) {
+      const result = await hook(currentRes)
+      if (result === false) {
+        return false
+      }
+      if (result instanceof Response) {
+        currentRes = result
+      }
+    }
+    return currentRes
+  }
+}
+
+export const combineAfterGenerateHooks = (
+  hooks: AfterGenerateHook | AfterGenerateHook[],
+  fsModule: FileSystemModule,
+  options?: ToSSGOptions
+): AfterGenerateHook => {
+  if (!Array.isArray(hooks)) {
+    return hooks
+  }
+  return async (result: ToSSGResult): Promise<void> => {
+    for (const hook of hooks) {
+      await hook(result, fsModule, options)
+    }
+  }
+}
+
+export interface SSGPlugin {
+  beforeRequestHook?: BeforeRequestHook | BeforeRequestHook[]
+  afterResponseHook?: AfterResponseHook | AfterResponseHook[]
+  afterGenerateHook?: AfterGenerateHook | AfterGenerateHook[]
+}
+
+export interface ToSSGOptions {
+  dir?: string
+  /**
+   * @deprecated Use plugins[].beforeRequestHook instead.
+   */
+  beforeRequestHook?: BeforeRequestHook | BeforeRequestHook[]
+  /**
+   * @deprecated Use plugins[].afterResponseHook instead.
+   */
+  afterResponseHook?: AfterResponseHook | AfterResponseHook[]
+  /**
+   * @deprecated Use plugins[].afterGenerateHook instead.
+   */
+  afterGenerateHook?: AfterGenerateHook | AfterGenerateHook[]
+  concurrency?: number
+  extensionMap?: Record<string, string>
+  plugins?: SSGPlugin[]
+}
+
+/**
+ * @experimental
+ * `fetchRoutesContent` is an experimental feature.
+ * The API might be changed.
+ */
+export const fetchRoutesContent = function* <
+  E extends Env = Env,
+  S extends Schema = {},
+  BasePath extends string = '/',
+>(
+  app: Acryl<E, S, BasePath>,
+  beforeRequestHook?: BeforeRequestHook,
+  afterResponseHook?: AfterResponseHook,
+  concurrency?: number
+): Generator<
+  Promise<
+    | Generator<
+        Promise<{ routePath: string; mimeType: string; content: string | ArrayBuffer } | undefined>
+      >
+    | undefined
+  >
+> {
+  const baseURL = 'http://localhost'
+  const pool = createPool({ concurrency })
+
+  for (const route of filterStaticGenerateRoutes(app)) {
+    // GET Route Info
+    const thisRouteBaseURL = new URL(route.path, baseURL).toString()
+
+    let forGetInfoURLRequest = new Request(thisRouteBaseURL) as AddedSSGDataRequest
+
+    // eslint-disable-next-line no-async-promise-executor
+    yield new Promise(async (resolveGetInfo, rejectGetInfo) => {
+      try {
+        if (beforeRequestHook) {
+          const maybeRequest = await beforeRequestHook(forGetInfoURLRequest)
+          if (!maybeRequest) {
+            resolveGetInfo(undefined)
+            return
+          }
+          forGetInfoURLRequest = maybeRequest as unknown as AddedSSGDataRequest
+        }
+
+        await pool.run(() => app.fetch(forGetInfoURLRequest, { [SSG_CONTEXT]: true }))
+
+        if (!forGetInfoURLRequest.ssgParams) {
+          if (isDynamicRoute(route.path)) {
+            resolveGetInfo(undefined)
+            return
+          }
+          forGetInfoURLRequest.ssgParams = [{}]
+        }
+
+        const requestInit = {
+          method: forGetInfoURLRequest.method,
+          headers: forGetInfoURLRequest.headers,
+        }
+
+        resolveGetInfo(
+          (function* () {
+            for (const param of forGetInfoURLRequest.ssgParams as SSGParams) {
+              // eslint-disable-next-line no-async-promise-executor
+              yield new Promise(async (resolveReq, rejectReq) => {
+                try {
+                  const replacedUrlParam = replaceUrlParam(route.path, param)
+                  let response = await pool.run(() =>
+                    app.request(replacedUrlParam, requestInit, {
+                      [SSG_CONTEXT]: true,
+                    })
+                  )
+                  if (response.headers.get(X_ACRYL_DISABLE_SSG_HEADER_KEY)) {
+                    resolveReq(undefined)
+                    return
+                  }
+                  if (afterResponseHook) {
+                    const maybeResponse = await afterResponseHook(response)
+                    if (!maybeResponse) {
+                      resolveReq(undefined)
+                      return
+                    }
+                    response = maybeResponse
+                  }
+                  const mimeType =
+                    response.headers.get('Content-Type')?.split(';')[0] || DEFAULT_CONTENT_TYPE
+                  const content = await parseResponseContent(response)
+                  resolveReq({
+                    routePath: replacedUrlParam,
+                    mimeType,
+                    content,
+                  })
+                } catch (error) {
+                  rejectReq(error)
+                }
+              })
+            }
+          })()
+        )
+      } catch (error) {
+        rejectGetInfo(error)
+      }
+    })
+  }
+}
+
+/**
+ * @experimental
+ * `saveContentToFile` is an experimental feature.
+ * The API might be changed.
+ */
+const createdDirs: Set<string> = new Set()
+export const saveContentToFile = async (
+  data: Promise<{ routePath: string; content: string | ArrayBuffer; mimeType: string } | undefined>,
+  fsModule: FileSystemModule,
+  outDir: string,
+  extensionMap?: Record<string, string>
+): Promise<string | undefined> => {
+  const awaitedData = await data
+  if (!awaitedData) {
+    return
+  }
+  const { routePath, content, mimeType } = awaitedData
+  const filePath = generateFilePath(routePath, outDir, mimeType, extensionMap)
+  const dirPath = dirname(filePath)
+
+  // `dirPath` is empty when outDir itself is the current directory
+  if (dirPath !== '' && !createdDirs.has(dirPath)) {
+    await fsModule.mkdir(dirPath, { recursive: true })
+    createdDirs.add(dirPath)
+  }
+  if (typeof content === 'string') {
+    await fsModule.writeFile(filePath, content)
+  } else if (content instanceof ArrayBuffer) {
+    await fsModule.writeFile(filePath, new Uint8Array(content))
+  }
+  return filePath
+}
+
+/**
+ * @experimental
+ * `ToSSGInterface` is an experimental feature.
+ * The API might be changed.
+ */
+export interface ToSSGInterface {
+  (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    app: Acryl<any, any, any>,
+    fsModule: FileSystemModule,
+    options?: ToSSGOptions
+  ): Promise<ToSSGResult>
+}
+
+/**
+ * @experimental
+ * `ToSSGAdaptorInterface` is an experimental feature.
+ * The API might be changed.
+ */
+export interface ToSSGAdaptorInterface<
+  E extends Env = Env,
+  S extends Schema = {},
+  BasePath extends string = '/',
+> {
+  (app: Acryl<E, S, BasePath>, options?: ToSSGOptions): Promise<ToSSGResult>
+}
+
+/**
+ * @experimental
+ * `toSSG` is an experimental feature.
+ * The API might be changed.
+ */
+export const toSSG: ToSSGInterface = async (app, fs, options) => {
+  let result: ToSSGResult | undefined
+  const getInfoPromises: Promise<unknown>[] = []
+  const savePromises: Promise<string | undefined>[] = []
+  const plugins = options?.plugins || [defaultPlugin()]
+  const beforeRequestHooks: BeforeRequestHook[] = []
+  const afterResponseHooks: AfterResponseHook[] = []
+  const afterGenerateHooks: AfterGenerateHook[] = []
+  if (options?.beforeRequestHook) {
+    beforeRequestHooks.push(
+      ...(Array.isArray(options.beforeRequestHook)
+        ? options.beforeRequestHook
+        : [options.beforeRequestHook])
+    )
+  }
+  if (options?.afterResponseHook) {
+    afterResponseHooks.push(
+      ...(Array.isArray(options.afterResponseHook)
+        ? options.afterResponseHook
+        : [options.afterResponseHook])
+    )
+  }
+  if (options?.afterGenerateHook) {
+    afterGenerateHooks.push(
+      ...(Array.isArray(options.afterGenerateHook)
+        ? options.afterGenerateHook
+        : [options.afterGenerateHook])
+    )
+  }
+  for (const plugin of plugins) {
+    if (plugin.beforeRequestHook) {
+      beforeRequestHooks.push(
+        ...(Array.isArray(plugin.beforeRequestHook)
+          ? plugin.beforeRequestHook
+          : [plugin.beforeRequestHook])
+      )
+    }
+    if (plugin.afterResponseHook) {
+      afterResponseHooks.push(
+        ...(Array.isArray(plugin.afterResponseHook)
+          ? plugin.afterResponseHook
+          : [plugin.afterResponseHook])
+      )
+    }
+    if (plugin.afterGenerateHook) {
+      afterGenerateHooks.push(
+        ...(Array.isArray(plugin.afterGenerateHook)
+          ? plugin.afterGenerateHook
+          : [plugin.afterGenerateHook])
+      )
+    }
+  }
+  try {
+    const outputDir = options?.dir ?? DEFAULT_OUTPUT_DIR
+    const concurrency = options?.concurrency ?? DEFAULT_CONCURRENCY
+
+    const combinedBeforeRequestHook = combineBeforeRequestHooks(
+      beforeRequestHooks.length > 0 ? beforeRequestHooks : [(req) => req]
+    )
+    const combinedAfterResponseHook = combineAfterResponseHooks(
+      afterResponseHooks.length > 0 ? afterResponseHooks : [(req) => req]
+    )
+    const getInfoGen = fetchRoutesContent(
+      app,
+      combinedBeforeRequestHook,
+      combinedAfterResponseHook,
+      concurrency
+    )
+    for (const getInfo of getInfoGen) {
+      getInfoPromises.push(
+        getInfo.then((getContentGen) => {
+          if (!getContentGen) {
+            return
+          }
+          for (const content of getContentGen) {
+            savePromises.push(
+              saveContentToFile(content, fs, outputDir, options?.extensionMap).catch((e) => e)
+            )
+          }
+        })
+      )
+    }
+    await Promise.all(getInfoPromises)
+    const files: string[] = []
+    for (const savePromise of savePromises) {
+      const fileOrError = await savePromise
+      if (typeof fileOrError === 'string') {
+        files.push(fileOrError)
+      } else if (fileOrError) {
+        throw fileOrError
+      }
+    }
+    result = { success: true, files }
+  } catch (error) {
+    const errorObj = error instanceof Error ? error : new Error(String(error))
+    result = { success: false, files: [], error: errorObj }
+  }
+  if (afterGenerateHooks.length > 0) {
+    const combinedAfterGenerateHooks = combineAfterGenerateHooks(afterGenerateHooks, fs, options)
+    await combinedAfterGenerateHooks(result, fs, options)
+  }
+  return result
+}

package/plugins/acryl-router/src/core/helper/ssg/utils.ts

@@ -0,0 +1,118 @@
+import type { Acryl } from '../../app.ts'
+import { METHOD_NAME_ALL } from '../../router.ts'
+import type { Env, RouterRoute } from '../../types.ts'
+import { findTargetHandler, isMiddleware } from '../../utils/handler.ts'
+
+/**
+ * Get dirname
+ * @param path File Path
+ * @returns Parent dir path
+ */
+export const dirname = (path: string): string => {
+  const separatedPath = path.split(/[\/\\]/)
+  return separatedPath.slice(0, -1).join('/') // Windows supports slash path
+}
+
+const normalizePath = (path: string): string => {
+  return path.replace(/(\\)/g, '/').replace(/\/$/g, '')
+}
+
+const getUncRoot = (path: string): string | undefined => {
+  const uncRoot = path.replace(/\\/g, '/').match(/^\/\/([^/]+)\/([^/]+)/)
+  if (uncRoot) {
+    return `${uncRoot[1].toLowerCase()}/${uncRoot[2].toLowerCase()}`
+  }
+}
+
+const handleParent = (resultPaths: string[]): void => {
+  if (resultPaths.length === 0 || resultPaths[resultPaths.length - 1] === '..') {
+    resultPaths.push('..')
+  } else {
+    resultPaths.pop()
+  }
+}
+
+const handleNonDot = (path: string, resultPaths: string[]): void => {
+  path = path.replace(/^\.(?!.)/, '')
+  if (path !== '') {
+    resultPaths.push(path)
+  }
+}
+
+const handleSegments = (paths: string[], resultPaths: string[]): void => {
+  for (const path of paths) {
+    // Handle `..`
+    if (path === '..') {
+      handleParent(resultPaths)
+    } else {
+      // Handle `.` or `abc`
+      handleNonDot(path, resultPaths)
+    }
+  }
+}
+
+export const joinPaths = (...paths: string[]): string => {
+  const hasUncPrefix = getUncRoot(paths[0]) !== undefined
+  paths = paths.map(normalizePath)
+  const resultPaths: string[] = []
+  handleSegments(paths.join('/').split('/'), resultPaths)
+  return (hasUncPrefix ? '//' : paths[0][0] === '/' ? '/' : '') + resultPaths.join('/')
+}
+
+interface FilterStaticGenerateRouteData {
+  path: string
+}
+
+export const filterStaticGenerateRoutes = <E extends Env>(
+  acryl: Acryl<E>
+): FilterStaticGenerateRouteData[] => {
+  return acryl.routes.reduce((acc, { method, handler, path }: RouterRoute) => {
+    const targetHandler = findTargetHandler(handler)
+    if (['GET', METHOD_NAME_ALL].includes(method) && !isMiddleware(targetHandler)) {
+      acc.push({ path })
+    }
+    return acc
+  }, [] as FilterStaticGenerateRouteData[])
+}
+
+export const isDynamicRoute = (path: string): boolean => {
+  return path.split('/').some((segment) => segment.startsWith(':') || segment.includes('*'))
+}
+
+const toSegments = (path: string): string[] => (path === '' ? [] : path.split('/'))
+
+const getPathRoot = (path: string): string => {
+  const normalizedPath = path.replace(/\\/g, '/')
+  const uncRoot = getUncRoot(normalizedPath)
+  if (uncRoot) {
+    return `unc:${uncRoot}`
+  }
+
+  const driveRoot = normalizedPath.match(/^([A-Za-z]):/)
+  if (driveRoot) {
+    const kind = normalizedPath[2] === '/' ? 'drive-absolute' : 'drive-relative'
+    return `${kind}:${driveRoot[1].toLowerCase()}`
+  }
+
+  return normalizedPath.startsWith('/') ? 'absolute' : 'relative'
+}
+
+export const ensureWithinOutDir = (outDir: string, filePath: string): void => {
+  const outDirSegments = toSegments(joinPaths(outDir))
+  const filePathSegments = toSegments(joinPaths(filePath))
+
+  const hasMismatchedPathRoot = getPathRoot(outDir) !== getPathRoot(filePath)
+
+  // `joinPaths` collects every remaining `..` at the head, so a `..` right after
+  // the outDir segments means the file path climbs above outDir
+  const climbsAboveOutDir = filePathSegments[outDirSegments.length] === '..'
+
+  if (
+    hasMismatchedPathRoot ||
+    filePathSegments.length <= outDirSegments.length ||
+    !outDirSegments.every((segment, i) => segment === filePathSegments[i]) ||
+    climbsAboveOutDir
+  ) {
+    throw new Error(`Path traversal detected: "${filePath}" is outside the output directory`)
+  }
+}