Custom Route Generator

Plumier provided extension point to be able to extends the route generation system. This functionalities important when you develop a Facility that handles an endpoint internally and you want this endpoint visible on route analysis or Swagger UI.

Action Routes and Virtual Routes#

Plumier provided RouteMetadata type which separated into 2 kinds:

  • ActionRoute is a kind of route that handled by controller, this route will have Controller and Action metadata information required by the Open API Specification.
  • VirtualRoute is a kind of route that handled internally by a middleware, this route doesn't have Controller associated thus it need to specify Open API Specification for Operation itself.

Example#

For example you develop a Facility that handles and endpoint to generate CSRF key for the client /auth/generate-csrf. First you create middleware that handles the /auth/generate-csrf endpoint like below:

import { CustomMiddlewareFunction, ActionResult } from "@Plumier/core"
const CsrfMiddleware: CustomMiddlewareFunction = async ({ ctx, proceed }) => {
if (ctx.method === "GET" && ctx.path.toLocaleLowerCase() === "/auth/generate-csrf")
return new ActionResult()
.setCookie("__csrf_key", "your generated csrf key")
else
return proceed()
}

Next you register your middleware above and provide the Virtual Route definition for the /auth/generate-csrf endpoint like below

import { DefaultFacility, RouteMetadata, PlumierApplication } from "@plumier/core"
class CsrfGenerationFacility extends DefaultFacility {
async generateRoutes(): Promise<RouteMetadata[]> {
return [{
kind: "VirtualRoute",
method: "get",
provider: CsrfGenerationFacility,
url: "/auth/generate-csrf",
access: "Public",
openApiOperation: /** Operation Open API 3.0 Specification **/
}]
}
setup(app: Readonly<PlumierApplication>): void {
app.use(CsrfMiddleware)
}
}

Generate ActionRoute from Controller#

Plumier provided function to generate route metadata from controller generateRoutes. To generate routes from controller simply call the function like below:

class CsrfController {
@route.get("/auth/generate-csrf")
get(){
return new ActionResult()
.setCookie("__csrf_key", "your generated csrf key")
}
}

Then you can generate the controller from the facility like below

import { DefaultFacility, RouteMetadata, PlumierApplication, generateRoutes } from "@plumier/core"
class CsrfGenerationFacility extends DefaultFacility {
async generateRoutes(): Promise<RouteMetadata[]> {
return generateRoutes(CsrfController)
}
setup(app: Readonly<PlumierApplication>): void {
app.use(CsrfMiddleware)
}
}