npm package: @stone-ton/lambda-handlers
Description: Handlers for lambdas with otlp
Author: Emerson Katsumi Matsumoto
Latest version: 2.1.2

# Lambda Handlers

## Descrição

Esta biblioteca fornece um handler para facilitar o manejo das funções Lambda no AWS. Com a integração do OpenTelemetry, permite uma visibilidade clara das requisições, melhorando a capacidade de monitoramento e rastreamento.

## Principais Características.
- Integração nativa com OpenTelemetry para rastreamento de requisições.
- Capacidade de adicionar `body` e `headers` de `request` e `response` ao span de um trace através da variável de ambiente `OTLP_LAMBDA_DEBUG`.

## Como Usar

### Instalação:

Para instalar via npm:

```
npm install @stone-ton/lambda-handlers --save
```

### Lambda trigada pela API Gateway como proxy (múltiplas rotas numa lambda)

```javascript
import { LambdaApiProxyHandler, Controller } from '@stone-ton/lambda-handlers'
import { APIGatewayProxyHandler } from 'aws-lambda'
import authentication from './authentication'
import foo from './controllers/foo'

const api = new LambdaApiProxyHandler({
  base: process.env.ADMIN_API_BASE_PATH,
})

const foo: Controller = (req) => {
  return Promise.resolve({
    body: {
      message: 'Hello World'
    },
  })
}

export const handler: APIGatewayProxyHandler = async (
  event,
  context,
) => {
  api.addRoute({
    method: 'GET',
    path: '/',
    run: foo,
    auth: authentication(['admin']),
  })

  return api.handler(event, context)
}
```

### Lambda trigada pela API Gateway como proxy (uma rota por lambda)
```javascript
import { Controller, LambdaApiHandler } from '@stone-ton/lambda-handlers'
import { APIGatewayProxyHandler } from 'aws-lambda'

const getUserController: Controller = async (request) => {
  const user = await getUser(request.params.id)

  return {
    body: user,
  }
}

const apiHandler = new LambdaApiHandler(getUserController)

export const handler: APIGatewayProxyHandler = async (
  event,
  context,
) => {
  return apiHandler.handler(event, context)
}

```


### Lambda trigada por SQS

```javascript
import { LambdaSqsHandler, Worker } from '@stone-ton/lambda-handlers'
import { SQSHandler } from 'aws-lambda'

interface CreateUserMessage {
  user_id: string
}

const workerCreateUser: Worker<CreateUserMessage> = async (messages) => {
  for (const { body } of messages) {
    const user = await getUser(body.user_id)
  }
}

const sqsHandler = new LambdaSqsHandler(workerCreateUser)

export const handler: SQSHandler = async (event, context) => {
  return sqsHandler.handler(event, context)
}

```

### Lambda trigada por SQS (Worker com processamento em paralelo)

```javascript
import { LambdaSqsHandlerV2, WorkerV2 } from '@stone-ton/lambda-handlers'
import { SQSHandler } from 'aws-lambda'

interface CreateUserMessage {
  user_id: string
}

const workerCreateUser: WorkerV2<CreateUserMessage> = async (message, logger) => {
  logger.debug('Start create user')
  const user = await getUser(body.user_id)
}

const sqsHandler = new LambdaSqsHandler({
  worker: workerCreateUser,
  parallel: false,
  service: 'migraton',
})

export const handler: SQSHandler = async (event, context) => {
  return sqsHandler.handler(event, context)
}
```

A LambdaSqsHandlerV2 precisa ter o Report Batch Item Failures habilitado. Abaixo exemplo com terraform:

```terraform
resource "aws_lambda_event_source_mapping" "event_handler" {
  event_source_arn        = module.sqs_event_handler.sqs_arn
  function_name           = module.event_handler.arn
  batch_size              = 1
  function_response_types = ["ReportBatchItemFailures"]
}
```

### Lambda trigada pelo sdk

```javascript
import { LambdaInvokeHandler, InvokeHandler } from '@stone-ton/lambda-handlers'
import { Handler } from 'aws-lambda'

interface CreateUserRequest {
  user_id: string
}

interface CreateUserResponse {
  message: string
}

const createUserInvoke: InvokeHandler<CreateUserRequest, CreateUserResponse> = async (event, context) => {
  return {
    message: event.user_id
  }
}

const invokeHandler = new LambdaInvokeHandler(createUserInvoke)

export const handler: Handler<CreateUserRequest, CreateUserResponse> = async (event, context) => {
  return invokeHandler.handler(event, context)
}

```

### Lambda trigada pelo cloudwatch events (cron)

```javascript
import { LambdaCloudwatchHandler, CloudwatchHandler } from '@stone-ton/lambda-handlers'
import { ScheduledHandler } from 'aws-lambda'

const main: CloudwatchHandler = async (event, context) => {
}

const cwHandler = new LambdaCloudwatchHandler(main)

export const handler: ScheduledHandler = async (event, context) => {
  return cwHandler.handler(event, context)
}

```

## Opentelemetry

Antes de começar a usar a biblioteca, certifique-se de definir as variáveis de ambiente necessárias:

- `OTLP`: Deve ser definido como `true` para habilitar o rastreamento com OpenTelemetry.
- `OTLP_TIMEOUT`: Define o limite máximo de espera em milissegundos para o envio do trace pela lambda, com o valor padrão de 200ms caso não seja definido.
- `OTLP_TRACE_URL`: Deve ser definido com a URL do servidor OpenTelemetry Collector, por exemplo, `localhost:4318`.
- `OTLP_LAMBDA_DEBUG`: Quando definido como true, acrescenta detalhes de requisição e resposta HTTP, incluindo body e headers, aos spans do handler da Lambda. Atenção à possível presença de dados sensíveis.