@stone-ton/lambda-handlers

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)

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)

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

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)

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:

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

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)

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.