@adonisjs/http-server 6.8.2-3 → 6.8.2-5

package/src/router/lookup_store/url_builder.ts

@@ -0,0 +1,250 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import { RuntimeException } from '@poppinss/utils'
+import type { Encryption } from '@adonisjs/encryption'
+
+import type { Qs } from '../../qs.js'
+import { parseRoutePattern } from '../parser.js'
+import type { RouteFinder } from './route_finder.js'
+
+/**
+ * URL builder class is used to create URIs for pre-registered
+ * routes.
+ *
+ * ```ts
+ * const builder = new UrlBuilder(encryption, routeFinder)
+ *
+ * builder
+ *  .qs({ sort: 'id' })
+ *  .params([category.id])
+ *  .make('categories.posts.index')
+ * ```
+ */
+export class UrlBuilder {
+  /**
+   * Query string parser
+   */
+  #qsParser: Qs
+
+  /**
+   * The parameters to apply on the route
+   */
+  #params: any[] | Record<string, any> = {}
+
+  /**
+   * Query string to append to the route
+   */
+  #qs: Record<string, any> = {}
+
+  /**
+   * Should we perform the route lookup or just build the
+   * given pattern as it is.
+   */
+  #shouldPerformLookup = true
+
+  /**
+   * BaseURL to append to the constructored URL
+   */
+  #baseUrl?: string
+
+  /**
+   * Encryption class for making signed URLs
+   */
+  #encryption: Encryption
+
+  /**
+   * Route finder for finding route pattern
+   */
+  #routeFinder: RouteFinder
+
+  constructor(encryption: Encryption, routeFinder: RouteFinder, qsParser: Qs) {
+    this.#qsParser = qsParser
+    this.#encryption = encryption
+    this.#routeFinder = routeFinder
+  }
+
+  /**
+   * Raises exception when wildcard values array is missing or
+   * has length of zero.
+   */
+  #ensureHasWildCardValues(pattern: string, values?: string[]) {
+    if (!values || !Array.isArray(values) || !values.length) {
+      throw new RuntimeException(
+        `Cannot make URL for "${pattern}" route. Invalid value provided for wildcard param`
+      )
+    }
+  }
+
+  /*
+   * Raises exception when value is not defined
+   */
+  #ensureHasParamValue(pattern: string, param: string, value: string) {
+    if (value === undefined || value === null) {
+      throw new RuntimeException(
+        `Cannot make URL for "${pattern}" route. Missing value for "${param}" param`
+      )
+    }
+  }
+
+  /**
+   * Processes the pattern against the params
+   */
+  #processPattern(pattern: string): string {
+    const uriSegments: string[] = []
+    const paramsArray = Array.isArray(this.#params) ? this.#params : null
+    const paramsObject = !Array.isArray(this.#params) ? this.#params : {}
+
+    let paramsIndex = 0
+    const tokens = parseRoutePattern(pattern)
+
+    for (const token of tokens) {
+      /**
+       * Expected wildcard param to be at the end always and hence
+       * we must break out from the loop
+       */
+      if (token.type === 0) {
+        uriSegments.push(`${token.val}${token.end}`)
+      } else if (token.type === 2) {
+        const values: string[] = paramsArray ? paramsArray.slice(paramsIndex) : paramsObject['*']
+        this.#ensureHasWildCardValues(pattern, values)
+        uriSegments.push(`${values.join('/')}${token.end}`)
+        break
+      } else {
+        const paramName = token.val
+        const value = paramsArray ? paramsArray[paramsIndex] : paramsObject[paramName]
+
+        /**
+         * Type = 1 means param is required
+         */
+        if (token.type === 1) {
+          this.#ensureHasParamValue(pattern, paramName, value)
+        }
+
+        paramsIndex++
+        if (value !== undefined && value !== null) {
+          uriSegments.push(`${value}${token.end}`)
+        }
+      }
+    }
+
+    return `/${uriSegments.join('/')}`
+  }
+
+  /**
+   * Suffix the query string to the URL
+   */
+  #suffixQueryString(url: string, qs?: Record<string, any>): string {
+    if (qs) {
+      const queryString = this.#qsParser.stringify(qs)
+      url = queryString ? `${url}?${queryString}` : url
+    }
+
+    return url
+  }
+
+  /**
+   * Prefixes base URL to the uri string
+   */
+  #prefixBaseUrl(uri: string) {
+    return this.#baseUrl ? `${this.#baseUrl}${uri}` : uri
+  }
+
+  /**
+   * Prefix a custom base URL to the final URI
+   */
+  prefixUrl(url: string): this {
+    this.#baseUrl = url
+    return this
+  }
+
+  /**
+   * Disable route lookup. Calling this method considers
+   * the "identifier" as the route pattern
+   */
+  disableRouteLookup(): this {
+    this.#shouldPerformLookup = false
+    return this
+  }
+
+  /**
+   * Append query string to the final URI
+   */
+  qs(queryString?: Record<string, any>): this {
+    if (!queryString) {
+      return this
+    }
+
+    this.#qs = queryString
+    return this
+  }
+
+  /**
+   * Specify params to apply to the route pattern
+   */
+  params(params?: any[] | Record<string, any>): this {
+    if (!params) {
+      return this
+    }
+
+    this.#params = params
+    return this
+  }
+
+  /**
+   * Generate URL for the given route identifier. The identifier can be the
+   * route name, controller.method name or the route pattern
+   * itself.
+   */
+  make(identifier: string) {
+    let url: string
+
+    if (this.#shouldPerformLookup) {
+      const route = this.#routeFinder.findOrFail(identifier)
+      url = this.#processPattern(route.pattern)
+    } else {
+      url = this.#processPattern(identifier)
+    }
+
+    return this.#suffixQueryString(this.#prefixBaseUrl(url), this.#qs)
+  }
+
+  /**
+   * Generate a signed URL for the given route identifier. The identifier can be the
+   * route name, controller.method name or the route pattern
+   * itself.
+   */
+  makeSigned(identifier: string, options?: { expiresIn?: string | number; purpose?: string }) {
+    let url: string
+
+    if (this.#shouldPerformLookup) {
+      const route = this.#routeFinder.findOrFail(identifier)
+      url = this.#processPattern(route.pattern)
+    } else {
+      url = this.#processPattern(identifier)
+    }
+
+    /*
+     * Making the signature from the qualified url. We do not prefix the domain when
+     * making signature, since it just makes the signature big.
+     *
+     * There might be a case, when someone wants to generate signature for the same route
+     * on their 2 different domains, but we ignore that case for now and can consider
+     * it later (when someone asks for it)
+     */
+    const signature = this.#encryption.verifier.sign(
+      this.#suffixQueryString(url, this.#qs),
+      options?.expiresIn,
+      options?.purpose
+    )
+
+    const qs = Object.assign({}, this.#qs, { signature })
+    return this.#suffixQueryString(this.#prefixBaseUrl(url), qs)
+  }
+}

package/src/router/main.ts

@@ -0,0 +1,431 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import is from '@sindresorhus/is'
+import { moduleImporter } from '@adonisjs/fold'
+import { RuntimeException } from '@poppinss/utils'
+import type { Encryption } from '@adonisjs/encryption'
+import type { Application } from '@adonisjs/application'
+
+import type { Qs } from '../qs.js'
+import { Route } from './route.js'
+import { RouteGroup } from './group.js'
+import { BriskRoute } from './brisk.js'
+import { RoutesStore } from './store.js'
+import { toRoutesJSON } from '../helpers.js'
+import { RouteResource } from './resource.js'
+import { LookupStore } from './lookup_store/main.js'
+import { RouteMatchers as Matchers } from './matchers.js'
+import type { Constructor, LazyImport } from '../types/base.js'
+import { defineNamedMiddleware } from '../define_middleware.js'
+import type { MiddlewareAsClass, ParsedGlobalMiddleware } from '../types/middleware.js'
+
+import type {
+  RouteFn,
+  MatchedRoute,
+  RouteMatcher,
+  RouteMatchers,
+  MakeUrlOptions,
+  MakeSignedUrlOptions,
+  GetControllerHandlers,
+} from '../types/route.js'
+import { parseRoutePattern } from './parser.js'
+
+/**
+ * Router class exposes a unified API to register new routes, group them or
+ * create route resources.
+ *
+ * ```ts
+ * const router = new Router()
+ *
+ * router.get('/', async function () {
+ *   // handle request
+ * })
+ * ```
+ */
+export class Router extends LookupStore {
+  /**
+   * Application is needed to resolve string based controller expressions
+   */
+  #app: Application<any>
+
+  /**
+   * Store with tokenized routes
+   */
+  #store: RoutesStore = new RoutesStore()
+
+  /**
+   * Global matchers to test route params against regular expressions.
+   */
+  #globalMatchers: RouteMatchers = {}
+
+  /**
+   * Middleware store to be shared with the routes
+   */
+  #middleware: ParsedGlobalMiddleware[] = []
+
+  /**
+   * A boolean to tell the router that a group is in
+   * open state right now
+   */
+  #openedGroups: RouteGroup[] = []
+
+  /**
+   * Collection of routes, including route resource and route
+   * group. To get a flat list of routes, call `router.toJSON()`
+   */
+  routes: (Route | RouteResource | RouteGroup | BriskRoute)[] = []
+
+  /**
+   * A flag to know if routes for explicit domains have been registered.
+   * The boolean is computed after calling the "commit" method.
+   */
+  usingDomains: boolean = false
+
+  /**
+   * Shortcut methods for commonly used route matchers
+   */
+  matchers = new Matchers()
+
+  constructor(app: Application<any>, encryption: Encryption, qsParser: Qs) {
+    super(encryption, qsParser)
+    this.#app = app
+  }
+
+  /**
+   * Push a give router entity to the list of routes or the
+   * recently opened group.
+   */
+  #pushToRoutes(entity: Route | RouteResource | RouteGroup | BriskRoute) {
+    const openedGroup = this.#openedGroups[this.#openedGroups.length - 1]
+    if (openedGroup) {
+      openedGroup.routes.push(entity)
+      return
+    }
+
+    this.routes.push(entity)
+  }
+
+  /**
+   * Parses the route pattern
+   */
+  parsePattern(pattern: string, matchers?: RouteMatchers) {
+    return parseRoutePattern(pattern, matchers)
+  }
+
+  /**
+   * Define an array of middleware to use on all the routes.
+   * Calling this method multiple times pushes to the
+   * existing list of middleware
+   */
+  use(middleware: LazyImport<MiddlewareAsClass>[]): this {
+    middleware.forEach((one) =>
+      this.#middleware.push(moduleImporter(one, 'handle').toHandleMethod())
+    )
+
+    return this
+  }
+
+  /**
+   * Define a collection of named middleware. The defined collection is
+   * not registered anywhere, but instead converted in a new collection
+   * of functions you can apply on the routes, or router groups.
+   */
+  named<NamedMiddleware extends Record<string, LazyImport<MiddlewareAsClass>>>(
+    collection: NamedMiddleware
+  ) {
+    return defineNamedMiddleware<NamedMiddleware>(collection)
+  }
+
+  /**
+   * Add route for a given pattern and methods
+   */
+  route<T extends Constructor<any>>(
+    pattern: string,
+    methods: string[],
+    handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]
+  ) {
+    const route = new Route(this.#app, this.#middleware, {
+      pattern,
+      methods,
+      handler,
+      globalMatchers: this.#globalMatchers,
+    })
+
+    this.#pushToRoutes(route)
+    return route
+  }
+
+  /**
+   * Define a route that handles all common HTTP methods
+   */
+  any<T extends Constructor<any>>(
+    pattern: string,
+    handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]
+  ) {
+    return this.route(
+      pattern,
+      ['HEAD', 'OPTIONS', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+      handler
+    )
+  }
+
+  /**
+   * Define `GET` route
+   */
+  get<T extends Constructor<any>>(
+    pattern: string,
+    handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]
+  ) {
+    return this.route(pattern, ['GET', 'HEAD'], handler)
+  }
+
+  /**
+   * Define `POST` route
+   */
+  post<T extends Constructor<any>>(
+    pattern: string,
+    handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]
+  ) {
+    return this.route(pattern, ['POST'], handler)
+  }
+
+  /**
+   * Define `PUT` route
+   */
+  put<T extends Constructor<any>>(
+    pattern: string,
+    handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]
+  ) {
+    return this.route(pattern, ['PUT'], handler)
+  }
+
+  /**
+   * Define `PATCH` route
+   */
+  patch<T extends Constructor<any>>(
+    pattern: string,
+    handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]
+  ) {
+    return this.route(pattern, ['PATCH'], handler)
+  }
+
+  /**
+   * Define `DELETE` route
+   */
+  delete<T extends Constructor<any>>(
+    pattern: string,
+    handler: string | RouteFn | [LazyImport<T> | T, GetControllerHandlers<T>?]
+  ) {
+    return this.route(pattern, ['DELETE'], handler)
+  }
+
+  /**
+   * Creates a group of routes. A route group can apply transforms
+   * to routes in bulk
+   */
+  group(callback: () => void) {
+    /*
+     * Create a new group with empty set of routes
+     */
+    const group = new RouteGroup([])
+
+    /**
+     * Track group
+     */
+    this.#pushToRoutes(group)
+
+    /*
+     * Track the group, so that the upcoming calls inside the callback
+     * can use this group
+     */
+    this.#openedGroups.push(group)
+
+    /*
+     * Execute the callback. Now all registered routes will be
+     * collected seperately from the `routes` array
+     */
+    callback()
+
+    /*
+     * Now the callback is over, get rid of the opened group
+     */
+    this.#openedGroups.pop()
+
+    return group
+  }
+
+  /**
+   * Registers a route resource with conventional set of routes
+   */
+  resource(resource: string, controller: string | LazyImport<Constructor<any>> | Constructor<any>) {
+    const resourceInstance = new RouteResource(this.#app, this.#middleware, {
+      resource,
+      controller,
+      shallow: false,
+      globalMatchers: this.#globalMatchers,
+    })
+
+    this.#pushToRoutes(resourceInstance)
+    return resourceInstance
+  }
+
+  /**
+   * Register a route resource with shallow nested routes.
+   */
+  shallowResource(
+    resource: string,
+    controller: string | LazyImport<Constructor<any>> | Constructor<any>
+  ) {
+    const resourceInstance = new RouteResource(this.#app, this.#middleware, {
+      resource,
+      controller,
+      shallow: true,
+      globalMatchers: this.#globalMatchers,
+    })
+
+    this.#pushToRoutes(resourceInstance)
+    return resourceInstance
+  }
+
+  /**
+   * Returns a brisk route instance for a given URL pattern
+   */
+  on(pattern: string) {
+    const briskRoute = new BriskRoute(this.#app, this.#middleware, {
+      pattern,
+      globalMatchers: this.#globalMatchers,
+    })
+
+    this.#pushToRoutes(briskRoute)
+    return briskRoute
+  }
+
+  /**
+   * Define matcher for a given param. The global params are applied
+   * on all the routes (unless overridden at the route level).
+   */
+  where(param: string, matcher: RouteMatcher | string | RegExp): this {
+    if (typeof matcher === 'string') {
+      this.#globalMatchers[param] = { match: new RegExp(matcher) }
+    } else if (is.regExp(matcher)) {
+      this.#globalMatchers[param] = { match: matcher }
+    } else {
+      this.#globalMatchers[param] = matcher
+    }
+
+    return this
+  }
+
+  /**
+   * Commit routes to the store. The router is freezed after the
+   * commit method is called.
+   */
+  commit() {
+    const routeNamesByDomain: Map<string, Set<string>> = new Map()
+
+    toRoutesJSON(this.routes).forEach((route) => {
+      if (!routeNamesByDomain.has(route.domain)) {
+        routeNamesByDomain.set(route.domain, new Set())
+      }
+
+      const routeNames = routeNamesByDomain.get(route.domain)!
+
+      /*
+       * Raise error when route name is already in use. Route names have to be unique
+       * to ensure that only one route is returned during lookup.
+       */
+      if (route.name && routeNames.has(route.name)) {
+        throw new RuntimeException(
+          `Route with duplicate name found. A route with name "${route.name}" already exists`
+        )
+      }
+
+      /*
+       * If route has a unique, then track the name for checking duplicates
+       */
+      if (route.name) {
+        routeNames.add(route.name)
+      }
+
+      /**
+       * Register the route with the lookup store
+       */
+      this.register(route)
+      this.#store.add(route)
+    })
+
+    routeNamesByDomain.clear()
+
+    this.usingDomains = this.#store.usingDomains
+    this.routes = []
+    this.#globalMatchers = {}
+    this.#middleware = []
+  }
+
+  /**
+   * Find route for a given URL, method and optionally domain
+   */
+  match(url: string, method: string, hostname?: string | null): null | MatchedRoute {
+    const matchingDomain = this.#store.matchDomain(hostname)
+
+    return matchingDomain.length
+      ? this.#store.match(url, method, {
+          tokens: matchingDomain,
+          hostname: hostname!,
+        })
+      : this.#store.match(url, method)
+  }
+
+  /**
+   * Make URL to a pre-registered route
+   */
+  makeUrl(
+    routeIdentifier: string,
+    params?: any[] | Record<string, any>,
+    options?: MakeUrlOptions
+  ): string {
+    const normalizedOptions = Object.assign({}, options)
+
+    const builder = normalizedOptions.domain
+      ? this.builderForDomain(normalizedOptions.domain)
+      : this.builder()
+
+    builder.params(params)
+    builder.qs(normalizedOptions.qs)
+
+    normalizedOptions.prefixUrl && builder.prefixUrl(normalizedOptions.prefixUrl)
+    normalizedOptions.disableRouteLookup && builder.disableRouteLookup()
+
+    return builder.make(routeIdentifier)
+  }
+
+  /**
+   * Makes a signed URL to a pre-registered route.
+   */
+  makeSignedUrl(
+    routeIdentifier: string,
+    params?: any[] | Record<string, any>,
+    options?: MakeSignedUrlOptions
+  ): string {
+    const normalizedOptions = Object.assign({}, options)
+
+    const builder = normalizedOptions.domain
+      ? this.builderForDomain(normalizedOptions.domain)
+      : this.builder()
+
+    builder.params(params)
+    builder.qs(normalizedOptions.qs)
+
+    normalizedOptions.prefixUrl && builder.prefixUrl(normalizedOptions.prefixUrl)
+    normalizedOptions.disableRouteLookup && builder.disableRouteLookup()
+
+    return builder.makeSigned(routeIdentifier, normalizedOptions)
+  }
+}

package/src/router/matchers.ts

@@ -0,0 +1,40 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import Macroable from '@poppinss/macroable'
+
+/**
+ * Shortcut methods for commonly used route matchers
+ */
+export class RouteMatchers extends Macroable {
+  /**
+   * Enforce value to be a number and also casts it to number data
+   * type
+   */
+  number() {
+    return { match: /^[0-9]+$/, cast: (value: string) => Number(value) }
+  }
+
+  /**
+   * Enforce value to be formatted as uuid
+   */
+  uuid() {
+    return {
+      match: /^[0-9a-zA-F]{8}-[0-9a-zA-F]{4}-[0-9a-zA-F]{4}-[0-9a-zA-F]{4}-[0-9a-zA-F]{12}$/,
+      cast: (value: string) => value.toLowerCase(),
+    }
+  }
+
+  /**
+   * Enforce value to be formatted as slug
+   */
+  slug() {
+    return { match: /^[^\s-_](?!.*?[-_]{2,})([a-z0-9-\\]{1,})[^\s]*[^-_\s]$/ }
+  }
+}