16
Fallas, operación y evolución

Arquitecturas reales y cierre del curso

Fallas, operación y evolución

Semana 16 — Arquitecturas reales y cierre del curso

Objetivos

  • Leer la descripción de la arquitectura de un sistema real e identificar sus escenarios de calidad, sus decisiones y los trade-offs que aceptó.
  • Reconocer en casos reales las ideas del curso (estilos, tácticas, replicación, sharding, cache, resiliencia) y cómo cambiaron cuando cambió el contexto.
  • Presentar y defender la arquitectura de un sistema propio: qué se decidió, qué se descartó y cómo se comprobó.
  • Describir qué hace en un equipo quien se ocupa de la arquitectura, y con qué otras actividades se cruza.

Sesión A — Casos: la arquitectura de sistemas reales · ✂️ el rol de quien hace arquitectura

Lecturas:

Lecturas complementarias:

  • The Architecture of Open Source Applications, vol. 2, nginx.
  • Kirsten Westeinde, Deconstructing the Monolith (Shopify, 2019).
  • ✂️ Software Architecture in Practice, cap. 24 The Role of Architects in Projects y cap. 25 Architecture Competence; Martin Fowler, Who Needs an Architect?.

Temas:

  • Cómo se lee un caso. Las cinco preguntas del curso: ¿cuál era el escenario que apretaba (carga, crecimiento, fallas, velocidad de cambio)?, ¿qué alternativas había?, ¿qué se eligió?, ¿qué se sacrificó?, ¿cómo supieron que funcionó? Un texto que solo cuenta la solución, sin lo que costó, es publicidad.
  • Stack Overflow (según el artículo de 2016): un sitio de muchísimo tráfico atendido con pocas máquinas: nueve servidores web, dos clusters de SQL Server (cada uno con un principal y réplicas asíncronas), caches en varios niveles y un servicio aparte para las etiquetas. El artículo no usa la palabra “monolito” ni presenta “escalar hacia arriba” como una decisión: es lo que se infiere del hardware que lista. Lo que enseña: el estilo no determina la escala, y la simplicidad es una decisión con sus propios costos (dependencia de pocas máquinas grandes y de un equipo que conoce cada detalle).
  • Discord (2023): mensajes guardados en un almacén distribuido con sharding por canal y por ventana de tiempo. El problema: particiones calientes (un canal enorme) que degradaban a los demás. Las decisiones: una capa de servicios de datos delante, que une las peticiones idénticas y las enruta por canal para proteger la base de datos, y una migración a otro motor. La migración se planeó gradual y terminó haciéndose con un migrador que copió todo en nueve días y un solo cambio. Lo que enseña: los hot spots (semana 11), proteger un recurso compartido (la relación con el bulkhead de la semana 14 es nuestra, no del artículo) y lo que una migración cuesta de verdad (semanas 9 y 15).
  • Figma (2024): una sola base de datos PostgreSQL en 2020; para fines de 2022, cache, réplicas de lectura y una docena de bases de datos separadas por dominio; después, sharding horizontal, que a la fecha del artículo cubría solo las tablas más simples. Lo que enseña: agotar cada táctica antes de pasar a la siguiente y más cara, elegir la clave de sharding por los patrones de acceso, y separar el sharding lógico (barato de revertir) del físico (posible de revertir, pero más complejo).
  • Lo que tienen en común: ninguno empezó con la arquitectura con la que terminó, y cada cambio respondió a un problema medido. En lo demás difieren, y eso también enseña: Figma migra por pasos con vuelta atrás; Discord termina cambiando de una sola vez; Stack Overflow no cuenta una migración ni casi nada de lo que salió mal. Al leer, distingan lo que el artículo afirma de lo que uno infiere.
  • El recorrido del curso, en una página: la arquitectura la determinan los atributos de calidad (semanas 1 y 2); la modularidad decide cuánto cuesta cambiar (3 y 4); distribuir se paga con fallas parciales y consistencia (5, 9 a 13); cada táctica mejora un atributo y cuesta otro (6); una decisión vale lo que vale su justificación y su comprobación (7 y 15); y el sistema tiene que seguir funcionando mientras algo falla (14).
  • Lo que el curso no cubrió y dónde sigue: el despliegue y la operación en detalle (pipelines, infraestructura como código, orquestación de contenedores), la arquitectura en la nube y sus costos, los algoritmos de los sistemas distribuidos (consenso, relojes), y el diseño de la interfaz de usuario.
  • ✂️ El rol. Arquitectura es una actividad antes que un cargo: en un equipo pequeño la hace todo el equipo. Lo que exige: entender el negocio lo suficiente para saber qué atributo importa, conocer un abanico amplio de opciones más que una a fondo, comunicar (la mayor parte del trabajo es explicar y negociar), y seguir cerca del código para que las decisiones no se separen de la realidad. La idea de Fowler: una de las tareas más importantes de quien hace arquitectura es quitar arquitectura, eliminando lo irreversible.
  • Error común: copiar la arquitectura de un caso sin su contexto. La de Discord responde a billones de mensajes; la de Stack Overflow, a un equipo y un patrón de lectura muy particulares.

Sesión B — Presentaciones finales

Cada equipo presenta su Tinkuy de P5. Formato y contenido en projects/p5-fallas/README.md.

Qué se presenta:

  • El recorrido: cómo era el sistema en P0 y cómo es ahora, con los diagramas de contenedores de antes y de después.
  • Las tres decisiones más importantes del semestre, cada una con su escenario, las alternativas que se descartaron y la medición que la respalda.
  • Una decisión de la que hoy se arrepienten, o que tomarían distinto, y por qué.
  • Una demostración en vivo: la venta bajo carga con la pasarela lenta, y lo que muestran los logs y las métricas mientras ocurre.
  • Lo que queda como deuda, escrito como tal.

Temas:

  • Cómo se presenta una arquitectura: primero el problema y los escenarios, después las decisiones, al final la tecnología. Un diagrama por idea, con su leyenda.
  • Cómo se critica una arquitectura: con escenarios, no con preferencias. “¿Qué pasa con este diseño si…?” es una pregunta útil; “yo habría usado otra cosa” no lo es.

Laboratorio — Defensa oral del proyecto

Cada equipo responde preguntas sobre su entrega. Cualquier integrante puede recibir cualquier pregunta.

  1. Recorrer una compra de punta a punta sobre el diagrama de contenedores: qué componente interviene en cada paso, qué pasa si ese paso falla y dónde quedaría registrado.
  2. Elegir un ADR del equipo al azar: explicar el contexto, por qué se descartó cada alternativa y qué tendría que cambiar para revisar la decisión.
  3. Correr make fitness y explicar qué decisión protege cada comprobación. Romper una a propósito y mostrar qué reporta.
  4. Con Toxiproxy, aplicar una falla que el docente elige en el momento (latencia, corte, respuestas lentas en una parte de las conexiones) y explicar lo que se observa con los logs y las métricas del equipo.
  5. Responder un cambio de requisito propuesto en el momento (“se venderán entradas de cien eventos a la vez”, “se agrega un segundo país con otra pasarela”): qué partes de la arquitectura lo aguantan, cuáles no y qué decisión habría que revisar.

Entregas

P5 · Cuando algo falla se entrega esta semana (projects/p5-fallas/README.md), con el documento de arquitectura final.

Preguntas de repaso

  1. Para el caso que leyeron, escriban el escenario de calidad principal con sus seis partes y la decisión que lo atendió.
  2. Comparen las migraciones de Discord y de Figma con la secuencia expandir, migrar y contraer: ¿cuál escribió en los dos sistemas a la vez y cuál lo evitó a propósito? ¿Qué pagó cada una?
  3. Stack Overflow escala hacia arriba y usa mucha cache. ¿Qué riesgos acepta con eso? ¿En qué contexto sería una mala decisión?
  4. Elijan una decisión de su Tinkuy y digan qué cambio en el contexto (carga, equipo, negocio) los haría revisarla.
  5. ¿Por qué “reducir la cantidad de decisiones irreversibles” resume bien el trabajo de arquitectura? Den un ejemplo del proyecto.
  6. Nombren un tema que el curso no cubrió y que su Tinkuy necesitaría para salir a producción.

Código de la semana

Compilar y probar dentro del contenedor del curso con make y make test.

Ejemplos (10)Errores (1)Pruebas (2)Compilación (3)

Ejemplos

Los programas que usan los apuntes y la clase.

case-worksheet-template.mdDescargar case-worksheet-template.md
# Ficha de lectura de un caso: <sistema>

<!--
Template de la ficha de lectura de un caso real. Copien el archivo, reemplacen
cada <indicación> por su texto y revísenlo con:

    node check-doc.ts worksheet <este archivo>

En cada pregunta hay dos campos. En "Lo que dice el texto" va solo lo que el
texto afirma, con sus palabras o sus números. En "Lo que inferimos" va lo que
ustedes deducen: es válido, pero es de ustedes, y en la presentación se dice
así. Si no infieren nada, escriban "Nada".
-->

## El texto

- **Título:** <el título, tal como está publicado>
- **Quién lo escribe:** <nombre y rol: no lee igual quien operó el sistema que quien lo vende>
- **Fecha:** <fecha de publicación, con el año>
- **Enlace:** <la URL>
- **Qué describe:** <qué sistema o qué parte, y en qué momento de su historia>

## 1. El escenario que apretaba

- **Lo que dice el texto:** <qué problema cuenta: carga, crecimiento, fallas, velocidad de cambio; con los números que da>
- **Lo que inferimos:** <el escenario de seis partes que escribirían ustedes; qué partes tuvieron que suponer>

## 2. Las alternativas

- **Lo que dice el texto:** <qué otras opciones nombra y por qué las descartó>
- **Lo que inferimos:** <alternativas que el texto no nombra y que ustedes habrían evaluado>

## 3. Lo que se eligió

- **Lo que dice el texto:** <la decisión, en una o dos frases, y las piezas que la implementan>
- **Lo que inferimos:** <qué estilo, táctica o patrón del curso es, aunque el texto no lo llame así>

## 4. Lo que se sacrificó

- **Lo que dice el texto:** <qué costo reconoce: qué dejó de poder hacerse, qué se volvió más difícil>
- **Lo que inferimos:** <costos que el texto no menciona y que la decisión trae>

## 5. Cómo supieron que funcionó

- **Lo que dice el texto:** <qué midieron antes y después, o qué evidencia dan>
- **Lo que inferimos:** <qué faltaría medir para estar seguros>

## Lo que el texto no dice

<Lo que hace falta saber para evaluar la decisión y no está: costos, tamaño del
equipo, lo que salió mal, qué pasó después de la fecha del texto.>

## Semanas del curso

<Qué semanas ilustra el caso y con qué parte: "semana 11: el hot spot de…".>

## Qué no copiaríamos sin su contexto

<Una decisión del caso que sería mala idea en un sistema del tamaño de los que
ustedes van a construir, y qué tendría que cambiar para que fuera buena.>
check-doc.tsDescargar check-doc.ts
// Revisa los tres documentos de la semana: la ficha de lectura de un caso, el
// guion de la presentación final y la lista de la defensa.
//
//   node check-doc.ts worksheet    mi-ficha.md
//   node check-doc.ts presentation mi-presentacion.md
//   node check-doc.ts checklist    defence-checklist.md
//
// Comprueba la forma: que estén las secciones y los campos, que ninguno siga
// con el texto del template y unas pocas cosas que sí se pueden contar (que
// la ficha diga de cuándo es el texto, que haya tres decisiones, que cada
// medición tenga un número). No sabe si una decisión está bien justificada ni
// si el caso se leyó bien: eso se discute en clase.
//
// Termina con código 1 si encuentra problemas.

import { readFileSync } from 'node:fs';
import { pathToFileURL } from 'node:url';

export const KINDS = ['worksheet', 'presentation', 'checklist'] as const;
export type Kind = (typeof KINDS)[number];

export type Section = {
  level: number;
  title: string;
  /** Línea del título, contando desde 1. */
  line: number;
  /** El texto de la sección, sin sus subsecciones. */
  body: string;
  /** Campos de la forma "- **Nombre:** texto", con el nombre normalizado. */
  fields: Map<string, string>;
  children: Section[];
};

const normalize = (text: string) =>
  text
    .trim()
    .toLowerCase()
    .normalize('NFD')
    .replace(/\p{M}/gu, '')
    .replace(/\s+/g, ' ');

const HEADING = /^(#{1,6})\s+(.*)$/;
const FIELD = /^\s*[-*]\s+\*\*([^*:]+):\*\*\s*(.*)$/;

/** Quita los comentarios HTML: las instrucciones del template van ahí. */
const stripComments = (markdown: string) => markdown.replace(/<!--[\s\S]*?-->/g, (text) => text.replace(/[^\n]/g, ''));

/** Arma el árbol de secciones de un documento Markdown. */
export function parseSections(markdown: string): Section[] {
  const roots: Section[] = [];
  const stack: Section[] = [];
  let openField: string | undefined;
  let inFence = false;

  stripComments(markdown)
    .split('\n')
    .forEach((line, index) => {
      if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
      const heading = inFence ? null : HEADING.exec(line);
      if (heading) {
        const section: Section = {
          level: heading[1]!.length,
          title: heading[2]!.trim(),
          line: index + 1,
          body: '',
          fields: new Map(),
          children: [],
        };
        while (stack.length > 0 && stack.at(-1)!.level >= section.level) stack.pop();
        if (stack.length === 0) roots.push(section);
        else stack.at(-1)!.children.push(section);
        stack.push(section);
        openField = undefined;
        return;
      }
      const current = stack.at(-1);
      if (!current) return;
      current.body += `${line}\n`;
      const field = inFence ? null : FIELD.exec(line);
      if (field) {
        openField = normalize(field[1]!);
        current.fields.set(openField, field[2]!.trim());
      } else if (line.trim() === '' || /^\s*[-*]\s/.test(line)) {
        openField = undefined;
      } else if (openField) {
        // Un campo puede seguir en las líneas de abajo.
        current.fields.set(openField, `${current.fields.get(openField)} ${line.trim()}`.trim());
      }
    });
  return roots;
}

/** Texto que quedó del template: vacío, puntos suspensivos o <una indicación>. */
export const isPlaceholder = (text: string) => {
  const trimmed = text.trim();
  return trimmed === '' || /^(…|\.\.\.)$/.test(trimmed) || /^<[^>]*>$/.test(trimmed);
};

/** Una sección está sin llenar si, quitadas las <indicaciones> y los nombres de los campos, no queda texto. */
function isUnfilled(section: Section): boolean {
  const rest = section.body
    .replace(/<[^>]*>/g, '') // una indicación puede ocupar varias líneas
    .replace(/^\s*[-*]\s+\*\*[^*]+\*\*/gm, '');
  return !/[\p{L}\p{N}]/u.test(rest) && section.children.every(isUnfilled);
}

const flatten = (sections: Section[]): Section[] => sections.flatMap((section) => [section, ...flatten(section.children)]);

/** Busca una sección por el comienzo de su título, sin importar tildes ni mayúsculas. */
function find(sections: Section[], title: string): Section | undefined {
  const wanted = normalize(title);
  return flatten(sections).find((section) => normalize(section.title).startsWith(wanted));
}

export type Problem = { where: string; message: string };

function requireFields(section: Section, labels: string[], problems: Problem[]): void {
  for (const label of labels) {
    const value = section.fields.get(normalize(label));
    if (value === undefined) problems.push({ where: section.title, message: `falta el campo "${label}"` });
    else if (isPlaceholder(value)) {
      problems.push({ where: section.title, message: `el campo "${label}" está vacío o con el texto del template` });
    }
  }
}

function requireSection(sections: Section[], title: string, problems: Problem[]): Section | undefined {
  const section = find(sections, title);
  if (!section) problems.push({ where: title, message: 'falta la sección' });
  else if (isUnfilled(section)) problems.push({ where: section.title, message: 'la sección está vacía o con el texto del template' });
  return section;
}

// ---------------------------------------------------------------------------
// Ficha de lectura de un caso

export const WORKSHEET_QUESTIONS = [
  '1. El escenario que apretaba',
  '2. Las alternativas',
  '3. Lo que se eligió',
  '4. Lo que se sacrificó',
  '5. Cómo supieron que funcionó',
] as const;

export const WORKSHEET_SOURCE_FIELDS = ['Título', 'Quién lo escribe', 'Fecha', 'Enlace', 'Qué describe'];
/** En cada pregunta se separa lo que afirma el texto de lo que deduce quien lee. */
export const WORKSHEET_ANSWER_FIELDS = ['Lo que dice el texto', 'Lo que inferimos'];

export function checkWorksheet(markdown: string): Problem[] {
  const sections = parseSections(markdown);
  const problems: Problem[] = [];

  const source = requireSection(sections, 'El texto', problems);
  if (source) {
    requireFields(source, WORKSHEET_SOURCE_FIELDS, problems);
    const date = source.fields.get('fecha');
    if (date && !isPlaceholder(date) && !/\b(19|20)\d{2}\b/.test(date)) {
      problems.push({ where: source.title, message: 'la fecha no dice el año: un caso describe su sistema en un momento' });
    }
  }
  for (const question of WORKSHEET_QUESTIONS) {
    const section = requireSection(sections, question, problems);
    if (section && !isUnfilled(section)) requireFields(section, WORKSHEET_ANSWER_FIELDS, problems);
  }
  requireSection(sections, 'Lo que el texto no dice', problems);
  const weeks = requireSection(sections, 'Semanas del curso', problems);
  if (weeks && !isUnfilled(weeks)) {
    const mentioned = [...weeks.body.matchAll(/semanas?\s+(\d{1,2})/gi)].map((match) => Number(match[1]));
    if (mentioned.length === 0) problems.push({ where: weeks.title, message: 'no nombra ninguna semana ("semana 11")' });
    for (const week of mentioned) {
      if (week < 1 || week > 16) problems.push({ where: weeks.title, message: `la semana ${week} no existe` });
    }
  }
  requireSection(sections, 'Qué no copiaríamos sin su contexto', problems);
  return problems;
}

// ---------------------------------------------------------------------------
// Guion de la presentación final

export const PRESENTATION_SECTIONS = [
  'El problema y los escenarios',
  'El recorrido',
  'Decisiones',
  'Lo que haríamos distinto',
  'Demostración',
  'Deuda',
] as const;

export const DECISION_FIELDS = ['Escenario', 'Alternativas descartadas', 'Decisión', 'Lo que costó', 'Medición'];
export const DEMO_FIELDS = ['Qué se va a mostrar', 'Qué se espera ver', 'Plan si la demostración falla'];
export const DECISION_COUNT = 3;

export function checkPresentation(markdown: string): Problem[] {
  const sections = parseSections(markdown);
  const problems: Problem[] = [];
  const found = new Map<string, Section | undefined>();
  for (const title of PRESENTATION_SECTIONS) found.set(title, requireSection(sections, title, problems));

  const journey = found.get('El recorrido');
  if (journey) {
    for (const title of ['Antes', 'Ahora']) {
      const part = find(journey.children, title);
      if (!part) problems.push({ where: journey.title, message: `falta la subsección "${title}"` });
      else if (isUnfilled(part)) problems.push({ where: `${journey.title} / ${part.title}`, message: 'está vacía o con el texto del template' });
    }
  }

  const decisions = found.get('Decisiones');
  if (decisions) {
    if (decisions.children.length !== DECISION_COUNT) {
      problems.push({
        where: decisions.title,
        message: `hay ${decisions.children.length} decisiones y se presentan ${DECISION_COUNT}: elegir es parte del trabajo`,
      });
    }
    for (const decision of decisions.children) {
      requireFields(decision, DECISION_FIELDS, problems);
      const measurement = decision.fields.get(normalize('Medición'));
      if (measurement && !isPlaceholder(measurement) && !/\d/.test(measurement)) {
        problems.push({ where: decision.title, message: 'la medición no tiene ningún número' });
      }
      const alternatives = decision.fields.get(normalize('Alternativas descartadas'));
      if (alternatives && /^(ninguna|no hubo|no hay)\b/i.test(alternatives)) {
        problems.push({ where: decision.title, message: 'sin alternativas no hubo decisión: ¿qué otra cosa se pudo hacer?' });
      }
    }
  }

  const demo = found.get('Demostración');
  if (demo && !isUnfilled(demo)) requireFields(demo, DEMO_FIELDS, problems);

  const debt = found.get('Deuda');
  if (debt && !isUnfilled(debt)) {
    const items = debt.body.split('\n').filter((line) => /^\s*[-*]\s+\S/.test(line) && !isPlaceholder(line.replace(/^\s*[-*]\s+/, '')));
    if (items.length === 0) problems.push({ where: debt.title, message: 'la deuda se escribe como lista, un ítem por cosa pendiente' });
  }
  return problems;
}

// ---------------------------------------------------------------------------
// Lista de la defensa

const CHECKBOX = /^\s*[-*]\s+\[( |x|X)\]\s+(.*)$/;

export function checkChecklist(markdown: string): Problem[] {
  const problems: Problem[] = [];
  let total = 0;
  for (const section of flatten(parseSections(markdown))) {
    for (const line of section.body.split('\n')) {
      const item = CHECKBOX.exec(line);
      if (!item) continue;
      total += 1;
      if (item[1] === ' ') problems.push({ where: section.title, message: `pendiente: ${item[2]}` });
    }
  }
  if (total === 0) problems.push({ where: '(documento)', message: 'no tiene ningún ítem "- [ ]"' });
  return problems;
}

export function checkDocument(kind: Kind, markdown: string): Problem[] {
  if (kind === 'worksheet') return checkWorksheet(markdown);
  if (kind === 'presentation') return checkPresentation(markdown);
  return checkChecklist(markdown);
}

function main(args: string[]): number {
  const [kind, ...files] = args;
  if (!(KINDS as readonly string[]).includes(kind ?? '') || files.length === 0) {
    console.error('Uso: node check-doc.ts <worksheet|presentation|checklist> <archivo.md> [...]');
    return 2;
  }
  let failed = false;
  for (const file of files) {
    const problems = checkDocument(kind as Kind, readFileSync(file, 'utf8'));
    console.log(`${problems.length === 0 ? '✔' : '✖'} ${file}`);
    for (const problem of problems) console.log(`    ${problem.where}: ${problem.message}`);
    if (problems.length > 0) failed = true;
  }
  return failed ? 1 : 0;
}

// Solo cuando se ejecuta como programa, no cuando lo importan las pruebas.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  process.exitCode = main(process.argv.slice(2));
}
defence-checklist.mdDescargar defence-checklist.md
# Lista para la defensa

<!--
Lo que conviene haber hecho antes de la defensa. Marquen cada ítem con [x]
cuando esté hecho y revisen con:

    node check-doc.ts checklist <este archivo>

que lista lo que sigue pendiente. Cada integrante debería poder marcar la
lista completa por su cuenta: cualquiera puede recibir cualquier pregunta.
-->

## El recorrido de una compra

- [ ] Puedo seguir una compra sobre el diagrama de contenedores sin leer notas
- [ ] Para cada paso sé decir qué pasa si falla y dónde queda registrado
- [ ] Comprobé el diagrama contra el sistema corriendo: no hay cajas de más ni de menos

## Los ADR

- [ ] Abrí cada ADR del equipo, no solo los que escribí
- [ ] De cada uno puedo decir por qué se descartó cada alternativa
- [ ] De cada uno puedo decir qué cambio en el contexto haría revisarlo

## Las comprobaciones

- [ ] Corrí todas las comprobaciones automáticas del equipo en esta computadora
- [ ] De cada una sé qué decisión protege
- [ ] Rompí una a propósito y vi qué reporta

## Las fallas

- [ ] El sistema llama a su dependencia por el proxy de Toxiproxy
- [ ] Probé `latency`, `slow-third`, `cut` y `blackhole` con `fault.ts`
- [ ] Para cada falla sé qué línea de log y qué métrica mirar
- [ ] Sé volver al estado normal con `node fault.ts clear` y comprobarlo

## Un requisito nuevo

- [ ] Ensayamos dos cambios de requisito que no estaban en ningún enunciado
- [ ] Para cada uno dijimos qué parte aguanta, cuál no y qué decisión se revisa
fault.tsDescargar fault.ts
// Aplica una falla, elegida en el momento, a una dependencia HTTP cualquiera,
// a través de Toxiproxy. Es el script de la defensa: sirve para cualquier
// sistema que llame a su dependencia por un proxy de Toxiproxy.
//
//   svc start toxiproxy
//   node fault.ts setup              crea el proxy (FAULT_LISTEN -> FAULT_UPSTREAM)
//   node fault.ts latency 2000       toda respuesta tarda 2000 ms más
//   node fault.ts slow-third 2000    una de cada tres conexiones tarda 2000 ms más
//   node fault.ts cut                corte: la conexión se rechaza de inmediato
//   node fault.ts blackhole          acepta la conexión y no entrega nada
//   node fault.ts clear              quita todas las fallas
//   node fault.ts status             qué falla hay puesta
//   node fault.ts remove             borra el proxy
//
// Variables de entorno (con sus valores por defecto, los del ejemplo de demo/):
//   FAULT_PROXY=dependency  FAULT_LISTEN=127.0.0.1:4601  FAULT_UPSTREAM=127.0.0.1:4600
//   TOXIPROXY_URL=http://127.0.0.1:8474
//
// Cada comando deja exactamente una falla: antes de poner la nueva quita la
// anterior. Así, lo que se observa después tiene una sola causa.

import { pathToFileURL } from 'node:url';

export type ProxyConfig = {
  /** Nombre del proxy dentro de Toxiproxy. */
  name: string;
  /** Dónde escucha el proxy: a esta dirección debe llamar el sistema. */
  listen: string;
  /** La dependencia real. */
  upstream: string;
  /** La API de Toxiproxy. */
  apiUrl: string;
};

export const FAULT_KINDS = ['latency', 'slow-third', 'cut', 'blackhole'] as const;
export type FaultKind = (typeof FAULT_KINDS)[number];

export type Toxic = {
  name: string;
  type: string;
  stream: 'upstream' | 'downstream';
  toxicity: number;
  attributes: Record<string, number>;
};

export type ProxyState = { name: string; listen: string; upstream: string; enabled: boolean; toxics: Toxic[] };

/** Fracción de conexiones afectadas por slow-third. */
export const ONE_IN_THREE = 1 / 3;

export function configFromEnv(env: NodeJS.ProcessEnv = process.env): ProxyConfig {
  return {
    name: env.FAULT_PROXY ?? 'dependency',
    listen: env.FAULT_LISTEN ?? '127.0.0.1:4601',
    upstream: env.FAULT_UPSTREAM ?? '127.0.0.1:4600',
    apiUrl: env.TOXIPROXY_URL ?? 'http://127.0.0.1:8474',
  };
}

async function api(config: ProxyConfig, method: string, path: string, body?: unknown): Promise<Response> {
  let response: Response;
  try {
    response = await fetch(`${config.apiUrl}${path}`, {
      method,
      body: body === undefined ? undefined : JSON.stringify(body),
      headers: { 'content-type': 'application/json' },
    });
  } catch {
    throw new Error(`Toxiproxy no responde en ${config.apiUrl}: ¿corrieron "svc start toxiproxy"?`);
  }
  return response;
}

async function expectOk(response: Response, what: string): Promise<Response> {
  if (!response.ok) throw new Error(`${what}: Toxiproxy respondió ${response.status} ${await response.text()}`);
  return response;
}

/** Crea el proxy, o lo deja como nuevo (habilitado y sin fallas) si ya existía. */
export async function setupProxy(config: ProxyConfig): Promise<ProxyState> {
  const existing = await api(config, 'GET', `/proxies/${config.name}`);
  await existing.arrayBuffer();
  if (existing.status === 404) {
    const created = await api(config, 'POST', '/proxies', {
      name: config.name,
      listen: config.listen,
      upstream: config.upstream,
      enabled: true,
    });
    await (await expectOk(created, 'crear el proxy')).arrayBuffer();
  } else {
    const updated = await api(config, 'POST', `/proxies/${config.name}`, {
      listen: config.listen,
      upstream: config.upstream,
      enabled: true,
    });
    await (await expectOk(updated, 'actualizar el proxy')).arrayBuffer();
    await clearFaults(config);
  }
  return status(config);
}

export async function status(config: ProxyConfig): Promise<ProxyState> {
  const response = await api(config, 'GET', `/proxies/${config.name}`);
  if (response.status === 404) {
    await response.arrayBuffer();
    throw new Error(`No existe el proxy "${config.name}": corran primero "node fault.ts setup"`);
  }
  return (await (await expectOk(response, 'leer el proxy')).json()) as ProxyState;
}

/** Quita todas las fallas: borra los tóxicos y vuelve a habilitar el proxy. */
export async function clearFaults(config: ProxyConfig): Promise<void> {
  const current = await status(config);
  for (const toxic of current.toxics) {
    const removed = await api(config, 'DELETE', `/proxies/${config.name}/toxics/${toxic.name}`);
    await (await expectOk(removed, 'quitar un tóxico')).arrayBuffer();
  }
  if (!current.enabled) {
    const enabled = await api(config, 'POST', `/proxies/${config.name}`, { enabled: true });
    await (await expectOk(enabled, 'habilitar el proxy')).arrayBuffer();
  }
}

async function addToxic(config: ProxyConfig, toxic: Toxic): Promise<void> {
  const added = await api(config, 'POST', `/proxies/${config.name}/toxics`, toxic);
  await (await expectOk(added, 'agregar el tóxico')).arrayBuffer();
}

/**
 * Deja puesta una sola falla.
 *
 * - latency: un tóxico `latency` en el camino de vuelta (downstream). El
 *   pedido llega a la dependencia a tiempo; lo que se demora es la respuesta.
 * - slow-third: el mismo tóxico con toxicity 1/3. Toxiproxy sortea por
 *   conexión, no por pedido: todo lo que viaja por una conexión afectada es
 *   lento, y todo lo que viaja por una no afectada es normal.
 * - cut: el proxy deshabilitado. Deja de escuchar y cierra las conexiones
 *   abiertas: quien llama recibe un error de conexión enseguida.
 * - blackhole: un tóxico `timeout` con timeout 0 en el camino de ida
 *   (upstream). La conexión se acepta, pero el pedido no llega a la
 *   dependencia y nadie responde: quien llama espera hasta su propio timeout.
 */
export async function applyFault(config: ProxyConfig, kind: FaultKind, delayMs = 2000): Promise<ProxyState> {
  if (!Number.isInteger(delayMs) || delayMs <= 0) throw new Error('La demora va en milisegundos, como entero mayor que 0');
  await clearFaults(config);
  if (kind === 'latency') {
    await addToxic(config, {
      name: 'fault',
      type: 'latency',
      stream: 'downstream',
      toxicity: 1,
      attributes: { latency: delayMs, jitter: 0 },
    });
  } else if (kind === 'slow-third') {
    await addToxic(config, {
      name: 'fault',
      type: 'latency',
      stream: 'downstream',
      toxicity: ONE_IN_THREE,
      attributes: { latency: delayMs, jitter: 0 },
    });
  } else if (kind === 'blackhole') {
    await addToxic(config, { name: 'fault', type: 'timeout', stream: 'upstream', toxicity: 1, attributes: { timeout: 0 } });
  } else {
    const disabled = await api(config, 'POST', `/proxies/${config.name}`, { enabled: false });
    await (await expectOk(disabled, 'deshabilitar el proxy')).arrayBuffer();
  }
  return status(config);
}

export async function removeProxy(config: ProxyConfig): Promise<void> {
  const removed = await api(config, 'DELETE', `/proxies/${config.name}`);
  await removed.arrayBuffer();
  if (!removed.ok && removed.status !== 404) throw new Error(`borrar el proxy: Toxiproxy respondió ${removed.status}`);
}

/** Una línea que dice qué falla hay puesta, para leerla en voz alta en la defensa. */
export function describe(state: ProxyState): string {
  const route = `${state.name}: ${state.listen} -> ${state.upstream}`;
  if (!state.enabled) return `${route} · corte (proxy deshabilitado: conexión rechazada)`;
  if (state.toxics.length === 0) return `${route} · sin fallas`;
  const parts = state.toxics.map((toxic) => {
    if (toxic.type === 'latency') {
      const who = toxic.toxicity >= 1 ? 'todas las conexiones' : `${Math.round(toxic.toxicity * 100)} % de las conexiones`;
      return `latencia de ${toxic.attributes.latency} ms en ${who} (${toxic.stream})`;
    }
    if (toxic.type === 'timeout' && toxic.attributes.timeout === 0) return `no entrega nada (${toxic.stream})`;
    return `${toxic.type} (${toxic.stream})`;
  });
  return `${route} · ${parts.join(', ')}`;
}

const USAGE = `Uso: node fault.ts <comando>
  setup              crea el proxy (FAULT_LISTEN -> FAULT_UPSTREAM)
  latency [ms]       toda respuesta tarda [ms] más (2000 si no se dice)
  slow-third [ms]    una de cada tres conexiones tarda [ms] más
  cut                corte: la conexión se rechaza de inmediato
  blackhole          acepta la conexión y no entrega nada
  clear              quita todas las fallas
  status             qué falla hay puesta
  remove             borra el proxy`;

async function main(args: string[]): Promise<number> {
  const config = configFromEnv();
  const [command, value] = args;
  const delayMs = value === undefined ? 2000 : Number(value);
  try {
    if (command === 'setup') console.log(describe(await setupProxy(config)));
    else if (command === 'status') console.log(describe(await status(config)));
    else if (command === 'clear') {
      await clearFaults(config);
      console.log(describe(await status(config)));
    } else if (command === 'remove') {
      await removeProxy(config);
      console.log(`${config.name}: proxy borrado`);
    } else if ((FAULT_KINDS as readonly string[]).includes(command ?? '')) {
      console.log(describe(await applyFault(config, command as FaultKind, delayMs)));
    } else {
      console.error(USAGE);
      return 2;
    }
    return 0;
  } catch (error) {
    console.error(error instanceof Error ? error.message : error);
    return 1;
  }
}

// Solo cuando se ejecuta como programa, no cuando lo importan las pruebas.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  process.exitCode = await main(process.argv.slice(2));
}
presentation-template.mdDescargar presentation-template.md
# Presentación final: <equipo>

<!--
Template del guion de la presentación final. No es la presentación: es la
lista de lo que van a decir y mostrar, en orden. Copien el archivo, reemplacen
cada <indicación> y revísenlo con:

    node check-doc.ts presentation <este archivo>

El orden es parte del contenido: primero el problema, después las decisiones,
al final la tecnología.
-->

## El problema y los escenarios

<Qué tenía que lograr el sistema, dicho con los dos o tres escenarios de
calidad que más pesaron, cada uno con su medida.>

## El recorrido

### Antes

<El diagrama de contenedores del punto de partida: dónde está el archivo y qué
tres cosas van a señalar en él.>

### Ahora

<El diagrama de contenedores de hoy: dónde está, y qué cajas y qué flechas son
nuevas respecto del anterior.>

## Decisiones

### Decisión 1: <título, como el de su ADR>

- **Escenario:** <el escenario que la motivó, con su medida>
- **Alternativas descartadas:** <cuáles y por qué: una frase por alternativa>
- **Decisión:** <qué se hizo, en una frase, y en qué ADR está>
- **Lo que costó:** <qué atributo empeoró o qué se volvió más difícil>
- **Medición:** <antes y después, con el comando, la máquina y el archivo donde está el resumen>

### Decisión 2: <título>

- **Escenario:** <…>
- **Alternativas descartadas:** <…>
- **Decisión:** <…>
- **Lo que costó:** <…>
- **Medición:** <…>

### Decisión 3: <título>

- **Escenario:** <…>
- **Alternativas descartadas:** <…>
- **Decisión:** <…>
- **Lo que costó:** <…>
- **Medición:** <…>

## Lo que haríamos distinto

<Una decisión que hoy tomarían de otra manera: qué sabían cuando la tomaron,
qué saben ahora y qué harían.>

## Demostración

- **Qué se va a mostrar:** <los comandos, en orden, y en qué terminal va cada uno>
- **Qué se espera ver:** <qué número o qué línea de log van a señalar, y qué significaría que no apareciera>
- **Plan si la demostración falla:** <la salida guardada de una corrida anterior, con su fecha>

## Deuda

- <Una cosa pendiente por ítem: qué es, qué riesgo trae y qué la haría urgente>
probe.tsDescargar probe.ts
// Hace varios pedidos GET a una URL y resume lo que vio quien llama: cuántos
// de cada resultado y cuánto tardaron (p50, p95 y máximo).
//
//   node probe.ts http://127.0.0.1:4602/quotes/7            30 pedidos, uno tras otro
//   node probe.ts http://127.0.0.1:4602/quotes/7 60 --concurrency=6
//   node probe.ts http://127.0.0.1:4601/prices/7 30 --keep-alive
//
// Por defecto abre una conexión nueva por pedido. Con --keep-alive reutiliza
// las conexiones (una por pedido concurrente), como hace un cliente HTTP
// normal. La diferencia importa con slow-third: Toxiproxy sortea por conexión.

import { Agent, request } from 'node:http';
import { pathToFileURL } from 'node:url';

export type CallResult = {
  /** Código HTTP, o el código del error de red (ECONNREFUSED, ECONNRESET, TIMEOUT). */
  result: string;
  ms: number;
};

export type ProbeOptions = {
  count?: number;
  concurrency?: number;
  keepAlive?: boolean;
  /** Cuánto espera cada pedido antes de rendirse. */
  timeoutMs?: number;
};

function callOnce(url: string, agent: Agent, timeoutMs: number): Promise<CallResult> {
  const started = performance.now();
  return new Promise((resolve) => {
    const finish = (result: string) => resolve({ result, ms: performance.now() - started });
    const req = request(url, { agent, method: 'GET' }, (response) => {
      response.resume();
      response.on('end', () => finish(String(response.statusCode)));
      response.on('error', () => finish('ECONNRESET'));
    });
    req.setTimeout(timeoutMs, () => req.destroy(Object.assign(new Error('timeout'), { code: 'TIMEOUT' })));
    req.on('error', (error: NodeJS.ErrnoException) => finish(error.code ?? 'ERROR'));
    req.end();
  });
}

export async function probe(url: string, options: ProbeOptions = {}): Promise<CallResult[]> {
  const count = options.count ?? 30;
  const concurrency = options.concurrency ?? 1;
  const timeoutMs = options.timeoutMs ?? 10_000;
  const agent = new Agent({ keepAlive: options.keepAlive ?? false, maxSockets: concurrency });
  const results: CallResult[] = [];
  let next = 0;
  const worker = async () => {
    while (next < count) {
      next += 1;
      results.push(await callOnce(url, agent, timeoutMs));
    }
  };
  await Promise.all(Array.from({ length: concurrency }, worker));
  agent.destroy();
  return results;
}

/** Percentil por rango más cercano, como en la semana 2: la medición en la posición ⌈p/100 × n⌉. */
export function percentile(values: number[], p: number): number {
  if (values.length === 0) throw new Error('No hay mediciones');
  const sorted = [...values].sort((a, b) => a - b);
  const position = Math.max(1, Math.ceil((p / 100) * sorted.length));
  return sorted[position - 1]!;
}

export type Summary = { count: number; byResult: Record<string, number>; p50: number; p95: number; max: number };

export function summarize(results: CallResult[]): Summary {
  const byResult: Record<string, number> = {};
  for (const { result } of results) byResult[result] = (byResult[result] ?? 0) + 1;
  const times = results.map((entry) => entry.ms);
  return {
    count: results.length,
    byResult,
    p50: percentile(times, 50),
    p95: percentile(times, 95),
    max: Math.max(...times),
  };
}

export function formatSummary(summary: Summary): string {
  const results = Object.entries(summary.byResult)
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([result, count]) => `${result} × ${count}`)
    .join(', ');
  const ms = (value: number) => `${Math.round(value)} ms`;
  return `${summary.count} pedidos: ${results} · p50 ${ms(summary.p50)}, p95 ${ms(summary.p95)}, máx ${ms(summary.max)}`;
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const args = process.argv.slice(2);
  const flags = args.filter((arg) => arg.startsWith('--'));
  const [url, count] = args.filter((arg) => !arg.startsWith('--'));
  if (!url) {
    console.error('Uso: node probe.ts <url> [pedidos] [--keep-alive] [--concurrency=N]');
    process.exitCode = 2;
  } else {
    const concurrency = flags.find((flag) => flag.startsWith('--concurrency='))?.split('=')[1];
    const results = await probe(url, {
      count: count ? Number(count) : undefined,
      keepAlive: flags.includes('--keep-alive'),
      concurrency: concurrency ? Number(concurrency) : undefined,
    });
    console.log(formatSummary(summarize(results)));
  }
}
demo/caller.tsDescargar demo/caller.ts
// El servicio del ejemplo: responde GET /quotes/:id pidiéndole el precio a la
// dependencia. La llama por el proxy de Toxiproxy y con un timeout propio.
// Por cada pedido escribe una línea de log en JSON con el resultado y lo que
// tardó: es lo que se mira mientras se aplica una falla.
//
//   node demo/caller.ts            escucha en 127.0.0.1:4602
//
// Solo tiene una defensa, el timeout. No tiene retry, circuit breaker ni
// respuesta alternativa: lo que hace con cada falla es lo mínimo, para que se
// vea la falla y no la defensa.

import { createServer, type Server } from 'node:http';
import { pathToFileURL } from 'node:url';

export type Outcome = 'ok' | 'dependency_timeout' | 'dependency_unavailable' | 'dependency_error';

export type LogLine = { route: string; status: number; outcome: Outcome; ms: number };

export type CallerOptions = {
  port?: number;
  /** Dónde está la dependencia: la dirección del proxy, no la real. */
  dependencyUrl?: string;
  /** Cuánto espera a la dependencia antes de rendirse. */
  timeoutMs?: number;
  log?: (line: LogLine) => void;
};

export type Caller = { server: Server; close: () => Promise<void> };

async function fetchPrice(url: string, timeoutMs: number): Promise<{ outcome: Outcome; body?: unknown }> {
  try {
    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
    if (!response.ok) {
      await response.arrayBuffer();
      return { outcome: 'dependency_error' };
    }
    return { outcome: 'ok', body: await response.json() };
  } catch (error) {
    // AbortSignal.timeout rechaza con un error de nombre TimeoutError; lo demás
    // (conexión rechazada, conexión cerrada) es que la dependencia no está.
    const timedOut = error instanceof Error && error.name === 'TimeoutError';
    return { outcome: timedOut ? 'dependency_timeout' : 'dependency_unavailable' };
  }
}

export function startCaller(options: CallerOptions = {}): Promise<Caller> {
  const port = options.port ?? 4602;
  const dependencyUrl = options.dependencyUrl ?? 'http://127.0.0.1:4601';
  const timeoutMs = options.timeoutMs ?? 1000;
  const log = options.log ?? ((line: LogLine) => console.log(JSON.stringify(line)));

  const server = createServer(async (request, response) => {
    const started = performance.now();
    const route = request.url ?? '';
    const match = /^\/quotes\/(\d+)$/.exec(route);
    let status = 404;
    let outcome: Outcome = 'ok';
    let body: unknown = { error: 'not_found' };
    if (request.method === 'GET' && match) {
      const result = await fetchPrice(`${dependencyUrl}/prices/${match[1]}`, timeoutMs);
      outcome = result.outcome;
      status = outcome === 'ok' ? 200 : 503;
      body = outcome === 'ok' ? { quote: result.body } : { error: outcome };
    }
    response.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
    log({ route, status, outcome, ms: Math.round(performance.now() - started) });
  });

  return new Promise((resolve) => {
    server.listen(port, '127.0.0.1', () => {
      resolve({
        server,
        close: () =>
          new Promise<void>((done) => {
            server.close(() => done());
            server.closeAllConnections();
          }),
      });
    });
  });
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const port = Number(process.env.CALLER_PORT ?? 4602);
  await startCaller({
    port,
    dependencyUrl: process.env.DEPENDENCY_URL,
    timeoutMs: process.env.TIMEOUT_MS ? Number(process.env.TIMEOUT_MS) : undefined,
  });
  console.error(`servicio (cotizaciones) en http://127.0.0.1:${port}`);
}
demo/dependency.tsDescargar demo/dependency.ts
// La dependencia del ejemplo: un servicio de precios mínimo. Responde
// GET /prices/:id con un precio fijo y cuenta cuántos pedidos le llegaron,
// para poder decir si una falla ocurrió antes o después de que trabajara.
//
//   node demo/dependency.ts        escucha en 127.0.0.1:4600

import { createServer, type Server } from 'node:http';
import { pathToFileURL } from 'node:url';

export type Dependency = { server: Server; received: () => number; close: () => Promise<void> };

export function startDependency(port = 4600): Promise<Dependency> {
  let received = 0;
  const server = createServer((request, response) => {
    received += 1;
    const match = /^\/prices\/(\d+)$/.exec(request.url ?? '');
    if (request.method !== 'GET' || !match) {
      response.writeHead(404, { 'content-type': 'application/json' }).end('{"error":"not_found"}');
      return;
    }
    const id = Number(match[1]);
    // Un precio que depende solo del id: la misma pregunta da siempre la misma respuesta.
    const body = JSON.stringify({ id, cents: 5000 + (id % 10) * 500 });
    response.writeHead(200, { 'content-type': 'application/json' }).end(body);
  });
  return new Promise((resolve) => {
    server.listen(port, '127.0.0.1', () => {
      resolve({
        server,
        received: () => received,
        close: () =>
          new Promise<void>((done) => {
            server.close(() => done());
            server.closeAllConnections();
          }),
      });
    });
  });
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const port = Number(process.env.DEPENDENCY_PORT ?? 4600);
  await startDependency(port);
  console.log(`dependencia (precios) en http://127.0.0.1:${port}`);
}
demo/run.tsDescargar demo/run.ts
// La demostración completa: levanta la dependencia y el servicio, crea el
// proxy y aplica una falla tras otra, mostrando después de cada una lo que ve
// quien llama al servicio y una línea de su log.
//
//   svc start toxiproxy
//   node demo/run.ts               (o make demo)
//
// En la defensa no se usa este archivo: se usa fault.ts contra el sistema del
// equipo. Este sirve para ver, en un sistema de dos piezas, cómo se ve cada
// falla desde afuera.

import { applyFault, clearFaults, configFromEnv, describe, removeProxy, setupProxy, type FaultKind } from '../fault.ts';
import { formatSummary, probe, summarize } from '../probe.ts';
import { startCaller, type LogLine } from './caller.ts';
import { startDependency } from './dependency.ts';

const config = configFromEnv();
const QUOTE_URL = 'http://127.0.0.1:4602/quotes/7';
const TIMEOUT_MS = 500;
// A partir de cuánto se cuenta un pedido como lento en el resumen.
const SLOW_MS = 150;

const lines: LogLine[] = [];
const dependency = await startDependency(4600);
const caller = await startCaller({
  port: 4602,
  dependencyUrl: `http://${config.listen}`,
  timeoutMs: TIMEOUT_MS,
  log: (line) => lines.push(line),
});

async function round(title: string, count = 12, concurrency = 1): Promise<void> {
  lines.length = 0;
  const before = dependency.received();
  const results = await probe(QUOTE_URL, { count, concurrency });
  console.log(`\n== ${title}`);
  console.log(`  ${formatSummary(summarize(results))}`);
  console.log(`  pedidos que llegaron a la dependencia: ${dependency.received() - before} de ${count}`);
  console.log(`  pedidos que tardaron más de ${SLOW_MS} ms: ${results.filter((entry) => entry.ms > SLOW_MS).length} de ${count}`);
  // La línea de log del pedido más lento de la ronda.
  const slowest = lines.reduce((a, b) => (b.ms > a.ms ? b : a));
  console.log(`  log del más lento: ${JSON.stringify(slowest)}`);
}

async function fault(kind: FaultKind, delayMs: number, count = 12, concurrency = 1): Promise<void> {
  const state = await applyFault(config, kind, delayMs);
  await round(describe(state), count, concurrency);
}

// slow-third, mirado conexión por conexión: ocho conexiones directas al proxy,
// con seis pedidos seguidos por cada una.
async function perConnection(): Promise<void> {
  console.log('\n== la misma falla, por conexión: 8 conexiones al proxy, 6 pedidos por cada una');
  for (let connection = 1; connection <= 8; connection += 1) {
    const results = await probe(`http://${config.listen}/prices/7`, { count: 6, keepAlive: true });
    const times = results.map((entry) => `${Math.round(entry.ms)}`.padStart(4)).join(' ');
    console.log(`  conexión ${connection}: ${times}  ms`);
  }
}

try {
  console.log(`El servicio espera a la dependencia ${TIMEOUT_MS} ms como máximo.`);
  await round(describe(await setupProxy(config)));
  await fault('latency', 200);
  await fault('latency', 1000);
  await fault('cut', 1000);
  await fault('blackhole', 1000);
  // Con seis pedidos a la vez el servicio abre varias conexiones a la dependencia.
  await fault('slow-third', 200, 30, 6);
  await perConnection();
  await clearFaults(config);
  await round('sin fallas otra vez');
} finally {
  await removeProxy(config);
  await caller.close();
  await dependency.close();
}
example/case-worksheet-shopify.mdDescargar example/case-worksheet-shopify.md
# Ficha de lectura de un caso: Shopify, del monolito al modular monolith

## El texto

- **Título:** Deconstructing the Monolith: Designing Software that Maximizes Developer Productivity
- **Quién lo escribe:** Kirsten Westeinde, del equipo de ingeniería de Shopify
- **Fecha:** 21 de febrero de 2019
- **Enlace:** https://shopify.engineering/deconstructing-monolith-designing-software-maximizes-developer-productivity
- **Qué describe:** la aplicación principal de Shopify, escrita en Ruby on Rails, entre
  2016 (cuando el texto dice que el monolito les quedó chico) y comienzos de 2019. Es un
  trabajo en curso: el texto dice que el aislamiento completo todavía no se alcanzó.

## 1. El escenario que apretaba

- **Lo que dice el texto:** es un problema de velocidad de cambio, no de carga. Una base
  de código con más de diez años y más de mil desarrolladores, en la que un cambio que
  parecía inocuo hacía fallar pruebas sin relación, las pruebas eran difíciles de escribir
  y lentas en CI, y una persona nueva tenía que entender órdenes y pagos para poder tocar
  envíos. Sitúa el problema en 2016 y lo atribuye a la falta de límites entre dominios.
- **Lo que inferimos:** el escenario es de modificabilidad. Fuente: un desarrollador del
  equipo de envíos. Estímulo: un cambio en el cálculo de impuestos. Artefacto: el código
  de la aplicación principal. Entorno: desarrollo normal. Respuesta: el cambio se hace y se
  prueba sin tocar otros dominios. La medida la tuvimos que suponer (cuántos componentes
  toca el cambio): el texto no da ninguna cifra de antes ni de después.

## 2. Las alternativas

- **Lo que dice el texto:** microservicios. Reconoce que resolverían el acoplamiento y
  los descarta por lo que traen: un pipeline de pruebas y de despliegue por servicio,
  infraestructura por servicio, datos que ya no están a una consulta de distancia,
  llamadas por la red con más latencia y menos confiabilidad, y refactorings que
  atraviesan varios servicios y exigen coordinar despliegues.
- **Lo que inferimos:** no nombra la alternativa de no hacer nada ni la de extraer solo
  uno o dos servicios (un estilo service-based). Con más de mil personas sobre un solo
  despliegue, nos habría parecido razonable evaluarla.

## 3. Lo que se eligió

- **Lo que dice el texto:** un modular monolith: todo el código sigue en una base de
  código y un despliegue, con límites entre dominios que se hacen respetar. En tres pasos:
  reorganizar el código por conceptos del negocio (órdenes, envíos, inventario, cobros) en
  vez de por conceptos de Rails, en un solo cambio hecho con scripts sobre unas 6 000
  clases; aislar las dependencias, con una API pública por componente y ownership
  exclusivo de sus datos; y una herramienta propia, Wedge, que en CI arma el grafo de
  llamadas y lista las violaciones de los límites por componente, con un puntaje.
- **Lo que inferimos:** es lo que el curso llama modular monolith (interfaz pública, datos
  propios, dependencias sin ciclos), y Wedge cumple el papel de una fitness function,
  aunque el texto no usa esa palabra. La reorganización es pasar de dividir por rol
  técnico a dividir por dominio.

## 4. Lo que se sacrificó

- **Lo que dice el texto:** poco. Reconoce que el cambio masivo de archivos hizo que
  GitHub perdiera buena parte del historial (los movimientos quedaron como borrados y
  creaciones), que el equipo que empezó no pudo aislar todos los componentes porque hacían
  falta expertos de cada dominio, y que los límites todavía no se hacen cumplir: Wedge
  reporta, no bloquea.
- **Lo que inferimos:** sigue habiendo un solo despliegue, así que el despliegue acoplado
  y los recursos compartidos del monolito no cambian. Y medir violaciones sin bloquear el
  build deja que el número vuelva a crecer si nadie lo mira.

## 5. Cómo supieron que funcionó

- **Lo que dice el texto:** da un ejemplo, no una medición: pudieron reemplazar un motor
  de impuestos antiguo por un sistema nuevo, algo que, dice, antes habría sido casi
  imposible. También cuenta que la decisión de partir el código salió de una encuesta a los
  desarrolladores, y que el puntaje de Wedge todavía no se grafica en el tiempo.
- **Lo que inferimos:** falta la medida del escenario: cuánto tardan las pruebas en CI y
  cuántos componentes toca un cambio típico, antes y después. Sin eso, el texto muestra
  que el cambio fue posible, no cuánto mejoró.

## Lo que el texto no dice

Cuánto costó el trabajo (personas y tiempo, más allá de "un equipo pequeño" formado a
comienzos de 2017), cuántos componentes quedaron, cuántas violaciones había y cuántas
quedan, y qué pasó después de 2019. Tampoco dice nada de la carga ni de los datos: es un
texto sobre el código, y de la base de datos solo dice que cada componente pasa a ser
owner de los suyos.

## Semanas del curso

- Semana 3: acoplamiento entre dominios, interfaz pública por módulo y dependencias que
  una herramienta revisa.
- Semana 4: dividir por rol técnico o por dominio, modular monolith y monolith first.
- Semana 5: las razones para no distribuir, dichas por quien podía hacerlo.
- Semana 15: una comprobación automática de los límites, y la deuda que se paga de a pocos.

## Qué no copiaríamos sin su contexto

El cambio único que mueve miles de archivos a la vez. Shopify lo eligió para interrumpir
una sola vez a un equipo muy grande y tenía una suite de pruebas en la que confiaba para
detectar un archivo mal movido. En un proyecto con pocas pruebas, ese cambio no se puede
comprobar; ahí conviene mover un módulo por vez, con las reglas de dependencia como red.

Errores

Ejemplos con errores a propósito: no compilan, fallan o dan un resultado incorrecto. Los apuntes explican cada uno.

errors/worksheet-only-solution.mdDescargar errors/worksheet-only-solution.md
# Ficha de lectura de un caso: Discord

<!--
Una ficha mal hecha, a propósito. Cuenta la solución y casi nada más: no dice
de cuándo es el texto, no separa lo que el texto afirma de lo que deduce quien
lee, no tiene alternativas ni costos, y concluye que el caso "aplica a todo".
check-doc.ts la rechaza; los apuntes explican por qué cada falta importa.
-->

## El texto

- **Título:** How Discord Stores Trillions of Messages
- **Quién lo escribe:** Bo Ingram
- **Fecha:** hace unos años
- **Enlace:** https://discord.com/blog/how-discord-stores-trillions-of-messages

## 1. El escenario que apretaba

Tenían muchísimos mensajes y la base de datos no escalaba.

## 3. Lo que se eligió

- **Lo que dice el texto:** migraron los mensajes de Cassandra a ScyllaDB y pusieron
  delante servicios de datos escritos en Rust.
- **Lo que inferimos:** Nada

## 5. Cómo supieron que funcionó

- **Lo que dice el texto:** ahora es mucho más rápido.
- **Lo que inferimos:** Nada

## Semanas del curso

Todas.

Pruebas

Comprueban lo que afirman los apuntes; se ejecutan con make test.

check-doc.test.tsDescargar check-doc.test.ts
// Comprueban el revisor de documentos con los archivos de la semana.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import {
  checkChecklist,
  checkPresentation,
  checkWorksheet,
  DECISION_FIELDS,
  parseSections,
  PRESENTATION_SECTIONS,
  WORKSHEET_QUESTIONS,
} from './check-doc.ts';

const read = (file: string) => readFileSync(new URL(file, import.meta.url), 'utf8');
const run = (...args: string[]) =>
  spawnSync(process.execPath, ['check-doc.ts', ...args], { cwd: import.meta.dirname, encoding: 'utf8' });

/** Llena un template: cada <indicación> se cambia por un texto cualquiera con un número. */
const fill = (template: string) =>
  template.replace(/<!--[\s\S]*?-->/g, '').replace(/<[^>]*>/g, 'Texto de prueba de la semana 11, con 3 mediciones de 2024');

test('el árbol de secciones respeta los niveles y junta los campos de varias líneas', () => {
  const [root] = parseSections('# A\n\n## B\n\n- **Campo uno:** primera\n  segunda\n\n### C\n\ntexto\n\n## D\n');
  assert.equal(root!.title, 'A');
  assert.deepEqual(
    root!.children.map((section) => section.title),
    ['B', 'D'],
  );
  assert.equal(root!.children[0]!.fields.get('campo uno'), 'primera segunda');
  assert.equal(root!.children[0]!.children[0]!.title, 'C');
});

test('un título dentro de un bloque de código no es una sección', () => {
  const [root] = parseSections('# A\n\n```sh\n# comentario de shell\n```\n\n## B\n');
  assert.deepEqual(
    root!.children.map((section) => section.title),
    ['B'],
  );
});

test('la ficha de ejemplo (Shopify) pasa', () => {
  assert.deepEqual(checkWorksheet(read('example/case-worksheet-shopify.md')), []);
});

test('el template de la ficha sin llenar no pasa: todas sus secciones siguen con la indicación', () => {
  const problems = checkWorksheet(read('case-worksheet-template.md'));
  // El texto, las cinco preguntas y las tres secciones finales.
  assert.equal(problems.filter((problem) => /la sección está vacía/.test(problem.message)).length, 9);
});

test('el template de la ficha, una vez lleno, pasa', () => {
  assert.deepEqual(checkWorksheet(fill(read('case-worksheet-template.md'))), []);
});

test('errors/: la ficha que solo cuenta la solución', () => {
  const problems = checkWorksheet(read('errors/worksheet-only-solution.md'));
  const messages = problems.map((problem) => `${problem.where}: ${problem.message}`);

  // No dice de cuándo es el texto ni qué describe.
  assert.ok(messages.includes('El texto: falta el campo "Qué describe"'));
  assert.ok(messages.some((message) => /la fecha no dice el año/.test(message)));
  // Faltan justo las dos preguntas que separan un caso de un anuncio.
  assert.ok(messages.includes('2. Las alternativas: falta la sección'));
  assert.ok(messages.includes('4. Lo que se sacrificó: falta la sección'));
  // El escenario está, pero sin separar lo que dice el texto de lo que se infiere.
  assert.ok(messages.includes('1. El escenario que apretaba: falta el campo "Lo que dice el texto"'));
  assert.ok(messages.includes('1. El escenario que apretaba: falta el campo "Lo que inferimos"'));
  // "Todas" no nombra ninguna semana.
  assert.ok(messages.some((message) => /no nombra ninguna semana/.test(message)));
  assert.ok(messages.includes('Qué no copiaríamos sin su contexto: falta la sección'));
  // Las preguntas que sí respondió con los dos campos no se reportan.
  assert.ok(!messages.some((message) => message.startsWith('3.') || message.startsWith('5.')));
});

test('una ficha que cita una semana que no existe se reporta', () => {
  const filled = fill(read('case-worksheet-template.md')).replace(/semana 11/g, 'semana 17');
  assert.ok(checkWorksheet(filled).some((problem) => problem.message === 'la semana 17 no existe'));
});

test('el template de la presentación sin llenar no pasa, y lleno sí', () => {
  const template = read('presentation-template.md');
  const problems = checkPresentation(template);
  for (const title of PRESENTATION_SECTIONS) {
    assert.ok(
      problems.some((problem) => problem.where === title && /vacía/.test(problem.message)),
      `debería reportar "${title}"`,
    );
  }
  // Tres decisiones por cinco campos cada una.
  assert.equal(problems.filter((problem) => /^el campo/.test(problem.message)).length, 3 * DECISION_FIELDS.length);
  assert.deepEqual(checkPresentation(fill(template)), []);
});

test('la presentación lleva exactamente tres decisiones', () => {
  const filled = fill(read('presentation-template.md'));
  const two = filled.replace(/### Decisión 3[\s\S]*?(?=\n## )/, '');
  assert.ok(checkPresentation(two).some((problem) => /hay 2 decisiones y se presentan 3/.test(problem.message)));
  const four = filled.replace('## Lo que haríamos distinto', '### Decisión 4: otra\n\n- **Escenario:** uno\n\n## Lo que haríamos distinto');
  assert.ok(checkPresentation(four).some((problem) => /hay 4 decisiones/.test(problem.message)));
});

test('una decisión sin alternativas o con una medición sin números se reporta', () => {
  const filled = fill(read('presentation-template.md'))
    .replace(/(### Decisión 1[\s\S]*?\*\*Alternativas descartadas:\*\*) [^\n]*/, '$1 Ninguna, era la única opción')
    .replace(/(### Decisión 2[\s\S]*?\*\*Medición:\*\*) [^\n]*/, '$1 quedó mucho mejor');
  const messages = checkPresentation(filled).map((problem) => problem.message);
  assert.equal(messages.length, 2);
  assert.match(messages[0]!, /sin alternativas no hubo decisión/);
  assert.match(messages[1]!, /la medición no tiene ningún número/);
});

test('la lista de la defensa reporta lo pendiente y pasa cuando todo está marcado', () => {
  const list = read('defence-checklist.md');
  const pending = checkChecklist(list);
  assert.equal(pending.length, 15);
  assert.ok(pending.every((problem) => problem.message.startsWith('pendiente: ')));
  assert.deepEqual(checkChecklist(list.replaceAll('- [ ]', '- [x]')), []);
  // Un documento sin casillas no es una lista.
  assert.equal(checkChecklist('# Lista\n\nTodo bien.\n').length, 1);
});

test('las cinco preguntas de la ficha son las del curso, en su orden', () => {
  assert.deepEqual(
    WORKSHEET_QUESTIONS.map((question) => question.slice(0, 2)),
    ['1.', '2.', '3.', '4.', '5.'],
  );
});

test('como programa: código 0 si pasa, 1 si no, 2 si se usa mal', () => {
  const good = run('worksheet', 'example/case-worksheet-shopify.md');
  assert.equal(good.status, 0);
  assert.match(good.stdout, /^✔ example\/case-worksheet-shopify\.md/);

  const bad = run('worksheet', 'errors/worksheet-only-solution.md');
  assert.equal(bad.status, 1);
  assert.match(bad.stdout, /^✖ errors\/worksheet-only-solution\.md/);
  assert.match(bad.stdout, /4\. Lo que se sacrificó: falta la sección/);

  assert.equal(run('ficha', 'example/case-worksheet-shopify.md').status, 2);
  assert.equal(run('worksheet').status, 2);
});
fault.test.tsDescargar fault.test.ts
// Comprueban lo que los apuntes dicen de cada falla, contra el ejemplo de
// demo/. Necesitan Toxiproxy corriendo (svc start toxiproxy; make test lo
// inicia). Usan sus propios puertos y su propio proxy, para no chocar con
// make demo.
import { after, before, test } from 'node:test';
import assert from 'node:assert/strict';
import { applyFault, clearFaults, describe, removeProxy, setupProxy, status, type ProxyConfig } from './fault.ts';
import { percentile, probe, summarize } from './probe.ts';
import { startCaller, type Caller, type LogLine } from './demo/caller.ts';
import { startDependency, type Dependency } from './demo/dependency.ts';

const config: ProxyConfig = {
  name: 'w16_test',
  listen: '127.0.0.1:4611',
  upstream: '127.0.0.1:4610',
  apiUrl: process.env.TOXIPROXY_URL ?? 'http://127.0.0.1:8474',
};
const PROXY_URL = `http://${config.listen}/prices/7`;
const QUOTE_URL = 'http://127.0.0.1:4612/quotes/7';
// Lo que el servicio espera a su dependencia.
const CALLER_TIMEOUT_MS = 400;
// La demora que se inyecta cuando el servicio debe aguantarla, y cuando no.
const SHORT_DELAY_MS = 250;
const LONG_DELAY_MS = 1500;

let dependency: Dependency;
let caller: Caller;
const logs: LogLine[] = [];

before(async () => {
  dependency = await startDependency(4610);
  caller = await startCaller({
    port: 4612,
    dependencyUrl: `http://${config.listen}`,
    timeoutMs: CALLER_TIMEOUT_MS,
    log: (line) => logs.push(line),
  });
  await setupProxy(config);
});

after(async () => {
  await removeProxy(config);
  await caller.close();
  await dependency.close();
});

test('sin fallas, el proxy deja pasar todo y el servicio responde 200', async () => {
  await clearFaults(config);
  const before = dependency.received();
  const summary = summarize(await probe(QUOTE_URL, { count: 5 }));
  assert.deepEqual(summary.byResult, { '200': 5 });
  assert.equal(dependency.received() - before, 5);
  assert.match(describe(await status(config)), /sin fallas$/);
});

test('latency: la respuesta se demora, pero el pedido sí llegó a la dependencia', async () => {
  const state = await applyFault(config, 'latency', SHORT_DELAY_MS);
  assert.equal(state.toxics.length, 1);
  assert.equal(state.toxics[0]!.stream, 'downstream');

  const before = dependency.received();
  const results = await probe(PROXY_URL, { count: 4 });
  assert.deepEqual(summarize(results).byResult, { '200': 4 });
  assert.equal(dependency.received() - before, 4);
  // Todos tardan al menos la demora inyectada (con un margen por el reloj).
  for (const result of results) assert.ok(result.ms >= SHORT_DELAY_MS - 20, `tardó ${result.ms} ms`);
});

test('latency por debajo del timeout del servicio: responde 200, más lento', async () => {
  await applyFault(config, 'latency', SHORT_DELAY_MS);
  logs.length = 0;
  const results = await probe(QUOTE_URL, { count: 3 });
  assert.deepEqual(summarize(results).byResult, { '200': 3 });
  assert.ok(logs.every((line) => line.outcome === 'ok' && line.ms >= SHORT_DELAY_MS - 20));
});

test('latency por encima del timeout: 503 al cumplirse el timeout, y la dependencia hizo el trabajo igual', async () => {
  await applyFault(config, 'latency', LONG_DELAY_MS);
  logs.length = 0;
  const before = dependency.received();
  const results = await probe(QUOTE_URL, { count: 3 });
  assert.deepEqual(summarize(results).byResult, { '503': 3 });
  assert.deepEqual(
    logs.map((line) => line.outcome),
    ['dependency_timeout', 'dependency_timeout', 'dependency_timeout'],
  );
  // El servicio se rinde cerca de su timeout, mucho antes de la demora inyectada.
  for (const result of results) {
    assert.ok(result.ms >= CALLER_TIMEOUT_MS - 20 && result.ms < LONG_DELAY_MS, `tardó ${result.ms} ms`);
  }
  // Un timeout no cancela nada: los tres pedidos llegaron a la dependencia.
  assert.equal(dependency.received() - before, 3);
});

test('cut: error de conexión enseguida, y a la dependencia no le llega nada', async () => {
  const state = await applyFault(config, 'cut');
  assert.equal(state.enabled, false);
  assert.match(describe(state), /corte/);

  const before = dependency.received();
  const direct = await probe(PROXY_URL, { count: 3 });
  assert.deepEqual(summarize(direct).byResult, { ECONNREFUSED: 3 });

  logs.length = 0;
  const results = await probe(QUOTE_URL, { count: 3 });
  assert.deepEqual(summarize(results).byResult, { '503': 3 });
  assert.ok(logs.every((line) => line.outcome === 'dependency_unavailable'));
  // Falla rápido: no espera al timeout.
  for (const line of logs) assert.ok(line.ms < CALLER_TIMEOUT_MS, `tardó ${line.ms} ms`);
  assert.equal(dependency.received() - before, 0);
});

test('blackhole: la conexión se acepta, nadie responde y el pedido no llega a la dependencia', async () => {
  const state = await applyFault(config, 'blackhole');
  assert.equal(state.toxics[0]!.type, 'timeout');
  assert.equal(state.toxics[0]!.stream, 'upstream');

  const before = dependency.received();
  // Directo al proxy, con un timeout propio de 300 ms: no hay error de conexión, solo silencio.
  const direct = await probe(PROXY_URL, { count: 2, timeoutMs: 300 });
  assert.deepEqual(summarize(direct).byResult, { TIMEOUT: 2 });

  logs.length = 0;
  const results = await probe(QUOTE_URL, { count: 2 });
  assert.deepEqual(summarize(results).byResult, { '503': 2 });
  // Desde el servicio se ve igual que una dependencia lenta.
  assert.ok(logs.every((line) => line.outcome === 'dependency_timeout' && line.ms >= CALLER_TIMEOUT_MS - 20));
  assert.equal(dependency.received() - before, 0);
});

test('slow-third: con una conexión nueva por pedido, uno tras otro, cerca de un tercio son lentos', async () => {
  const delayMs = 100;
  await applyFault(config, 'slow-third', delayMs);
  const results = await probe(PROXY_URL, { count: 90 });
  assert.deepEqual(summarize(results).byResult, { '200': 90 });
  const slow = results.filter((result) => result.ms >= delayMs - 10).length;
  // Se esperan unos 30 de 90. Los límites están a cuatro desviaciones estándar
  // (la desviación es de unos 4,5), para que la prueba no falle por azar.
  assert.ok(slow >= 12 && slow <= 48, `${slow} de 90 fueron lentos`);
});

test('slow-third: el sorteo es por conexión; por una misma conexión, todos lentos o todos normales', async () => {
  await applyFault(config, 'slow-third', SHORT_DELAY_MS);
  let slowConnections = 0;
  const connections = 12;
  for (let connection = 0; connection < connections; connection += 1) {
    // keepAlive con un pedido a la vez: los cuatro pedidos viajan por la misma conexión.
    const results = await probe(PROXY_URL, { count: 4, keepAlive: true });
    const slow = results.filter((result) => result.ms >= SHORT_DELAY_MS - 20).length;
    assert.ok(slow === 0 || slow === 4, `conexión mixta: ${slow} de 4 lentos`);
    if (slow === 4) slowConnections += 1;
  }
  // No se afirma cuántas: con 12 conexiones puede salir cualquier número.
  assert.ok(slowConnections >= 0 && slowConnections <= connections);
});

test('cada comando deja una sola falla, y clear vuelve al estado normal', async () => {
  await applyFault(config, 'cut');
  const afterLatency = await applyFault(config, 'latency', SHORT_DELAY_MS);
  // Poner latency después de cut vuelve a habilitar el proxy.
  assert.equal(afterLatency.enabled, true);
  assert.equal(afterLatency.toxics.length, 1);
  const afterBlackhole = await applyFault(config, 'blackhole');
  assert.equal(afterBlackhole.toxics.length, 1);
  assert.equal(afterBlackhole.toxics[0]!.type, 'timeout');

  await clearFaults(config);
  const clean = await status(config);
  assert.equal(clean.enabled, true);
  assert.deepEqual(clean.toxics, []);
  assert.deepEqual(summarize(await probe(QUOTE_URL, { count: 3 })).byResult, { '200': 3 });
});

test('una demora que no es un entero positivo se rechaza antes de tocar el proxy', async () => {
  await clearFaults(config);
  await assert.rejects(applyFault(config, 'latency', 0), /milisegundos/);
  await assert.rejects(applyFault(config, 'latency', Number.NaN), /milisegundos/);
  assert.deepEqual((await status(config)).toxics, []);
});

test('si el proxy no existe, el error dice qué correr', async () => {
  await assert.rejects(status({ ...config, name: 'w16_missing' }), /node fault\.ts setup/);
});

test('percentil por rango más cercano, como en la semana 2', () => {
  const values = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
  assert.equal(percentile(values, 50), 50);
  assert.equal(percentile(values, 95), 100);
  assert.equal(percentile(values, 10), 10);
  assert.equal(percentile([7], 99), 7);
  assert.throws(() => percentile([], 50));
});

Compilación

Cómo se compilan y ejecutan los ejemplos.

MakefileDescargar Makefile
# Semana 16: leer un caso real, presentar una arquitectura y defenderla. Se usa
# dentro del contenedor del curso.
#
#   make             inicia Toxiproxy (lo único que la semana necesita preparar)
#   make test        revisa los tipos (tsc) y corre las pruebas (*.test.ts): el
#                    revisor de documentos y las cuatro fallas contra el ejemplo de demo/
#   make check       revisa la ficha de ejemplo con check-doc.ts
#   make errors      lo mismo con la ficha mal hecha de errors/ (falla a propósito)
#   make demo        el ejemplo completo: un servicio, su dependencia y una falla
#                    tras otra, con lo que ve quien llama (unos 20 s)
#   make up          levanta el ejemplo en segundo plano (logs en build/) y crea el
#                    proxy, para aplicarle fallas a mano con fault.ts
#   make down        detiene el ejemplo y borra el proxy
#   make clean       borra build/
#
# Para el sistema del equipo no hace falta este Makefile: se usa fault.ts con
# FAULT_LISTEN y FAULT_UPSTREAM apuntando a la dependencia de ese sistema.

.PHONY: all test check errors demo up down clean

all:
	@svc start toxiproxy

test: all
	tsc -p .
	node --test --test-concurrency=1 "*.test.ts"

check:
	node check-doc.ts worksheet example/case-worksheet-shopify.md

# El revisor termina con error cuando encuentra algo: aquí eso es lo que se quiere ver.
errors:
	@node check-doc.ts worksheet errors/worksheet-only-solution.md ; echo "check-doc terminó con código $$?"

demo: all
	@node demo/run.ts

up: all
	@mkdir -p build
	@node demo/dependency.ts > build/dependency.log 2>&1 & echo $$! > build/dependency.pid
	@node demo/caller.ts > build/caller.log 2> build/caller.err & echo $$! > build/caller.pid
	@node fault.ts setup
	@echo "servicio en http://127.0.0.1:4602/quotes/7 · su log, en build/caller.log"

down:
	@-kill `cat build/dependency.pid build/caller.pid 2>/dev/null` 2>/dev/null ; rm -f build/dependency.pid build/caller.pid
	@-node fault.ts remove 2>/dev/null

clean: down
	rm -rf build
package.jsonDescargar package.json
{"private": true, "type": "module"}
tsconfig.jsonDescargar tsconfig.json
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "types": ["node"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["*.ts", "demo/*.ts"]
}