Fluxos e automação

Um fluxo é um grafo orientado: nós ligados por fios, percorridos a partir de um único ponto de partida. Não é, de propósito, um guião com um ciclo. Quatro regras fixam a forma, e o editor recusa publicar um desenho que quebre alguma delas, apontando o nó errado.

• Exatamente um disparador. O nó disparador é a única entrada, e é ele que decide que variáveis existem no resto do desenho.
• Sem ciclos. Um fio que volta a um nó de onde saiu é recusado, porque um fluxo não sabe esperar: um ciclo simplesmente nunca terminaria.
• Todos os nós têm de ser alcançáveis a partir do disparador. Um nó solto é um erro que uma captura de ecrã não mostra, por isso é um erro no momento de publicar.
• Os ramos são percorridos um a seguir ao outro, nunca lado a lado. Dois ramos ao mesmo tempo escreveriam em state no mesmo instante, e o resultado dependeria do acaso do relógio.

O editor é uma tela, e não há uma segunda. Um fluxo novo abre logo nela, e um fluxo que era uma lista direita de passos abre como uma cadeia direita de nós.

• A paleta contém os doze tipos de nó. Basta clicar num deles para o pousar na tela, ou arrastá-lo para o sítio pretendido.
• Um nó move-se arrastando-o pelo seu cabeçalho. Tudo o resto no nó é um controlo e portanto não inicia um arrasto.
• Um fio vai de um ponto de saída para um ponto de entrada. Arrasta-se de um para o outro, ou clica-se primeiro na saída e depois na entrada. As duas coisas fazem o mesmo, e a segunda é o caminho pelo teclado.
• Largar um fio no vazio não faz nada. Para remover um, seleciona-se e carrega-se em Delete, ou usa-se a cruz que está em cima dele.
• O zoom vai de 50 a 200 por cento, Ajustar mostra o desenho inteiro, e arrastar o fundo desloca a vista. Não há minimapa.

Doze tipos, e a lista é curta de propósito. Cada tipo é um painel, nove traduções, um ramo no executor e uma linha na tabela de verdade, por isso um tipo que ganha o seu lugar vale mais do que um que quase o ganha.

Cinco momentos, e o que se escolhe não é só quando o fluxo corre. É também que variáveis existem, quais o seletor oferece e quais a plataforma recusa guardar. Um caminho que não pode existir nesse momento é um erro ao guardar, e não um texto vazio a meio de uma execução.

Todos os valores que um fluxo pode ler vêm de um destes grupos. O seletor do editor mostra os grupos que existem para o disparador escolhido, e mais nada. Ler um caminho desconhecido é um erro e nunca um valor vazio: um pressuposto errado tem de fazer barulho.

Um nó set escreve em state. O seu valor é texto literal, a não ser que se marque a caixa de expressão; aí é lido como um modelo, com as variáveis desta execução já preenchidas.

• Essa caixa é uma decisão deliberada. Um valor que por acaso tem duas chavetas, um pedaço de Ansible ou um fragmento de Helm, continua a significar o que dizia. Nada muda de sentido por causa de uma alteração que ninguém pediu.
• A linguagem é só saída. Duas chavetas e um caminho, e mais nada: sem assign, sem capture, sem ciclo, sem include. O que está na tela é o que sai, com os valores preenchidos.
• Há 46 filtros: texto, números, datas, os poucos filtros de lista que produzem texto, e os próprios quote, ini e ipoctet. O seletor do editor enumera-os. Faltam duas famílias de propósito, as que tiram à sorte e as que devolvem um objeto onde se queria uma palavra.
• Os segredos não estão disponíveis aqui, nem os fragmentos reutilizáveis. O que um nó set escreve acaba no relato da execução, e um segredo não tem nada que fazer ali.

Um fluxo pode parar e esperar por uma pessoa, e pode percorrer os mesmos nós mais do que uma vez. Nenhuma das duas coisas era possível enquanto uma execução não pudesse ser estacionada e acordada depois; essa fila já existe.

• Um nó de aprovação para a execução, cria um pedido e avisa a conta. Responder exige um direito separado, para que quem escreveu o fluxo não seja automaticamente quem o assina.
• Cada pedido leva um prazo e o que acontece sem resposta: continuar como aprovado, continuar como rejeitado ou terminar a execução como não aplicável. Não há uma quarta opção, porque uma execução que espera para sempre é uma execução de que ninguém volta a saber.
• Para cada percorre a sua saída de ciclo uma vez por elemento de uma lista. Dentro do ciclo, state.loop contém o elemento atual, a sua posição e o total.
• Nada de fora de um ciclo pode ligar-se aos nós que estão dentro. Esses nós correm de novo em cada volta, e um aviso ligado a ambos escreveria uma mensagem por volta.
• Um passo de aprovação também pode enviar e-mail. Esse e-mail chega apenas aos membros que podem decidir sobre aprovações, não a todos os que veem fluxos, e a notificação do painel é escrita de qualquer forma.

Uma execução parada não é uma execução falhada. Três coisas podem pô-la de lado, e as três usam a mesma fila: uma aprovação, uma pausa longa e um subfluxo cujo filho também espera.

• Uma pausa de meio minuto ou menos espera dentro do pedido que a iniciou, que é o que se pretende ao dar um momento a um agente. Tudo o que demore mais põe a execução de lado, para que a encomenda que a iniciou termine já e o resto do fluxo venha depois.
• Um subfluxo executa outro fluxo desta conta como um único passo. O resultado decide a saída: um filho bem-sucedido, ou que nada encontrou para fazer, segue por OK; um filho falhado segue por Erro. O estado, a execução e o nome do fluxo ficam em state.subflow.
• Um fluxo nunca pode alcançar-se a si próprio, nem diretamente nem através de outro fluxo. Isso é verificado ao publicar, e a mensagem nomeia a cadeia encontrada.
• Os fluxos podem chamar-se no máximo três níveis de profundidade. Como cada fluxo é editado por si, esse limite é verificado duas vezes: ao publicar e enquanto a execução avança de facto.

Um ponto de entrada de webhook dá a um sistema exterior um URL só dele. Esse sistema envia JSON, o fluxo por trás do URL corre, e a resposta é um código de estado nu. Os pontos de entrada vivem em Scripts, no separador Webhooks, e são objetos próprios: o mesmo ponto de entrada pode apontar para outro fluxo sem que o remetente dê por isso.

1. 01Criar o ponto de entrada e dar-lhe um nome que se reconheça mais tarde. O URL é gerado e não se pode escolher: 32 caracteres aleatórios, ou seja 160 bits, com o que adivinhar não é uma estratégia.
2. 02Escolher como o remetente se identifica, e copiar o segredo. É mostrado uma só vez e nunca mais; se se perder, regenera-se, e então também muda o URL.
3. 03Apontar o ponto de entrada para um fluxo cujo disparador seja um webhook. O ponto de entrada pode existir antes do fluxo, e até lá um pedido é aceite e recebe um 202 que não arranca nada. É a ordem pela qual as pessoas constroem isto de verdade, por isso não é tratado como um erro.

A assinatura é a palavra sha256, um sinal de igual e o HMAC-SHA256 sobre exatamente os bytes da marca temporal, de um ponto e do corpo, em hexadecimal minúsculo. Vai em X-Provibr-Signature, e a própria marca temporal vai em X-Provibr-Timestamp, em segundos inteiros desde a época.

Um pedido cuja marca temporal tenha mais de 300 segundos, ou esteja no futuro, é recusado com um 401. Essa janela é uma regra a sério e não um adorno, porque a marca temporal está dentro do material assinado: um pedido intercetado não se consegue reenviar amanhã colando-lhe por cima uma marca nova.

Assinar um pedido é uma linha de openssl. Este exemplo envia um objeto pequeno; o texto para o terminal fica em inglês de propósito, para coincidir com aquilo que o terminal mostra.

# Sign the raw body together with the timestamp, then post it.
SECRET="$PROVIBR_WEBHOOK_SECRET"
BODY='{"reason":"maintenance","attempt":1}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -sS -X POST 'https://app.provibr.com/api/hooks/flows/<your-slug>' \
  -H 'Content-Type: application/json' \
  -H "X-Provibr-Timestamp: $TS" \
  -H "X-Provibr-Signature: sha256=$SIG" \
  --data "$BODY"

Cada pedido deixa um recibo, aceite ou não: o desfecho, o estado devolvido, o endereço de origem por inteiro e quantos bytes foram mesmo lidos. O corpo nunca é guardado. Os recibos desaparecem ao fim de 90 dias, mais cedo do que as próprias execuções, porque um endereço de origem é um dado pessoal de alguém que não é nosso cliente.

Duas perguntas parecidas têm aqui duas respostas diferentes. Quem mudou o quê, e quando, é uma revisão. O que esta execução em concreto percorreu de facto é uma cópia guardada na própria execução. Uma fotografia não consegue responder à primeira pergunta e uma revisão não consegue responder à segunda, por isso existem ambas.

• Cada publicação escreve uma revisão, mesmo uma publicação que não mudou nada. O número sobe por fluxo e nunca é reutilizado.
• A diferença entre duas revisões é uma lista legível e não JSON em bruto: um nó acrescentado, removido ou alterado com os campos nomeados, um fio acrescentado ou removido. Onde está um nó na tela não é uma alteração.
• Repor não rebobina. Escreve o desenho antigo como uma revisão nova por cima da história, com uma nota a dizer de onde veio.
• Cada execução guarda o desenho que percorreu. Editar um fluxo depois nunca reescreve o que uma execução mais antiga fez.
• Uma execução tem uma linha por cada nó visitado, com o desfecho e a saída por onde passou, e uma linha por cada nó não visitado com o motivo. Não visitado é um facto que vale a pena anotar, não uma ausência.
• A lista de execuções filtra por disparador, estado e revisão, e exporta-se para CSV. A exportação para às 5000 linhas e di-lo dentro do próprio ficheiro em vez de acabar em silêncio.

Os modelos de script mantêm ao lado uma história própria: cada versão guardada do conteúdo, e uma diferença linha a linha entre duas quaisquer delas.