Criar um runtime personalizado para AWS Lambda - AWS Lambda
RequisitosImplementação do streaming de resposta em um runtime personalizado

Criar um runtime personalizado para AWS Lambda

Você pode implementar um runtime do AWS Lambda em qualquer linguagem de programação. O runtime é um programa que executa um método de manipulador da função do Lambda quando a função é invocada. Você pode ser incluir o runtime no pacote de implantação da função ou distribuí-lo em uma camada. Ao criar a função do Lambda, escolha um runtime somente do sistema operacional (a família de runtime provided).

nota

Criar um runtime personalizado é um caso de uso avançado. Se você estiver procurando informações sobre como compilar em um binário nativo ou usar um runtime pronto para uso de terceiros, consulte Quando usar runtimes somente para sistema operacional do Lambda.

Para obter uma explicação passo a passo do processo de implantação de runtime personalizado, consulte Tutorial: criar um runtime personalizado. Você também pode explorar um runtime personalizado implementado em C++ em awslabs/aws-lambda-cpp no GitHub.

Requisitos

Os runtimes personalizados devem realizar determinadas tarefas de inicialização e processamento. Um runtime executa o código de configuração da função, lê o nome do manipulador de uma variável de ambiente e lê eventos de invocação da API de runtime do Lambda. O runtime transmite os dados de eventos para o manipulador de funções e publica a resposta do manipulador de volta no Lambda.

Tarefas de inicialização

As tarefas de inicialização são executadas uma vez por instância da função a fim de preparar o ambiente para processar invocações.

  • Recuperar configurações: leia variáveis de ambiente para obter detalhes sobre a função e o ambiente.

    • _HANDLER: a localização do manipulador, da configuração da função. O formato padrão é file.method, em que file é o nome do arquivo sem uma extensão, e method é o nome de um método ou da função que é definido no arquivo.

    • LAMBDA_TASK_ROOT: o diretório que contém o código da função.

    • AWS_LAMBDA_RUNTIME_API: o host e a porta da API do runtime.

    Para obter uma lista completa das variáveis disponíveis, consulte Variáveis de ambiente com runtime definido.

  • Inicializar a função: carregar o arquivo do manipulador e executar qualquer código global ou estático que ele contenha. As funções devem criar recursos estáticos como clientes SDK e conexões de banco de dados uma vez e reutilizá-los para várias invocações.

  • Lidar com erros: se ocorrer um erro, chame a API erro de inicialização e saia imediatamente.

A inicialização é considerada no runtime e tempo limite cobrados. Quando uma execução aciona a inicialização de uma nova instância da função, é possível ver o tempo de inicialização nos logs e no rastreamento do AWS X-Ray.

exemplo log
REPORT RequestId: f8ac1208... Init Duration: 48.26 ms   Duration: 237.17 ms   Billed Duration: 300 ms   Memory Size: 128 MB   Max Memory Used: 26 MB

Tarefas de processamento

Enquanto ela é executada, um usa a interface de runtime do Lambda para gerenciar eventos de entrada e relatar erros. Depois de executar as tarefas de inicialização, o runtime processa eventos de entrada em um loop. No código do seu runtime, execute as seguintes etapas em ordem.

  • Obter um evento: chame a API próxima invocação para obter o próximo evento. O corpo da resposta contém os dados do evento. Os cabeçalhos da resposta contêm o ID da solicitação e outras informações.

  • Propagar o cabeçalho de rastreamento: obtenha o cabeçalho de rastreamento do X-Ray do cabeçalho Lambda-Runtime-Trace-Id na resposta da API. Defina a variável de ambiente _X_AMZN_TRACE_ID localmente com o mesmo valor. O X-Ray SDK usa esse valor para conectar dados de rastreamento entre serviços.

  • Criar um contexto de objeto: crie um objeto com informações de contexto de variáveis do ambiente e cabeçalhos na resposta da API.

  • Invocar o manipulador de funções: transmita o evento e o objeto de contexto para o manipulador.

  • Processar a resposta: chame a API de resposta de invocação para publicar a resposta do manipulador.

  • Processar erros: se ocorrer um erro, chame a API erro de invocação.

  • Limpeza: libere recursos não utilizados, envie dados para outros serviços ou execute tarefas adicionais antes de receber o próximo evento.

Entrypoint

O ponto de entrada de um runtime personalizado é um arquivo executável denominado bootstrap. O arquivo de bootstrap pode ser o runtime ou ele pode invocar outro arquivo que criará o runtime. Se a raiz do pacote de implantação não contiver um arquivo denominado bootstrap, o Lambda procurará o arquivo nas camadas da função. Se o arquivo bootstrap não existir ou não for executável, a função retornará um erro de Runtime.InvalidEntrypoint na invocação.

Veja um exemplo em que o arquivo bootstrap usa um pacote de versão do Node.js para executar um runtime do JavaScript em um arquivo separado denominado runtime.js.

exemplo bootstrap
#!/bin/sh
    cd $LAMBDA_TASK_ROOT
    ./node-v11.1.0-linux-x64/bin/node runtime.js

Implementação do streaming de resposta em um runtime personalizado

Para funções de streaming de resposta, os endpoints response e error têm um comportamento ligeiramente modificado que possibilita que o runtime faça o streaming de respostas parciais para o cliente e retorne cargas úteis em blocos. Para obter mais informações sobre o comportamento específico, consulte o seguinte:

  • /runtime/invocation/AwsRequestId/response: propaga o cabeçalho Content-Type do runtime para enviar ao cliente. O Lambda retorna a carga de resposta em blocos por meio de codificação de transferência em blocos do HTTP/1.1. O stream de resposta pode ter um tamanho máximo de 20 MiB. Para fazer o streaming da resposta para o Lambda, o runtime deve:

    • Definir o cabeçalho HTTP Lambda-Runtime-Function-Response-Mode como streaming.

    • Defina o cabeçalho Transfer-Encoding como chunked.

    • Gravar a resposta em conformidade com a especificação de codificação de transferência em blocos HTTP/1.1.

    • Encerrar a conexão subjacente após escrever a resposta com êxito.

  • /runtime/invocation/AwsRequestId/error: o runtime pode usar esse endpoint para relatar erros de função ou de runtime ao Lambda, que também aceita o cabeçalho Transfer-Encoding. Esse endpoint pode ser chamado somente antes que o runtime comece a enviar uma resposta de invocação.

  • Relatar erros intermediários usando trailers de erro em /runtime/invocation/AwsRequestId/response: para relatar erros ocorridos após o runtime começar a gravar a resposta da invocação, o runtime pode, opcionalmente, anexar cabeçalhos HTTP no final, chamados de Lambda-Runtime-Function-Error-Type e Lambda-Runtime-Function-Error-Body. O Lambda trata isso como uma resposta com êxito e encaminha os metadados de erro fornecidos pelo runtime ao cliente.

    nota

    Para vincular cabeçalhos à direita, o runtime deve definir o valor do cabeçalho Trailer no início da solicitação HTTP. Isso é um requisito da especificação de codificação de transferência em blocos do HTTP/1.1.

    • Lambda-Runtime-Function-Error-Type: o tipo de erro encontrado pelo runtime. Este cabeçalho consiste em um valor de string. O Lambda aceita qualquer string, mas recomendamos um formato <category.reason>. Por exemplo, Runtime.APIKeyNotFound.

    • Lambda-Runtime-Function-Error-Body: informações sobre o erro codificadas em Base64.