SDK de execução durável

O SDK de execução durável é a base para a criação de funções duráveis. Ele fornece os elementos básicos de que você precisa para verificar o progresso, lidar com novas tentativas e gerenciar o fluxo de execução. O SDK abstrai a complexidade do gerenciamento e da reprodução de pontos de verificação, permitindo que você escreva um código sequencial que automaticamente se torna com tolerância a falhas.

O SDK está disponível para JavaScript, TypeScript e Python. Para obter exemplos e documentação completa da API, consulte o SDK do Javascript/TypeScript e o SDK do Python no GitHub.

DurableContext

O SDK fornece à sua função um objeto DurableContext que expõe todas as operações duráveis. Esse contexto substitui o contexto padrão do Lambda e fornece métodos para a criação de pontos de verificação, gerenciamento do fluxo de execução e coordenação com sistemas externos.

Para usar o SDK, encapsule seu manipulador Lambda com o wrapper de execução durável:

TypeScript

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

export const handler = withDurableExecution(
  async (event: any, context: DurableContext) => {
    // Your function receives DurableContext instead of Lambda context
    // Use context.step(), context.wait(), etc.
    return result;
  }
);
          

Python

from aws_durable_execution_sdk_python import durable_execution, DurableContext

@durable_execution
def handler(event: dict, context: DurableContext):
    # Your function receives DurableContext
    # Use context.step(), context.wait(), etc.
    return result
          

O wrapper intercepta a invocação da sua função, carrega qualquer log de ponto de verificação existente e fornece o DurableContext que gerencia a reprodução e a criação dos pontos de verificação.

O que o SDK faz

O SDK lida com três responsabilidades críticas que habilitam a execução durável:

Gerenciamento de pontos de verificação: o SDK cria pontos de verificação automaticamente à medida que sua função executa operações duráveis. Cada ponto de verificação registra o tipo de operação, as entradas e os resultados. Quando sua função conclui uma etapa, o SDK persiste no ponto de verificação antes de prosseguir. Isso garante que sua função possa ser retomada a partir de qualquer operação concluída, caso seja interrompida.

Coordenação de reprodução: quando sua função é retomada após uma pausa ou interrupção, o SDK executa a reprodução. Ele executa seu código desde o início, mas ignora as operações concluídas, usando resultados de pontos de verificação armazenados em vez de reexecutá-las. O SDK garante que a reprodução seja determinística, de forma que, dadas as mesmas entradas e o mesmo log do ponto de verificação, sua função produz os mesmos resultados.

Isolamento de estado: o SDK mantém o estado de execução separadamente da sua lógica de negócios. Cada execução durável tem seu próprio log de ponto de verificação que outras execuções não podem acessar. O SDK criptografa os dados em repouso do ponto de verificação e garante que o estado permaneça consistente em todas as reproduções.

Como o ponto de verificação funciona

Quando você chama uma operação durável, o SDK segue esta sequência:

Essa sequência garante que, após a conclusão da operação, seu resultado seja armazenado com segurança. Se sua função for interrompida em algum momento, o SDK poderá reproduzi-la até o último ponto de verificação concluído.

Comportamento da reprodução

Quando sua função é retomada após uma pausa ou interrupção, o SDK executa a reprodução.

Esse mecanismo de reprodução exige que seu código seja determinístico. Com as mesmas entradas e o mesmo log do ponto de verificação, sua função deve fazer a mesma sequência de chamadas de operação duráveis. O SDK aplica isso validando se os nomes e tipos de operação correspondem ao log do ponto de verificação durante a reprodução.

Operações duráveis disponíveis

O DurableContext fornece operações para diferentes padrões de coordenação. Cada operação durável cria pontos de verificação automaticamente, garantindo que sua função possa ser retomada a partir de qualquer ponto.

Steps

Executa a lógica de negócios com verificação automática e nova tentativa. Use etapas para operações que chamem serviços externos, realizem cálculos ou executem qualquer lógica que deva ser verificada. O SDK cria um ponto de verificação antes e depois da etapa, armazenando o resultado para reprodução.

TypeScript

const result = await context.step('process-payment', async () => {
  return await paymentService.charge(amount);
});
            

Python

result = context.step(
    lambda _: payment_service.charge(amount),
    name='process-payment'
)
            

As etapas oferecem suporte a estratégias de reprodução configuráveis, semântica de execução (no máximo uma vez ou pelo menos uma vez) e serialização personalizada.

Espera

Pausa a execução por um período especificado sem consumir recursos computacionais. O SDK cria um ponto de verificação, encerra a invocação da função e agenda a retomada. Quando a espera é concluída, o Lambda invoca sua função novamente e o SDK faz a reprodução até o ponto de espera antes de prosseguir.

TypeScript

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

Python

# Wait 1 hour without charges
context.wait(3600)
            

Retornos de chamada

Os retornos de chamadas permitem que sua função faça uma pausa e aguarde até que sistemas externos forneçam entrada. Quando você cria um retorno de chamada, o SDK gera um ID de retorno de chamada exclusivo e cria um ponto de verificação. Em seguida, sua função é suspensa (encerra a invocação) sem incorrer em cobranças computacionais. Sistemas externos enviam resultados de retorno de chamada usando as APIs SendDurableExecutionCallbackSuccess ou SendDurableExecutionCallbackFailure do Lambda. Quando um retorno de chamada é enviado, o Lambda invoca sua função novamente, o SDK faz a reprodução até o ponto de retorno de chamada e sua função prossegue com o resultado do retorno de chamada.

O SDK fornece dois métodos para o trabalho com retornos de chamadas:

createCallback: cria um retorno de chamada e retorna uma promessa e um ID de retorno de chamada. Você envia o ID de retorno de chamada para um sistema externo, que envia o resultado usando a API do Lambda.

TypeScript

const [promise, callbackId] = await context.createCallback('approval', {
  timeout: { hours: 24 }
});

await sendApprovalRequest(callbackId, requestData);
const approval = await promise;
            

Python

callback = context.create_callback(
    name='approval',
    config=CallbackConfig(timeout_seconds=86400)
)

context.step(
    lambda _: send_approval_request(callback.callback_id),
    name='send_request'
)

approval = callback.result()
            

waitForCallback: simplifica o tratamento do retorno de chamada combinando a criação e o envio de retornos de chamada em uma única operação. O SDK cria o retorno de chamada, executa sua função de envio com o ID de retorno de chamada e aguarda pelo resultado.

TypeScript

const result = await context.waitForCallback(
  'external-api',
  async (callbackId, ctx) => {
    await submitToExternalAPI(callbackId, requestData);
  },
  { timeout: { minutes: 30 } }
);
            

Python

result = context.wait_for_callback(
    lambda callback_id: submit_to_external_api(callback_id, request_data),
    name='external-api',
    config=WaitForCallbackConfig(timeout_seconds=1800)
)
            

Configure os tempos limite para evitar que as funções esperem indefinidamente. Se um retorno de chamada atingir o tempo limite, o SDK lançará um CallbackError e sua função poderá tratar o caso de tempo limite. Use tempos limite de pulsação para retornos de chamada de longa duração para detectar quando os sistemas externos param de responder.

Use retornos de chamada para fluxos de trabalho com humanos no loop, integração de sistemas externos, respostas de webhook ou qualquer cenário em que a execução deva ser pausada para entradas externas.

Execução paralela

Execute várias operações simultaneamente com o controle de simultaneidade opcional. O SDK gerencia a execução paralela, cria pontos de verificação para cada operação e trata as falhas de acordo com sua política de conclusão.

TypeScript

const results = await context.parallel([
  async (ctx) => ctx.step('task1', async () => processTask1()),
  async (ctx) => ctx.step('task2', async () => processTask2()),
  async (ctx) => ctx.step('task3', async () => processTask3())
]);
            

Python

results = context.parallel(
    lambda ctx: ctx.step(lambda _: process_task1(), name='task1'),
    lambda ctx: ctx.step(lambda _: process_task2(), name='task2'),
    lambda ctx: ctx.step(lambda _: process_task3(), name='task3')
)
            

Use parallel para executar operações independentes simultaneamente.

Mapa

Execute simultaneamente uma operação em cada item em uma matriz com controle de simultaneidade opcional. O SDK gerencia a execução simultânea, cria pontos de verificação para cada operação e trata as falhas de acordo com sua política de conclusão.

TypeScript

const results = await context.map(itemArray, async (ctx, item, index) =>
  ctx.step('task', async () => processItem(item, index))
);
            

Python

results = context.map(
    item_array,
    lambda ctx, item, index: ctx.step(
        lambda _: process_item(item, index),
        name='task'
    )
)
            

Use map para processar matrizes com controle de simultaneidade.

Contextos secundários

Cria um contexto de execução isolado para operações de agrupamento. Os contextos secundários têm seu próprio log de pontos de verificação e podem conter várias etapas, esperas e outras operações. O SDK trata todo o contexto secundário como uma única unidade para novas tentativas e recuperações.

Use contextos secundários para organizar fluxos de trabalho complexos, implementar subfluxos de trabalho ou isolar operações que devem ser tentadas novamente juntas.

TypeScript

const result = await context.runInChildContext(
  'batch-processing',
  async (childCtx) => {
    return await processBatch(childCtx, items);
  }
);
            

Python

result = context.run_in_child_context(
    lambda child_ctx: process_batch(child_ctx, items),
    name='batch-processing'
)
            

O mecanismo de reprodução exige que operações duráveis ocorram em uma ordem determinística. Usando vários contextos secundários, é possível ter vários fluxos de trabalho executados simultaneamente, e o determinismo se aplica separadamente em cada contexto. Isso permite que você crie funções de alta performance que utilizem com eficiência vários núcleos de CPU.

Por exemplo, imagine que iniciamos dois contextos secundários, A e B. Na invocação inicial, as etapas dentro dos contextos foram executadas nessa ordem, com as etapas 'A' sendo executadas simultaneamente com as etapas 'B': A1, B1, B2, A2, A3. Na reprodução, o tempo é muito mais rápido, pois os resultados são recuperados do log do ponto de verificação e as etapas são encontradas em uma ordem diferente: B1, A1, A2, B2, A3. Como as etapas 'A' foram encontradas na ordem correta (A1, A2, A3) e as etapas 'B' foram encontradas na ordem correta (B1, B2), a necessidade de determinismo foi satisfeita corretamente.

Esperas condicionais

Sondagens para uma condição com verificação automática entre as tentativas. O SDK executa sua função de verificação, cria um ponto de verificação com o resultado, espera de acordo com sua estratégia e repete até que a condição seja atendida.

TypeScript

const result = await context.waitForCondition(
  async (state, ctx) => {
    const status = await checkJobStatus(state.jobId);
    return { ...state, status };
  },
  {
    initialState: { jobId: 'job-123', status: 'pending' },
    waitStrategy: (state) => 
      state.status === 'completed' 
        ? { shouldContinue: false }
        : { shouldContinue: true, delay: { seconds: 30 } }
  }
);
            

Python

result = context.wait_for_condition(
    lambda state, ctx: check_job_status(state['jobId']),
    config=WaitForConditionConfig(
        initial_state={'jobId': 'job-123', 'status': 'pending'},
        wait_strategy=lambda state, attempt: 
            {'should_continue': False} if state['status'] == 'completed'
            else {'should_continue': True, 'delay': 30}
    )
)
            

Use waitForCondition para sondar sistemas externos, esperar que os recursos estejam prontos ou implementar novas tentativas com recuo.

invocação de funções

Invoca uma outra função do Lambda e aguarda seu resultado. O SDK cria um ponto de verificação, invoca a função de destino e retoma sua função quando a invocação é concluída. Isso permite a composição da função e a decomposição do fluxo de trabalho.

TypeScript

const result = await context.invoke(
  'invoke-processor',
  'arn:aws:lambda:us-east-1:123456789012:function:processor',
  { data: inputData }
);
            

Python

result = context.invoke(
    'arn:aws:lambda:us-east-1:123456789012:function:processor',
    {'data': input_data},
    name='invoke-processor'
)
            

Como as operações duráveis são medidas

Cada operação durável que você executa por DurableContext cria pontos de verificação para monitorar o progresso da execução e armazenar dados de estado. Essas operações incorrem em cobranças com base em seu uso, e os pontos de verificação podem conter dados que contribuam para seus custos de gravação e retenção de dados. Os dados armazenados incluem dados de eventos de invocação, cargas úteis retornadas das etapas e dados transmitidos ao concluir retornos de chamada. Entender como as operações duráveis são medidas ajuda você a estimar os custos de execução e a otimizar seus fluxos de trabalho. Para obter detalhes de preços, consulte a página de dfinição de preços do Lambda.

O tamanho da carga útil se refere ao tamanho dos dados serializados em que uma operação durável persiste. Os dados são medidos em bytes e o tamanho pode variar dependendo do serializador usado pela operação. A carga útil de uma operação pode ser o resultado em si de uma conclusão com êxito ou o objeto de erro serializado se a operação falhar.

Operações básicas

As operações básicas são os blocos de construção fundamentais para funções duráveis:

Operações de retorno de chamada

Os retornos de retorno de chamada permitem que sua função faça uma pausa e aguarde até que sistemas externos forneçam entrada. Essas operações criam pontos de verificação quando o retorno de chamada é criado e quando é concluído:

Operações compostas

As operações compostas combinam várias operações duráveis para lidar com padrões complexos de coordenação, como execução paralela, processamento de matrizes e contextos aninhados:

Para contextos, como de runInChildContext ou usados internamente por operações compostas, resultados menores que 256 KB são verificados diretamente. Resultados maiores não são armazenados. Em vez disso, eles são reconstruídos durante a reprodução por meio do reprocessamento das operações do contexto.