UNPKG

6.54 kBTypeScriptView Raw
1import { Context, ValueOrPromise } from '@loopback/core';
2import { InvokeMiddleware, InvokeMiddlewareOptions } from '@loopback/express';
3import { RequestContext } from './request-context';
4import { FindRoute, InvokeMethod, ParseParams, Reject, Send } from './types';
5/**
6 * A sequence function is a function implementing a custom
7 * sequence of actions to handle an incoming request.
8 */
9export type SequenceFunction = (context: RequestContext, sequence: DefaultSequence) => ValueOrPromise<void>;
10/**
11 * A sequence handler is a class implementing sequence of actions
12 * required to handle an incoming request.
13 */
14export interface SequenceHandler {
15 /**
16 * Handle the request by running the configured sequence of actions.
17 *
18 * @param context - The request context: HTTP request and response objects,
19 * per-request IoC container and more.
20 */
21 handle(context: RequestContext): Promise<void>;
22}
23/**
24 * The default implementation of SequenceHandler.
25 *
26 * @remarks
27 * This class implements default Sequence for the LoopBack framework.
28 * Default sequence is used if user hasn't defined their own Sequence
29 * for their application.
30 *
31 * Sequence constructor() and run() methods are invoked from [[http-handler]]
32 * when the API request comes in. User defines APIs in their Application
33 * Controller class.
34 *
35 * @example
36 * User can bind their own Sequence to app as shown below
37 * ```ts
38 * app.bind(CoreBindings.SEQUENCE).toClass(MySequence);
39 * ```
40 */
41export declare class DefaultSequence implements SequenceHandler {
42 protected findRoute: FindRoute;
43 protected parseParams: ParseParams;
44 protected invoke: InvokeMethod;
45 send: Send;
46 reject: Reject;
47 /**
48 * Optional invoker for registered middleware in a chain.
49 * To be injected via SequenceActions.INVOKE_MIDDLEWARE.
50 */
51 protected invokeMiddleware: InvokeMiddleware;
52 /**
53 * Constructor: Injects findRoute, invokeMethod & logError
54 * methods as promises.
55 *
56 * @param findRoute - Finds the appropriate controller method,
57 * spec and args for invocation (injected via SequenceActions.FIND_ROUTE).
58 * @param parseParams - The parameter parsing function (injected
59 * via SequenceActions.PARSE_PARAMS).
60 * @param invoke - Invokes the method specified by the route
61 * (injected via SequenceActions.INVOKE_METHOD).
62 * @param send - The action to merge the invoke result with the response
63 * (injected via SequenceActions.SEND)
64 * @param reject - The action to take if the invoke returns a rejected
65 * promise result (injected via SequenceActions.REJECT).
66 */
67 constructor(findRoute: FindRoute, parseParams: ParseParams, invoke: InvokeMethod, send: Send, reject: Reject);
68 /**
69 * Runs the default sequence. Given a handler context (request and response),
70 * running the sequence will produce a response or an error.
71 *
72 * Default sequence executes these steps
73 * - Executes middleware for CORS, OpenAPI spec endpoints
74 * - Finds the appropriate controller method, swagger spec
75 * and args for invocation
76 * - Parses HTTP request to get API argument list
77 * - Invokes the API which is defined in the Application Controller
78 * - Writes the result from API into the HTTP response
79 * - Error is caught and logged using 'logError' if any of the above steps
80 * in the sequence fails with an error.
81 *
82 * @param context - The request context: HTTP request and response objects,
83 * per-request IoC container and more.
84 */
85 handle(context: RequestContext): Promise<void>;
86}
87/**
88 * Built-in middleware groups for the REST sequence
89 */
90export declare namespace RestMiddlewareGroups {
91 /**
92 * Invoke downstream middleware to get the result or catch errors so that it
93 * can produce the http response
94 */
95 const SEND_RESPONSE = "sendResponse";
96 /**
97 * Enforce CORS
98 */
99 const CORS = "cors";
100 /**
101 * Server OpenAPI specs
102 */
103 const API_SPEC = "apiSpec";
104 /**
105 * Default middleware group
106 */
107 const MIDDLEWARE = "middleware";
108 const DEFAULT = "middleware";
109 /**
110 * Find the route that can serve the request
111 */
112 const FIND_ROUTE = "findRoute";
113 /**
114 * Perform authentication
115 */
116 const AUTHENTICATION = "authentication";
117 /**
118 * Parse the http request to extract parameter values for the operation
119 */
120 const PARSE_PARAMS = "parseParams";
121 /**
122 * Invoke the target controller method or handler function
123 */
124 const INVOKE_METHOD = "invokeMethod";
125}
126/**
127 * A sequence implementation using middleware chains
128 */
129export declare class MiddlewareSequence implements SequenceHandler {
130 readonly invokeMiddleware: InvokeMiddleware;
131 readonly options: InvokeMiddlewareOptions;
132 private middlewareView;
133 static defaultOptions: InvokeMiddlewareOptions;
134 /**
135 * Constructor: Injects `InvokeMiddleware` and `InvokeMiddlewareOptions`
136 *
137 * @param invokeMiddleware - invoker for registered middleware in a chain.
138 * To be injected via RestBindings.INVOKE_MIDDLEWARE_SERVICE.
139 */
140 constructor(context: Context, invokeMiddleware: InvokeMiddleware, options?: InvokeMiddlewareOptions);
141 /**
142 * Runs the default sequence. Given a handler context (request and response),
143 * running the sequence will produce a response or an error.
144 *
145 * Default sequence executes these groups of middleware:
146 *
147 * - `cors`: Enforces `CORS`
148 * - `openApiSpec`: Serves OpenAPI specs
149 * - `findRoute`: Finds the appropriate controller method, swagger spec and
150 * args for invocation
151 * - `parseParams`: Parses HTTP request to get API argument list
152 * - `invokeMethod`: Invokes the API which is defined in the Application
153 * controller method
154 *
155 * In front of the groups above, we have a special middleware called
156 * `sendResponse`, which first invokes downstream middleware to get a result
157 * and handles the result or error respectively.
158 *
159 * - Writes the result from API into the HTTP response (if the HTTP response
160 * has not been produced yet by the middleware chain.
161 * - Catches error logs it using 'logError' if any of the above steps
162 * in the sequence fails with an error.
163 *
164 * @param context - The request context: HTTP request and response objects,
165 * per-request IoC container and more.
166 */
167 handle(context: RequestContext): Promise<void>;
168}
169
\No newline at end of file