La lliçó anterior va deixar inventari funcionant com a servei XML-RPC, i va deixar a la vista les seves tres febleses: 230 bytes d'XML per transmetre dos arguments, un contracte implícit que es trenca en silenci quan canvia una signatura, i cap mecanisme perquè el servidor enviï un flux de dades al client. Les tres tenen a veure amb la mateixa pregunta de fons: com es converteixen les estructures de dades en bytes i com evoluciona aquest format sense trencar ningú. És la pregunta de la serialització, i de la seva resposta depèn bona part del rendiment, la interoperabilitat i la mantenibilitat d'una plataforma distribuïda.

En aquesta lliçó compararem formats de text (JSON, XML) i binaris (Protocol Buffers, Avro, MessagePack), aprendrem a escriure esquemes Protocol Buffers i les regles que permeten canviar-los sense trencar clients antics, i construirem la versió definitiva de la interfície comandes → inventari de Quilòmetre Zero amb gRPC: contracte a inventari.proto, servidor a serveis/inventari/servidor.py, client amb deadline a comandes, i un flux del servidor per observar canvis d'estoc. Acabarem mesurant amb codi quants bytes estalvia protobuf respecte de JSON per a la mateixa comanda. La missatgeria asíncrona (cues, Kafka) és el tema de la lliçó següent: aquí tot és síncron.

1. Serialització: d'estructures en memòria a bytes
2. Formats de text contra formats binaris
3. Contract-first: l'esquema com a font de veritat
4. Protocol Buffers: sintaxi, tipus i camps numerats
5. Evolució d'esquemes: compatibilitat cap endavant i cap enrere
6. gRPC: RPC sobre HTTP/2
7. inventari en gRPC: contracte, servidor i client amb deadline
8. Streaming del servidor: observar canvis d'estoc
9. Mesurar: JSON contra protobuf per a la mateixa comanda
10. Errors comuns i consells
11. Exercicis
12. Conclusió

A la lliçó 02-02 en vam dir marshalling; el terme general és serialització: transformar un objecte en memòria (un diccionari de Python, una instància d'una classe Java) en una seqüència de bytes que es pugui escriure a la xarxa o al disc, i deserialització, el procés invers. Tot el que travessa una frontera de procés passa per aquí: arguments d'RPC, esdeveniments en una cua, files en una base de dades, fitxers en un magatzem d'objectes.

Un format de serialització ha de decidir quatre coses:

1. Com representa els tipus: un enter és text ("120") o binari (4 bytes)? Distingeix entre enter i decimal? Té dates, o són cadenes amb un conveni?
2. Com anomena els camps: porta el nom a cada missatge ("producte": "formatge-curat"), o un número (1: "formatge-curat"), o res (posició fixa)?
3. On viu l'esquema: al mateix missatge (autodescriptiu), en un fitxer extern que tots dos extrems comparteixen, o al cap dels programadors?
4. Com evoluciona: què passa quan l'emissor afegeix un camp que el receptor no coneix, o a l'inrevés?

Les respostes a aquestes preguntes separen els formats en dues grans famílies.

Algunes observacions que la taula no captura:

• JSON no distingeix enters de decimals ni té tipus per als diners: 14.50 és un float de doble precisió, i ja vam veure a 01-06 que el preu en float és un error (fal·làcia 8, i errors d'arrodoniment). Els convenis habituals (enviar cèntims com a enter, o l'import com a cadena "14.50") són això, convenis, que cal documentar i que cada client pot incomplir.
• El cost de JSON no és només la mida, és el parseig: convertir "120" en l'enter 120 requereix interpretar caràcters; llegir 4 bytes com un enter és una instrucció. En un servei que serialitza milers de missatges per segon, la CPU dedicada a JSON és mesurable.
• Els formats binaris sense esquema (MessagePack) estalvien poc: continuen enviant els noms de camp a cada missatge. L'estalvi gran ve de substituir noms per números, i això exigeix un esquema compartit.
• Avro i Protocol Buffers resolen el mateix problema amb filosofies diferents: protobuf compila l'esquema a codi i numera els camps; Avro no genera codi necessàriament i resol les diferències entre l'esquema amb què es va escriure una dada i l'esquema amb què es llegeix. Avro encaixa especialment bé amb Kafka i amb fitxers de dades massives (Mòdul 5); protobuf, amb RPC.

Hi ha dues maneres d'arribar a un contracte entre comandes i inventari:

• Code-first: s'escriu la implementació (la classe Inventari d'XML-RPC, la interfície Java d'RMI) i el contracte és el que se'n dedueix. Ràpid al principi; el contracte queda acoblat a un llenguatge i canvia sense que ningú ho revisi.
• Contract-first: s'escriu primer el contracte en un llenguatge neutre (l'IDL de 02-02), es revisa com es revisaria una API pública, es versiona al repositori, i a partir d'ell es genera el codi de client i servidor en cada llenguatge.

Amb contract-first, el fitxer .proto és l'única font de veritat: si l'equip de comandes vol saber què retorna ReservarEstoc, ho llegeix allà, no al codi Python d'inventari. Els canvis al contracte passen per revisió de codi, es poden validar automàticament contra les regles de compatibilitat (apartat 5), i la generació de codi garanteix que cap client no pot cridar un mètode amb tipus equivocats: el TypeError de l'exercici 3 de la lliçó anterior es converteix en un error de compilació. A Quilòmetre Zero, els contractes viuran a km0/contractes/ i cada servei generarà el seu codi des d'allà.

Protocol Buffers (protobuf) és l'IDL i format de serialització de Google, i el que fa servir gRPC per defecte. Un fitxer .proto defineix missatges (estructures de dades) i, opcionalment, serveis (conjunts d'RPC). Comencem per un missatge senzill, la comanda de Quilòmetre Zero:

Cada element té un paper:

• syntax = "proto3" fixa la versió del llenguatge. proto3 és l'actual i la que farem servir.
• package evita col·lisions de noms entre contractes i apareix als noms complets dels tipus (km0.comandes.v1.Comanda). El sufix v1 és una convenció per versionar contractes complets, diferent de l'evolució camp a camp de l'apartat 5.
• Cada camp té un tipus, un nom i un número. El número és l'important: és el que viatja per la xarxa, no el nom. Quan se serialitza producte = "formatge-curat", s'escriu "camp 1, tipus cadena, longitud 14, bytes". El nom producte no apareix a cap byte; existeix només al codi generat. Per això protobuf és compacte i per això reanomenar un camp és gratuït mentre que canviar-ne el número ho trenca tot.
• repeated marca una llista. A proto3 tots els camps són opcionals en el sentit que poden faltar; si falten, se'n llegeix el valor per defecte (0, cadena buida, llista buida, false), i un camp amb valor per defecte no se serialitza (més bytes estalviats).

Més enllà dels escalars: enum (amb el valor 0 obligatori com a primer element i reservat a "desconegut"), missatges imbricats, map<string, int32> (diccionaris), oneof (exactament un de diversos camps, útil per a "resultat o error") i el modificador optional de proto3 (des de la versió 3.15), que permet distingir "camp absent" de "camp amb valor per defecte", cosa que d'altra manera no és possible: sense optional, no hi ha manera de saber si quantitat = 0 vol dir zero o "no m'ho han dit".

Per entendre l'estalvi, aquí hi ha la serialització de LiniaComanda{producte: "formatge-curat", quantitat: 2, preu_centims: 1450}:

21 bytes. El mateix objecte en JSON compacte, {"producte":"formatge-curat","quantitat":2,"preu_centims":1450}, n'ocupa 63. La diferència són els noms de camp, les cometes, els dos punts i els números representats com a text.

Un contracte que no pot canviar no serveix. Quilòmetre Zero desplegarà inventari i comandes de manera independent (era un dels objectius de 01-06), cosa que vol dir que durant un temps conviuran versions diferents del contracte en producció. Dues definicions:

• Compatibilitat cap enrere (backward): el codi nou pot llegir missatges escrits amb l'esquema antic. Necessària quan s'actualitza primer el lector (per exemple, un inventari nou rep peticions d'un comandes vell).
• Compatibilitat cap endavant (forward): el codi antic pot llegir missatges escrits amb l'esquema nou. Necessària quan s'actualitza primer l'escriptor.

A la pràctica calen totes dues, perquè no es controla l'ordre de desplegament de tots els clients (i amb esdeveniments persistits a Kafka, 02-04, es llegiran missatges de fa dies amb l'esquema d'avui). Protobuf les proporciona si se segueixen aquestes regles:

Exemple: a la segona fase, comandes vol afegir l'adreça de lliurament a la comanda i eliminar mercat (que passa a deduir-se de l'adreça):

Un comandes nou envia el camp 6; un repartiment vell l'ignora i continua funcionant (amb mercat buit, que el seu codi ha de tolerar). Un comandes vell envia el camp 5; un repartiment nou el descarta. Cap desplegament no s'ha de coordinar. Aquesta disciplina (números únics i mai reutilitzats, reserved en eliminar, camps nous sempre opcionals amb valor per defecte tolerable) és probablement l'habilitat més valuosa de tota la lliçó, i s'aplicarà igual als esquemes d'esdeveniments a 02-05.

gRPC és el sistema RPC de Google, publicat el 2015, i avui l'estàndard de fet per a la comunicació síncrona entre serveis. Pren les idees de 02-02 (stubs, skeleton, IDL) i les apuntala sobre les dues peces anteriors: Protocol Buffers com a IDL i serialització, i HTTP/2 com a transport. Aquesta segona decisió no és un detall:

• La multiplexació d'HTTP/2 (lliçó 02-01) permet que comandes mantingui un sol canal cap a inventari i hi llanci centenars de crides simultànies sense obrir connexions noves ni esperar respostes en sèrie.
• Els fluxos d'HTTP/2 són bidireccionals i de llarga durada, cosa que fa possible l'streaming.
• Les capçaleres comprimides transporten les metadades (autenticació, traces) amb poc cost.
• En ser HTTP, travessa balancejadors, proxies i malles de serveis (amb suport d'HTTP/2).

Tres conceptes de gRPC que resolen problemes que a 02-02 van quedar a mitges:

• Deadline. En lloc d'un timeout relatiu ("espera 2 s"), gRPC propaga un instant absolut ("aquesta crida caduca a les 10:00:02,000"). La diferència importa quan una crida en provoca d'altres: si comandes té 2 s per respondre a l'Anna i triga 1,5 s a arribar a inventari, inventari sap que només li queden 0,5 s, i pot avortar feina inútil. El servidor consulta context.time_remaining(); el client rep DEADLINE_EXCEEDED. És la solució sistemàtica a "cap crida remota sense límit de temps".
• Codis d'estat. gRPC defineix 17 codis estàndard, amb semàntica compartida per tots els llenguatges. Substitueixen els nostres faultCode inventats:

• Metadades. Parells clau-valor que acompanyen la crida sense formar part del contracte: es transporten com a capçaleres HTTP/2. És on viatgen els tokens d'autenticació (06-01), els identificadors de traça (07-02) i, com veurem, l'identificador de petició per a la idempotència (02-05).

És el moment de substituir el servidor XML-RPC. Instal·lació (al requirements.txt del servei):

Això produeix dos fitxers que no s'editen a mà (es regeneren cada vegada que canvia el .proto, idealment en construir la imatge Docker):

• inventari_pb2.py: les classes de missatge (ReservarEstocRequest, etc.), amb serialització inclosa.
• inventari_pb2_grpc.py: InventariServicer (la classe base que el servidor implementa: l'skeleton) i InventariStub (l'stub del client).

La mateixa ordre, executada a serveis/comandes, genera els mateixos fitxers per al client. Cada servei compila el contracte compartit; ningú no copia codi d'un altre servei.

Comparat amb XML-RPC (02-02), fixa't en el que ha canviat: els errors fan servir codis estàndard amb semàntica coneguda per qualsevol client; el context dona accés al deadline i a la cancel·lació; un mètode d'streaming és simplement un generador de Python; i el servidor és un ThreadPoolExecutor amb una mida explícita (16 fils: quan s'esgotin, les crides esperen, i amb deadline caduquen en lloc d'acumular-se indefinidament).

Sortida:

I amb inventari aturat: Anna: NO - inventari no disponible; comanda en espera (no s'ha executat), en mil·lisegons, gràcies al fet que gRPC distingeix UNAVAILABLE (connexió rebutjada) de DEADLINE_EXCEEDED (silenci). És la taula de quatre famílies d'errors de 02-02, ara estandarditzada. L'id_reserva viatja a cada petició però el servidor encara no el fa servir per filtrar duplicats: això és exactament el que afegirà 02-05.

Un client que vulgui mostrar "en queden poques unitats" (serà cataleg) no hauria de preguntar l'estoc a cada visualització. Amb ObservarCanvis obre un flux i rep cada canvi:

Engega l'observador i després executa el client de comandes: veuràs formatge-curat: 5 -> 3 (reserva) <- EN QUEDEN POCS. Tot viatja per un flux HTTP/2 que es manté obert; cada yield del servidor és una trama en aquest flux. Dos advertiments: aquest flux és una connexió punt a punt, així que si l'observador es reinicia es perd el que ha passat entremig, i si hi ha deu serveis interessats en els canvis, inventari manté deu fluxos. Per difondre esdeveniments a molts consumidors amb persistència, l'eina adequada és la missatgeria de la lliçó següent; l'streaming gRPC brilla en fluxos d'un a un, com la telemetria d'un repartidor concret.

Res no convenç més que els números. Generem el codi de comanda.proto (python -m grpc_tools.protoc -I ../../contractes --python_out=. ../../contractes/comanda.proto) i comparem:

Sortida orientativa (els temps depenen de la màquina i de si protobuf fa servir la seva implementació en C):

Una comanda de tres línies pesa menys de la meitat i es processa unes tres vegades més ràpid. Amb 1.200 comandes per segon (lliçó 01-03) i desenes de crides internes per comanda, la diferència es tradueix en amplada de banda, CPU i latència. I el que no mesura aquest script és igual d'important: el .proto ha validat els tipus en el moment de construir el missatge (preu_centims="14.50" hauria fallat immediatament), mentre que el diccionari accepta qualsevol cosa.

Amb això, inventari és el primer servei real de km0/serveis/. El seu Dockerfile compila el contracte en construir la imatge, i docker-compose.yml guanya un servei:

El monòlit, de moment, continua fent servir el seu propi mòdul inventari intern; l'estrangulament (01-06) consisteix a anar redirigint les seves crides a aquest servei. Aquest canvi no té res d'especial tècnicament (és substituir una crida local per ClientInventari) i no el detallarem; el que sí que té molt d'especial és que ara comandes i inventari tenen dades separades, i aquest és el problema del Mòdul 3.

• Reutilitzar un número de camp. L'error més greu amb protobuf, perquè no produeix cap error: produeix dades corruptes llegides amb total confiança. reserved sempre en eliminar.
• Canviar el tipus d'un camp "perquè és equivalent". int32 → string trenca; int32 → int64 funciona al cable, però un valor gran escrit pel nou es truncarà al vell. En cas de dubte, camp nou amb número nou.
• Diners en float/double. Cèntims en int64, o una cadena decimal si cal precisió arbitrària. Ho repetirem fins al projecte final.
• Confiar que "camp absent" i "valor per defecte" es distingeixen. A proto3 no es distingeixen llevat que es faci servir optional. Si quantitat = 0 pot ser legítim, fes servir optional o valida al servidor.
• Un canal per crida. grpc.insecure_channel obre una connexió HTTP/2 amb el seu handshake; crea'n un per procés (o uns quants) i reutilitza'l. Un canal per crida és HTTP/1.1 sense keep-alive amb més passos.
• Sense deadline. El paràmetre timeout és opcional a l'API i obligatori a la pràctica. Sense ell, la crida espera per sempre, amb tot el que vam aprendre a 01-04.
• Ignorar el codi d'estat i mirar només el text. e.details() és per a persones; e.code() és per a programes. El text pot canviar entre versions del servidor; el codi, no.
• Editar els fitxers _pb2.py generats. Se sobreescriuen a la generació següent. Tot canvi va al .proto.
• Consell: valida la compatibilitat dels .proto a la integració contínua amb una eina com buf breaking: converteix les regles de l'apartat 5 en una comprovació automàtica, i cap canvi incompatible no arriba a producció per descuit.
• Consell: quan dissenyis un missatge, pensa en la versió 3 abans de publicar la 1: deixa els números baixos (1-15, que ocupen un sol byte d'etiqueta) per als camps més freqüents, fes servir noms neutres, i no fiquis en un missatge el que pertany a un altre servei.

L'equip de comandes necessita que una reserva pugui ser temporal (caduca al cap de 15 minuts si no es paga, per alliberar l'últim formatge si l'Anna abandona el cistell) i vol a més eliminar comanda_id de la petició, perquè a partir d'ara viatjarà com a metadada. Escriu la nova versió del missatge respectant les regles de compatibilitat i explica què veurà un servidor inventari antic quan rebi la petició nova, i què veurà un inventari nou quan rebi una petició antiga.

comandes rep de l'app de l'Anna una petició amb un límit total de 3 segons, i per atendre-la crida primer inventari (reservar) i després pagaments (cobrar). Explica per què fer servir timeout=3.0 en totes dues crides gRPC és incorrecte, i escriu una funció temps_restant(deadline_absolut) que calculi el timeout a passar a cada crida. Què hauria de fer comandes si en anar a cridar pagaments queden 50 ms?

Per a cada interacció indica el tipus de crida gRPC (unària, streaming de servidor, de client o bidireccional) o si convé una altra cosa (REST, missatgeria), i el format de serialització:

1. L'app de la Llúcia descarrega la fitxa d'un producte amb la seva foto.
2. comandes demana a inventari l'estoc dels 8 productes d'un cistell.
3. furgoneta-3 envia 1 posició per segon a repartiment durant una ruta de 2 hores, i al final rep el resum de quilòmetres.
4. analitica necessita totes les comandes de la "Setmana de la Verema" per a un informe nocturn.
5. Un operador d'atenció al client i l'app d'un repartidor intercanvien missatges curts en temps real sobre una incidència de lliurament.

Solució 1:

S'elimina comanda_id reservant-ne el número (3) i el nom; el camp nou pren el número 5, mai el 3. Es tria que el valor per defecte (0) signifiqui "comportament anterior", de manera que una petició que no l'enviï es comporti com abans. Un inventari antic que rebi la petició nova veurà comanda_id buit (la cadena per defecte: el seu log de traçabilitat imprimirà comanda : en blanc, tolerable) i ignorarà el camp 5, que no coneix: farà una reserva permanent, cosa que és un comportament degradat però no un error; l'equip ha de saber que la caducitat no funciona fins que inventari es desplegui. Un inventari nou que rebi una petició antiga veurà caduca_en_segons = 0 i farà una reserva permanent, exactament el que aquell client esperava. Cap desplegament no necessita coordinar-se, encara que la funcionalitat completa només existeix quan tots dos estan actualitzats.

Solució 2:

Amb timeout=3.0 a cada crida, el pitjor cas és que inventari trigui 2,9 s (dins del seu límit) i pagaments uns altres 2,9 s: comandes respondria a l'Anna en 5,8 s, gairebé el doble del que s'havia promès, i l'app ja hauria abandonat. El deadline ha de ser un de sol i absolut, calculat en rebre la petició, i cada crida rep el que queda:

Amb 50 ms restants el correcte és no cridar pagaments: una crida que caducarà deixa l'operació més perillosa (un cobrament) en estat "no se sap". Avortar abans és la versió de "fallar ràpid" que gRPC facilita en fer explícit el temps que queda; els servidors gRPC poden a més consultar context.time_remaining() per no començar feina que no podran acabar. Fixa't que es fa servir time.monotonic() (no time.time()): el deadline és una durada, no un instant de rellotge de paret, i els rellotges de paret salten (lliçó 01-05).

Solució 3:

1. REST amb JSON per a les metadades i la foto com a recurs HTTP a part (que la CDN pot desar en memòria cau). És un client extern, navegador o app, i el contingut es beneficia de la memòria cau d'HTTP. gRPC al navegador requereix gRPC-Web i no aporta memòria cau.
2. Unària amb un missatge que porti repeated string productes: una crida, una resposta amb les 8 unitats (gra gruixut, 02-02). Protobuf.
3. Streaming de client: N posicions → 1 resum. Protobuf; cada posició són ~25 bytes. Compte: si la xarxa mòbil és dolenta, un flux HTTP/2 sobre TCP pateix bloqueig de cap de línia (02-01), i MQTT (08-02) pot ser millor opció per al tram mòbil; l'streaming gRPC encaixa entre la passarel·la i repartiment.
4. Cap crida síncrona: és un volum gran i un procés per lots. analitica hauria de consumir els esdeveniments de comanda (02-04) o llegir del magatzem analític (Mòdul 5), no demanar a comandes desenes de milers de registres en una crida (encara que tècnicament un streaming de servidor ho permetria, acoblaria la càrrega analítica al servei transaccional: símptoma 5 de 01-06). Format: Avro o Parquet per a dades massives.
5. Bidireccional: missatges en tots dos sentits, en qualsevol ordre, en temps real. Protobuf. Si un dels extrems és un navegador, l'alternativa pràctica és WebSockets (08-02), que és el mateix conceptualment amb un transport que els navegadors suporten de manera nativa.

Aquesta lliçó ha tancat el cercle obert a 02-02. La serialització decideix com es converteixen les estructures en bytes, i aquesta decisió determina mida, velocitat, seguretat de tipus i capacitat d'evolució: els formats de text (JSON, XML) són llegibles i universals però pesants i sense esquema; els binaris amb esquema (Protocol Buffers, Avro) pesen menys de la meitat, es processen diverses vegades més ràpid i, sobretot, tenen regles d'evolució (números de camp únics i mai reutilitzats, reserved en eliminar, camps nous amb valors per defecte tolerables) que permeten desplegar comandes i inventari de manera independent. Amb contract-first, el .proto és la font de veritat de la qual es genera el codi. gRPC apuntala aquests esquemes sobre HTTP/2 per oferir un canal multiplexat, quatre tipus de crida (unària i tres formes d'streaming), deadlines absoluts que es propaguen, codis d'estat estàndard i metadades. Quilòmetre Zero té ara el seu primer servei extret de debò: inventari a serveis/inventari/servidor.py, amb el seu contracte a contractes/inventari.proto, un client a comandes que tradueix cada codi d'estat a una decisió de negoci, i un flux de canvis d'estoc. La mesura ha confirmat l'estalvi: una comanda de tres línies passa de 276 bytes en JSON a 100 en protobuf.

Però tot el que s'ha fet en aquest mòdul fins aquí és síncron: comandes crida, espera i rep. Al final de 01-06 va quedar clar que això és el correcte per reservar estoc i l'incorrecte per a gairebé tota la resta: avisar analitica d'una venda, planificar el repartiment o actualitzar l'indicador del catàleg no haurien de bloquejar el client ni dependre que el destinatari sigui viu en aquell instant. Per a això cal que algú desi el missatge i el lliuri quan el destinatari pugui: un broker. La lliçó següent, Missatgeria i Cues de Missatges, introdueix RabbitMQ i Apache Kafka, i amb ells el primer flux asíncron de Quilòmetre Zero: l'esdeveniment comanda.creada.