Conceitos básicos

O Lambda fornece SDKs de execução durável para JavaScript, TypeScript e Python. Esses SDKs são a base para a criação de funções duráveis, fornecendo as primitivas de que você precisa para pontos de verificação de progresso, lidar com novas tentativas e gerenciar o fluxo de execução. Para obter exemplos e documentação completa do SDK, consulte o SDK do Javascript/TypeScript e o SDK do Python no GitHub.

Execução durável

Uma execução durável representa o ciclo de vida completo de uma função durável do Lambda, usando um mecanismo de ponto de verificação e reprodução para acompanhar o progresso da lógica de negócios, suspender a execução e recuperar as falhas. Quando as funções são retomadas após suspensões ou interrupções, os pontos de verificação concluídos anteriormente são repetidos e a função continua em execução.

O ciclo de vida pode incluir várias invocações de uma função do Lambda para concluir a execução, especialmente após suspensões ou recuperação de falhas. Essa abordagem permite que sua função funcione por longos períodos (até um ano), mantendo um progresso confiável apesar das interrupções.

Como a reprodução funciona

O Lambda mantém um log em execução de todas as operações duráveis (etapas, esperas e outras operações) à medida que sua função é executada. Quando sua função precisa fazer uma pausa ou encontra uma interrupção, o Lambda salva esse log de ponto de verificação e interrompe a execução. Quando chega a hora de retomar, o Lambda invoca sua função novamente desde o início e reproduz o log do ponto de verificação, substituindo os valores armazenados pelas operações concluídas. Isso significa que seu código é executado novamente, mas as etapas concluídas anteriormente não são reexecutadas. Seus resultados armazenados são usados em vez disso.

Esse mecanismo de reprodução é fundamental para entender as funções duráveis. Seu código deve ser determinístico durante a reprodução, o que significa que ele produz os mesmos resultados com as mesmas entradas. Evite operações com efeitos colaterais (como a geração de números aleatórios ou a obtenção da hora atual) fora das etapas, pois elas podem produzir valores diferentes durante a reprodução e causar um comportamento não determinístico.

DurableContext

DurableContext é o objeto de contexto que sua função durável recebe. Ele fornece métodos para operações duráveis, como etapas e esperas, que criam pontos de verificação e gerenciam o fluxo de execução.

Sua função durável recebe um DurableContext em vez do contexto do Lambda padrão:

TypeScript

import {
  DurableContext,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

export const handler = withDurableExecution(
  async (event: any, context: DurableContext) => {
    const result = await context.step(async () => {
      return "step completed";
    });
    return result;
  },
);

Python

from aws_durable_execution_sdk_python import (
    DurableContext,
    durable_execution,
    durable_step,
)

@durable_step
def my_step(step_context, data):
    # Your business logic
    return result

@durable_execution
def handler(event, context: DurableContext):
    result = context.step(my_step(event["data"]))
    return result

O SDK do Python para funções duráveis usa métodos síncronos e não oferece suporte a await. O SDK do TypeScript usa async/await.

Steps

O Steps executa a lógica de negócios com novas tentativas integradas e pontos de verificação automáticos. Cada etapa salva seu resultado, garantindo que sua função possa ser retomada a partir de qualquer etapa concluída após interrupções.

TypeScript

// Each step is automatically checkpointed
const order = await context.step(async () => processOrder(event));
const payment = await context.step(async () => processPayment(order));
const result = await context.step(async () => completeOrder(payment));

Python

# Each step is automatically checkpointed
order = context.step(lambda: process_order(event))
payment = context.step(lambda: process_payment(order))
result = context.step(lambda: complete_order(payment))

Estados de espera

Os estados de espera são pausas planejadas em que sua função para de funcionar (e para de carregar) até a hora de continuar. Use-os para aguardar períodos de tempo, retornos de chamada externos ou condições específicas.

TypeScript

// Wait for 1 hour without consuming resources
await context.wait({ seconds:3600 });

// Wait for external callback
const approval = await context.waitForCallback(
  async (callbackId) => sendApprovalRequest(callbackId)
);

Python

# Wait for 1 hour without consuming resources
context.wait(3600)

# Wait for external callback
approval = context.wait_for_callback(
    lambda callback_id: send_approval_request(callback_id)
)

Quando sua função encontra uma espera ou precisa fazer uma pausa, o Lambda salva esse log de ponto de verificação e interrompe a execução. Quando chega a hora de retomar, o Lambda invoca sua função novamente e reproduz o log do ponto de verificação, substituindo os valores armazenados pelas operações concluídas.

Para fluxos de trabalho mais complexos, as funções do Lambda duráveis também vêm com operações avançadas como parallel() para execução simultânea, map() para o processamento de matrizes, runInChildContext() para operações aninhadas e waitForCondition() para sondagem. Consulte Exemplos para obter exemplos detalhados e orientações sobre quando usar cada operação.

Invocação de outras funções

Invoke permite que uma função durável chame outras funções do Lambda e aguarde por seus resultados. A função de chamada é suspensa enquanto a função invocada é executada, criando um ponto de verificação que preserva o resultado. Isso permite que você crie fluxos de trabalho modulares em que funções especializadas tratam tarefas específicas.

Use context.invoke() para chamar outras funções de dentro de sua função durável. A invocação é marcada com ponto de verificação, portanto, se sua função for interrompida após a conclusão da função invocada, ela será retomada com o resultado armazenado sem invocar novamente a função.

TypeScript

// Invoke another function and wait for result
const customerData = await context.invoke(
  'validate-customer',
  'arn:aws:lambda:us-east-1:123456789012:function:customer-service:1',
  { customerId: event.customerId }
);

// Use the result in subsequent steps
const order = await context.step(async () => {
  return processOrder(customerData);
});

Python

# Invoke another function and wait for result
customer_data = context.invoke(
    'arn:aws:lambda:us-east-1:123456789012:function:customer-service:1',
    {'customerId': event['customerId']},
    name='validate-customer'
)

# Use the result in subsequent steps
order = context.step(
    lambda: process_order(customer_data),
    name='process-order'
)

A função invocada pode ser uma função do Lambda durável ou padrão. Se você invocar uma função durável, a função de chamada aguardará a conclusão da execução durável completa. Esse padrão é comum em arquiteturas de microsserviços em que cada função manipula um domínio específico, permitindo que você componha fluxos de trabalho complexos a partir de funções especializadas e reutilizáveis.

Configuração de função durável

As funções duráveis têm configurações específicas que controlam o comportamento de execução e a retenção de dados. Essas configurações são separadas da configuração padrão da função do Lambda e se aplicam a todo o ciclo de vida de execução durável.

O objeto DurableConfig define a configuração para as funções duráveis:

{
  "ExecutionTimeout": Integer,
  "RetentionPeriodInDays": Integer
}

Execution timeout (Tempo limite de execução)

O tempo limite de execução controla por quanto tempo uma execução durável pode ser executada do início à conclusão. Isso é diferente do tempo limite da função do Lambda, que controla por quanto tempo uma única invocação de função pode ser executada.

Uma execução durável pode abranger várias invocações de função do Lambda à medida que avança nos pontos de verificação, esperas e repetições. O tempo limite de execução se aplica ao tempo total decorrido da execução durável, não às invocações de funções individuais.

Como compreender as diferenças

O tempo limite da função do Lambda (máximo de 15 minutos) limita cada invocação individual de sua função. O tempo limite de execução durável (máximo de 1 ano) limita o tempo total desde o início da execução até sua conclusão, falha ou tempo limite. Durante esse período, sua função pode ser invocada várias vezes enquanto processa etapas, espera e se recupera de falhas.

Por exemplo, se você definir um tempo limite de execução durável de 24 horas e um tempo limite da função do Lambda de 5 minutos:

É possível configurar o tempo limite de execução ao criar uma função durável usando o console do Lambda, a AWS CLI ou o AWS SAM. No console do Lambda, escolha sua função e, em seguida, Configuração, Execução durável. Defina o valor do tempo limite de execução em segundos (padrão: 86400 segundos/24 horas, mínimo: 60 segundos, máximo: 31536000 segundos/ 1 ano).

Período de retenção

O período de retenção controla por quanto tempo o Lambda retém o histórico de execução e os dados do ponto de verificação após a conclusão de uma execução durável. Esses dados incluem resultados da etapa, estado de execução e o log completo dos pontos de verificação.

Depois que o período de retenção expira, o Lambda exclui o histórico de execução e os dados do ponto de verificação. Não será possível mais recuperar os detalhes da execução nem repetir a execução. O período de retenção começa quando a execução atinge um estado terminal (SUCCEEDED, FAILED, STOPPED ou TIMED_OUT).

É possível configurar o período de retenção ao criar uma função durável usando o console do Lambda, a AWS CLI ou o AWS SAM. No console do Lambda, escolha sua função e, em seguida, Configuração, Execução durável. Defina o valor do período de retenção em dias (padrão: 14 dias, mínimo: 1 dia, máximo: 90 dias).

Escolha um período de retenção com base em seus requisitos de conformidade, necessidades de depuração e considerações de custo. Períodos de retenção mais longos fornecem mais tempo para depuração e auditoria, mas aumentam os custos de armazenamento.