Como trabalhar com camadas para funções do Lambda em TypeScript

Uma camada do Lambda é um arquivo .zip que contém código ou dados complementares. As camadas geralmente contêm dependências de biblioteca, um runtime personalizado ou arquivos de configuração. A criação de uma camada envolve três etapas gerais:

Este tópico contém as etapas e orientações sobre como empacotar e criar adequadamente uma camada do Lambda com Node.js com dependências externas de bibliotecas. Além disso, este tópico explica como usar a camada com uma função escrita em TypeScript.

Pré-requisitos

Para seguir as etapas desta seção, você deve ter o seguinte:

Neste tópico, fazemos referência à aplicação de exemplo layer-nodejs no repositório aws-lambda-developer-guide do GitHub. Esta aplicação contém scripts que empacotarão a biblioteca lodash em uma camada do Lambda. O diretório layer contém os scripts para gerar a camada. A aplicação também contém uma função de amostra em TypeScript no diretório function-ts, que usa a dependência da camada. Após a criação de uma camada, é possível converter código de uma linguagem para outra, implantar e invocar a função correspondente para verificar se tudo está funcionando corretamente. Este documento fornece uma orientação sobre como criar, empacotar, implantar e testar essa camada usando a função de amostra em TypeScript.

Essa aplicação de exemplo usa o runtime do Node.js 20. Se você adicionar dependências adicionais à camada, elas deverão ser compatíveis com o Node.js 20.

Compatibilidade da camada Node.js com o ambiente de runtime do Lambda

Ao empacotar o código em uma camada Node.js, você especifica os ambientes de runtime do Lambda com os quais o código é compatível. Para avaliar a compatibilidade do código com um runtime, considere para quais versões do Node.js, quais sistemas operacionais e quais arquiteturas de conjunto de instruções o código foi projetado.

Os runtimes do Node.js do Lambda especificam a versão e o sistema operacional do Node.js. Neste documento, você usará o runtime do Node.js 20, que é baseado no AL2023. Para obter mais informações sobre as versões do runtime, consulte Tempos de execução compatíveis. Ao criar a função do Lambda, você especifica a arquitetura do conjunto de instruções. Neste documento, você usará a arquitetura arm64. Para obter mais informações sobre arquiteturas no Lambda, consulte Selecionar e configurar a arquitetura de um conjunto de instruções para a função do Lambda.

Quando você usa o código fornecido em um pacote, cada mantenedor do pacote define sua compatibilidade de forma independente. A maior parte do desenvolvimento do Node.js foi projetada para funcionar independentemente do sistema operacional e da arquitetura do conjunto de instruções. Além disso, falhas de incompatibilidades com novas versões do Node.js não são tão comuns. Espere passar mais tempo avaliando a compatibilidade entre pacotes do que avaliando a compatibilidade de pacotes com a versão, o sistema operacional ou a arquitetura do conjunto de instruções do Node.js.

Às vezes, os pacotes do Node.js incluem código compilado, o que exige que você considere a compatibilidade da arquitetura do sistema operacional e do conjunto de instruções. Se precisar avaliar a compatibilidade do código dos pacotes, você precisará inspecionar os pacotes e a documentação deles. Os pacotes no NPM podem especificar a compatibilidade por meio dos campos engines, os e cpu do arquivo de manifesto package.json. Para obter mais informações sobre os arquivos package.json, consulte package.json na documentação do NPM.

Caminhos de camada para runtimes do Node.js

Quando você adiciona uma camada a uma função, o Lambda carrega o conteúdo da camada no diretório nesse ambiente de execução. Se as dependências de pacotes da camada estiverem em caminhos de pasta específicos, o ambiente de execução do Node.js reconhecerá os módulos e você poderá referenciá-los no seu código de função.

Para garantir que os módulos sejam selecionados, empacote-os em seu arquivo de camada .zip em um dos caminhos de pasta a seguir. Esses arquivos são armazenados em /opt, e os caminhos das pastas são carregados na variável PATH de ambiente.

Por exemplo, o arquivo .zip de camada resultante que você cria neste tutorial tem a seguinte estrutura de diretórios:

layer_content.zip
└ nodejs
    └ node20
        └ node_modules
            └ lodash
            └ <other potential dependencies>
            └ ...

Você colocará a biblioteca lodash no diretório nodejs/node20/node_modules. Isso garante que o Lambda possa localizar a biblioteca durante as invocações da função.

Empacotar o conteúdo de camada

Neste exemplo, você empacota a biblioteca lodash em um arquivo de camada .zip. Conclua as etapas a seguir para instalar e empacotar o conteúdo de camada.

Como criar a camada

Pegue o arquivo layer_content.zip gerado na seção anterior e o carregue como uma camada do Lambda. É possível fazer upload de uma camada usando o AWS Management Console ou a API do Lambda por meio da AWS Command Line Interface (AWS CLI). Ao carregar seu arquivo .zip de camada, no seguinte comando PublishLayerVersion da AWS CLI, especifique nodejs20.x como o runtime compatível e arm64 como a arquitetura compatível.

aws lambda publish-layer-version --layer-name nodejs-lodash-layer \
    --zip-file fileb://layer_content.zip \
    --compatible-runtimes nodejs20.x \
    --compatible-architectures "arm64"

Na resposta, anote o LayerVersionArn, que será algo como arn:aws:lambda:us-east-1:123456789012:layer:nodejs-lodash-layer:1. Você precisará desse nome do recurso da Amazon (ARN) na próxima etapa deste tutorial, ao adicionar a camada à função.

Como adicionar a camada à sua função

Implante um exemplo de função do Lambda que usa a biblioteca lodash em seu código de função, e depois anexe a camada que você criou. Para criar uma função do Lambda usando código escrito em TypeScript, é necessário converter código da linguagem TypeScript para JavaScript para que ele possa ser usado pelo runtime em Node.js. Para ter mais informações sobre esse processo, consulte Definir o manipulador de função do Lambda em TypeScript. Para obter melhor compatibilidade, use “tsc” para converter código de uma linguagem para outra no módulo TypeScript ao distribuir as dependências em camadas. Se você realizar o empacotamento das dependências, considere usar “esbuild”. Para obter mais informações sobre o empacotamento com “esbuild”, consulte Implantar código TypeScript transcompilado no Lambda com arquivos .zip.

Para implantar a função, você precisará de um perfil de execução. Para ter mais informações, consulte Definir permissões de uma função do Lambda com um perfil de execução. Se ainda não tiver um perfil de execução, siga as etapas na seção recolhível. Caso contrário, pule para a próxima seção para implantar a função.

O código da função de exemplo usa o método lodash _.findLastIndex para ler por meio de uma matriz de objetos. Ele compara os objetos com os critérios para encontrar o índice de uma correspondência. Em seguida, ele retorna o índice e o valor do objeto na resposta do Lambda.

import { Handler } from 'aws-lambda';
import * as _ from 'lodash';

type User = {
  user: string;
  active: boolean;
}

type UserResult = {
  statusCode: number;
  body: string;
}

const users: User[] = [
  { 'user': 'Carlos', 'active': true },
  { 'user': 'Gil-dong', 'active': false },
  { 'user': 'Pat', 'active': false }
];

export const handler: Handler<any, UserResult> = async (): Promise<UserResult> => {

  let out = _.findLastIndex(users, (user: User) => { return user.user == 'Pat'; });
  const response = {
    statusCode: 200,
    body: JSON.stringify(out + ", " + users[out].user),
  };
  return response;
};