La lección anterior dejó a inventario funcionando como servicio XML-RPC, y dejó a la vista sus tres debilidades: 230 bytes de XML para transmitir dos argumentos, un contrato implícito que se rompe en silencio cuando cambia una firma, y ningún mecanismo para que el servidor envíe un flujo de datos al cliente. Las tres tienen que ver con la misma pregunta de fondo: cómo se convierten las estructuras de datos en bytes y cómo evoluciona ese formato sin romper a nadie. Es la pregunta de la serialización, y de su respuesta depende buena parte del rendimiento, la interoperabilidad y la mantenibilidad de una plataforma distribuida.

En esta lección compararemos formatos de texto (JSON, XML) y binarios (Protocol Buffers, Avro, MessagePack), aprenderemos a escribir esquemas Protocol Buffers y las reglas que permiten cambiarlos sin romper clientes antiguos, y construiremos la versión definitiva de la interfaz pedidos → inventario de Kilómetro Cero con gRPC: contrato en inventario.proto, servidor en servicios/inventario/servidor.py, cliente con deadline en pedidos, y un flujo del servidor para observar cambios de stock. Terminaremos midiendo con código cuántos bytes ahorra protobuf frente a JSON para el mismo pedido. La mensajería asíncrona (colas, Kafka) es el tema de la lección siguiente: aquí todo es síncrono.

1. Serialización: de estructuras en memoria a bytes
2. Formatos de texto frente a formatos binarios
3. Contract-first: el esquema como fuente de verdad
4. Protocol Buffers: sintaxis, tipos y campos numerados
5. Evolución de esquemas: compatibilidad hacia delante y hacia atrás
6. gRPC: RPC sobre HTTP/2
7. inventario en gRPC: contrato, servidor y cliente con deadline
8. Streaming del servidor: observar cambios de stock
9. Medir: JSON frente a protobuf para el mismo pedido
10. Errores comunes y consejos
11. Ejercicios
12. Conclusión

En la lección 02-02 lo llamamos marshalling; el término general es serialización: transformar un objeto en memoria (un diccionario de Python, una instancia de una clase Java) en una secuencia de bytes que pueda escribirse en la red o en disco, y deserialización, el proceso inverso. Todo lo que cruza una frontera de proceso pasa por aquí: argumentos de RPC, eventos en una cola, filas en una base de datos, ficheros en un almacén de objetos.

Un formato de serialización tiene que decidir cuatro cosas:

1. Cómo representa los tipos: ¿un entero es texto ("120") o binario (4 bytes)? ¿Distingue entre entero y decimal? ¿Tiene fechas, o son cadenas con un convenio?
2. Cómo nombra los campos: ¿lleva el nombre en cada mensaje ("producto": "queso-curado"), o un número (1: "queso-curado"), o nada (posición fija)?
3. Dónde vive el esquema: ¿en el propio mensaje (autodescriptivo), en un fichero externo que ambos extremos comparten, o en la cabeza de los programadores?
4. Cómo evoluciona: ¿qué pasa cuando el emisor añade un campo que el receptor no conoce, o al revés?

Las respuestas a estas preguntas separan a los formatos en dos grandes familias.

Algunas observaciones que la tabla no captura:

• JSON no distingue enteros de decimales ni tiene tipo para dinero: 14.50 es un float de doble precisión, y ya vimos en 01-06 que el precio en float es un error (falacia 8, y errores de redondeo). Los convenios habituales (enviar céntimos como entero, o el importe como cadena "14.50") son eso, convenios, que hay que documentar y que cada cliente puede incumplir.
• El coste de JSON no es solo el tamaño, es el parseo: convertir "120" en el entero 120 requiere interpretar caracteres; leer 4 bytes como un entero es una instrucción. En un servicio que serializa miles de mensajes por segundo, la CPU dedicada a JSON es medible.
• Los formatos binarios sin esquema (MessagePack) ahorran poco: siguen enviando los nombres de campo en cada mensaje. El ahorro grande viene de sustituir nombres por números, y eso exige un esquema compartido.
• Avro y Protocol Buffers resuelven el mismo problema con filosofías distintas: protobuf compila el esquema a código y numera los campos; Avro no genera código necesariamente y resuelve las diferencias entre el esquema con el que se escribió un dato y el esquema con el que se lee. Avro encaja especialmente bien con Kafka y con ficheros de datos masivos (Módulo 5); protobuf, con RPC.

Hay dos maneras de llegar a un contrato entre pedidos e inventario:

• Code-first: se escribe la implementación (la clase Inventario de XML-RPC, la interfaz Java de RMI) y el contrato es lo que se deduce de ella. Rápido al principio; el contrato queda acoplado a un lenguaje y cambia sin que nadie lo revise.
• Contract-first: se escribe primero el contrato en un lenguaje neutro (el IDL de 02-02), se revisa como se revisaría una API pública, se versiona en el repositorio, y a partir de él se genera el código de cliente y servidor en cada lenguaje.

Con contract-first, el fichero .proto es la única fuente de verdad: si el equipo de pedidos quiere saber qué devuelve ReservarStock, lo lee ahí, no en el código Python de inventario. Los cambios al contrato pasan por revisión de código, se pueden validar automáticamente contra las reglas de compatibilidad (apartado 5), y la generación de código garantiza que ningún cliente puede llamar a un método con tipos equivocados: el TypeError del ejercicio 3 de la lección anterior se convierte en un error de compilación. En Kilómetro Cero, los contratos vivirán en km0/contratos/ y cada servicio generará su código desde allí.

Protocol Buffers (protobuf) es el IDL y formato de serialización de Google, y el que usa gRPC por defecto. Un fichero .proto define mensajes (estructuras de datos) y, opcionalmente, servicios (conjuntos de RPC). Empecemos por un mensaje sencillo, el pedido de Kilómetro Cero:

Cada elemento tiene un papel:

• syntax = "proto3" fija la versión del lenguaje. proto3 es la actual y la que usaremos.
• package evita colisiones de nombres entre contratos y aparece en los nombres completos de los tipos (km0.pedidos.v1.Pedido). El sufijo v1 es una convención para versionar contratos completos, distinta de la evolución campo a campo del apartado 5.
• Cada campo tiene un tipo, un nombre y un número. El número es lo importante: es lo que viaja por la red, no el nombre. Cuando se serializa producto = "queso-curado", se escribe "campo 1, tipo cadena, longitud 12, bytes". El nombre producto no aparece en ningún byte; existe solo en el código generado. Por eso protobuf es compacto y por eso renombrar un campo es gratis mientras cambiar su número rompe todo.
• repeated marca una lista. En proto3 todos los campos son opcionales en el sentido de que pueden faltar; si faltan, se lee su valor por defecto (0, cadena vacía, lista vacía, false), y un campo con valor por defecto no se serializa (más bytes ahorrados).

Más allá de los escalares: enum (con el valor 0 obligatorio como primer elemento y reservado a "desconocido"), mensajes anidados, map<string, int32> (diccionarios), oneof (exactamente uno de varios campos, útil para "resultado o error") y el modificador optional de proto3 (desde la versión 3.15), que permite distinguir "campo ausente" de "campo con valor por defecto", algo que de otro modo no es posible: sin optional, no hay forma de saber si cantidad = 0 significa cero o "no me lo dijeron".

Para entender el ahorro, aquí está la serialización de LineaPedido{producto: "queso-curado", cantidad: 2, precio_centimos: 1450}:

19 bytes. El mismo objeto en JSON compacto, {"producto":"queso-curado","cantidad":2,"precio_centimos":1450}, ocupa 63. La diferencia son los nombres de campo, las comillas, los dos puntos y los números representados como texto.

Un contrato que no puede cambiar no sirve. Kilómetro Cero desplegará inventario y pedidos de forma independiente (era uno de los objetivos de 01-06), lo que significa que durante un tiempo convivirán versiones distintas del contrato en producción. Dos definiciones:

• Compatibilidad hacia atrás (backward): el código nuevo puede leer mensajes escritos con el esquema antiguo. Necesaria cuando se actualiza primero el lector (por ejemplo, inventario nuevo recibe peticiones de un pedidos viejo).
• Compatibilidad hacia delante (forward): el código antiguo puede leer mensajes escritos con el esquema nuevo. Necesaria cuando se actualiza primero el escritor.

En la práctica hacen falta las dos, porque no se controla el orden de despliegue de todos los clientes (y con eventos persistidos en Kafka, 02-04, se leerán mensajes de hace días con el esquema de hoy). Protobuf las proporciona si se siguen estas reglas:

Ejemplo: en la segunda fase, pedidos quiere añadir la dirección de entrega al pedido y eliminar mercado (que pasa a deducirse de la dirección):

Un pedidos nuevo envía el campo 6; un reparto viejo lo ignora y sigue funcionando (con mercado vacío, que su código debe tolerar). Un pedidos viejo envía el campo 5; un reparto nuevo lo descarta. Ningún despliegue tiene que coordinarse. Esta disciplina (números únicos y nunca reutilizados, reserved al eliminar, campos nuevos siempre opcionales con valor por defecto tolerable) es probablemente la habilidad más valiosa de toda la lección, y se aplicará igual a los esquemas de eventos en 02-05.

gRPC es el sistema RPC de Google, publicado en 2015, y hoy el estándar de hecho para comunicación síncrona entre servicios. Toma las ideas de 02-02 (stubs, skeleton, IDL) y las apoya sobre las dos piezas anteriores: Protocol Buffers como IDL y serialización, y HTTP/2 como transporte. Esa segunda decisión no es un detalle:

• La multiplexación de HTTP/2 (lección 02-01) permite que pedidos mantenga un solo canal hacia inventario y lance por él cientos de llamadas simultáneas sin abrir conexiones nuevas ni esperar respuestas en serie.
• Los flujos de HTTP/2 son bidireccionales y de larga duración, lo que hace posible el streaming.
• Las cabeceras comprimidas transportan los metadatos (autenticación, trazas) con poco coste.
• Al ser HTTP, atraviesa balanceadores, proxies y mallas de servicios (con soporte de HTTP/2).

Tres conceptos de gRPC que resuelven problemas que en 02-02 quedaron a medias:

• Deadline. En lugar de un timeout relativo ("espera 2 s"), gRPC propaga un instante absoluto ("esta llamada caduca a las 10:00:02,000"). La diferencia importa cuando una llamada provoca otras: si pedidos tiene 2 s para responder a Ana y tarda 1,5 s en llegar a inventario, inventario sabe que solo le quedan 0,5 s, y puede abortar trabajo inútil. El servidor consulta context.time_remaining(); el cliente recibe DEADLINE_EXCEEDED. Es la solución sistemática a "ninguna llamada remota sin límite de tiempo".
• Códigos de estado. gRPC define 17 códigos estándar, con semántica compartida por todos los lenguajes. Sustituyen a nuestros faultCode inventados:

• Metadatos. Pares clave-valor que acompañan a la llamada sin formar parte del contrato: se transportan como cabeceras HTTP/2. Es donde viajan los tokens de autenticación (06-01), los identificadores de traza (07-02) y, como veremos, el identificador de petición para la idempotencia (02-05).

Es el momento de reemplazar el servidor XML-RPC. Instalación (en el requirements.txt del servicio):

Esto produce dos ficheros que no se editan a mano (se regeneran cada vez que cambia el .proto, idealmente en la construcción de la imagen Docker):

• inventario_pb2.py: las clases de mensaje (ReservarStockRequest, etc.), con serialización incluida.
• inventario_pb2_grpc.py: InventarioServicer (la clase base que el servidor implementa: el skeleton) e InventarioStub (el stub del cliente).

El mismo comando, ejecutado en servicios/pedidos, genera los mismos ficheros para el cliente. Cada servicio compila el contrato compartido; nadie copia código de otro servicio.

Comparado con XML-RPC (02-02), fíjate en lo que ha cambiado: los errores usan códigos estándar con semántica conocida por cualquier cliente; el context da acceso al deadline y a la cancelación; un método de streaming es simplemente un generador de Python; y el servidor es un ThreadPoolExecutor con un tamaño explícito (16 hilos: cuando se agoten, las llamadas esperan, y con deadline caducan en lugar de acumularse indefinidamente).

Salida:

Y con inventario parado: Ana: NO - inventario no disponible; pedido en espera (no se ejecutó), en milisegundos, gracias a que gRPC distingue UNAVAILABLE (conexión rechazada) de DEADLINE_EXCEEDED (silencio). Es la tabla de cuatro familias de errores de 02-02, ahora estandarizada. El id_reserva viaja en cada petición pero el servidor aún no lo usa para filtrar duplicados: eso es exactamente lo que añadirá 02-05.

Un cliente que quiera mostrar "quedan pocas unidades" (será catalogo) no debería preguntar el stock en cada visualización. Con ObservarCambios abre un flujo y recibe cada cambio:

Arranca el observador y luego ejecuta el cliente de pedidos: verás queso-curado: 5 -> 3 (reserva) <- QUEDAN POCAS. Todo viaja por un flujo HTTP/2 que se mantiene abierto; cada yield del servidor es una trama en ese flujo. Dos advertencias: este flujo es una conexión punto a punto, así que si el observador se reinicia se pierde lo ocurrido entretanto, y si hay diez servicios interesados en los cambios, inventario mantiene diez flujos. Para difundir eventos a muchos consumidores con persistencia, la herramienta adecuada es la mensajería de la lección siguiente; el streaming gRPC brilla en flujos de uno a uno, como la telemetría de un repartidor concreto.

Nada convence más que los números. Generamos el código de pedido.proto (python -m grpc_tools.protoc -I ../../contratos --python_out=. ../../contratos/pedido.proto) y comparamos:

Salida orientativa (los tiempos dependen de la máquina y de si protobuf usa su implementación en C):

Un pedido de tres líneas pesa menos de la mitad y se procesa unas tres veces más rápido. Con 1.200 pedidos por segundo (lección 01-03) y decenas de llamadas internas por pedido, la diferencia se traduce en ancho de banda, CPU y latencia. Y lo que no mide este script es igual de importante: el .proto ha validado los tipos en tiempo de construcción del mensaje (precio_centimos="14.50" habría fallado inmediatamente), mientras que el diccionario acepta cualquier cosa.

Con esto, inventario es el primer servicio real de km0/servicios/. Su Dockerfile compila el contrato al construir la imagen, y docker-compose.yml gana un servicio:

El monolito, por ahora, sigue usando su propio módulo inventario interno; el estrangulamiento (01-06) consiste en ir redirigiendo sus llamadas a este servicio. Ese cambio no tiene nada de especial técnicamente (es sustituir una llamada local por ClienteInventario) y no lo detallaremos; lo que sí tiene mucho de especial es que ahora pedidos e inventario tienen datos separados, y ese es el problema del Módulo 3.

• Reutilizar un número de campo. El error más grave con protobuf, porque no produce ningún error: produce datos corruptos leídos con total confianza. reserved siempre al eliminar.
• Cambiar el tipo de un campo "porque es equivalente". int32 → string rompe; int32 → int64 funciona en el cable, pero un valor grande escrito por el nuevo se truncará en el viejo. Ante la duda, campo nuevo con número nuevo.
• Dinero en float/double. Céntimos en int64, o una cadena decimal si hace falta precisión arbitraria. Lo repetiremos hasta el proyecto final.
• Confiar en que "campo ausente" y "valor por defecto" se distinguen. En proto3 no se distinguen salvo con optional. Si cantidad = 0 puede ser legítimo, usa optional o valida en el servidor.
• Un canal por llamada. grpc.insecure_channel abre una conexión HTTP/2 con su handshake; crea uno por proceso (o unos pocos) y reutilízalo. Un canal por llamada es HTTP/1.1 sin keep-alive con más pasos.
• Sin deadline. El parámetro timeout es opcional en la API y obligatorio en la práctica. Sin él, la llamada espera para siempre, con todo lo que aprendimos en 01-04.
• Ignorar el código de estado y mirar solo el texto. e.details() es para personas; e.code() es para programas. El texto puede cambiar entre versiones del servidor; el código, no.
• Editar los ficheros _pb2.py generados. Se sobrescriben en la siguiente generación. Todo cambio va al .proto.
• Consejo: valida la compatibilidad de los .proto en la integración continua con una herramienta como buf breaking: convierte las reglas del apartado 5 en una comprobación automática, y ningún cambio incompatible llega a producción por descuido.
• Consejo: cuando diseñes un mensaje, piensa en la versión 3 antes de publicar la 1: deja los números bajos (1-15, que ocupan un solo byte de etiqueta) para los campos más frecuentes, usa nombres neutros, y no metas en un mensaje lo que pertenece a otro servicio.

El equipo de pedidos necesita que una reserva pueda ser temporal (caduca a los 15 minutos si no se paga, para liberar el último queso si Ana abandona el carrito) y quiere además eliminar pedido_id de la petición, porque a partir de ahora viajará como metadato. Escribe la nueva versión del mensaje respetando las reglas de compatibilidad y explica qué verá un servidor inventario antiguo cuando reciba la petición nueva, y qué verá un inventario nuevo cuando reciba una petición antigua.

pedidos recibe de la app de Ana una petición con un límite total de 3 segundos, y para atenderla llama primero a inventario (reservar) y luego a pagos (cobrar). Explica por qué usar timeout=3.0 en ambas llamadas gRPC es incorrecto, y escribe una función tiempo_restante(deadline_absoluto) que calcule el timeout a pasar a cada llamada. ¿Qué debería hacer pedidos si al ir a llamar a pagos quedan 50 ms?

Para cada interacción indica el tipo de llamada gRPC (unaria, streaming de servidor, de cliente o bidireccional) o si conviene otra cosa (REST, mensajería), y el formato de serialización:

1. La app de Lucía descarga la ficha de un producto con su foto.
2. pedidos pide a inventario el stock de los 8 productos de un carrito.
3. furgoneta-3 envía 1 posición por segundo a reparto durante una ruta de 2 horas, y al final recibe el resumen de kilómetros.
4. analitica necesita todos los pedidos de la "Semana de la Vendimia" para un informe nocturno.
5. Un operador de atención al cliente y la app de un repartidor intercambian mensajes cortos en tiempo real sobre una incidencia de entrega.

Solución 1:

Se elimina pedido_id reservando su número (3) y su nombre; el campo nuevo toma el número 5, nunca el 3. Se elige que el valor por defecto (0) signifique "comportamiento anterior", de modo que una petición que no lo envíe se comporte como antes. Un inventario antiguo que reciba la petición nueva verá pedido_id vacío (la cadena por defecto: su log de trazabilidad imprimirá pedido : en blanco, tolerable) e ignorará el campo 5, que no conoce: hará una reserva permanente, lo cual es un comportamiento degradado pero no un error; el equipo debe saber que la caducidad no funciona hasta que inventario se despliegue. Un inventario nuevo que reciba una petición antigua verá caduca_en_segundos = 0 y hará una reserva permanente, exactamente lo que ese cliente esperaba. Ningún despliegue necesita coordinarse, aunque la funcionalidad completa solo existe cuando ambos están actualizados.

Solución 2:

Con timeout=3.0 en cada llamada, el peor caso es que inventario tarde 2,9 s (dentro de su límite) y pagos otros 2,9 s: pedidos respondería a Ana en 5,8 s, casi el doble de lo prometido, y la app ya habría abandonado. El deadline debe ser uno solo y absoluto, calculado al recibir la petición, y cada llamada recibe lo que queda:

Con 50 ms restantes lo correcto es no llamar a pagos: una llamada que va a caducar deja la operación más peligrosa (un cobro) en estado "no se sabe". Abortar antes es la versión de "fallar rápido" que gRPC facilita al hacer explícito el tiempo que queda; los servidores gRPC pueden además consultar context.time_remaining() para no empezar trabajo que no podrán terminar. Nota que se usa time.monotonic() (no time.time()): el deadline es una duración, no un instante de reloj de pared, y los relojes de pared saltan (lección 01-05).

Solución 3:

1. REST con JSON para los metadatos y la foto como recurso HTTP aparte (cacheable por CDN). Es un cliente externo, navegador o app, y el contenido se beneficia de la caché HTTP. gRPC en navegador requiere gRPC-Web y no aporta caché.
2. Unaria con un mensaje que lleve repeated string productos: una llamada, una respuesta con las 8 unidades (grano grueso, 02-02). Protobuf.
3. Streaming de cliente: N posiciones → 1 resumen. Protobuf; cada posición son ~25 bytes. Ojo: si la red móvil es mala, un flujo HTTP/2 sobre TCP sufre bloqueo de cabeza de línea (02-01), y MQTT (08-02) puede ser mejor opción para el tramo móvil; el streaming gRPC encaja entre la pasarela y reparto.
4. Ninguna llamada síncrona: es un volumen grande y un proceso por lotes. analitica debería consumir los eventos de pedido (02-04) o leer del almacén analítico (Módulo 5), no pedir a pedidos decenas de miles de registros en una llamada (aunque técnicamente un streaming de servidor lo permitiría, acoplaría la carga analítica al servicio transaccional: síntoma 5 de 01-06). Formato: Avro o Parquet para datos masivos.
5. Bidireccional: mensajes en ambos sentidos, en cualquier orden, en tiempo real. Protobuf. Si uno de los extremos es un navegador, la alternativa práctica es WebSockets (08-02), que es lo mismo conceptualmente con un transporte que los navegadores soportan de forma nativa.

Esta lección ha cerrado el círculo abierto en 02-02. La serialización decide cómo se convierten las estructuras en bytes, y esa decisión determina tamaño, velocidad, seguridad de tipos y capacidad de evolución: los formatos de texto (JSON, XML) son legibles y universales pero pesados y sin esquema; los binarios con esquema (Protocol Buffers, Avro) pesan menos de la mitad, se procesan varias veces más rápido y, sobre todo, tienen reglas de evolución (números de campo únicos y nunca reutilizados, reserved al eliminar, campos nuevos con valores por defecto tolerables) que permiten desplegar pedidos e inventario de forma independiente. Con contract-first, el .proto es la fuente de verdad de la que se genera el código. gRPC apoya esos esquemas sobre HTTP/2 para ofrecer un canal multiplexado, cuatro tipos de llamada (unaria y tres formas de streaming), deadlines absolutos que se propagan, códigos de estado estándar y metadatos. Kilómetro Cero tiene ahora su primer servicio extraído de verdad: inventario en servicios/inventario/servidor.py, con su contrato en contratos/inventario.proto, un cliente en pedidos que traduce cada código de estado a una decisión de negocio, y un flujo de cambios de stock. La medición ha confirmado el ahorro: un pedido de tres líneas pasa de 282 bytes en JSON a 97 en protobuf.

Pero todo lo hecho en este módulo hasta aquí es síncrono: pedidos llama, espera y recibe. Al final de 01-06 quedó claro que eso es lo correcto para reservar stock y lo incorrecto para casi todo lo demás: avisar a analitica de una venta, planificar el reparto o actualizar el indicador del catálogo no deberían bloquear al cliente ni depender de que el destinatario esté vivo en ese instante. Para eso hace falta que alguien guarde el mensaje y lo entregue cuando el destinatario pueda: un broker. La siguiente lección, Mensajería y Colas de Mensajes, introduce RabbitMQ y Apache Kafka, y con ellos el primer flujo asíncrono de Kilómetro Cero: el evento pedido.creado.