Flujos y automatización

Un flujo es un grafo dirigido: nodos con hilos entre ellos, recorridos desde un único punto de partida. No es, deliberadamente, un guion con un bucle. Cuatro reglas fijan la forma, y el editor se niega a publicar un dibujo que rompa alguna de ellas, señalando el nodo que falla.

• Exactamente un disparador. El nodo disparador es la única entrada, y decide qué variables existen en el resto del dibujo.
• Sin ciclos. Un hilo que vuelve a un nodo del que salió se rechaza, porque un flujo no sabe esperar: un bucle sencillamente no terminaría nunca.
• Todo nodo tiene que ser alcanzable desde el disparador. Un nodo suelto es un error que no se ve en una captura de pantalla, así que es un error al publicar.
• Las ramas se recorren una tras otra, nunca a la vez. Dos ramas simultáneas escribirían en state al mismo tiempo, y el resultado dependería del azar del reloj.

El editor es un lienzo y no hay un segundo. Un flujo nuevo se abre directamente en él, y un flujo que era una lista recta de pasos se abre como una cadena recta de nodos.

• La paleta contiene los doce tipos de nodo. Basta con pulsar uno para ponerlo en el lienzo, o arrastrarlo al sitio deseado.
• Un nodo se mueve arrastrándolo por su cabecera. Todo lo demás del nodo es un control, así que no inicia un arrastre.
• Un hilo va de un punto de salida a un punto de entrada. Se puede arrastrar de uno a otro, o pulsar primero la salida y después la entrada. Ambas cosas hacen lo mismo, y la segunda es el camino por teclado.
• Soltar un hilo en el vacío no hace nada. Para quitar uno se selecciona y se pulsa Suprimir, o se usa la cruz que lleva encima.
• El zoom va del 50 al 200 por ciento, Ajustar muestra el dibujo entero y arrastrando el fondo se desplaza la vista. No hay minimapa.

Doce tipos, y la lista es corta a propósito. Cada tipo es un panel, nueve traducciones, una rama en el ejecutor y una fila en la tabla de verdad, así que un tipo que se gana su sitio vale más que uno que casi lo hace.

Cinco momentos, y el elegido no es solo cuándo se ejecuta el flujo. Es también qué variables existen, cuáles ofrece el selector y cuáles se niega a guardar la plataforma. Una ruta que no puede existir en ese momento es un error al guardar y no una cadena vacía a mitad de una ejecución.

Todo valor que un flujo puede leer procede de uno de estos grupos. El selector del editor muestra los grupos que existen en el disparador elegido y nada más. Leer una ruta desconocida es un error y nunca un valor vacío: una suposición equivocada tiene que sonar fuerte.

Un nodo set escribe en state. Su valor es texto literal, salvo que se marque la casilla de expresión; entonces se lee como una plantilla, con las variables de esta ejecución ya puestas.

• Esa casilla es una decisión deliberada. Un valor que por casualidad lleva dos llaves, un trozo de Ansible o un fragmento de Helm, sigue significando lo que decía. Nada cambia de sentido por un cambio que nadie pidió.
• El lenguaje es solo salida. Dos llaves y una ruta, y nada más: sin assign, sin capture, sin bucle, sin include. Lo que se ve en el lienzo es lo que sale, con los valores puestos.
• Hay 46 filtros: texto, números, fechas, los pocos filtros de lista que producen texto, y los propios quote, ini e ipoctet. El selector del editor los enumera. Faltan dos familias a propósito, las que echan a suertes y las que devuelven un objeto donde se quería una palabra.
• Los secretos no están disponibles aquí, ni tampoco los fragmentos reutilizables. Lo que escribe un nodo set acaba en el registro de la ejecución, y un secreto no pinta nada ahí.

Un flujo puede detenerse y esperar a una persona, y puede recorrer los mismos nodos más de una vez. Ninguna de las dos cosas era posible mientras una ejecución no se pudiera aparcar y despertar después; esa cola ya existe.

• Un nodo de aprobación detiene la ejecución, escribe una solicitud y avisa a la cuenta. Responderla requiere un permiso aparte, de modo que quien escribió el flujo no es automáticamente quien lo firma.
• Cada solicitud lleva un plazo y qué ocurre sin respuesta: continuar como aprobado, continuar como rechazado o terminar la ejecución como no aplicable. No hay una cuarta opción, porque una ejecución que espera para siempre es una de la que nadie vuelve a saber.
• Para cada recorre su salida de bucle una vez por elemento de una lista. Dentro del bucle, state.loop contiene el elemento actual, su posición y el total.
• Nada de fuera de un bucle puede conectarse a los nodos que hay dentro. Esos nodos se ejecutan de nuevo en cada vuelta, y un aviso conectado a ambos escribiría un mensaje por vuelta.
• Un paso de aprobación también puede enviar correo. Ese correo llega solo a los miembros que pueden decidir sobre aprobaciones, no a todos los que ven flujos, y la notificación del panel se escribe igualmente.

Una ejecución detenida no es una ejecución fallida. Tres cosas pueden aparcarla, y las tres usan la misma cola: una aprobación, una pausa larga y un subflujo cuyo hijo también espera.

• Una pausa de medio minuto o menos espera dentro de la petición que la inició, que es lo que se quiere al dar un momento a un agente. Todo lo más largo aparca la ejecución, de modo que el pedido que la inició termina enseguida y el resto del flujo llega después.
• Un subflujo ejecuta otro flujo de esta cuenta como un solo paso. Su resultado decide la salida: un hijo correcto, o que no encontró nada que hacer, sigue por OK; uno fallido, por Error. El estado, la ejecución y el nombre del flujo están en state.subflow.
• Un flujo nunca puede alcanzarse a sí mismo, ni directamente ni a través de otro flujo. Se comprueba al desplegar, y el mensaje nombra la cadena encontrada.
• Los flujos pueden llamarse como máximo tres niveles de profundidad. Como cada flujo se edita por separado, ese límite se comprueba dos veces: al desplegar y mientras la ejecución avanza de verdad.

Un extremo de webhook da a un sistema externo una URL propia. Ese sistema envía JSON, se ejecuta el flujo que hay detrás de la URL, y la respuesta es un código de estado desnudo. Los extremos viven bajo Scripts, en la pestaña Webhooks, y son objetos propios: el mismo extremo puede apuntar a otro flujo sin que el remitente note nada.

1. 01Crear el extremo y darle un nombre reconocible más adelante. La URL se genera sola y no se puede elegir: 32 caracteres al azar, o sea 160 bits, con lo cual adivinarla no es una estrategia.
2. 02Elegir cómo se acredita el remitente y copiar el secreto. Se muestra una sola vez y nunca más; si se pierde, se regenera, y entonces también cambia la URL.
3. 03Apuntar el extremo a un flujo cuyo disparador sea un webhook. El extremo puede existir antes que el flujo, y hasta entonces una petición se acepta y se responde con un 202 que no arranca nada. Ese es el orden en que la gente construye esto de verdad, así que no se trata como un error.

La firma es la palabra sha256, un signo igual y el HMAC-SHA256 sobre exactamente los bytes de la marca de tiempo, un punto y el cuerpo, en hexadecimal minúsculo. Va en X-Provibr-Signature, y la marca de tiempo en sí va en X-Provibr-Timestamp, en segundos enteros desde la época.

Una petición cuya marca de tiempo tenga más de 300 segundos, o esté en el futuro, se rechaza con un 401. Esa ventana es una regla real y no un adorno, porque la marca de tiempo está dentro del material firmado: una petición interceptada no se puede reenviar mañana pegándole encima una marca nueva.

Firmar una petición es una línea de openssl. Este ejemplo envía un objeto pequeño; el texto de consola se queda en inglés a propósito, para que coincida con lo que muestra la terminal.

# 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 petición deja un recibo, aceptada o no: el desenlace, el estado devuelto, la dirección de origen completa y cuántos bytes se leyeron realmente. El cuerpo no se guarda nunca. Los recibos desaparecen a los 90 días, antes que las propias ejecuciones, porque una dirección de origen es un dato personal de alguien que no es cliente nuestro.

Dos preguntas que se parecen tienen aquí dos respuestas distintas. Quién cambió qué y cuándo es una revisión. Qué recorrió realmente esta ejecución concreta es una copia guardada en la propia ejecución. Una instantánea no puede responder a la primera pregunta y una revisión no puede responder a la segunda, así que existen las dos.

• Cada publicación escribe una revisión, incluso una publicación que no cambió nada. El número sube por flujo y no se reutiliza jamás.
• La diferencia entre dos revisiones es una lista legible y no JSON en bruto: un nodo añadido, quitado o cambiado con los campos nombrados, un hilo añadido o quitado. Dónde está un nodo en el lienzo no es un cambio.
• Restaurar no rebobina. Escribe el dibujo antiguo como una revisión nueva encima de la historia, con una nota de dónde venía.
• Cada ejecución conserva el dibujo que recorrió. Editar un flujo después nunca reescribe lo que hizo una ejecución más antigua.
• Una ejecución tiene una fila por nodo visitado, con el desenlace y la salida por la que se fue, y una fila por nodo no visitado con el motivo. No visitado es un hecho que merece anotarse, no una ausencia.
• La lista de ejecuciones filtra por disparador, estado y revisión, y se exporta a CSV. La exportación se detiene en 5000 filas y lo dice dentro del propio fichero en lugar de acabarse en silencio.

Las plantillas de script llevan al lado su propia historia: cada versión guardada del contenido, y una diferencia línea a línea entre dos cualesquiera de ellas.