@fran-834/gs-microservice-core/README.md

Core package for Node.js microservices by Galduria Software. Includes security, logging, validation, and error handling middlewares.

# Galduria Software – Microservice Core

`gs-microservice-core` es un paquete **opinionated** para la creación de microservicios basados en **Node.js y Express**, utilizado como núcleo común en la plataforma **Factal** y en otros productos de Galduria Software.

Su objetivo es **estandarizar y acelerar** la creación de microservicios proporcionando una configuración base común que incluye middlewares, logging, validación, manejo de errores y utilidades transversales.

Este paquete está pensado **principalmente para uso interno**, aunque se publica de forma abierta para facilitar su reutilización, pruebas y despliegue.  
No contiene **claves, secretos, certificados ni lógica de negocio sensible**.

## License

ISC

## Funcionalidades

`gs-microservice-core` proporciona un conjunto de funcionalidades comunes para microservicios Node.js/Express, con el objetivo de reducir código repetido y garantizar comportamientos homogéneos entre servicios.

Incluye, entre otras, las siguientes características:

- **Inicialización estandarizada de Express**
  - Configuración base de la aplicación.
  - Preparado para ejecutarse detrás de proxies (Nginx, load balancers).

- **Logging centralizado y estructurado**
  - Integración con Morgan y Winston.
  - Logs en formato JSON, pensados para sistemas como CloudWatch.
  - Inclusión automática de información de contexto (requestId, navegador, sistema operativo, tipo de dispositivo, etc.).

- **Identificador único de petición (requestId)**
  - Asignación automática de un identificador único por request.
  - Permite trazar una petición a través de múltiples microservicios.

- **Detección de User-Agent**
  - Identificación del navegador, sistema operativo y tipo de dispositivo (desktop, mobile, tablet).
  - Información accesible desde el contexto de la petición y disponible en los logs.

- **Validación de esquemas**
  - Validación de payloads mediante esquemas JSON (AJV).
  - Respuestas de error homogéneas ante datos inválidos.

- **Autenticación basada en JWT**
  - Middleware opcional para validación de tokens JWT.
  - Pensado para escenarios de microservicios detrás de un API Gateway.

- **Manejo centralizado de errores**
  - Captura y normalización de errores no controlados.
  - Respuestas consistentes para el cliente.

- **Configuración de seguridad básica**
  - Integración con Helmet.
  - Configuración de CORS.

- **Estructura común de respuestas**
  - Respuestas HTTP homogéneas en todos los microservicios.
  - Facilita el consumo desde frontend y otros servicios.

## Ejemplo de uso

A continuación se muestra un ejemplo básico de cómo inicializar un microservicio Express utilizando `gs-microservice-core`.

### Ejemplo básico (sin autenticación)

```ts
import express from "express";
import { setupCoreMiddlewares, setupErrorHandler, standardResponse, logInfo } from "gs-microservice-core";

const app = express();

setupCoreMiddlewares(app, {
  gateway: false,
});

app.get("/health", (_req, res) => {
  standardResponse(res, 200, "Servicio operativo");
});

setupErrorHandler(app);

app.listen(3000, () => {
  logInfo("Servicio iniciado en el puerto 3000");
});
```

### Ejemplo con autenticación

```ts
import express from "express";
import { setupCoreMiddlewares, setupErrorHandler, verifyToken, standardResponse } from "gs-microservice-core";

const app = express();

setupCoreMiddlewares(app, {
  jwtSecret: process.env.JWT_SECRET,
  gateway: false,
});

app.get("/secure", verifyToken, (req, res) => {
  standardResponse(res, 200, "Endpoint protegido", {
    userId: req.userId,
  });
});

setupErrorHandler(app);

app.listen(3000);
```

## API

### setupCoreMiddlewares(app, options)

Inicializa y configura los middlewares comunes del core en una aplicación Express.

Incluye, entre otros:

- logging y trazabilidad
- configuración de seguridad (Helmet)
- configuración de CORS
- parseo de JSON
- contexto de petición
- soporte para autenticación JWT

#### Firma

```ts
setupCoreMiddlewares(
  app: any,
  options?: {
    gateway?: boolean;
    jwtSecret?: string;
    helmetConfig?: HelmetOptions;
    corsOptions?: CorsOptions;
  }
): void
```

#### Parámetros

- **app**  
  Instancia de Express sobre la que se aplicarán los middlewares.

- **options.gateway** (opcional, por defecto `false`)  
  Indica si el microservicio actúa como API Gateway.

- **options.jwtSecret** (opcional)  
  Clave secreta para la validación de tokens JWT.

- **options.helmetConfig** (opcional)  
  Configuración personalizada para Helmet.

- **options.corsOptions** (opcional)  
  Configuración personalizada para CORS.

---

### setupErrorHandler(app)

Configura el manejador global de errores de la aplicación.

Captura errores no controlados y los transforma en respuestas homogéneas.

#### Firma

```ts
setupErrorHandler(app: any): void
```

Debe ejecutarse **después** de definir todas las rutas.

---

### verifyToken

Middleware para validar tokens JWT en rutas protegidas.
El middleware añade la información del usuario autenticado al objeto `req`.

#### Firma

```ts
verifyToken(req: any, res: any, next: any): void
```

---

### verifyPublicToken

Middleware para validar tokens públicos.

#### Firma

```ts
verifyPublicToken(req: any, res: any, next: any): void
```

---

### standardResponse(res, code, message, data?, time?, invalidatedAt?, schema?, count?)

Envía una respuesta HTTP estandarizada.

#### Firma

```ts
standardResponse(
  res: any,
  code: number,
  message: string,
  data?: any,
  time?: number,
  invalidatedAt?: Date,
  schema?: any,
  count?: number
): void
```

---

### validateSchema(schema, data)

Valida datos contra un esquema definido.

#### Firma

```ts
validateSchema(schema: any, data: any): boolean
```

---

### Logging

Funciones de logging integradas en el core.

#### logInfo

```ts
logInfo(message: string): void
```

#### logError

```ts
logError(error: any): void
```

#### logDebug

```ts
logDebug(message: string): void
```

#### logOperation

Registra información de una operación a partir del contexto de la petición.

```ts
logOperation(req: any): void
```

---

### Errores comunes

Clases y catálogos de errores reutilizables.

```ts
AppError;
commonErrors;
commonHTTPErrors;
```