1 | /// <reference types="node" />
|
2 | import * as express from 'express';
|
3 | import { asyncHandler, retry, sleep, verifyBodyParam, verifyQueryParam } from './utils';
|
4 | export { asyncHandler, retry, sleep, verifyBodyParam, verifyQueryParam };
|
5 | import * as http from 'http';
|
6 | /**
|
7 | * Interface used to time various events.
|
8 | */
|
9 | export interface ITimer {
|
10 | /**
|
11 | * Start a timer.
|
12 | *
|
13 | * @param timerName The name of the timer.
|
14 | */
|
15 | start(timerName: string): void;
|
16 | /**
|
17 | * Stop a timer.
|
18 | *
|
19 | * @param timerName The name of the timer.
|
20 | */
|
21 | stop(timerName: string): void;
|
22 | }
|
23 | /**
|
24 | * Interface for a service to output metrics.
|
25 | */
|
26 | export interface IMetrics {
|
27 | /**
|
28 | * Output a discrete metric value.
|
29 | *
|
30 | * @param name The name of the metric.
|
31 | * @param value The value of the metric.
|
32 | */
|
33 | discrete(name: string, value: number): void;
|
34 | /**
|
35 | * Output a continous metric value.
|
36 | *
|
37 | * @param name The name of the metric.
|
38 | * @param value The value of the metric.
|
39 | */
|
40 | continuous(name: string, value: number): void;
|
41 | }
|
42 | /**
|
43 | * Configures a microservice.
|
44 | */
|
45 | export interface IMicroServiceConfig {
|
46 | /**
|
47 | * The name that identifies the service.
|
48 | */
|
49 | serviceName: string;
|
50 | /**
|
51 | * Enable verbose logging from micro.
|
52 | */
|
53 | verbose?: boolean;
|
54 | /**
|
55 | * Host to run the REST API.
|
56 | */
|
57 | host?: string;
|
58 | /**
|
59 | * Port to run the REST API.
|
60 | */
|
61 | port?: number;
|
62 | /**
|
63 | * Defines the connection to the RabbitMQ server.
|
64 | */
|
65 | messagingHost?: string;
|
66 | }
|
67 | /**
|
68 | * Interface for responding to events.
|
69 | */
|
70 | export interface IEventResponse {
|
71 | /**
|
72 | * Acknoledge that the event was successfully handled.
|
73 | */
|
74 | ack(): Promise<void>;
|
75 | }
|
76 | export interface IEventHandler {
|
77 | }
|
78 | /**
|
79 | * Defines a potentially asynchronous callback function for handling an incoming event.
|
80 | */
|
81 | export declare type EventHandlerFn<EventArgsT> = (eventArgs: EventArgsT, response: IEventResponse) => Promise<void>;
|
82 | /**
|
83 | * Defines a potentially asynchronous callback function for handling an incoming HTTP GET request.
|
84 | */
|
85 | export declare type RequestHandlerFn = (request: express.Request, response: express.Response) => Promise<void>;
|
86 | /**
|
87 | * Interface for defining HTTP routes on a REST API.
|
88 | */
|
89 | export interface IHttpServer {
|
90 | /**
|
91 | * Create a handler for incoming HTTP GET requests.
|
92 | * Implemented by Express under the hood.
|
93 | */
|
94 | get(route: string, requestHandler: RequestHandlerFn): void;
|
95 | /**
|
96 | * Create a handler for incoming HTTP POST requests.
|
97 | * Implemented by Express under the hood
|
98 | *
|
99 | * @param route
|
100 | * @param requestHandler
|
101 | */
|
102 | post(route: string, requestHandler: RequestHandlerFn): void;
|
103 | /**
|
104 | * Create a handler for incoming HTTP PUT requests.
|
105 | * Implemented by Express under the hood
|
106 | *
|
107 | * @param route
|
108 | * @param requestHandler
|
109 | */
|
110 | put(route: string, requestHandler: RequestHandlerFn): void;
|
111 | /**
|
112 | * Setup serving of static files.
|
113 | *
|
114 | * @param dirPath The path to the directory that contains static files.
|
115 | */
|
116 | static(dirPath: string): void;
|
117 | }
|
118 | /**
|
119 | * Interface for issuing HTTP requests to a REST API.
|
120 | */
|
121 | export interface IHttpRequest {
|
122 | /**
|
123 | * Make a HTTP get request to another service.
|
124 | *
|
125 | * @param serviceName The name (logical or host) of the service.
|
126 | * @param route The HTTP route on the service to make the request to.
|
127 | * @param params Query parameters for the request.
|
128 | */
|
129 | get<T = any>(serviceName: string, route: string, body?: any): Promise<T>;
|
130 | /**
|
131 | * Make a HTTP get request to another service.
|
132 | *
|
133 | * @param serviceName The name (logical or host) of the service.
|
134 | * @param route The HTTP route on the service to make the request to.
|
135 | * @param params Query parameters for the request.
|
136 | */
|
137 | post<T = void>(serviceName: string, route: string, body: any): Promise<T>;
|
138 | /**
|
139 | * Forward HTTP get request to another named service.
|
140 | * The response from the forward requests is automatically piped into the passed in response.
|
141 | *
|
142 | * @param serviceName The name of the service to forward the request to.
|
143 | * @param route The HTTP GET route to forward to.
|
144 | * @param params Query parameters for the request.
|
145 | * @param res The stream to pipe response to.
|
146 | */
|
147 | forward(serviceName: string, route: string, req: express.Request, res: express.Response): void;
|
148 | }
|
149 | /**
|
150 | * Interface that represents a particular microservice instance.
|
151 | */
|
152 | export interface IMicroService {
|
153 | /**
|
154 | * Get the name that identifies the service.
|
155 | */
|
156 | getServiceName(): string;
|
157 | /**
|
158 | * Get the instance ID for the particular instance of the service.
|
159 | */
|
160 | getInstanceId(): string;
|
161 | /**
|
162 | * Returns true if the messaging system is currently available.
|
163 | */
|
164 | isMessagingAvailable(): boolean;
|
165 | /**
|
166 | * Create a handler for a named incoming event from a direct queue.
|
167 | * Implemented by Rabbitmq under the hood for reliable messaging.
|
168 | *
|
169 | * @param eventName The name of the event to handle.
|
170 | * @param eventHandler Callback to be invoke when the incoming event is received.
|
171 | */
|
172 | on<EventArgsT = any>(eventName: string, eventHandlerFn: EventHandlerFn<EventArgsT>): Promise<IEventHandler>;
|
173 | /**
|
174 | * Unregister a previously register event handler.
|
175 | *
|
176 | * @param eventHandler The event handler to unregister.
|
177 | */
|
178 | off(eventHandler: IEventHandler): void;
|
179 | /**
|
180 | * Create a once-off handler for a named incoming event.
|
181 | * The event handler will only be invoke once before the event is unregistered.
|
182 | * Implemented by Rabbitmq under the hood for reliable messaging.
|
183 | *
|
184 | * @param eventName The name of the event to handle.
|
185 | * @param eventHandler Callback to be invoke when the incoming event is received.
|
186 | */
|
187 | once<EventArgsT = any>(eventName: string, eventHandlerFn: EventHandlerFn<EventArgsT>): Promise<void>;
|
188 | /***
|
189 | * Wait for a single incoming event, returns the events arguments and then unregister the event handler.
|
190 | *
|
191 | * @param eventName The name of the event to handle.
|
192 | *
|
193 | * @returns A promise to resolve the incoming event's arguments.
|
194 | */
|
195 | waitForOneEvent<EventArgsT = any>(eventName: string): Promise<EventArgsT>;
|
196 | /**
|
197 | * Emit a named outgoing event.
|
198 | * Implemented by Rabbitmq under the hood for reliable messaging.
|
199 | *
|
200 | * @param eventName The name of the event to emit.
|
201 | * @param eventArgs Event args to publish with the event and be received at the other end.
|
202 | */
|
203 | emit<EventArgsT = any>(eventName: string, eventArgs: EventArgsT): Promise<void>;
|
204 | /**
|
205 | * Reference to the timer interface.
|
206 | * Allows a service to time code for performance.
|
207 | */
|
208 | readonly timer: ITimer;
|
209 | /**
|
210 | * Reference to the metrics interface.
|
211 | * Allows a service to output metrics.
|
212 | */
|
213 | readonly metrics: IMetrics;
|
214 | /**
|
215 | * Reference to the express object.
|
216 | */
|
217 | readonly expressApp: express.Express;
|
218 | /**
|
219 | * Reference to the HTTP server.
|
220 | */
|
221 | readonly httpServer: http.Server;
|
222 | /**
|
223 | * Interface for defining the REST API.
|
224 | */
|
225 | readonly rest: IHttpServer;
|
226 | /**
|
227 | * Interface for issuing HTTP requests to a REST API.
|
228 | */
|
229 | readonly request: IHttpRequest;
|
230 | /**
|
231 | * Starts the microservice.
|
232 | * It starts listening for incoming HTTP requests and events.
|
233 | */
|
234 | start(): Promise<void>;
|
235 | /**
|
236 | * Start the HTTP server.
|
237 | * ! No need to call this if you already called 'start'.
|
238 | */
|
239 | startHttpServer(): Promise<void>;
|
240 | /**
|
241 | * Start the RabbitMQ message queue.
|
242 | * ! No need to call this if you already called 'start'.
|
243 | */
|
244 | startMessaging(): Promise<void>;
|
245 | }
|
246 | export declare class MicroService implements IMicroService {
|
247 | private id;
|
248 | private messagingConnection?;
|
249 | private messagingChannel?;
|
250 | private config;
|
251 | private registeredEventHandlers;
|
252 | constructor(config: IMicroServiceConfig);
|
253 | private verbose;
|
254 | /**
|
255 | * Get the name that identifies the service.
|
256 | */
|
257 | getServiceName(): string;
|
258 | /**
|
259 | * Get the instance ID for the particular instance of the service.
|
260 | */
|
261 | getInstanceId(): string;
|
262 | /**
|
263 | * Returns true if the messaging system is currently available.
|
264 | */
|
265 | isMessagingAvailable(): boolean;
|
266 | private internalOn;
|
267 | private internalOff;
|
268 | /**
|
269 | * Create an ongoing handler for a named incoming event.
|
270 | * Implemented by Rabbitmq under the hood for reliable messaging.
|
271 | *
|
272 | * @param eventName The name of the event to handle.
|
273 | * @param eventHandler Callback to be invoke when the incoming event is received.
|
274 | */
|
275 | on<EventArgsT = any>(eventName: string, eventHandlerFn: EventHandlerFn<EventArgsT>): Promise<IEventHandler>;
|
276 | /**
|
277 | * Unregister a previously register event handler.
|
278 | *
|
279 | * @param handler The event handler to unregister.
|
280 | */
|
281 | off(handler: IEventHandler): void;
|
282 | /**
|
283 | * Create a once-off handler for a named incoming event.
|
284 | * The event handler will only be invoke once before the event is unregistered.
|
285 | * Implemented by Rabbitmq under the hood for reliable messaging.
|
286 | *
|
287 | * @param eventName The name of the event to handle.
|
288 | * @param eventHandler Callback to be invoke when the incoming event is received.
|
289 | */
|
290 | once<EventArgsT = any>(eventName: string, eventHandlerFn: EventHandlerFn<EventArgsT>): Promise<void>;
|
291 | /***
|
292 | * Wait for a single incoming event, returns the events arguments and then unregister the event handler.
|
293 | *
|
294 | * @param eventName The name of the event to handle.
|
295 | *
|
296 | * @returns A promise to resolve the incoming event's arguments.
|
297 | */
|
298 | waitForOneEvent<EventArgsT = any>(eventName: string): Promise<EventArgsT>;
|
299 | /**
|
300 | * Emit a named outgoing event.
|
301 | * Implemented by Rabbitmq under the hood for reliable messaging.
|
302 | *
|
303 | * @param eventName The name of the event to emit.
|
304 | * @param eventArgs Event args to publish with the event and be received at the other end.
|
305 | */
|
306 | emit<EventArgsT = any>(eventName: string, eventArgs: EventArgsT): Promise<void>;
|
307 | /**
|
308 | * Reference to the timer interface.
|
309 | * Allows code to be timed for performance.
|
310 | */
|
311 | readonly timer: ITimer;
|
312 | /**
|
313 | * Reference to the metrics interface.
|
314 | * Allows a service to output metrics.
|
315 | */
|
316 | readonly metrics: IMetrics;
|
317 | /**
|
318 | * Reference to the express object.
|
319 | */
|
320 | readonly expressApp: express.Express;
|
321 | /**
|
322 | * Reference to the HTTP server.
|
323 | */
|
324 | readonly httpServer: http.Server;
|
325 | /**
|
326 | * Interface for defining the REST API.
|
327 | */
|
328 | readonly rest: IHttpServer;
|
329 | /**
|
330 | * Interface for issuing HTTP requests to a REST API.
|
331 | */
|
332 | readonly request: IHttpRequest;
|
333 | /**
|
334 | * Start the HTTP server.
|
335 | * ! No need to call this if you already called 'start'.
|
336 | */
|
337 | startHttpServer(): Promise<void>;
|
338 | /**
|
339 | * Start the RabbitMQ message queue.
|
340 | * ! No need to call this if you already called 'start'.
|
341 | */
|
342 | startMessaging(): Promise<void>;
|
343 | /**
|
344 | * Starts the microservice.
|
345 | * It starts listening for incoming HTTP requests and events.
|
346 | */
|
347 | start(): Promise<void>;
|
348 | }
|
349 | /**
|
350 | * Instantiates a microservice.
|
351 | *
|
352 | * @param [config] Optional configuration for the microservice.
|
353 | */
|
354 | export declare function micro(config: IMicroServiceConfig): IMicroService;
|