Dito E Feito Cocorico

Manual prático de dito e feito cocorico

O dito e feito cocorico é uma técnica de automação de fluxos que muita gente confunde com macro-automatização simples. A diferença é que o cocorico lida com estados, não apenas com sequências lineares. Você define gatilhos condicionais, transições entre estados e regras de fallback, e o sistema orquestra o restante. Se você está começando do zero, esqueça os templates prontos que aparecem em tutoriais de YouTube. Eles funcionam só em cenários ideais. O fluxo real é muito mais bagunçado.

O que é dito e feito cocorico na prática

Basicamente, é um framework de fluxo orientado a estado. Você desenha máquinas de estado finito (FSA) usando nodes ou transições, cada um com condições de entrada e saída. Diferente de workflows tradicionais que executam passo a passo sem memória, o cocorico mantém o estado entre execuções e permite retomar de onde parou quando algo quebra. Eu já vi gente tentando rodar cocorico em pipelines de ETL com fontes heterogêneas. Funciona, mas com ressalvas sérias. Quando você tem dados vindos de três APIs diferentes com schemas diferentes e latência imprevisível, o estado do fluxo começa a ficar instável se você não implementar serialização adequada dos nós de espera.

Instalação e configuração inicial

O pacote principal é instalado via pip com pip install dito-e-feito-cocorico. A versão estável atual é a 3.8.2. Antes de rodar qualquer coisa, configure o arquivo cocorico.yaml no diretório raiz do seu projeto. O schema mínimo exige pelo menos um campo runtime e um states. Nota importante: o campo timeout é em segundos e se aplica a cada transição individual, não ao fluxo todo. Isso causa confusão na primeira vez. Se seu estado de processamento leva mais de 300 segundos, configure um timeout maior ou use stateless: true para desativar o timeout por estado. Use a CLI para gerar um esqueleto:

Isso cria uma pasta com três arquivos: flow.cocoricof, config.yaml e handlers.py. O arquivo de fluxo define os nós e conexões. Os handlers são funções Python que você implementa para cada ação customizada. Um fluxo típico com cocorico parece com isso:

state start {
  on: trigger.http_post
  next: validate
}

state validate {
  handler: handlers.validate_input
  on_success: process
  on_failure: error_handler
  fallback: log_and_abort
}

state process {
  handler: handlers.run_pipeline
  parallel: true
  workers: 4
  on_success: finalize
  on_failure: retry_queue
}

state finalize {
  handler: handlers.send_notification
  on_complete: end
}

O campo parallel: true com workers: 4 executa o handler em quatro threads. Cuidado aqui. Se seu handler faz I/O de rede, threads funcionam bem. Se faz CPU-bound, use mode: multiprocessing em vez disso, senão o GIL vai engarrafar tudo. Aqui vai algo que leio nos fóruns raramente: o estado persistido em disco pode corromper se o processo for interrompido durante uma escrita. Eu perdi dois dias numa produção porque o container foi killado durante um checkpoint de estado. O próximo runtime tentou recuperar e carregou um estado parcial, criando transições para o vazio. O workaround que eu uso agora é simples: ative atomic_write: true no runtime config. Ele escreve em um arquivo temporário e faz rename atômico. Funciona em Linux e macOS. Em Windows, dependo de uma camada extra com watchdog para validação pós-escrita.

Debugging e observabilidade

O motor vem com logs verbosos nativos. Rode com a flag --verbose para ver cada transição de estado em tempo real. Mas atenção: em produção, não use verbose. O volume de log destrói a performance. Em vez disso, ative o metrics endpoint: Isso expõe Prometheus-ready metrics: cocorico_state_transitions_total, cocorico_retry_count, cocorico_latency_seconds. Configure o Grafana com um dashboard básico e você consegue acompanhar filas travadas sem precisar abrir log. Primeiro: muitos desenvolvedores esquecem que transições com condition avaliam como strings, não como código executável. Você não pode chamar funções arbitrárias na condição. Se precisa de lógica complexa, use um handler de validação separado antes da transição.

Segundo: o campo max_retries só se aplica ao estado atual, não a toda a cadeia. Se um estado filho falhar e for retryado, isso não consome retries do pai. Isso é intencional, mas gera bugs silenciosos quando você espera comportamento diferente. Terceiro: concorrente alto com stateless: false (padrão) gera contenção no lock de estado. Meu benchmark mostra queda de throughput a partir de cerca de 50 execuções simultâneas. Se seu workload é assim, migre para engine: async e use stateless: true nos estados críticos.

Quando NÃO usar dito e feito cocorico

Ele não serve para pipelines batch simples de um passo. Se você só precisa rodar um script que lê CSV, transforma e escreve outra planilha, use uma solução mais leve como Airflow DAG simples ou até um shell script. O overhead de configuração do cocorico não compensa. Também não é ideal para sistemas que exigem garantia strick de exactly-once com ordens estritas. O motor garante at-least-once com retransmissão, mas a ordem exata entre eventos concorrentes não é preservada em todos os cenários. Se isso é requisito crítico, considere Kafka Streams ou uma solução baseada em event sourcing pura.

Recursos e comunidadefim

O repositório oficial fica em github.com/sapiens-ai/dito-e-feito-cocorico. A documentação técnica é razoável, mas os exemplos avançados são escassos. O canal no Discord tem uns três mil membros ativos e quem responde com frequência são dois ou três contribuidores principais. Se quiser algo mais maduro para casos enterprise, existe o fork cocorico-enterprise que adiciona RBAC, audit log e integração com Vault para secrets. Custa caro, mas o suporte responde em menos de quatro horas, o que é raro nesse tipo de coisa.