@fiado/gateway-adapter
Advanced tools
Facilita la comunicación e integración entre AWS Lambda y API Gateway , sqs y Event Bridge
@fiado/gateway-adapter es la libreria core del ecosistema Fiado que actua como router central para todos los eventos que recibe una funcion Lambda. Proporciona:
En el modelo de desarrollo Fiado, cada Lambda recibe multiples tipos de eventos:
Esta libreria unifica el manejo de todos estos eventos en un unico punto de entrada.
LAMBDA HANDLER
index.ts
|
v
+---------------+
| GatewayAdapter | <-- Router Principal
+-------+-------+
|
+-------------------+-------------------+
v v v
+-----------------+ +-----------------+ +-----------------+
|ApiGatewayAdapter| |QueueGatewayAdapter| |EventBridgeAdapter|
+--------+--------+ +--------+--------+ +--------+--------+
| | |
v v v
+-----------------+ +-----------------+ +-----------------+
| Controllers | | SQS Subscriber | | EB Subscriber |
| Public/Private/ | |IMessageSubscriber| |IEventBridgeSub |
| Backoffice | | | | |
+-----------------+ +-----------------+ +-----------------+
El GatewayAdapter detecta automaticamente el tipo de evento:
event.httpMethod existeevent.Records[0].eventSource === 'aws:sqs'event.source === 'EVENT_BRIDGE'npm install @fiado/gateway-adapter
{
"@fiado/logger": "^1.0.2",
"@fiado/type-kit": "^2.1.35",
"inversify": "^6.2.2",
"reflect-metadata": "^0.2.2"
}
import { Container } from "inversify";
import {
gatewayAdapterBindings,
TypeQueue,
TypeEventBridge,
IController,
IMessageSubscriber,
IEventBridgeMessageSubscriber
} from "@fiado/gateway-adapter";
const container = new Container();
// Cargar bindings del gateway adapter
container.load(gatewayAdapterBindings);
// Registrar controladores del proyecto
container.bind<IController>('PublicController').to(PublicController);
container.bind<IController>('PrivateController').to(PrivateController);
container.bind<IController>('BackofficeController').to(BackofficeController);
// Registrar subscriber de SQS (si aplica)
container.bind<IMessageSubscriber<any>>("SQSMessageSubscriber").to(MySqsSubscriber);
container.bind<() => IMessageSubscriber<any>>(TypeQueue.SQSMessageSubscriberFactory)
.toAutoFactory("SQSMessageSubscriber");
// Registrar subscriber de EventBridge (si aplica)
container.bind<IEventBridgeMessageSubscriber<any>>("EventBridgeMessageSubscriber")
.to(MyEventBridgeSubscriber);
container.bind<() => IEventBridgeMessageSubscriber<any>>(
TypeEventBridge.EventBridgeMessageSubscriberFactory
).toAutoFactory("EventBridgeMessageSubscriber");
export { container };
import 'reflect-metadata';
import warmer from "lambda-warmer";
import { container } from './container.config';
import { GatewayAdapter, TypeGateway } from '@fiado/gateway-adapter';
import { log } from "@fiado/logger";
export const handler = async (event: any, context: any) => {
// Soporte para lambda warming
if (await warmer(event)) {
return 'warmed';
}
log.info(`Event received: ${JSON.stringify(event)}`);
// Obtener el router y ejecutar
const gatewayAdapter = container.get<GatewayAdapter>(TypeGateway.GatewayAdapter);
return await gatewayAdapter.execute(event);
}
El GatewayAdapter es el componente central que detecta el tipo de evento y lo enruta al adaptador correspondiente.
| Tipo | Deteccion | Adaptador |
|---|---|---|
| API Gateway | event.httpMethod existe | ApiGatewayAdapter |
| SQS | event.Records[0].eventSource === 'aws:sqs' | QueueGatewayAdapter |
| EventBridge | event.source === 'EVENT_BRIDGE' | EventBridgeGatewayAdapter |
import { GatewayAdapter, TypeGateway } from '@fiado/gateway-adapter';
const gatewayAdapter = container.get<GatewayAdapter>(TypeGateway.GatewayAdapter);
// El adapter detecta automaticamente el tipo de evento
const result = await gatewayAdapter.execute(event);
Interface tipada que representa una peticion HTTP transformada:
interface ApiGatewayRequest<TBody> {
body: TBody | null; // Body parseado
headers: { [key: string]: string | undefined }; // Headers HTTP
method: string; // GET, POST, PUT, DELETE
pathParameter: { [key: string]: string | undefined }; // Path params (/users/:id)
queryStringParameters: { [key: string]: string }; // Query params (?key=value)
multiValueQueryStringParameters: { [key: string]: string[] }; // Arrays
token: TokenPayload | undefined | null; // Token JWT decodificado
operationName: string | null; // Nombre de la operacion
base64EncodedFile?: string; // Archivos en base64
requestContext: { identity?: { sourceIp?: string } }; // Contexto de request
}
Los controladores se identifican por prefijo en el operationName:
| Prefijo | Controlador | Uso |
|---|---|---|
public* | PublicController | Endpoints publicos (internet) |
private* | PrivateController | Endpoints privados (VPC) |
backoffice* | BackofficeController | Endpoints administrativos |
agent* / agents* | AgentController | Endpoints de agentes |
import { injectable, inject } from 'inversify';
import {
IController,
ApiGatewayRequest,
ApiResponse,
AuthorizedFeatures,
Feature,
Endpoint,
HttpMethod,
SecurityType
} from '@fiado/gateway-adapter';
@injectable()
export class PublicController implements IController {
constructor(
@inject("IUserManager") private userManager: IUserManager
) {}
@AuthorizedFeatures(Feature.ANONIMUS)
@Endpoint({
method: HttpMethod.GET,
path: '/users/:id',
summary: 'Obtener usuario por ID',
tags: ['PublicController'],
security: SecurityType.CognitoAppAuthorizer
})
async getUser(request: ApiGatewayRequest<void>): Promise<any> {
const userId = request.pathParameter?.id;
const user = await this.userManager.getById(userId);
return ApiResponse.success({ data: user });
}
@AuthorizedFeatures(Feature.ANONIMUS)
@Endpoint({
method: HttpMethod.POST,
path: '/users',
summary: 'Crear usuario',
tags: ['PublicController'],
security: SecurityType.CognitoAppAuthorizer
})
async createUser(request: ApiGatewayRequest<CreateUserDto>): Promise<any> {
const user = await this.userManager.create(request.body);
return ApiResponse.created({ data: user });
}
}
Servicio para decodificar tokens JWT de Cognito:
import { TokenService } from '@fiado/gateway-adapter';
const tokenService = new TokenService();
const payload = tokenService.decodeToken(bearerToken);
// payload contiene:
// - sub: ID del usuario
// - email: Email del usuario
// - permissions: Array de permisos/features
// - cognito:groups: Grupos de Cognito
Interface para procesar mensajes de SQS:
export interface IMessageSubscriber<T> {
handle(messageBody: T, receiptHandle: string): Promise<void>;
deleteMessage(queueUrl: string, receiptHandle: string): Promise<void>;
}
import { injectable } from 'inversify';
import { IMessageSubscriber } from '@fiado/gateway-adapter';
import { log } from '@fiado/logger';
@injectable()
export class OrderMessageSubscriber implements IMessageSubscriber<OrderMessage> {
async handle(messageBody: OrderMessage, receiptHandle: string): Promise<void> {
log.info('Processing order message', { orderId: messageBody.orderId });
await this.processOrder(messageBody);
}
async deleteMessage(queueUrl: string, receiptHandle: string): Promise<void> {
// Implementar si se necesita borrado manual
}
private async processOrder(order: OrderMessage): Promise<void> {
// Logica de procesamiento
}
}
Interface para publicar mensajes a SQS:
export interface IMessagePublisher<T> {
publish(messageBody: T, options?: PublishOptions): Promise<void>;
}
Interface para procesar eventos de EventBridge:
import { EventBridgeMessageRequest } from "@fiado/type-kit";
export interface IEventBridgeMessageSubscriber<TPayload> {
handle(message: EventBridgeMessageRequest<TPayload>): Promise<void>;
}
import { injectable } from 'inversify';
import { IEventBridgeMessageSubscriber } from '@fiado/gateway-adapter';
import { EventBridgeMessageRequest } from '@fiado/type-kit';
@injectable()
export class PaymentEventSubscriber implements IEventBridgeMessageSubscriber<PaymentEvent> {
async handle(message: EventBridgeMessageRequest<PaymentEvent>): Promise<void> {
const { payload, eventType } = message;
switch (eventType) {
case 'PAYMENT_COMPLETED':
await this.handlePaymentCompleted(payload);
break;
case 'PAYMENT_FAILED':
await this.handlePaymentFailed(payload);
break;
}
}
}
Decorador para definir que features/permisos pueden acceder a un metodo:
import { AuthorizedFeatures, Feature } from '@fiado/gateway-adapter';
// Acceso anonimo (sin token)
@AuthorizedFeatures(Feature.ANONIMUS)
async publicEndpoint(request: ApiGatewayRequest<any>): Promise<any> { }
// Requiere feature especifico en el token
@AuthorizedFeatures(Feature.PAYROLL)
async payrollEndpoint(request: ApiGatewayRequest<any>): Promise<any> { }
// Multiples features (OR - cualquiera autoriza)
@AuthorizedFeatures(Feature.ADMIN, Feature.MANAGER)
async adminEndpoint(request: ApiGatewayRequest<any>): Promise<any> { }
export enum Feature {
ANONIMUS = "ANONIMUS", // Acceso publico sin autenticacion
TEST = "test",
FEATURE1 = "feature1",
PAYROLL = "PAYROLL"
}
Decorador para definir metadata del endpoint (usado para generacion OpenAPI):
import { Endpoint, HttpMethod, SecurityType } from '@fiado/gateway-adapter';
@Endpoint({
method: HttpMethod.POST,
path: '/payments',
summary: 'Procesar pago',
tags: ['PaymentController'],
security: SecurityType.CognitoAppAuthorizer,
queryParams: ['currency'],
pathParams: ['id']
})
async processPayment(request: ApiGatewayRequest<PaymentDto>): Promise<any> { }
export enum HttpMethod {
GET = 'get',
POST = 'post',
PUT = 'put',
DELETE = 'delete'
}
export enum SecurityType {
CognitoAppAuthorizer = 'CognitoAppAuthorizer', // Usuarios de la app
CognitoBackofficeAuthorizer = 'CognitoBackofficeAuthorizer', // Administradores
CognitoCombinedAuthorizer = 'CognitoCombinedAuthorizer', // Ambos pools
CognitoAgentAuthorizer = 'CognitoAgentAuthorizer' // Agentes
}
Clase estatica para construir respuestas HTTP estandarizadas:
import { ApiResponse } from '@fiado/gateway-adapter';
// 200 OK
return ApiResponse.success({ data: result, msg: 'Operacion exitosa' });
// 201 Created
return ApiResponse.created({ data: newResource });
// 400 Bad Request
return ApiResponse.badRequest({ code: 'VALIDATION_ERROR', msg: 'Campo requerido' });
// 401 Unauthorized
return ApiResponse.unauthorized({ msg: 'Token invalido' });
// 403 Forbidden
return ApiResponse.forbidden({ msg: 'Acceso denegado' });
// 404 Not Found
return ApiResponse.notFound({ msg: 'Recurso no encontrado' });
// 425 Too Early
return ApiResponse.tooEarly({ msg: 'Intente mas tarde' });
// 500 Internal Server Error
return ApiResponse.internalServerError({ msg: 'Error interno' });
// 302 Redirect
return ApiResponse.redirect({ data: { url: 'https://...' } });
// Redireccion real con header Location
return ApiResponse.redirectTo('https://example.com/callback', 302);
Todas las respuestas siguen el formato estandar:
{
statusCode: 200,
headers: {
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Headers": "*",
"Access-Control-Allow-Methods": "*",
"Content-Type": "application/json"
},
body: {
code: "PROCESS_OK", // Codigo de respuesta
date: "2024-01-15T...", // Timestamp ISO
data: { ... }, // Datos de respuesta
description: null, // Descripcion opcional
msg: null, // Mensaje opcional
encrypted: false // Flag de encriptacion (opcional)
}
}
interface ResponseOptions<T> {
data?: T; // Datos a retornar
code?: string; // Codigo personalizado
msg?: string; // Mensaje
description?: string; // Descripcion
encrypted?: boolean; // Flag de encriptacion
}
Servicio para encriptar respuestas sensibles usando JWE (JSON Web Encryption):
Variables de entorno para habilitar encriptacion:
Environment:
Variables:
# Encriptar TODOS los endpoints de app
JWE_ENCRYPTION_APP: "true"
# O encriptar endpoints especificos
JWE_ENCRYPTION_APP_ENDPOINTS: "publicGetBalance,publicGetTransactions"
# Para backoffice
JWE_ENCRYPTION_BACKOFFICE: "true"
JWE_ENCRYPTION_BACKOFFICE_ENDPOINTS: "backofficeGetUserData"
x-session-key con session key encriptada (JWE con llave publica RSA)data se encripta con AES-256-GCM usando session keyLa encriptacion se aplica automaticamente si:
x-session-key// La respuesta se encripta automaticamente
return ApiResponse.success({ data: sensitiveData });
// Respuesta encriptada:
{
code: "PROCESS_OK",
data: "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0...", // JWE
encrypted: true
}
src/
├── index.ts # Exportaciones publicas
├── container.config.ts # ContainerModule con bindings
├── GatewayAdapter.ts # Router principal
│
├── apigateway/ # Modulo API Gateway
│ ├── abstractions/
│ │ ├── ApiGatewayRequest.ts
│ │ ├── ApiGatewayResponse.ts
│ │ ├── FeatureEnum.ts
│ │ ├── IController.ts
│ │ ├── ResponseOptions.ts
│ │ ├── StandardResponse.ts
│ │ └── TypeGateway.ts
│ ├── decorators/
│ │ └── AuthorizedFeatures.ts
│ └── services/
│ ├── ActivitySessionService.ts
│ ├── ApiGatewayAdapter.ts
│ ├── ApiResponse.ts
│ ├── JweEncryptionService.ts
│ └── TokenService.ts
│
├── queue/ # Modulo SQS
│ ├── abstractions/
│ │ ├── IMessagePublisher.ts
│ │ ├── IMessageSubscriber.ts
│ │ ├── IPublishOptions.ts
│ │ └── TypeQueue.ts
│ ├── decorators/
│ └── services/
│ └── QueueGatewayAdapter.ts
│
├── eventBridge/ # Modulo EventBridge
│ ├── abstractions/
│ │ ├── IEventBridgeMessageSubscriber.ts
│ │ └── TypeEventBridge.ts
│ └── service/
│ └── EventBridgeGatewayAdapter.ts
│
└── endpoint/ # Decorador @Endpoint
└── endpointDecorator.ts
| Dependencia | Version | Proposito |
|---|---|---|
@fiado/api-invoker | ^1.4.6 | Invocacion de APIs internas |
@fiado/logger | ^1.0.2 | Logging estructurado |
@fiado/type-kit | ^2.1.35 | DTOs y tipos compartidos |
aws-lambda | ^1.0.7 | Tipos de AWS Lambda |
inversify | ^6.2.2 | Inyeccion de dependencias |
jose | ^4.15.5 | Encriptacion JWE |
jsonwebtoken | ^9.0.2 | Decodificacion JWT |
reflect-metadata | ^0.2.2 | Metadatos para decoradores |
uuid | ^9.0.1 | Generacion de UUIDs |
| Dependencia | Version | Proposito |
|---|---|---|
@types/jsonwebtoken | ^9.0.6 | Tipos de jsonwebtoken |
npm run build
Genera archivos .js y .d.ts en el directorio bin/.
npm version patch|minor|major
npm publish
Fiado Inc. | @fiado/gateway-adapter v1.1.59
FAQs
Facilita la comunicación e integración entre AWS Lambda y API Gateway , sqs y Event Bridge
We found that @fiado/gateway-adapter demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Socket uncovered secret-stealing workflows that ran in LiteLLM’s GitHub repository 11 days before the supply chain attack on PyPI and Docker.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.