@ez4/gateway 0.35.0 → 0.36.0

package/dist/services/{contract.d.ts → http/contract.d.ts}

@@ -1,52 +1,64 @@
 import type { Service as CommonService } from '@ez4/common';
 import type { LinkedVariables } from '@ez4/project/library';
-import type { HttpSuccessStatuses, HttpSuccessEmptyResponse, HttpSuccessResponse } from './utils';
+import type { AuthResponse as HttpAuthResponse } from '../auth/response';
+import type { AuthRequest as HttpAuthRequest } from '../auth/request';
+import type { WebJsonBody, WebRawBody } from '../web/body';
+import type { WebPathParameters } from '../web/parameters';
+import type { WebPreferences } from '../web/preferences';
+import type { AuthIdentity } from '../auth/identity';
+import type { WebQueryStrings } from '../web/query';
+import type { WebHeaders } from '../web/headers';
+import type { AuthCache } from '../auth/cache';
+import type { HttpSuccessStatuses, HttpSuccessEmptyResponse, HttpSuccessResponse, HttpEmptyRequest } from './utils';
 import type { HttpAuthorization } from './authorization';
-import type { HttpPreferences } from './preferences';
 import type { HttpDefaults } from './defaults';
 import type { HttpProvider } from './provider';
+import type { HttpListener } from './listener';
+import type { HttpIncoming } from './incoming';
+import type { HttpResponse } from './response';
+import type { HttpRequest } from './request';
+import type { HttpHandler } from './handler';
+import type { HttpClient } from './client';
 import type { HttpAccess } from './access';
+import type { HttpErrors } from './errors';
 import type { HttpRoute } from './route';
-import type { HttpCache } from './cache';
 import type { HttpCors } from './cors';
-import type { Client } from './client';
-import type { HttpHeaders, HttpIdentity, HttpPathParameters, HttpQueryStrings, HttpJsonBody, HttpRawBody, HttpAuthRequest, HttpAuthResponse, HttpRequest, HttpResponse, HttpErrors, HttpIncoming, HttpListener, HttpAuthorizer, HttpHandler } from './common';
 /**
  * Provide all contracts for a self-managed HTTP service.
  */
 export declare namespace Http {
-    type Headers = HttpHeaders;
-    type Identity = HttpIdentity;
-    type PathParameters = HttpPathParameters;
-    type QueryStrings = HttpQueryStrings;
-    type JsonBody = HttpJsonBody;
-    type RawBody = HttpRawBody;
+    type Headers = WebHeaders;
+    type Identity = AuthIdentity;
+    type PathParameters = WebPathParameters;
+    type QueryStrings = WebQueryStrings;
+    type JsonBody = WebJsonBody;
+    type RawBody = WebRawBody;
     type Authorization = HttpAuthorization;
-    type Preferences = HttpPreferences;
-    type AuthRequest = HttpAuthRequest;
+    type Access = HttpAccess;
+    type Preferences = WebPreferences;
+    type Cache = AuthCache;
     type Request = HttpRequest;
-    type AuthResponse = HttpAuthResponse;
     type Response = HttpResponse;
+    type AuthRequest = HttpAuthRequest;
+    type AuthResponse = HttpAuthResponse;
     type Errors = HttpErrors;
     type Provider = HttpProvider;
-    type Cache = HttpCache;
-    type Access = HttpAccess;
     type Cors = HttpCors;
-    type Incoming<T extends Request | AuthRequest> = HttpIncoming<T>;
-    type Listener<T extends Request | AuthRequest> = HttpListener<T>;
-    type Authorizer<T extends AuthRequest> = HttpAuthorizer<T>;
+    type Incoming<T extends Request> = HttpIncoming<T>;
+    type Listener<T extends Request> = HttpListener<T>;
     type Handler<T extends Request> = HttpHandler<T>;
     type Route<T extends Request = Request, U extends AuthRequest = AuthRequest> = HttpRoute<T, U>;
-    type Defaults<T extends HttpRequest | HttpAuthRequest = any> = HttpDefaults<T>;
-    type ServiceEvent<T extends Request | AuthRequest = Request> = CommonService.AnyEvent<Incoming<T>>;
+    type Defaults<T extends Request = Request> = HttpDefaults<T>;
+    type ServiceEvent<T extends Request = Request> = CommonService.AnyEvent<Incoming<T>>;
     type SuccessEmptyResponse<S extends HttpSuccessStatuses = 204> = HttpSuccessEmptyResponse<S>;
-    type SuccessResponse<S extends HttpSuccessStatuses, T extends HttpRawBody | HttpJsonBody> = HttpSuccessResponse<S, T>;
+    type SuccessResponse<S extends HttpSuccessStatuses, T extends JsonBody | RawBody> = HttpSuccessResponse<S, T>;
+    type EmptyRequest = HttpEmptyRequest;
     /**
      * HTTP Route definition.
      */
     type UseRoute<T extends Route<any, any>> = T;
     /**
-     * HTTP Service definition.
+     * HTTP Defaults definition.
      */
     type UseDefaults<T extends Defaults<any>> = T;
     /**
@@ -74,7 +86,7 @@ export declare namespace Http {
      */
     abstract class Service implements CommonService.Provider {
         /**
-         * All expected routes.
+         * All routes associated to the gateway.
          */
         abstract readonly routes: Route<any, any>[];
         /**
@@ -82,19 +94,19 @@ export declare namespace Http {
          */
         readonly name?: string;
         /**
-         * Default parameters.
+         * Default gateway parameters.
          */
         readonly defaults?: Defaults<any>;
         /**
-         * CORS configuration.
+         * CORS configuration for all routes.
          */
         readonly cors?: Cors;
         /**
-         * Cache configuration.
+         * Cache configuration for authorizers.
          */
         readonly cache?: Cache;
         /**
-         * Access configuration.
+         * Access configuration for logs.
          */
         readonly access?: Access;
         /**
@@ -104,7 +116,7 @@ export declare namespace Http {
         /**
          * Service client.
          */
-        readonly client: Client<Service>;
+        readonly client: HttpClient<Service>;
     }
     /**
      * Imported HTTP service.
@@ -137,7 +149,7 @@ export declare namespace Http {
         /**
          * Imported service client (do not replace).
          */
-        readonly client: Client<T>;
+        readonly client: HttpClient<T>;
         /**
          * Variables are not allowed.
          */

package/dist/services/http/defaults.d.ts

@@ -0,0 +1,17 @@
+import type { WebDefaults } from '../web/defaults';
+import type { HttpListener } from './listener';
+import type { HttpRequest } from './request';
+import type { HttpErrors } from './errors';
+/**
+ * Default HTTP service parameters.
+ */
+export interface HttpDefaults<T extends HttpRequest> extends WebDefaults {
+    /**
+     * Default listener.
+     */
+    readonly listener?: HttpListener<T>;
+    /**
+     * Status codes for all known exceptions.
+     */
+    readonly httpErrors?: HttpErrors;
+}

package/dist/services/http/errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * HTTP errors.
+ */
+export type HttpErrors = {
+    [code: number]: readonly Error[];
+};

package/dist/services/http/handler.d.ts

@@ -0,0 +1,10 @@
+import type { Service } from '@ez4/common';
+import type { HttpProvider } from './provider';
+import type { HttpIncoming } from './incoming';
+import type { HttpResponse } from './response';
+import type { HttpRequest } from './request';
+import type { Http } from './contract';
+/**
+ * HTTP request handler.
+ */
+export type HttpHandler<T extends HttpRequest> = (request: HttpIncoming<T> | T, context: Service.Context<Http.Service | HttpProvider>) => Promise<HttpResponse> | HttpResponse;

package/dist/services/http/incoming.d.ts

@@ -0,0 +1,30 @@
+import type { HttpRequest } from './request';
+/**
+ * Incoming request.
+ */
+export type HttpIncoming<T extends HttpRequest> = T & {
+    /**
+     * Request tracking Id.
+     */
+    readonly requestId: string;
+    /**
+     * Determines whether request is base64 encoded or not.
+     */
+    readonly encoded?: boolean;
+    /**
+     * Request timestamp.
+     */
+    readonly timestamp: Date;
+    /**
+     * Request method.
+     */
+    readonly method: string;
+    /**
+     * Request path.
+     */
+    readonly path: string;
+    /**
+     * Raw body data (when provided in the request).
+     */
+    readonly data?: string;
+};

package/dist/services/http/listener.d.ts

@@ -0,0 +1,9 @@
+import type { Service } from '@ez4/common';
+import type { HttpProvider } from './provider';
+import type { HttpIncoming } from './incoming';
+import type { HttpRequest } from './request';
+import type { Http } from './contract';
+/**
+ * HTTP request listener.
+ */
+export type HttpListener<T extends HttpRequest> = (event: Service.AnyEvent<HttpIncoming<T>>, context: Service.Context<Http.Service | HttpProvider>) => Promise<void> | void;

package/dist/services/http/path.d.ts

@@ -0,0 +1,2 @@
+export type HttpVerb = 'ANY' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+export type HttpPath = `${HttpVerb} /${string}`;

package/dist/services/http/request.d.ts

@@ -0,0 +1,30 @@
+import type { AuthIdentity } from '../auth/identity';
+import type { WebPathParameters } from '../web/parameters';
+import type { WebQueryStrings } from '../web/query';
+import type { WebHeaders } from '../web/headers';
+import type { WebBody } from '../web/body';
+/**
+ * HTTP request.
+ */
+export interface HttpRequest {
+    /**
+     * Expected identity.
+     */
+    readonly identity?: AuthIdentity;
+    /**
+     * Expected HTTP headers.
+     */
+    readonly headers?: WebHeaders;
+    /**
+     * Expected HTTP path parameters.
+     */
+    readonly parameters?: WebPathParameters;
+    /**
+     * Expected HTTP query strings.
+     */
+    readonly query?: WebQueryStrings;
+    /**
+     * Expected HTTP body payload.
+     */
+    readonly body?: WebBody;
+}

package/dist/services/http/response.d.ts

@@ -0,0 +1,19 @@
+import type { WebHeaders } from '../web/headers';
+import type { WebBody } from '../web/body';
+/**
+ * HTTP response.
+ */
+export interface HttpResponse {
+    /**
+     * HTTP status code.
+     */
+    readonly status: number;
+    /**
+     * HTTP headers.
+     */
+    readonly headers?: WebHeaders;
+    /**
+     * HTTP body payload.
+     */
+    readonly body?: WebBody;
+}

package/dist/services/http/route.d.ts

@@ -0,0 +1,45 @@
+import type { AuthHandler } from '../auth/handler';
+import type { AuthRequest } from '../auth/request';
+import type { WebTarget } from '../web/target';
+import type { HttpListener } from './listener';
+import type { HttpRequest } from './request';
+import type { HttpHandler } from './handler';
+import type { HttpErrors } from './errors';
+import type { HttpPath } from './path';
+/**
+ * HTTP route.
+ */
+export interface HttpRoute<T extends HttpRequest, U extends AuthRequest> extends WebTarget {
+    /**
+     * Route operation name.
+     */
+    readonly name?: string;
+    /**
+     * Route path including the HTTP verb.
+     */
+    readonly path: HttpPath;
+    /**
+     * Life-cycle listener function for the route.
+     */
+    readonly listener?: HttpListener<T>;
+    /**
+     * Entry-point authorizer handler function for the route.
+     */
+    readonly authorizer?: AuthHandler<U>;
+    /**
+     * Entry-point handler function for the route.
+     */
+    readonly handler: HttpHandler<T>;
+    /**
+     * Map status codes and errors for all known exceptions.
+     */
+    readonly httpErrors?: HttpErrors;
+    /**
+     * Determines whether or not the route is disabled.
+     */
+    readonly disabled?: boolean;
+    /**
+     * Determines whether or not CORS is enabled for the route.
+     */
+    readonly cors?: boolean;
+}

package/dist/services/{utils.d.ts → http/utils.d.ts}

@@ -1,18 +1,26 @@
-import type { HttpResponse, HttpJsonBody, HttpRawBody } from './common';
+import type { Http } from './contract';
+/**
+ * HTTP success status codes.
+ */
 export type HttpSuccessStatuses = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208;
 /**
- * Common HTTP success response without a response body.
+ * HTTP empty request.
+ */
+export declare class HttpEmptyRequest implements Http.Request {
+}
+/**
+ * HTTP success response without a response body.
  */
-export declare class HttpSuccessEmptyResponse<S extends HttpSuccessStatuses> implements HttpResponse {
+export declare class HttpSuccessEmptyResponse<S extends HttpSuccessStatuses> implements Http.Response {
     /**
      * HTTP status code.
      */
     readonly status: S;
 }
 /**
- * Common HTTP success response.
+ * HTTP success response.
  */
-export declare class HttpSuccessResponse<S extends HttpSuccessStatuses, T extends HttpJsonBody | HttpRawBody> implements HttpResponse {
+export declare class HttpSuccessResponse<S extends HttpSuccessStatuses, T extends Http.JsonBody | Http.RawBody> implements Http.Response {
     /**
      * HTTP status code.
      */

package/dist/services/web/body.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Json body payload.
+ */
+export interface WebJsonBody {
+}
+/**
+ * Raw body payload.
+ */
+export type WebRawBody = string;
+/**
+ * Body payload.
+ */
+export type WebBody = WebJsonBody | WebRawBody;

package/dist/services/web/defaults.d.ts

@@ -0,0 +1,22 @@
+import type { WebPreferences } from './preferences';
+/**
+ * Default service parameters.
+ */
+export interface WebDefaults {
+    /**
+     * Default preferences for all handlers.
+     */
+    readonly preferences?: WebPreferences;
+    /**
+     * Default log retention (in days) for the handlers.
+     */
+    readonly logRetention?: number;
+    /**
+     * Default execution time (in seconds) for handlers.
+     */
+    readonly timeout?: number;
+    /**
+     * Default amount of memory available (in megabytes) for handlers.
+     */
+    readonly memory?: number;
+}

package/dist/services/web/headers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Request headers.
+ */
+export interface WebHeaders {
+}
+/**
+ * Request path parameters.
+ */
+export interface WebPathParameters {
+}

package/dist/services/web/parameters.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Request path parameters.
+ */
+export interface WebPathParameters {
+}

package/dist/services/{preferences.d.ts → web/preferences.d.ts}

@@ -1,8 +1,8 @@
 import type { NamingStyle } from '@ez4/schema';
 /**
- * HTTP preferences configuration.
+ * Preferences configuration.
  */
-export interface HttpPreferences {
+export interface WebPreferences {
     /**
      * Determines the naming style for the query strings and body payloads.
      */

package/dist/services/web/query.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Request query strings.
+ */
+export interface WebQueryStrings {
+}

package/dist/services/web/target.d.ts

@@ -0,0 +1,27 @@
+import type { LinkedVariables } from '@ez4/project/library';
+import type { WebPreferences } from './preferences';
+/**
+ * Target configuration.
+ */
+export interface WebTarget {
+    /**
+     * Target preference options.
+     */
+    readonly preferences?: WebPreferences;
+    /**
+     * Default log retention (in days) for the handlers.
+     */
+    readonly logRetention?: number;
+    /**
+     * Variables associated to the event.
+     */
+    readonly variables?: LinkedVariables;
+    /**
+     * Max execution time (in seconds) for the event.
+     */
+    readonly timeout?: number;
+    /**
+     * Amount of memory available (in megabytes) for the handler.
+     */
+    readonly memory?: number;
+}

package/dist/services/ws/client.d.ts

@@ -0,0 +1,19 @@
+import type { Ws } from './contract';
+/**
+ * WS client.
+ */
+export interface WsClient<T extends Ws.JsonBody> {
+    /**
+     * Send a new JSON message to the connection.
+     *
+     * @param connectionId Connection identifier.
+     * @param message Message object.
+     */
+    sendMessage(connectionId: string, message: T): Promise<void>;
+    /**
+     * Terminate an active connection.
+     *
+     * @param connectionId Connection identifier.
+     */
+    disconnect(connectionId: string): Promise<void>;
+}

package/dist/services/ws/connect.d.ts

@@ -0,0 +1,23 @@
+import type { AuthHandler } from '../auth/handler';
+import type { AuthRequest } from '../auth/request';
+import type { WebTarget } from '../web/target';
+import type { WsListener } from './listener';
+import type { WsHandler } from './handler';
+import type { WsEvent } from './event';
+/**
+ * WS connect event.
+ */
+export interface WsConnect<T extends WsEvent, U extends AuthRequest> extends WebTarget {
+    /**
+     * Life-cycle listener function for the event.
+     */
+    readonly listener?: WsListener<T>;
+    /**
+     * Entry-point authorizer handler function for the event.
+     */
+    readonly authorizer?: AuthHandler<U>;
+    /**
+     * Entry-point handler function for the event.
+     */
+    readonly handler: WsHandler<T>;
+}

package/dist/services/ws/contract.d.ts

@@ -0,0 +1,108 @@
+import type { Service as CommonService } from '@ez4/common';
+import type { LinkedVariables } from '@ez4/project/library';
+import type { AuthResponse as WsAuthResponse } from '../auth/response';
+import type { AuthRequest as WsAuthRequest } from '../auth/request';
+import type { WebJsonBody, WebRawBody } from '../web/body';
+import type { WebPreferences } from '../web/preferences';
+import type { AuthIdentity } from '../auth/identity';
+import type { WebQueryStrings } from '../web/query';
+import type { WebHeaders } from '../web/headers';
+import type { WsEmptyEvent, WsEmptyRequest } from './utils';
+import type { WsDisconnect } from './disconnect';
+import type { WsDefaults } from './defaults';
+import type { WsIncoming } from './incoming';
+import type { WsListener } from './listener';
+import type { WsResponse } from './response';
+import type { WsRequest } from './request';
+import type { WsHandler } from './handler';
+import type { WsMessage } from './message';
+import type { WsConnect } from './connect';
+import type { WsClient } from './client';
+import type { WsEvent } from './event';
+/**
+ * Provide all contracts for a self-managed WS service.
+ */
+export declare namespace Ws {
+    type Headers = WebHeaders;
+    type Identity = AuthIdentity;
+    type QueryStrings = WebQueryStrings;
+    type JsonBody = WebJsonBody;
+    type RawBody = WebRawBody;
+    type Preferences = WebPreferences;
+    type Request = WsRequest;
+    type Response = WsResponse;
+    type Event = WsEvent;
+    type AuthRequest = WsAuthRequest;
+    type AuthResponse = WsAuthResponse;
+    type Incoming<T extends Request | Event> = WsIncoming<T>;
+    type Listener<T extends Request | Event> = WsListener<T>;
+    type Handler<T extends Request | Event> = WsHandler<T>;
+    type Connect<T extends Event = Event, U extends AuthRequest = AuthRequest> = WsConnect<T, U>;
+    type Disconnect<T extends Event = Event> = WsDisconnect<T>;
+    type Message<T extends Request = Request> = WsMessage<T>;
+    type Defaults<T extends Request | Event = any> = WsDefaults<T>;
+    type ServiceEvent<T extends Request | Event = Event> = CommonService.AnyEvent<Incoming<T>>;
+    type EmptyRequest = WsEmptyRequest;
+    type EmptyEvent = WsEmptyEvent;
+    /**
+     * WS Defaults definition.
+     */
+    type UseDefaults<T extends Defaults<any>> = T;
+    /**
+     * WS Preferences definition.
+     */
+    type UsePreferences<T extends Preferences> = T;
+    /**
+     * WS Connect event definition.
+     */
+    type UseConnect<T extends Connect<any, any>> = T;
+    /**
+     * WS Disconnect event definition.
+     */
+    type UseDisconnect<T extends Disconnect<any>> = T;
+    /**
+     * WS Message event definition.
+     */
+    type UseMessage<T extends Message<any>> = T;
+    /**
+     * WS service.
+     */
+    abstract class Service<T extends JsonBody> implements CommonService.Provider {
+        /**
+         * All connection events.
+         */
+        abstract readonly connect: Connect<any, any>;
+        /**
+         * All disconnection events.
+         */
+        abstract readonly disconnect: Disconnect<any>;
+        /**
+         * All message events.
+         */
+        abstract readonly message: Message<any>;
+        /**
+         * Default gateway parameters.
+         */
+        readonly defaults?: Defaults<any>;
+        /**
+         * Display name for the service.
+         */
+        readonly name?: string;
+        /**
+         * Service stage name.
+         */
+        readonly stage?: string;
+        /**
+         * Service schema.
+         */
+        readonly schema: T;
+        /**
+         * Variables associated to all routes.
+         */
+        readonly variables?: LinkedVariables;
+        /**
+         * Service client.
+         */
+        readonly client: WsClient<T>;
+    }
+}

package/dist/services/ws/defaults.d.ts

@@ -0,0 +1,13 @@
+import type { WebDefaults } from '../web/defaults';
+import type { WsRequest } from './request';
+import type { WsListener } from './listener';
+import type { WsEvent } from './event';
+/**
+ * Default WS service parameters.
+ */
+export interface WsDefaults<T extends WsRequest | WsEvent> extends WebDefaults {
+    /**
+     * Default listener.
+     */
+    readonly listener?: WsListener<T>;
+}

package/dist/services/ws/disconnect.d.ts

@@ -0,0 +1,17 @@
+import type { WebTarget } from '../web/target';
+import type { WsListener } from './listener';
+import type { WsHandler } from './handler';
+import type { WsEvent } from './event';
+/**
+ * WS disconnect event.
+ */
+export interface WsDisconnect<T extends WsEvent> extends WebTarget {
+    /**
+     * Life-cycle listener function for the event.
+     */
+    readonly listener?: WsListener<T>;
+    /**
+     * Entry-point handler function for the event.
+     */
+    readonly handler: WsHandler<T>;
+}

package/dist/services/ws/event.d.ts

@@ -0,0 +1,20 @@
+import type { AuthIdentity } from '../auth/identity';
+import type { WebQueryStrings } from '../web/query';
+import type { WebHeaders } from '../web/headers';
+/**
+ * WS event.
+ */
+export interface WsEvent {
+    /**
+     * Expected HTTP headers.
+     */
+    readonly headers?: WebHeaders;
+    /**
+     * Expected HTTP query strings.
+     */
+    readonly query?: WebQueryStrings;
+    /**
+     * Expected identity.
+     */
+    readonly identity?: AuthIdentity;
+}