|
|
|
@ -12,23 +12,66 @@ import {Middlewares} from "../../service/Middlewares";
|
|
|
|
|
import {Middleware} from "./Middleware";
|
|
|
|
|
import {Config} from "../../service/Config";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Type alias for an item that is a valid response object, or lack thereof.
|
|
|
|
|
*/
|
|
|
|
|
export type ResponseObject = ResponseFactory | string | number | void | any | Promise<ResponseObject>
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Type alias for an item that defines a direct route handler.
|
|
|
|
|
*/
|
|
|
|
|
export type RouteHandler = ((request: Request, response: Response) => ResponseObject) | ((request: Request) => ResponseObject) | (() => ResponseObject) | string
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Type alias for a function that applies a route handler to the request.
|
|
|
|
|
* The goal is to transform RouteHandlers to ResolvedRouteHandler.
|
|
|
|
|
*/
|
|
|
|
|
export type ResolvedRouteHandler = (request: Request) => ResponseObject
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// TODO domains, named routes - support this on groups as well
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A class that can be used to build and reference dynamic routes in the application.
|
|
|
|
|
*
|
|
|
|
|
* Routes can be defined in nested groups, with prefixes and middleware handlers.
|
|
|
|
|
*
|
|
|
|
|
* @example
|
|
|
|
|
* ```typescript
|
|
|
|
|
* Route.post('/api/v1/ping', (request: Request) => {
|
|
|
|
|
* return 'pong!'
|
|
|
|
|
* })
|
|
|
|
|
*
|
|
|
|
|
* Route.group('/api/v2', () => {
|
|
|
|
|
* Route.get('/status', 'controller::api:v2:Status.getStatus').pre('auth:UserOnly')
|
|
|
|
|
* })
|
|
|
|
|
* ```
|
|
|
|
|
*/
|
|
|
|
|
export class Route extends AppClass {
|
|
|
|
|
/** Routes that have been created and registered in the application. */
|
|
|
|
|
private static registeredRoutes: Route[] = []
|
|
|
|
|
|
|
|
|
|
/** Groups of routes that have been registered with the application. */
|
|
|
|
|
private static registeredGroups: RouteGroup[] = []
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The current nested group stack. This is used internally when compiling the routes by nested group.
|
|
|
|
|
* @private
|
|
|
|
|
*/
|
|
|
|
|
private static compiledGroupStack: RouteGroup[] = []
|
|
|
|
|
|
|
|
|
|
/** Register a route group handler. */
|
|
|
|
|
public static registerGroup(group: RouteGroup) {
|
|
|
|
|
this.registeredGroups.push(group)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Load and compile all of the registered routes and their groups, accounting
|
|
|
|
|
* for nested groups and resolving handlers.
|
|
|
|
|
*
|
|
|
|
|
* This function attempts to resolve the route handlers ahead of time to cache
|
|
|
|
|
* them and also expose any handler resolution errors that might happen at runtime.
|
|
|
|
|
*/
|
|
|
|
|
public static async compile(): Promise<Route[]> {
|
|
|
|
|
let registeredRoutes = this.registeredRoutes
|
|
|
|
|
const registeredGroups = this.registeredGroups
|
|
|
|
@ -103,53 +146,87 @@ export class Route extends AppClass {
|
|
|
|
|
return registeredRoutes
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Create a new route on the given endpoint for the given HTTP verb.
|
|
|
|
|
* @param method
|
|
|
|
|
* @param definition
|
|
|
|
|
* @param handler
|
|
|
|
|
*/
|
|
|
|
|
public static endpoint(method: HTTPMethod | HTTPMethod[], definition: string, handler: RouteHandler) {
|
|
|
|
|
const route = new Route(method, handler, definition)
|
|
|
|
|
this.registeredRoutes.push(route)
|
|
|
|
|
return route
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Create a new GET route on the given endpoint.
|
|
|
|
|
* @param definition
|
|
|
|
|
* @param handler
|
|
|
|
|
*/
|
|
|
|
|
public static get(definition: string, handler: RouteHandler) {
|
|
|
|
|
return this.endpoint('get', definition, handler)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Create a new POST route on the given endpoint. */
|
|
|
|
|
public static post(definition: string, handler: RouteHandler) {
|
|
|
|
|
return this.endpoint('post', definition, handler)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Create a new PUT route on the given endpoint. */
|
|
|
|
|
public static put(definition: string, handler: RouteHandler) {
|
|
|
|
|
return this.endpoint('put', definition, handler)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Create a new PATCH route on the given endpoint. */
|
|
|
|
|
public static patch(definition: string, handler: RouteHandler) {
|
|
|
|
|
return this.endpoint('patch', definition, handler)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Create a new DELETE route on the given endpoint. */
|
|
|
|
|
public static delete(definition: string, handler: RouteHandler) {
|
|
|
|
|
return this.endpoint('delete', definition, handler)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Create a new route on all HTTP verbs, on the given endpoint. */
|
|
|
|
|
public static any(definition: string, handler: RouteHandler) {
|
|
|
|
|
return this.endpoint(['get', 'put', 'patch', 'post', 'delete'], definition, handler)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Create a new route group with the given prefix. */
|
|
|
|
|
public static group(prefix: string, group: () => void | Promise<void>) {
|
|
|
|
|
const grp = <RouteGroup> Application.getApplication().make(RouteGroup, group, prefix)
|
|
|
|
|
this.registeredGroups.push(grp)
|
|
|
|
|
return grp
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Middlewares that should be applied to this route. */
|
|
|
|
|
protected middlewares: Collection<{ stage: 'pre' | 'post', handler: RouteHandler }> = new Collection<{stage: "pre" | "post"; handler: RouteHandler}>()
|
|
|
|
|
|
|
|
|
|
/** Pre-compiled route handlers for the pre-middleware for this route. */
|
|
|
|
|
protected _compiledPreflight?: ResolvedRouteHandler[]
|
|
|
|
|
|
|
|
|
|
/** Pre-compiled route handlers for the post-middleware for this route. */
|
|
|
|
|
protected _compiledHandler?: ResolvedRouteHandler
|
|
|
|
|
|
|
|
|
|
/** Pre-compiled route handler for the main route handler for this route. */
|
|
|
|
|
protected _compiledPostflight?: ResolvedRouteHandler[]
|
|
|
|
|
|
|
|
|
|
constructor(
|
|
|
|
|
/** The HTTP method(s) that this route listens on. */
|
|
|
|
|
protected method: HTTPMethod | HTTPMethod[],
|
|
|
|
|
|
|
|
|
|
/** The primary handler of this route. */
|
|
|
|
|
protected readonly handler: RouteHandler,
|
|
|
|
|
|
|
|
|
|
/** The route path this route listens on. */
|
|
|
|
|
protected route: string
|
|
|
|
|
) { super() }
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Returns true if this route matches the given HTTP verb and request path.
|
|
|
|
|
* @param method
|
|
|
|
|
* @param potential
|
|
|
|
|
*/
|
|
|
|
|
public match(method: HTTPMethod, potential: string): boolean {
|
|
|
|
|
if ( Array.isArray(this.method) && !this.method.includes(method) ) return false
|
|
|
|
|
else if ( !Array.isArray(this.method) && this.method !== method ) return false
|
|
|
|
@ -157,6 +234,20 @@ export class Route extends AppClass {
|
|
|
|
|
return !!this.extract(potential)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Given a request path, try to extract this route's paramters from the path string.
|
|
|
|
|
*
|
|
|
|
|
* @example
|
|
|
|
|
* For route `/foo/:bar/baz` and input `/foo/bob/baz`, extracts:
|
|
|
|
|
*
|
|
|
|
|
* ```typescript
|
|
|
|
|
* {
|
|
|
|
|
* bar: 'bob'
|
|
|
|
|
* }
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* @param potential
|
|
|
|
|
*/
|
|
|
|
|
public extract(potential: string): {[key: string]: string} | undefined {
|
|
|
|
|
const routeParts = (this.route.startsWith('/') ? this.route.substr(1) : this.route).split('/')
|
|
|
|
|
const potentialParts = (potential.startsWith('/') ? potential.substr(1) : potential).split('/')
|
|
|
|
@ -192,6 +283,9 @@ export class Route extends AppClass {
|
|
|
|
|
return params
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Try to pre-compile and return the preflight handlers for this route.
|
|
|
|
|
*/
|
|
|
|
|
public resolvePreflight(): ResolvedRouteHandler[] {
|
|
|
|
|
if ( !this._compiledPreflight ) {
|
|
|
|
|
this._compiledPreflight = this.resolveMiddlewareHandlersForStage('pre')
|
|
|
|
@ -200,6 +294,9 @@ export class Route extends AppClass {
|
|
|
|
|
return this._compiledPreflight
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Try to pre-compile and return the postflight handlers for this route.
|
|
|
|
|
*/
|
|
|
|
|
public resolvePostflight(): ResolvedRouteHandler[] {
|
|
|
|
|
if ( !this._compiledPostflight ) {
|
|
|
|
|
this._compiledPostflight = this.resolveMiddlewareHandlersForStage('post')
|
|
|
|
@ -208,6 +305,9 @@ export class Route extends AppClass {
|
|
|
|
|
return this._compiledPostflight
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Try to pre-compile and return the main handler for this route.
|
|
|
|
|
*/
|
|
|
|
|
public resolveHandler(): ResolvedRouteHandler {
|
|
|
|
|
if ( !this._compiledHandler ) {
|
|
|
|
|
this._compiledHandler = this._resolveHandler()
|
|
|
|
@ -216,6 +316,7 @@ export class Route extends AppClass {
|
|
|
|
|
return this._compiledHandler
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Register the given middleware as a preflight handler for this route. */
|
|
|
|
|
pre(middleware: RouteHandler) {
|
|
|
|
|
this.middlewares.push({
|
|
|
|
|
stage: 'pre',
|
|
|
|
@ -225,6 +326,7 @@ export class Route extends AppClass {
|
|
|
|
|
return this
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Register the given middleware as a postflight handler for this route. */
|
|
|
|
|
post(middleware: RouteHandler) {
|
|
|
|
|
this.middlewares.push({
|
|
|
|
|
stage: 'post',
|
|
|
|
@ -234,20 +336,27 @@ export class Route extends AppClass {
|
|
|
|
|
return this
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Prefix the route's path with the given prefix, normalizing `/` characters. */
|
|
|
|
|
private prepend(prefix: string) {
|
|
|
|
|
if ( !prefix.endsWith('/') ) prefix = `${prefix}/`
|
|
|
|
|
if ( this.route.startsWith('/') ) this.route = this.route.substring(1)
|
|
|
|
|
this.route = `${prefix}${this.route}`
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Add the given middleware item to the beginning of the preflight handlers. */
|
|
|
|
|
private prependMiddleware(def: { stage: 'pre' | 'post', handler: RouteHandler }) {
|
|
|
|
|
this.middlewares.prepend(def)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Add the given middleware item to the end of the postflight handlers. */
|
|
|
|
|
private appendMiddleware(def: { stage: 'pre' | 'post', handler: RouteHandler }) {
|
|
|
|
|
this.middlewares.push(def)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Resolve and return the route handler for this route.
|
|
|
|
|
* @private
|
|
|
|
|
*/
|
|
|
|
|
private _resolveHandler(): ResolvedRouteHandler {
|
|
|
|
|
if ( typeof this.handler !== 'string' ) {
|
|
|
|
|
return (request: Request) => {
|
|
|
|
@ -289,6 +398,11 @@ export class Route extends AppClass {
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Resolve and return the route handlers for the given pre- or post-flight stage.
|
|
|
|
|
* @param stage
|
|
|
|
|
* @private
|
|
|
|
|
*/
|
|
|
|
|
private resolveMiddlewareHandlersForStage(stage: 'pre' | 'post'): ResolvedRouteHandler[] {
|
|
|
|
|
return this.middlewares.where('stage', '=', stage)
|
|
|
|
|
.map<ResolvedRouteHandler>(def => {
|
|
|
|
@ -330,6 +444,7 @@ export class Route extends AppClass {
|
|
|
|
|
.toArray()
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** Cast the route to an intelligible string. */
|
|
|
|
|
toString() {
|
|
|
|
|
const method = Array.isArray(this.method) ? this.method : [this.method]
|
|
|
|
|
return `${method.join('|')} -> ${this.route}`
|
|
|
|
|