Skip to content

Fase 4: fila RabbitMQ, worker e agendamento cron (specs 005, 006, WorkerHost) - #4

Merged
net0well merged 10 commits into
mainfrom
fase-4/fila-worker
Oct 20, 2026
Merged

net0well merged 10 commits into
mainfrom
fase-4/fila-worker

Conversation

@net0well

Copy link
Copy Markdown
Collaborator

Resumo

Execução assíncrona de Stages e trilhas: um passo por mensagem no RabbitMQ, worker com lease e retry, agendamento cron, comando público StartPipelineRun e eventos de execução. Inclui o WorkerHost standalone.

Pacotes novos

  • PythonScriptRunner.RabbitMQ (spec 005):
    • topologia declarada ou validada;
    • relay do outbox com publisher confirms;
    • IRunQueue transacional;
    • consumidor de StartPipelineRun (run.queued / run.rejected);
    • cancelamento por psr.control;
    • assinaturas IRunEventHandler, duráveis ou por instância;
    • propagação de traceparent, métricas e health check.
  • PythonScriptRunner.Worker (spec 006):
    • consumidor de ExecuteStep com lease renovado;
    • retry com atraso via outbox;
    • reaper de leases;
    • limites por worker e por trilha (Pending FIFO);
    • scheduler cron;
    • limpeza de pastas e graceful shutdown;
    • AddPythonScriptRunnerChecks (banco, broker, uv).
  • hosts/WorkerHost + ServiceDefaults (parte da spec 009):
    • configuração por variáveis de ambiente;
    • /health/live e /health/ready;
    • Serilog em JSON e OTLP;
    • PSR_AUTO_MIGRATE.

Mudanças nos pacotes existentes

  • Core:
    • IRunEngine.ExecuteStepAsync executa uma tentativa de um passo sem gravar nada (D-102);
    • BindInputs;
    • contratos v1 de mensagens e eventos;
    • RunOptions.CorrelationId.
  • EF:
    • AsyncRunLifecycle concentra a lógica transacional assíncrona: criação, claim, conclusão, reaper, Pending e cron;
    • IRunMessageOutbox é o ponto de extensão das mensagens;
    • CRUD de agendamentos com Cronos;
    • reprocesso assíncrono;
    • PsrClock, alinhado ao relógio do PostgreSQL;
    • migration AsyncRuns (runs.trigger_details);
    • migrações concorrentes serializadas por pg_advisory_lock.
  • Contratos públicos: schemas/messages/start-pipeline-run.v1.json e run-event.v1.json, validados contra os payloads reais.

Decisões da fase

ID Decisão
D-104 Um PR único para a fase
D-105 Execuções síncronas também publicam eventos quando a fila está registrada
D-106 CS-2 com weasyprint, testado só no Linux (o CI instala pango)
D-107 WorkerHost + ServiceDefaults agora; Dockerfile na Fase 7
D-108 Coluna runs.trigger_details (missedOccurrences, scheduledFor, scheduleId)
D-109 Worker morto simulado em processo nos testes
D-110 Ponte genérica de fila exclusiva por instância (o SignalR liga nela na Fase 5)
D-111 Testes com rabbitmq:3.13 (versão mínima suportada)
D-112 Lógica transacional assíncrona no pacote EF, como API pública avançada

Mudanças aditivas aos contratos

  • psr.execute-step.v1 ganhou cause e triggeredBy.
  • psr.pipeline.start também tem x-delivery-limit.
  • O envelope de eventos ganhou stageVersion, trigger, retryAt e triggerDetails.
  • Não há Scheduler.DefaultTimeZone no worker: o fuso padrão é o de ScheduleData.

Testes

Tudo roda com PostgreSQL 16, RabbitMQ 3.13 e Mailpit via Testcontainers.

  • Spec 005: AC-1 a AC-12, mais eventos síncronos, ponte por instância e validação dos JSON Schemas.
  • Spec 006: AC-1 a AC-17, mais reprocesso assíncrono (spec 003 AC-10), editor de agendamentos e aviso D-77.
  • Spec 009: WorkerHost de ponta a ponta (WebApplicationFactory) e AC-8 (migrações concorrentes).
  • Local (Windows), build Release: 163 aprovados e 1 pulado, em duas execuções completas seguidas.
    • O pulado é o CS-2 (Spec006_AC02, weasyprint), que roda só no job Ubuntu do CI.
    • dotnet format --verify-no-changes sem pendências.

🤖 Generated with Claude Code

net0well and others added 10 commits October 20, 2026 12:15
…ndamentos (specs 005, 006)

- IRunEngine.ExecuteStepAsync executa uma tentativa de um passo sem gravar nada (D-102);
  BindInputs valida entradas sem executar; RemoveOrphanWorkFolders limpa pastas.
- Contratos v1: IRunQueue/RunHandle, RunEvent/IRunEventHandler, ExecuteStepCommand,
  StartPipelineRunCommand, CancelRunCommand e PsrMessageJson.
- Agendamentos no ICatalogAdmin (D-101) e novos códigos de erro.
- RunOptions.CorrelationId; RunSnapshot com correlação, agendamento e trigger_details (D-108).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…entos no outbox (specs 004, 005, 006)

- AsyncRunLifecycle (D-112): criação transacional com outbox e limite por trilha (Pending FIFO),
  claim com lease, conclusão (próximo passo, retry atrasado, fim), reaper de leases e disparo do cron
  com SKIP LOCKED e coalescência (D-45, D-77, D-85).
- IRunMessageOutbox: ponto de extensão das mensagens (no-op sem fila); toda execução síncrona
  também grava eventos quando a fila está registrada (D-105).
- PsrOutbox para o relay; PsrClock alinhado ao relógio do PostgreSQL.
- CRUD de agendamentos com Cronos, validação de cron/fuso/versão/entradas e SCHEDULE_FILE_INPUT;
  aviso na publicação da trilha (D-77).
- Cancelamento com CancelRun para todas as instâncias e reprocesso assíncrono (QA-003-3).
- Migration AsyncRuns: coluna runs.trigger_details (D-108).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ico e eventos (spec 005)

- Topologia declarada ou verificada (psr.commands, psr.public, psr.events, psr.control, psr.dlx;
  filas quorum com delivery-limit e DLX).
- Relay do outbox com publisher confirms e backoff; IRunQueue transacional.
- Consumidor de StartPipelineRun (run.queued / run.rejected, deduplicação por idempotencyKey ou
  message_id), cancelamento por psr.control e assinaturas IRunEventHandler duráveis ou por
  instância (D-110).
- Propagação de traceparent, métricas e health check (Degraded sem broker).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ron (spec 006)

- StepWorker consome psr.step.execute (uma mensagem por passo), renova o lease e conclui o passo
  na mesma transação do próximo; mensagens duplicadas ou obsoletas são confirmadas sem efeito.
- Reaper de leases, scheduler cron e limpeza de pastas de trabalho.
- Graceful shutdown com ShutdownGracePeriod; métricas psr.worker.*, psr.queue.wait, psr.lease.recovered,
  psr.schedule.* e psr.runs.pending; AddPythonScriptRunnerChecks (banco, broker, uv).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ers (specs 005, 006)

- RabbitMQ.Tests: AC-1 a AC-12 da spec 005, eventos de execução síncrona (D-105) e ponte por
  instância (D-110).
- Worker.Tests: AC-1 a AC-17 da spec 006, reprocesso assíncrono (spec 003 AC-10), editor de
  agendamentos (D-101) e aviso de entrada obrigatória nova (D-77); worker morto simulado em
  processo (D-109).
- Fixture html-para-email (CS-2, mapeamento §13.2); o teste roda só no Linux (D-106).
- ExecuteStep sem runId/stepRunId/attempt vai para a dead-letter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…advisory lock (spec 009)

- WorkerHost: worker standalone configurado por variáveis de ambiente, /health/live e /health/ready,
  PSR_AUTO_MIGRATE (D-107; Dockerfile fica para a Fase 7).
- ServiceDefaults: Serilog (console JSON) e OpenTelemetry com exportação OTLP opcional (D-54).
- MigratePythonScriptRunnerAsync serializa migrações concorrentes com pg_advisory_lock (AC-8).
- Testes: WorkerHost de ponta a ponta (WebApplicationFactory) e migrações concorrentes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…orker (specs 005, 006, 009)

- schemas/messages: start-pipeline-run.v1 e run-event.v1, validados contra os payloads reais.
- CI: instala pango para o weasyprint (CS-2) no job Linux, que roda os testes de fila e worker.
- README: fila, worker, agendamento, eventos e WorkerHost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…(spec 005)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uplo seguro (spec 006)

- O StepWorker limita os passos simultâneos com um semáforo de MaxConcurrency: após a recuperação
  da conexão AMQP, o canal novo recebe entregas enquanto as antigas ainda executam (AC-8).
- Os CancellationTokenSource de parada não são mais descartados: um segundo StopAsync do host não
  quebra o primeiro, que ainda aguarda os passos em andamento.
- Testes de cron com relógio simulado alinhado ao segundo 30 (um avanço = uma ocorrência).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…de consumo (specs 005, 006)

Um StopAsync logo após o StartAsync (ex.: start que falha) zerava o campo antes de a tarefa lê-lo.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@net0well
net0well merged commit 3b343d3 into main Oct 20, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant