@@ -5,7 +5,8 @@ com contrato de entrada/saída, trilhas (**Pipelines**), execução assíncrona
55cron e painel Vue opcional.
66
77> Projeto em desenvolvimento. Esta versão entrega o ** Core Runner** (execução síncrona de Stages e de
8- > trilhas), o SDK Python ** ` psrunner ` ** e a ** persistência em PostgreSQL** (catálogo versionado e histórico).
8+ > trilhas), o SDK Python ** ` psrunner ` ** , a ** persistência em PostgreSQL** (catálogo versionado e histórico) e a
9+ > ** execução assíncrona** com RabbitMQ, worker e agendamento cron.
910
1011## Como funciona
1112
@@ -120,21 +121,58 @@ await app.Services.MigratePythonScriptRunnerAsync(); // explícito; ou Generat
120121 um job de manutenção cria partições à frente e remove as antigas. Uma trilha pode encurtar a retenção.
121122- ** Auditoria:** ações humanas (` Actor.User(...) ` ) ficam em ` psr.audit_events ` ; disparos automáticos ficam na própria execução.
122123
124+ ## Fila, worker e agendamento (RabbitMQ)
125+
126+ Com ` PythonScriptRunner.RabbitMQ ` e ` PythonScriptRunner.Worker ` , execuções podem ser enfileiradas. Cada passo é uma
127+ mensagem: o worker assume o passo com um * lease* , executa o processo Python e grava o resultado e a mensagem do próximo
128+ passo na mesma transação (outbox no PostgreSQL). Enfileirar funciona mesmo com o broker fora do ar.
129+
130+ ``` csharp
131+ builder .Services
132+ .AddPythonScriptRunner ()
133+ .AddEntityFrameworkCore (o => o .UseNpgsql (builder .Configuration .GetConnectionString (" psr" )! ))
134+ .AddRabbitMq (o => o .ConnectionString = builder .Configuration .GetConnectionString (" rabbitmq" )) // RabbitMQ 3.13+
135+ .AddWorker (o => o .MaxConcurrency = 8 ) // só nos processos que executam passos
136+ .AddRunEventHandler <NotificarErp >(s => s .Subscription (" erp" ).On (" run.succeeded.calculo-progressao" , " run.failed.*" ));
137+ builder .Services .AddHealthChecks ().AddPythonScriptRunnerChecks (); // banco, broker e uv
138+
139+ // ...
140+ RunHandle run = await queue .EnqueuePipelineAsync (" calculo-progressao" , new { a1 = 1 , razao = 2 , n = 4 , coeficientes = new [] { 1 , 0 , 1 } });
141+ ```
142+
143+ - ** Confiabilidade:** retry automático por Stage com atraso exponencial; worker perdido é detectado pelo * lease* e o
144+ passo é retomado (Stage idempotente ou com retry restante) ou falha com ` WorkerLost ` para reprocesso manual;
145+ mensagens duplicadas não executam o passo duas vezes.
146+ - ** Concorrência:** ` MaxConcurrency ` por worker e ` max_concurrent_runs ` por trilha (as demais esperam como ` Pending ` , em ordem).
147+ - ** Cancelamento:** ` IRunManager.CancelAsync ` encerra a árvore de processos no worker que executa o passo.
148+ - ** Agendamento:** ` ICatalogAdmin.CreateScheduleAsync ` com expressão cron e fuso IANA (padrão ` America/Sao_Paulo ` );
149+ ocorrências perdidas viram uma execução de recuperação; vários workers nunca disparam a mesma ocorrência.
150+ - ** Sistemas externos:** o comando público ` StartPipelineRun ` (exchange ` psr.public ` ) inicia trilhas e os eventos
151+ ` run.* ` /` step.* ` (exchange ` psr.events ` ) informam o andamento e as saídas. Contratos em ` schemas/messages ` .
152+ - ** Observabilidade:** ` ActivitySource ` e ` Meter ` ` PythonScriptRunner ` ; o ` traceparent ` acompanha a execução até o worker.
153+
154+ O host ` hosts/PythonScriptRunner.WorkerHost ` é um worker pronto, configurado por variáveis de ambiente
155+ (` ConnectionStrings__psr ` , ` ConnectionStrings__rabbitmq ` , ` PythonScriptRunner__Worker__MaxConcurrency ` ,
156+ ` PythonScriptRunner__Secrets__<NOME> ` , ` PSR_AUTO_MIGRATE=true ` ), com ` /health/live ` , ` /health/ready ` , logs JSON e OTLP.
157+
123158## Requisitos
124159
125160- .NET 10 SDK
126161- [ uv] ( https://docs.astral.sh/uv/ ) no PATH (cria e cacheia um ambiente Python por conjunto de dependências)
127- - PostgreSQL 16+ apenas para o pacote de persistência (os testes usam Docker/Testcontainers)
162+ - PostgreSQL 16+ apenas para o pacote de persistência e RabbitMQ 3.13+ para a fila (os testes usam Docker/Testcontainers)
128163
129164## Estrutura
130165
131166| Pasta | Conteúdo |
132167| -------| ----------|
133168| ` src/PythonScriptRunner.Abstractions ` | contratos públicos (tipos de campo, ` StageDefinition ` , ` RunResult ` , ` PsrFile ` , interfaces) |
134169| ` src/PythonScriptRunner.Core ` | catálogos (código e pasta), validação, ambientes uv, executor de processos, runner |
135- | ` src/PythonScriptRunner.EntityFrameworkCore ` | PostgreSQL: catálogo versionado, histórico, arquivos, idempotência, outbox, auditoria, retenção |
170+ | ` src/PythonScriptRunner.EntityFrameworkCore ` | PostgreSQL: catálogo versionado, histórico, arquivos, idempotência, outbox, auditoria, retenção, agendamentos e ciclo das execuções enfileiradas |
171+ | ` src/PythonScriptRunner.RabbitMQ ` | topologia, relay do outbox, ` IRunQueue ` , comando público, eventos e assinaturas |
172+ | ` src/PythonScriptRunner.Worker ` | execução dos passos enfileirados, * lease* , retry, cancelamento, cron |
173+ | ` hosts ` | ` WorkerHost ` e ` ServiceDefaults ` (Serilog, OpenTelemetry, health checks) |
136174| ` python/psrunner ` | SDK Python (` @stage ` , ` Context ` , ` File ` , ` StageError ` , ` psrunner.testing ` , CLI) |
137- | ` schemas ` | JSON Schemas do ` stage.json ` e do ` *.pipeline.json ` |
175+ | ` schemas ` | JSON Schemas do ` stage.json ` , do ` *.pipeline.json ` e das mensagens públicas |
138176| ` tests ` | testes .NET (unitários e de integração com Python real) e fixtures de trilha |
139177
140178## Desenvolvimento
@@ -143,6 +181,8 @@ await app.Services.MigratePythonScriptRunnerAsync(); // explícito; ou Generat
143181dotnet build
144182dotnet test --project tests/PythonScriptRunner.Core.Tests
145183dotnet test --project tests/PythonScriptRunner.EntityFrameworkCore.Tests # precisa de Docker
184+ dotnet test --project tests/PythonScriptRunner.RabbitMQ.Tests # precisa de Docker
185+ dotnet test --project tests/PythonScriptRunner.Worker.Tests # precisa de Docker
146186
147187cd python/psrunner
148188uv sync
0 commit comments