Feature: Passing route information to template engine

packages/build/src/lib/schema-parser/middleware/responseSampler.ts

@@ -37,6 +37,7 @@ export class ResponseSampler extends SchemaParserMiddleware {
       {
         parameters: schema.sample.parameters,
         profileName: schema.sample.profile,
+        req: schema.sample?.req,
       },
       // We only need the columns of this query, so we set offset=0 and limit=1 here.
       // Some drivers guess the column types by data, so we should at least query 1 rows.

packages/core/src/lib/template-engine/compiler.ts

@@ -1,4 +1,4 @@
-import { DataResult } from '@vulcan-sql/core/models';
+import { DataResult, KoaRequest } from '@vulcan-sql/core/models';
 import { Pagination } from '../../models/pagination';
 
 export interface TemplateLocation {
@@ -31,6 +31,7 @@ export interface ExecuteContext {
   parameters?: Record<string, any>;
   user?: UserInfo;
   profileName: string;
+  req?: KoaRequest;
 }
 
 export interface Compiler {

packages/core/src/lib/template-engine/nunjucksExecutionMetadata.ts

@@ -1,5 +1,6 @@
 import * as nunjucks from 'nunjucks';
 import { ExecuteContext, UserInfo } from './compiler';
+import { KoaRequest } from '@vulcan-sql/core/models';
 
 export const ReservedContextKeys = {
   CurrentProfileName: 'RESERVED_CURRENT_PROFILE_NAME',
@@ -10,18 +11,21 @@ export class NunjucksExecutionMetadata {
   private profileName: string;
   private parameters: Record<string, any>;
   private userInfo?: UserInfo;
+  private req?: KoaRequest;
 
-  constructor({ parameters = {}, profileName, user }: ExecuteContext) {
+  constructor({ parameters = {}, profileName, user, req }: ExecuteContext) {
     this.parameters = parameters;
     this.profileName = profileName;
     this.userInfo = user;
+    this.req = req;
   }
 
   /** Load from nunjucks context */
   static load(context: nunjucks.Context) {
     return new NunjucksExecutionMetadata({
       parameters: context.lookup('context')?.params || {},
       user: context.lookup('context')?.user || {},
+      req: context.lookup('context')?.req || {},
       profileName: context.lookup(ReservedContextKeys.CurrentProfileName)!,
     });
   }
@@ -32,6 +36,7 @@ export class NunjucksExecutionMetadata {
       context: {
         params: this.parameters,
         user: this.userInfo,
+        req: this.req,
         profile: this.profileName,
       },
       [ReservedContextKeys.CurrentProfileName]: this.profileName,
@@ -45,4 +50,8 @@ export class NunjucksExecutionMetadata {
   public getUserInfo() {
     return this.userInfo;
   }
+
+  public getRequest() {
+    return this.req;
+  }
 }

packages/core/src/models/artifact.ts

@@ -29,6 +29,9 @@ import {
 } from '../lib/validators/constraints';
 import { Type } from 'class-transformer';
 import 'reflect-metadata';
+import { Request as KoaRequest } from 'koa';
+
+export type { KoaRequest };
 
 // Pagination mode should always be UPPERCASE because schema parser will transform the user inputs.
 export enum PaginationMode {
@@ -88,6 +91,7 @@ export class ErrorInfo {
 export class Sample {
   profile!: string;
   parameters!: Record<string, any>;
+  req?: KoaRequest;
 }
 
 export class APISchema {

packages/doc/docs/api-building/sql-syntax.mdx

@@ -150,6 +150,26 @@ from app_data.payments
 
 VulcanSQL will provide the feature by enhancing the [nunjucks](https://mozilla.github.io/nunjucks/templating.html#tags) macro function by importing a macro function from other files in the next version 😃
 
+## Useing HTTP Request data in SQL file
+
+You can easily use `{{ context.req.xxx }}` in the sql file to obtain data from the http request or a custom header as a query condition.
+
+the syntax like the below:
+
+```sql
+select
+  *
+from
+  "artists"
+where
+  {{ context.req.method }} = 'GET'
+and
+  {{ context.req.header.customParameters }} = 'custom parameters'
+  ......
+```
+
+For more available parameters, please refer to: [Koajs#Request](https://koajs.com/#request)
+
 ## Set variable
 
 You could set the variable not only primitive value e.g: integer, string, array. But also VulcanSQL support declares a variable by assigning the dynamic parameter to it. Use the `set` tag and `{% ... %}` to declare the variable and set:

packages/serve/src/lib/route/route-component/baseRoute.ts

@@ -9,6 +9,7 @@ import { IRequestValidator } from './requestValidator';
 import { IRequestTransformer, RequestParameters } from './requestTransformer';
 import { IPaginationTransformer } from './paginationTransformer';
 import { Evaluator } from '@vulcan-sql/serve/evaluator';
+import { KoaRequest } from '@vulcan-sql/core';
 
 export interface TransformedRequest {
   reqParams: RequestParameters;
@@ -57,7 +58,11 @@ export abstract class BaseRoute implements IRoute {
 
   protected abstract prepare(ctx: KoaContext): Promise<TransformedRequest>;
 
-  protected async handle(user: AuthUserInfo, transformed: TransformedRequest) {
+  protected async handle(
+    user: AuthUserInfo,
+    transformed: TransformedRequest,
+    req: KoaRequest
+  ) {
     const { reqParams, pagination } = transformed;
     // could template name or template path, use for template engine
     const { templateSource, profiles } = this.apiSchema;
@@ -74,6 +79,7 @@ export abstract class BaseRoute implements IRoute {
       {
         parameters: reqParams,
         user,
+        req,
         profileName: profile,
       },
       pagination

packages/serve/src/lib/route/route-component/graphQLRoute.ts

@@ -1,6 +1,7 @@
 /* istanbul ignore file */
 import { BaseRoute, RouteOptions } from './baseRoute';
 import { KoaContext } from '@vulcan-sql/serve/models';
+import { KoaRequest } from '@vulcan-sql/core';
 
 export class GraphQLRoute extends BaseRoute {
   public readonly operationName: string;
@@ -18,7 +19,8 @@ export class GraphQLRoute extends BaseRoute {
   public async respond(ctx: KoaContext) {
     const transformed = await this.prepare(ctx);
     const authUser = ctx.state.user;
-    await this.handle(authUser, transformed);
+    const req = ctx.request as KoaRequest;
+    await this.handle(authUser, transformed, req);
     // TODO: get template engine handled result and return response by checking API schema
     return transformed;
   }

packages/serve/src/lib/route/route-component/restfulRoute.ts

@@ -1,5 +1,7 @@
 import { BaseRoute, RouteOptions } from './baseRoute';
 import { KoaContext } from '@vulcan-sql/serve/models';
+import { KoaRequest } from '@vulcan-sql/core';
+
 export class RestfulRoute extends BaseRoute {
   public readonly urlPath: string;
 
@@ -12,7 +14,8 @@ export class RestfulRoute extends BaseRoute {
   public async respond(ctx: KoaContext) {
     const transformed = await this.prepare(ctx);
     const authUser = ctx.state.user;
-    const result = await this.handle(authUser, transformed);
+    const req = ctx.request as KoaRequest;
+    const result = await this.handle(authUser, transformed, req);
     ctx.response.body = {
       data: result.getData(),
       columns: result.getColumns(),