galbe 0.15.6 → 0.16.0

package/src/router.ts

@@ -13,51 +13,41 @@ const normalizePath = (path: string) => (path.length > 1 ? path.replace(/\/+$/g,
 
 const DEFAULT_CACHE_LIMIT = 1024
 
-const walk = (path: string[], node: RouteNode, index: number = 0): RouteNode => {
+const walk = (path: string[], node: RouteNode, index: number = 0): RouteNode | null => {
   if (index === path.length - 1) {
     if (node.routes && !!Object.keys(node.routes).length) return node
     // /a/* should match /a — fall back to a wildcard child if the node has no
     // routes of its own.
     const wc = node.children?.['*']
     if (wc?.routes && !!Object.keys(wc.routes).length) return wc
-    throw new NotFoundError()
+    return null
   }
 
   const nextSegment = path[index + 1]
 
   // 1. Exact Match
   if (node.children && nextSegment !== undefined && nextSegment in node.children) {
-    try {
-      return walk(path, node.children[nextSegment]!, index + 1)
-    } catch (error) {
-      if (!(error instanceof NotFoundError)) throw error
-    }
+    const r = walk(path, node.children[nextSegment]!, index + 1)
+    if (r) return r
   }
 
   // 2. Param Match
   if (node.param) {
-    try {
-      return walk(path, node.param, index + 1)
-    } catch (error) {
-      if (!(error instanceof NotFoundError)) throw error
-    }
+    const r = walk(path, node.param, index + 1)
+    if (r) return r
   }
 
   // 3. Wildcard Match
   if (node.children && '*' in node.children) {
-    try {
-      return walk(path, node.children['*'], index + 1)
-    } catch (error) {
-      if (error instanceof NotFoundError) {
-        if (node.children['*'].routes && !!Object.keys(node.children['*'].routes).length) {
-          return node.children['*']
-        }
-      }
-      if (!(error instanceof NotFoundError)) throw error
-    }
+    const wc = node.children['*']
+    const r = walk(path, wc, index + 1)
+    if (r) return r
+    // a wildcard with routes of its own swallows the remaining segments:
+    // /a/* answers /a/b/c once the deeper walk found nothing
+    if (wc.routes && !!Object.keys(wc.routes).length) return wc
   }
 
-  throw new NotFoundError()
+  return null
 }
 
 export class GalbeRouter {
@@ -66,7 +56,15 @@ export class GalbeRouter {
   cacheEnabled: boolean
   cacheLimit: number
   cachedRoutes: Map<string, Route | null>
-  constructor(options?: { prefix?: string; cacheEnabled?: boolean; cacheLimit?: number }) {
+  // registration-conflict warnings; injectable so tests can observe them. The
+  // console.warn default is silenced in production, an injected hook is not.
+  warn: (message: string) => void
+  constructor(options?: {
+    prefix?: string
+    cacheEnabled?: boolean
+    cacheLimit?: number
+    warn?: (message: string) => void
+  }) {
     this.routes = { routes: {} }
     let prefix = options?.prefix || ''
     if (prefix && !prefix.match(/^\//)) prefix = `/${prefix}`
@@ -74,6 +72,7 @@ export class GalbeRouter {
     this.cachedRoutes = new Map()
     this.cacheEnabled = options?.cacheEnabled ?? false
     this.cacheLimit = options?.cacheLimit ?? DEFAULT_CACHE_LIMIT
+    this.warn = options?.warn ?? (message => Bun.env.BUN_ENV !== 'production' && console.warn(message))
   }
   // bounded LRU: gets refresh recency, sets evict the oldest entry once past
   // cacheLimit, so a flood of distinct lookups (including cached misses) can't
@@ -100,33 +99,48 @@ export class GalbeRouter {
     let path = route.path.replace(/^\/+|\/+$/g, '').split('/')
     if (path[0] === '') path.shift()
     let r = this.routes
-    if (!path.length) {
-      r.routes[route.method] = route
-    } else {
-      while (path.length) {
-        let p = path.shift()
-        if (p === undefined) break
-        if (!path.length) {
-          if (p.match(/^:/)) {
-            if (!r.param) r.param = { routes: {} }
-            r.param.routes[route.method] = route
-          } else {
-            if (!r.children) r.children = newChildren()
-            if (!(p in r.children)) r.children[p] = { routes: {} }
-            r.children[p]!.routes[route.method] = route
-          }
-        } else {
-          if (p.match(/^:/)) {
-            if (!r.param) r.param = { routes: {} }
-            r = r.param
-          } else {
-            if (!r.children) r.children = newChildren()
-            if (!(p in r.children)) r.children[p] = { routes: {} }
-            r = r.children[p]!
-          }
-        }
+    let walked = ''
+    while (path.length) {
+      let p = path.shift()
+      if (p === undefined) break
+      if (p.match(/^:/)) {
+        // params sharing a trie node keep the first registered name: a later
+        // registration with a different name lands on the same node
+        if (!r.param) r.param = { routes: {}, paramName: p.slice(1) }
+        else if (r.param.paramName !== p.slice(1))
+          this.warn(
+            `${walked}/${p} collides with ${walked}/:${r.param.paramName} — param routes share one trie node regardless of name`
+          )
+        r = r.param
+      } else {
+        if (!r.children) r.children = newChildren()
+        if (!(p in r.children)) r.children[p] = { routes: {} }
+        r = r.children[p]!
       }
+      walked += `/${p}`
+    }
+    if (r.routes[route.method])
+      this.warn(`route ${route.method.toUpperCase()} ${route.path} redefined — previous registration overwritten`)
+    r.routes[route.method] = route
+  }
+  /**
+   * Unregister a route. Identity-checked: the node's entry is only deleted when
+   * it still holds this exact route object, so removing a route that was since
+   * redefined leaves the newer registration in place.
+   */
+  remove(route: Route): boolean {
+    let path = route.path.replace(/^\/+|\/+$/g, '').split('/')
+    if (path[0] === '') path.shift()
+    let r: RouteNode | undefined = this.routes
+    for (const p of path) {
+      if (p === '') break
+      r = p.match(/^:/) ? r.param : r.children?.[p]
+      if (!r) return false
     }
+    if (r.routes[route.method] !== route) return false
+    delete r.routes[route.method]
+    for (const [key, cached] of this.cachedRoutes) if (cached === route) this.cachedRoutes.delete(key)
+    return true
   }
   find(method: Method, path: string): Route {
     path = normalizePath(path)
@@ -138,8 +152,17 @@ export class GalbeRouter {
     if (!r || !Object.keys(r.routes).length) {
       if (this.cacheEnabled) this.cacheSet(`[${method}]${path}`, null)
       throw new NotFoundError()
-    } else if (!(method in r.routes)) throw new MethodNotAllowedError()
-    const route = r.routes[method] as Route
+    }
+    // RFC 9110 §9.3.3: HEAD is GET without a body. An explicit head route wins;
+    // otherwise fall back to the get route (the server strips the response body).
+    const route = (r.routes[method] ?? (method === 'head' ? r.routes.get : undefined)) as Route | undefined
+    if (!route) {
+      // RFC 9110 §15.5.6: a 405 must carry an Allow header listing the methods
+      // the resource supports; HEAD is implicitly allowed whenever GET is.
+      const allow = Object.keys(r.routes).map(m => m.toUpperCase())
+      if ('get' in r.routes && !('head' in r.routes)) allow.push('HEAD')
+      throw new MethodNotAllowedError(undefined, { allow: allow.join(', ') })
+    }
     if (this.cacheEnabled) this.cacheSet(`[${method}]${path}`, route)
     return route
   }

package/src/routes.ts

@@ -1,19 +1,30 @@
-import type { GalbeConfig, GalbePlugin, Method, Route } from './types'
+import type { GalbeConfig, Method, MiddlewareDef, Route } from './types'
 
 import { readdir, lstat } from 'fs/promises'
-import { extname } from 'path'
+import { extname, dirname, relative, resolve, sep } from 'path'
 import { parse } from 'acorn'
 import { simple } from 'acorn-walk'
-import { Galbe } from './index'
-import { transformSync } from '@swc/core'
+import { Galbe, GalbeGroup } from './index'
+import { joinPath } from './util'
+import { transformSync } from '@swc/wasm'
 import { Glob } from 'bun'
 
 export const DEFAULT_ROUTE_PATTERN = 'src/**/*.route.{js,ts}'
+export const DEFAULT_MIDDLEWARE_PATTERN = 'src/**/*.middleware.{js,ts}'
 
 const IGNORE_COMMENT_RGX = /^\s*\@galbe-ignore\s*$/
 const HIDE_COMMENT_RGX = /^\s*\@galbe-hide\s*$/
+const ROUTE_PATH_RGX = /^(\/(\*|:?\d+|:?\w+|:?[\w\d.][\w-.]+[\w\d]))*\/?$/
+// literal route segment: the router's segment rules minus ':param' and '*'
+const LITERAL_SEGMENT_RGX = /^(\d+|\w+|[\w\d.][\w-.]+[\w\d])$/
+const ROUTE_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'static'])
+/** directories that never hold app source — neither scanned nor watched */
+export const NEVER_SCANNED_DIRS = ['node_modules', '.git']
 
-export type RouteMeta = { head?: string, ignore?: boolean, hide?: boolean } & Record<string, boolean | string | string[]>
+export type RouteMeta = { head?: string; ignore?: boolean; hide?: boolean } & Record<
+  string,
+  boolean | string | string[]
+>
 export type RoutesMeta = {
   header: Record<string, boolean | string | string[]>
   routes: Record<string, Partial<Record<Method | 'static', RouteMeta>>>
@@ -30,93 +41,14 @@ export type RouteInstanciationCallback = <T extends 'add' | 'error'>(event: {
 export type RouteFileMeta = {
   file: string
 } & RoutesMeta
-
-export class GalbeProxy {
-  #g: Galbe
-  #plugins: GalbePlugin[] = []
-  _cb?: RouteInstanciationCallback
-  _metaTmp?: RoutesMeta
-  _filepath?: string
-  _meta: Array<RouteFileMeta> = []
-  _staticTargets: Array<{ path: string; target: string }> = []
-  constructor(g: Galbe, cb?: RouteInstanciationCallback) {
-    this.#g = g
-    this._cb = cb
-    this.#plugins = g.plugins
-  }
-  get server() {
-    return this.#g.server
-  }
-  get router() {
-    return this.#g.router
-  }
-  get config() {
-    return this.#g.config
-  }
-  get meta() {
-    return this._meta
-  }
-  set meta(meta: Array<RouteFileMeta>) {
-    this._meta = meta
-    this.#g.meta = meta
-  }
-  async init() {
-    for (const p of this.#plugins) {
-      // @ts-ignore
-      if (p.init) await p.init(this.#g.config?.plugin?.[p.name] || {}, this)
-    }
-  }
-  private async handleRoute(method: Method | 'static', ...args: any[]): Promise<Route | undefined> {
-    let path = args[0]
-    let meta = {
-      ...this._metaTmp?.routes?.[path]?.[method],
-      ...(this._metaTmp?.hide ? { hide: true } : {}),
-      ...(this._metaTmp?.ignore ? { ignore: true } : {})
-    }
-    if (meta?.ignore) return
-
-    //@ts-ignore
-    const route = this.#g[method](...args) as Route
-
-    if (this._cb && !meta?.ignore) {
-      await this._cb({
-        type: 'add',
-        route,
-        filepath: this._filepath || '',
-        meta
-      })
-    }
-    return route
-  }
-  async get(...args: any[]) {
-    return this.handleRoute('get', ...args)
-  }
-  async post(...args: any[]) {
-    return this.handleRoute('post', ...args)
-  }
-  async put(...args: any[]) {
-    return this.handleRoute('put', ...args)
-  }
-  async patch(...args: any[]) {
-    return this.handleRoute('patch', ...args)
-  }
-  async delete(...args: any[]) {
-    return this.handleRoute('delete', ...args)
-  }
-  async options(...args: any[]) {
-    return this.handleRoute('options', ...args)
-  }
-  async head(...args: any[]) {
-    return this.handleRoute('head', ...args)
-  }
-  async static(...args: any[]) {
-    const [path, target] = args
-    if (typeof path === 'string' && typeof target === 'string') {
-      this._staticTargets.push({ path, target })
-    }
-    return this.handleRoute('static', ...args)
-  }
+export type MiddlewareFileMeta = {
+  file: string
+  /** effective middleware pattern, e.g. `/api/*` or `*` */
+  scope: string
+  header: Record<string, boolean | string | string[]>
 }
+export type RouteFileRegistration = { file: string; prefix: string }
+export type MiddlewareFileRegistration = { file: string; scope: string }
 
 const parseComment = (comment: string): Record<string, string | string[]> => {
   // Find the first JSDoc-tag line (a line whose first non-whitespace/star
@@ -136,8 +68,7 @@ const parseComment = (comment: string): Record<string, string | string[]> => {
         const val = n[2] ?? true
         return {
           ...acc,
-          [tag]:
-            tag in acc ? [...(typeof acc[tag] === 'string' ? [acc[tag]] : acc[tag]), val] : val
+          [tag]: tag in acc ? [...(typeof acc[tag] === 'string' ? [acc[tag]] : acc[tag]), val] : val,
         }
       },
       {} as Record<string, any>
@@ -166,11 +97,12 @@ export const metaAnalysis = async (filePath: string): Promise<RoutesMeta> => {
     content = transformSync(content, {
       jsc: {
         parser: {
-          syntax: 'typescript'
+          syntax: 'typescript',
         },
         preserveAllComments: true,
-        target: 'esnext'
-      }
+        // @swc/wasm's JscTarget typing lags @swc/core's; 'esnext' is supported at runtime
+        target: 'esnext' as any,
+      },
     }).code
   }
 
@@ -186,13 +118,11 @@ export const metaAnalysis = async (filePath: string): Promise<RoutesMeta> => {
         if (!comments?.[locEnd.line]) comments[locEnd.line] = []
         if (IGNORE_COMMENT_RGX.test(text)) {
           ignoredLines.add(locEnd.line + 1)
-        }
-        else if (HIDE_COMMENT_RGX.test(text)) {
+        } else if (HIDE_COMMENT_RGX.test(text)) {
           hideLines.add(locEnd.line + 1)
-        }
-        else comments[locEnd.line]![locEnd.column] = text
+        } else comments[locEnd.line]![locEnd.column] = text
       }
-    }
+    },
   })
   simple(ast, {
     ExportDefaultDeclaration(node) {
@@ -217,59 +147,213 @@ export const metaAnalysis = async (filePath: string): Promise<RoutesMeta> => {
         CallExpression(node) {
           // @ts-ignore
           if (node?.callee?.object?.name === galbeIdentifier) {
-            // @ts-ignore
-            let path = node.arguments[0].value
-            if (!path?.startsWith("/")) path = `/${path}`
             // @ts-ignore
             const method = node.callee.property.name as Method
+            // 'group'/'middleware' calls are not routes; skip non-literal paths
+            // @ts-ignore
+            let path = node.arguments?.[0]?.value
+            if (!ROUTE_METHODS.has(method) || typeof path !== 'string') return
+            if (!path.startsWith('/')) path = `/${path}`
             const line = node.loc?.start.line || -1
             const col = node.loc?.start.column || -1
             const com = comments?.[line]?.[col - 1] ?? ''
-            const routeRefs = ignoredLines.has(line) ? { ignore: true } : { ...parseComment(com), ...(hide || hideLines.has(line) ? { hide: true } : {}) }
+            const routeRefs = ignoredLines.has(line)
+              ? { ignore: true }
+              : { ...parseComment(com), ...(hide || hideLines.has(line) ? { hide: true } : {}) }
             if (!(path in meta.routes)) meta.routes[path] = {}
             if (!(method in meta.routes[path]!)) meta.routes[path]![method] = routeRefs as RouteMeta
           }
-        }
+        },
       })
-    }
+    },
   })
   return meta
 }
 
-export const defineRoutes = async (
-  options: Pick<GalbeConfig, 'routes'>,
-  proxy: GalbeProxy,
-) => {
-  const routes = options?.routes === undefined || options?.routes === true ? DEFAULT_ROUTE_PATTERN : options?.routes
-  if (!routes) return
+// static base of a glob pattern: the segments before the first one containing a
+// glob metachar. Directory prefixes are derived relative to this anchor. A
+// pattern with no metachar names a file: its own directory is the base.
+export const globBase = (pattern: string): string => {
+  const segments = pattern.split('/')
+  const idx = segments.findIndex(s => /[*?[{]/.test(s))
+  return (idx === -1 ? segments.slice(0, -1) : segments.slice(0, idx)).join('/')
+}
+
+const dirPrefixOf = (file: string, base: string): string => {
+  const rel = relative(base, dirname(file))
+  if (!rel || rel === '.') return ''
+  const segments = rel.split(sep)
+  for (const s of segments) {
+    if (!LITERAL_SEGMENT_RGX.test(s))
+      throw new Error(
+        `invalid directory name '${s}' for ${file} — directory names must be valid literal route segments`
+      )
+  }
+  return `/${segments.join('/')}`
+}
+
+// '@prefix /v2' declares the file's route prefix, overriding the dir-derived
+// one entirely; '@prefix /' opts a file out of dirPrefix
+const headerPrefixOf = (meta: RoutesMeta, file: string): string | undefined => {
+  let p = meta.header?.prefix
+  if (p === undefined) return undefined
+  if (Array.isArray(p)) {
+    console.warn(`duplicate @prefix in ${file} — using the first one`)
+    p = p[0]!
+  }
+  if (typeof p !== 'string' || !ROUTE_PATH_RGX.test(p) || p.includes('*'))
+    throw new Error(`invalid @prefix ${String(p)} in ${file} — must be a valid route path`)
+  return p.replace(/\/+$/, '')
+}
+
+// rewrite meta keys to the final path relative to basePath: group/@prefix
+// included, basePath excluded — the shape every consumer looks up by
+const prefixMeta = (meta: RoutesMeta, prefix: string): RoutesMeta =>
+  !prefix
+    ? meta
+    : { ...meta, routes: Object.fromEntries(Object.entries(meta.routes).map(([p, m]) => [joinPath(prefix, p), m])) }
+
+// a directory scan returns entries in the filesystem's order, which differs from
+// machine to machine. Route registration order decides the emitted spec's `paths`
+// order, the printed route table and which param name a shared trie node keeps,
+// so discovery has to be sorted rather than trusted.
+const byDepthThenPath = (a: { file: string }, b: { file: string }) =>
+  a.file.split('/').length - b.file.split('/').length || a.file.localeCompare(b.file)
+
+const collectFiles = async (pattern: string): Promise<Array<{ file: string; base: string }>> => {
   const root = process.cwd()
-  if (typeof routes === 'string') {
-    for await (const path of new Glob(routes).scan({ cwd: root, absolute: true, onlyFiles: false, dot: true })) {
-      const isDir = (await lstat(path)).isDirectory()
+  const base = resolve(root, globBase(pattern))
+  // these hold other people's files, never the app's: an app-wide pattern like
+  // '**/*.route.ts' must not import (and prefix routes by) whatever a dependency
+  // happens to ship. A pattern naming one of them explicitly opts back in.
+  const skipped = NEVER_SCANNED_DIRS.filter(d => !pattern.split('/').includes(d))
+  const isSkipped = (path: string) =>
+    relative(root, path)
+      .split(sep)
+      .some(s => skipped.includes(s))
+  const out: Array<{ file: string; base: string }> = []
+  for await (const path of new Glob(pattern).scan({ cwd: root, absolute: true, onlyFiles: false, dot: true })) {
+    if (isSkipped(path)) continue
+    if ((await lstat(path)).isDirectory()) {
+      // a pattern naming a directory registers its direct children, unprefixed
+      for (const f of await readdir(path)) out.push({ file: `${path}/${f}`, base: path })
+    } else out.push({ file: path, base })
+  }
+  return out.sort(byDepthThenPath)
+}
 
-      let files: string[] = []
-      if (!isDir) files.push(path)
-      else files = files.concat((await readdir(path)).map(f => `${path}/${f}`))
-      for (const f of files) {
-        try {
-          const metadata = await metaAnalysis(f)
-          if (metadata?.ignore) continue
-          proxy._filepath = f
-          proxy._metaTmp = metadata
-          proxy.meta = [...proxy.meta, { file: path, ...metadata }]
-          const imported = await import(f)
-          if (!imported?.default) throw new Error('No default export function')
-          if (typeof imported.default !== 'function') throw new Error('Default export must be a function')
-          const routes = imported.default
-          routes(proxy)
-        } catch (err: any) {
-          if (proxy._cb) await proxy._cb({ type: 'error', error: err, filepath: f, route: undefined, meta: undefined })
+/**
+ * Automatic Route Analyzer: discovers middleware files (registered first,
+ * shallowest directory wins the outer position), then imports route files,
+ * handing each a registrar bound to its prefix (directory-derived or
+ * `@prefix`). Route-to-file correlation relies on `galbe.onRouteAdded` and
+ * assumes registration is synchronous within a file's default export.
+ */
+export const defineRoutes = async (
+  options: Pick<GalbeConfig, 'routes' | 'middleware'>,
+  galbe: Galbe,
+  cb?: RouteInstanciationCallback
+): Promise<{ routeFiles: RouteFileRegistration[]; middlewareFiles: MiddlewareFileRegistration[] }> => {
+  const result = { routeFiles: [] as RouteFileRegistration[], middlewareFiles: [] as MiddlewareFileRegistration[] }
+  const routesConf = options?.routes
+  if (routesConf === false) return result
+  const conf =
+    typeof routesConf === 'object' && !Array.isArray(routesConf)
+      ? routesConf
+      : { pattern: routesConf === undefined || routesConf === true ? undefined : routesConf }
+  const dirPrefix = conf.dirPrefix !== false
+  const patterns = conf.pattern === undefined ? [DEFAULT_ROUTE_PATTERN] : [conf.pattern].flat()
+
+  const relPath = (path: string) =>
+    galbe.router.prefix && path.startsWith(galbe.router.prefix) ? path.slice(galbe.router.prefix.length) || '/' : path
+
+  // middleware files first: outer scopes wrap route files' in-file registrations
+  const mwConf = options?.middleware
+  if (mwConf !== false) {
+    const mwPatterns = mwConf === undefined || mwConf === true ? [DEFAULT_MIDDLEWARE_PATTERN] : [mwConf].flat()
+    const files = (await Promise.all(mwPatterns.map(collectFiles))).flat()
+    // each pattern came back sorted already: this re-sorts across patterns
+    files.sort(byDepthThenPath)
+    for (const { file, base } of files) {
+      const dirScope = dirPrefixOf(file, base)
+      try {
+        const metadata = await metaAnalysis(file)
+        if (metadata?.ignore) continue
+        const imported = await import(file)
+        const exported = imported?.default
+        const scopeExport = imported.scope
+        if (scopeExport !== undefined && typeof scopeExport !== 'string')
+          throw new Error(`invalid scope export in ${file} — must be a middleware pattern string`)
+        const fileScope = (pattern?: string) =>
+          pattern !== undefined ? joinPath(dirScope, pattern) : dirScope ? `${dirScope}/*` : '*'
+        const before = galbe.middlewares.length
+        if (typeof exported === 'function') {
+          // registration function: a scoped registrar, like a route file gets
+          if (scopeExport !== undefined)
+            throw new Error(`unsupported scope export in ${file} — pass a pattern to g.middleware() instead`)
+          exported(new GalbeGroup(galbe, dirScope))
+        } else if (exported && !Array.isArray(exported) && typeof exported === 'object') {
+          galbe.middleware(fileScope(scopeExport), exported as MiddlewareDef)
+        } else {
+          throw new Error(
+            'Middleware file must default-export a middleware definition (see `middleware()`) or a registration function'
+          )
+        }
+        for (const entry of galbe.middlewares.slice(before)) {
+          // '/*' and '*' are the same pattern; record the canonical global form
+          const scope = entry.pattern === '/*' ? '*' : entry.pattern
+          galbe.metaMiddleware.push({ file, scope, header: metadata.header })
+          result.middlewareFiles.push({ file, scope })
         }
+      } catch (err: any) {
+        if (cb) await cb({ type: 'error', error: err, filepath: file, route: undefined, meta: undefined })
       }
     }
-  } else if (Array.isArray(routes)) {
-    for (const r of routes) {
-      await defineRoutes({ routes: r }, proxy)
+  }
+
+  for (const pattern of patterns) {
+    for (const { file, base } of await collectFiles(pattern)) {
+      let metadata: RoutesMeta
+      try {
+        metadata = await metaAnalysis(file)
+      } catch (err: any) {
+        if (cb) await cb({ type: 'error', error: err, filepath: file, route: undefined, meta: undefined })
+        continue
+      }
+      if (metadata?.ignore) continue
+      // invalid dir segments and invalid @prefix are boot errors, not per-file ones
+      const prefix = headerPrefixOf(metadata, file) ?? (dirPrefix ? dirPrefixOf(file, base) : '')
+      const meta = prefixMeta(metadata, prefix)
+      galbe.meta = [...(galbe.meta ?? []), { file, ...meta }]
+      const added: Route[] = []
+      const unsub = galbe.onRouteAdded(({ route }) => added.push(route))
+      try {
+        const imported = await import(file)
+        if (!imported?.default) throw new Error('No default export function')
+        if (typeof imported.default !== 'function') throw new Error('Default export must be a function')
+        imported.default(prefix ? new GalbeGroup(galbe, prefix) : galbe)
+        result.routeFiles.push({ file, prefix })
+      } catch (err: any) {
+        if (cb) await cb({ type: 'error', error: err, filepath: file, route: undefined, meta: undefined })
+      } finally {
+        unsub()
+      }
+      for (const route of added) {
+        const root = route.static?.root
+        const key = root ? (root[0] === '/' ? root : `/${root}`) : relPath(route.path)
+        const routeMeta: RouteMeta = {
+          ...meta.routes?.[key]?.[root ? 'static' : route.method],
+          ...(meta.hide ? { hide: true } : {}),
+          ...(meta.ignore ? { ignore: true } : {}),
+        }
+        // '@galbe-ignore'd routes must not be served: unregister them
+        if (routeMeta.ignore) {
+          galbe.router.remove(route)
+          continue
+        }
+        if (cb) await cb({ type: 'add', route, filepath: file, meta: routeMeta })
+      }
     }
   }
+  return result
 }