EventBridge Scheduler troca cron job por agendamento único em reservas

Um tutorial em CDK e TypeScript mostra como criar um EventBridge Scheduler one-time schedule por pedido, eliminando o polling no banco e a máquina que fica ociosa esperando a hora certa.

Todo sistema de reserva tem o mesmo problema: em um instante específico, uma única coisa precisa acontecer para um único pedido. A solução mais comum ainda é um cron job perguntando ao banco, minuto a minuto, se alguma coisa está pronta para disparar. Funciona, mas é um loop infinito rodando para um evento que acontece exatamente uma vez por pedido.

Em um tutorial publicado na DEV Community, o desenvolvedor que assina como sascha-ms monta a alternativa: um EventBridge Scheduler one-time schedule criado dinamicamente a cada reserva, via SDK, que invoca uma Lambda uma única vez e depois se apaga sozinho. Vale reproduzir o exemplo passo a passo, porque a parte interessante não é o anúncio do recurso (o at() existe há anos), e sim o jeito certo de lidar com fuso horário, idempotência e o comportamento de substituição total do UpdateSchedule.

O que você vai construir

O exemplo do autor é uma padaria fictícia que vende pão sob encomenda. O cliente escolhe um horário de retirada e, uma hora antes, recebe um lembrete. Se ele remarca, o lembrete se move junto; se cancela, nada é enviado.

O núcleo é um EventBridge Scheduler one-time schedule por pedido, criado com uma expressão at() e configurado com ActionAfterCompletion: DELETE. Ele invoca uma Lambda de lembrete exatamente uma vez e se remove sozinho da fila de schedules, sem deixar sobra cobrando quota.

A arquitetura tem duas Lambdas: uma de pedidos (cria, remarca, cancela) e uma de lembrete (invocada pelo scheduler). Todos os schedules vivem num grupo chamado bakery-reminders, e falhas de entrega caem numa fila SQS configurada como dead-letter queue.

Pré-requisitos

Para reproduzir o exemplo você precisa de:

• Node.js 22 ou mais novo, e npm
• aws-cdk-lib@2.275.0, constructs@10.8.1 e @aws-sdk/client-scheduler@3.1161.0, as versões que o autor fixou no artigo
• aws-cdk@2.1147.0 como CLI, mais typescript, tsx e esbuild instalados localmente (o esbuild local evita que o CDK precise de Docker para empacotar a NodejsFunction)
• Para cdk synth e os testes unitários, nenhuma conta AWS é necessária; só o cdk deploy exige uma conta com bootstrap feito
• Permissões de IAM para quem vai rodar o deploy chamar a API do Scheduler (criar, atualizar e remover schedules) com escopo restrito ao grupo bakery-reminders
• Uma role de execução separada, assumida pelo próprio serviço do Scheduler, com trust policy para o principal scheduler.amazonaws.com e permissão para invocar a Lambda de lembrete; quem cria o schedule precisa de iam:PassRole restrito a essa role específica

Passo a passo

1. Crie o projeto e trave as versões.

mkdir bakery-reminders && cd bakery-reminders
npm init -y && npm pkg set type=module
npm install aws-cdk-lib@2.275.0 constructs@10.8.1 @aws-sdk/client-scheduler@3.1161.0
npm install -D aws-cdk@2.1147.0 typescript@7.0.2 tsx@4.23.15 esbuild@0.28.2 @types/node@26.6.6

2. Calcule o instante com instantes reais, não com horário de parede.

O cliente escolhe "24 de dezembro, 08:00" em Berlim. Escrever esse horário direto na expressão at() funciona enquanto você só repassa o valor. O problema aparece quando você calcula em cima dele: na madrugada da troca de horário de verão, alguns horários locais existem duas vezes e outros não existem.

A solução do autor é converter o horário local em um instante UTC antes de subtrair a antecedência do lembrete, e só então gerar a expressão at() em UTC:

// Converte horário local + fuso em um instante inequívoco (UTC).
// Horários inexistentes (lacuna do horário de verão) são rejeitados;
// horários repetidos (fim do horário de verão) resolvem para o instante mais cedo.
export function localToInstant(local: string, timeZone: string): Date {
  // ... calcula offset comparando wallClock antes e depois da virada
}

// Expressão at() sem milissegundos, ex.: at(2026-12-24T07:00:00)
export function atExpression(instant: Date, timeZone = "UTC"): string {
  return `at(${wallClock(instant, timeZone)})`;
}

export function planReminder(
  pickupLocal: string,
  timeZone: string,
  leadMinutes: number,
  now: Date,
  minGapSeconds = 120,
) {
  const pickup = localToInstant(pickupLocal, timeZone);
  if (pickup.getTime() <= now.getTime()) throw new ScheduleError("Horário de retirada já passou");
  const remindAt = new Date(pickup.getTime() - leadMinutes * 60_000);
  if (remindAt.getTime() < now.getTime() + minGapSeconds * 1000) {
    return { kind: "skip", reason: "Lembrete chegaria tarde demais ou já passou" };
  }
  return { kind: "create", remindAt, expression: atExpression(remindAt), timeZone: "UTC" };
}

Vale notar uma lacuna da documentação: não há descrição clara do que o serviço faz com um at() no passado. Por isso o código checa isso antes, com uma folga de dois minutos.

3. Derive nome e ClientToken do ID do pedido, nunca de um contador à parte.

Idempotência aqui significa: a mesma chamada pode chegar duas vezes e o resultado não muda. O nome do schedule vem direto do ID do pedido, por exemplo pickup-B-2026-0042. Assim não existe tabela de mapeamento: quem sabe o ID do pedido sabe o nome do schedule.

const NAME_PATTERN = /^[0-9a-zA-Z\-_.]{1,64}$/;

export function scheduleName(orderId: string): string {
  const direct = `pickup-${orderId}`;
  if (NAME_PATTERN.test(direct)) return direct;
  const hash = createHash("sha256").update(orderId).digest("hex").slice(0, 40);
  return `pickup-h-${hash}`; // hash em vez de truncar, pra não colidir dois IDs longos
}

export function clientToken(orderId: string, version: number): string {
  return createHash("sha256").update(`${orderId}#${version}`).digest("hex");
}

O ClientToken depende do pedido e da versão. Uma repetição da mesma chamada gera o mesmo token; uma remarcação aumenta a versão e muda o token. Sem isso, o serviço gera um token aleatório, o que não ajuda quando sua Lambda refaz a chamada depois de um timeout.

4. Monte sempre a requisição completa, porque UpdateScheduleCommand substitui tudo.

Essa é a decisão de design mais importante do artigo. Segundo a referência da API, um UpdateSchedule aplica "todos os valores, inclusive os vazios": campo que você não manda volta ao padrão. Por isso existe uma única função que monta o corpo da requisição, usada tanto para criar quanto para remarcar.

export function scheduleRequest(o: Order, expression: string, env: Environment) {
  return {
    Name: scheduleName(o.orderId),
    GroupName: env.group,
    ScheduleExpression: expression,
    ScheduleExpressionTimezone: "UTC",
    FlexibleTimeWindow: { Mode: "OFF" },
    ActionAfterCompletion: "DELETE",
    State: "ENABLED",
    ClientToken: clientToken(o.orderId, o.version),
    Target: {
      Arn: env.targetArn,
      RoleArn: env.roleArn,
      Input: JSON.stringify({ orderId: o.orderId, version: o.version, pickupLocal: o.pickupLocal, timeZone: o.timeZone }),
      RetryPolicy: { MaximumRetryAttempts: 5, MaximumEventAgeInSeconds: 900 },
      DeadLetterConfig: { Arn: env.dlqArn },
    },
  };
}

Algumas escolhas de campo importam: FlexibleTimeWindow.Mode: "OFF" dá precisão de um minuto; com FLEXIBLE e uma janela de 1 a 1.440 minutos, o serviço espalharia as invocações, o que serve para jobs noturnos, não para lembretes. DeadLetterConfig só aceita fila SQS padrão, FIFO não é suportado como DLQ do Scheduler.

5. Escreva a Lambda de pedidos sobre CreateScheduleCommand, UpdateScheduleCommand e DeleteScheduleCommand.

Criar chama CreateScheduleCommand; remarcar chama UpdateScheduleCommand com o mesmo nome derivado; cancelar chama DeleteScheduleCommand. O ponto mais delicado são os erros que deixam de ser erro: tentar criar um schedule que já existe, ou cancelar um schedule que já disparou e se apagou sozinho graças ao ActionAfterCompletion: DELETE, não deveriam travar o fluxo do pedido. Nesse segundo caso, cancelar "com sucesso" é simplesmente não fazer nada.

Como escolher entre Scheduler, DynamoDB TTL e Step Functions Wait

O artigo original compara as três ferramentas de "fazer algo no instante X", e a diferença não é cosmética:

O TTL do DynamoDB é ferramenta de limpeza: o item some "em algum momento", sem custo de escrita, ótimo para expirar uma reserva, inútil para um lembrete às 07:00. Um Wait do Step Functions compensa quando há passos depois dele, como checar pagamento e reservar estoque, mas uma execução aberta por pedido é pesado para uma única invocação, e o limite padrão é um milhão de execuções abertas por conta e região.

Testando

O package.json do projeto já define "test": "node --import tsx --test test/*.test.ts", rodando os testes unitários de planReminder e localToInstant sem precisar de conta AWS: eles cobrem a lacuna do horário de verão (horário rejeitado), a hora repetida do fim do horário de verão (resolve para o instante mais cedo) e o caso de lembrete tarde demais (kind: "skip").

Para conferir informalmente se o fluxo funcionou depois do deploy, você pode consultar o schedule pela AWS CLI (algo como aws scheduler get-schedule --name pickup-B-2026-0042 --group-name bakery-reminders): antes do horário marcado, o comando deve retornar o schedule com State: ENABLED; depois, como ele se apagou sozinho graças ao ActionAfterCompletion: DELETE, a consulta deve falhar porque o recurso não existe mais. Vale também acompanhar os logs da Lambda de lembrete no CloudWatch Logs e a fila SQS configurada como DLQ, caso alguma invocação falhe repetidamente.

Limpando os recursos

Aqui mora uma armadilha que o artigo deixa implícita: os schedules de cada pedido são criados em tempo de execução, pela Lambda, via SDK, e não fazem parte do template do CDK. Como esses schedules não fazem parte da stack, um cdk destroy provavelmente remove as Lambdas, a role de execução e a fila SQS, mas não os schedules ativos criados por pedidos reais.

Para não deixar nada cobrando quota ou disparando lembretes órfãos, vale apagar o grupo bakery-reminders pela AWS CLI antes do cdk destroy: como o próprio autor avisa, apagar o grupo remove todos os schedules dentro dele, inclusive os que ainda não dispararam. Só depois disso faz sentido rodar o cdk destroy para remover as Lambdas, a role e a fila SQS.

O que pesa de fato na fatura é a invocação da Lambda de lembrete e o tráfego da fila SQS, cobrados à parte. Vale checar a conta de Lambda depois de rodar o exemplo com muitos pedidos simulados.

Próximos passos

O mesmo autor já tinha coberto duas peças vizinhas desse quebra-cabeça: EventBridge Scheduler time zone, sobre schedules recorrentes com cron() em fuso horário local, e DynamoDB TTL: seat holds with an expiry date, sobre expirar reservas sem código nenhum rodando. Os três artigos juntos cobrem a maioria dos casos de "fazer algo depois" numa aplicação serverless.

Para quem quiser ir além do exemplo da padaria, duas direções fazem sentido: trocar FlexibleTimeWindow.Mode: "OFF" por uma janela de alguns minutos quando o lembrete não precisa ser cirúrgico, reduzindo picos de invocação; e colocar um alarme do CloudWatch sobre a profundidade da fila DLQ, porque um lembrete que cai ali sem ninguém olhando é silêncio, não sucesso.

Fonte: DEV Community — #aws