The previous lesson left inventory running as an XML-RPC service, and left its three weaknesses in plain sight: 230 bytes of XML to transmit two arguments, an implicit contract that breaks silently when a signature changes, and no mechanism for the server to send a stream of data to the client. All three come down to the same underlying question: how are data structures turned into bytes, and how does that format evolve without breaking anyone? That is the question of serialization, and a good part of the performance, interoperability and maintainability of a distributed platform depends on its answer.

In this lesson we will compare text formats (JSON, XML) and binary formats (Protocol Buffers, Avro, MessagePack), learn how to write Protocol Buffers schemas and the rules that allow them to change without breaking old clients, and build the definitive version of Kilometre Zero's orders → inventory interface with gRPC: a contract in inventory.proto, a server in services/inventory/server.py, a client with a deadline in orders, and a server stream for watching stock changes. We will finish by measuring in code how many bytes protobuf saves compared with JSON for the same order. Asynchronous messaging (queues, Kafka) is the subject of the next lesson: here everything is synchronous.

1. Serialization: from in-memory structures to bytes
2. Text formats versus binary formats
3. Contract-first: the schema as the source of truth
4. Protocol Buffers: syntax, types and numbered fields
5. Schema evolution: forward and backward compatibility
6. gRPC: RPC over HTTP/2
7. inventory in gRPC: contract, server and client with a deadline
8. Server streaming: watching stock changes
9. Measuring: JSON versus protobuf for the same order
10. Common mistakes and tips
11. Exercises
12. Conclusion

In lesson 02-02 we called it marshalling; the general term is serialization: transforming an in-memory object (a Python dictionary, an instance of a Java class) into a sequence of bytes that can be written to the network or to disk, and deserialization, the reverse process. Everything that crosses a process boundary goes through it: RPC arguments, events on a queue, rows in a database, files in an object store.

A serialization format has to decide four things:

1. How it represents types: is an integer text ("120") or binary (4 bytes)? Does it distinguish between integers and decimals? Does it have dates, or are they strings that follow a convention?
2. How it names fields: does each message carry the name ("product": "aged-cheese"), or a number (1: "aged-cheese"), or nothing at all (fixed position)?
3. Where the schema lives: in the message itself (self-describing), in an external file that both ends share, or in the programmers' heads?
4. How it evolves: what happens when the sender adds a field the receiver does not know about, or the other way round?

The answers to these questions split the formats into two big families.

A few observations that the table does not capture:

• JSON does not distinguish integers from decimals, nor does it have a type for money: 14.50 is a double-precision float, and we already saw in 01-06 that storing the price as a float is a mistake (fallacy 8, plus rounding errors). The usual conventions (sending cents as an integer, or the amount as a string "14.50") are just that, conventions, which have to be documented and which any client can fail to follow.
• The cost of JSON is not just size, it is parsing: turning "120" into the integer 120 means interpreting characters; reading 4 bytes as an integer is a single instruction. In a service that serializes thousands of messages per second, the CPU spent on JSON is measurable.
• Schemaless binary formats (MessagePack) save very little: they still send the field names in every message. The big saving comes from replacing names with numbers, and that requires a shared schema.
• Avro and Protocol Buffers solve the same problem with different philosophies: protobuf compiles the schema into code and numbers the fields; Avro does not necessarily generate code and resolves the differences between the schema a piece of data was written with and the schema it is read with. Avro fits particularly well with Kafka and with large-scale data files (Module 5); protobuf, with RPC.

There are two ways to arrive at a contract between orders and inventory:

• Code-first: you write the implementation (the XML-RPC Inventory class, the RMI Java interface) and the contract is whatever can be deduced from it. Fast at first; the contract ends up coupled to one language and changes without anyone reviewing it.
• Contract-first: you write the contract first in a neutral language (the IDL from 02-02), review it as you would review a public API, version it in the repository, and generate the client and server code in each language from it.

With contract-first, the .proto file is the single source of truth: if the orders team wants to know what ReserveStock returns, they read it there, not in inventory's Python code. Changes to the contract go through code review, they can be validated automatically against the compatibility rules (section 5), and code generation guarantees that no client can call a method with the wrong types: the TypeError from exercise 3 of the previous lesson becomes a compile-time error. At Kilometre Zero, the contracts will live in km0/contracts/ and each service will generate its code from there.

Protocol Buffers (protobuf) is Google's IDL and serialization format, and the one gRPC uses by default. A .proto file defines messages (data structures) and, optionally, services (sets of RPCs). Let's start with a simple message, the Kilometre Zero order:

Each element has a role:

• syntax = "proto3" sets the language version. proto3 is the current one and the one we will use.
• package prevents name clashes between contracts and appears in the fully qualified type names (km0.orders.v1.Order). The v1 suffix is a convention for versioning whole contracts, which is different from the field-by-field evolution of section 5.
• Each field has a type, a name and a number. The number is what matters: it is what travels over the network, not the name. When product = "aged-cheese" is serialized, what gets written is "field 1, string type, length 11, bytes". The name product does not appear in a single byte; it exists only in the generated code. That is why protobuf is compact, and why renaming a field is free while changing its number breaks everything.
• repeated marks a list. In proto3 all fields are optional in the sense that they may be missing; if they are, their default value is read (0, empty string, empty list, false), and a field holding its default value is not serialized (more bytes saved).

Beyond the scalars: enum (with the value 0 mandatory as the first element and reserved for "unknown"), nested messages, map<string, int32> (dictionaries), oneof (exactly one of several fields, useful for "result or error") and proto3's optional modifier (since version 3.15), which makes it possible to distinguish "field absent" from "field set to its default value", something that is otherwise impossible: without optional, there is no way of knowing whether quantity = 0 means zero or "nobody told me".

To understand the saving, here is the serialization of OrderLine{product: "aged-cheese", quantity: 2, price_cents: 1450}:

18 bytes. The same object in compact JSON, {"product":"aged-cheese","quantity":2,"price_cents":1450}, takes 57. The difference is the field names, the quotes, the colons and the numbers represented as text.

A contract that cannot change is useless. Kilometre Zero will deploy inventory and orders independently (it was one of the goals of 01-06), which means that for a while, different versions of the contract will coexist in production. Two definitions:

• Backward compatibility: new code can read messages written with the old schema. Needed when the reader is upgraded first (for example, a new inventory receives requests from an old orders).
• Forward compatibility: old code can read messages written with the new schema. Needed when the writer is upgraded first.

In practice you need both, because you do not control the deployment order of every client (and with events persisted in Kafka, 02-04, messages from days ago will be read with today's schema). Protobuf provides them as long as you follow these rules:

Example: in the second phase, orders wants to add the delivery address to the order and remove market (which will now be derived from the address):

A new orders sends field 6; an old delivery ignores it and carries on working (with market empty, which its code must tolerate). An old orders sends field 5; a new delivery discards it. No deployment needs to be coordinated. This discipline (unique numbers that are never reused, reserved when removing, new fields always optional with a tolerable default value) is probably the most valuable skill in the whole lesson, and it will apply in just the same way to the event schemas in 02-05.

gRPC is Google's RPC system, released in 2015, and today the de facto standard for synchronous communication between services. It takes the ideas from 02-02 (stubs, skeleton, IDL) and builds them on the two pieces above: Protocol Buffers as the IDL and serialization format, and HTTP/2 as the transport. That second decision is not a minor detail:

• HTTP/2 multiplexing (lesson 02-01) lets orders keep a single channel open to inventory and fire hundreds of simultaneous calls through it without opening new connections or waiting for responses one after another.
• HTTP/2 streams are bidirectional and long-lived, which makes streaming possible.
• Compressed headers carry metadata (authentication, traces) at little cost.
• Being HTTP, it gets through load balancers, proxies and service meshes (as long as they support HTTP/2).

Three gRPC concepts that solve problems left half-finished in 02-02:

• Deadline. Instead of a relative timeout ("wait 2 s"), gRPC propagates an absolute point in time ("this call expires at 10:00:02.000"). The difference matters when one call triggers others: if orders has 2 s to answer Anna and takes 1.5 s to get to inventory, inventory knows it only has 0.5 s left and can abort pointless work. The server checks context.time_remaining(); the client receives DEADLINE_EXCEEDED. It is the systematic solution to "no remote call without a time limit".
• Status codes. gRPC defines 17 standard codes, with semantics shared across all languages. They replace our made-up faultCodes:

• Metadata. Key-value pairs that accompany the call without being part of the contract: they are carried as HTTP/2 headers. This is where authentication tokens (06-01), trace identifiers (07-02) and, as we will see, the request identifier for idempotency (02-05) travel.

It is time to replace the XML-RPC server. Installation (in the service's requirements.txt):

This produces two files that are never edited by hand (they are regenerated every time the .proto changes, ideally when the Docker image is built):

• inventory_pb2.py: the message classes (ReserveStockRequest, etc.), serialization included.
• inventory_pb2_grpc.py: InventoryServicer (the base class the server implements: the skeleton) and InventoryStub (the client stub).

The same command, run in services/orders, generates the same files for the client. Each service compiles the shared contract; nobody copies code from another service.

Compared with XML-RPC (02-02), notice what has changed: errors use standard codes with semantics known to any client; the context gives access to the deadline and to cancellation; a streaming method is simply a Python generator; and the server is a ThreadPoolExecutor with an explicit size (16 threads: when they run out, calls wait, and with a deadline they expire instead of piling up indefinitely).

Output:

And with inventory stopped: Anna: NO - inventory unavailable; order on hold (not executed), within milliseconds, thanks to gRPC distinguishing UNAVAILABLE (connection refused) from DEADLINE_EXCEEDED (silence). It is the table of four error families from 02-02, now standardised. The reservation_id travels in every request but the server does not yet use it to filter out duplicates: that is exactly what 02-05 will add.

A client that wants to show "only a few left" (it will be catalog) should not have to ask for the stock every time a product is displayed. With WatchChanges it opens a stream and receives every change:

Start the watcher and then run the orders client: you will see aged-cheese: 5 -> 3 (reservation) <- ONLY A FEW LEFT. Everything travels over one HTTP/2 stream that stays open; each yield on the server is a frame on that stream. Two warnings: this stream is a point-to-point connection, so if the watcher restarts, whatever happened in the meantime is lost, and if ten services are interested in the changes, inventory maintains ten streams. For broadcasting events to many consumers with persistence, the right tool is the messaging of the next lesson; gRPC streaming shines in one-to-one flows, such as the telemetry of one particular courier.

Nothing is more convincing than numbers. We generate the code for order.proto (python -m grpc_tools.protoc -I ../../contracts --python_out=. ../../contracts/order.proto) and compare:

Indicative output (the timings depend on the machine and on whether protobuf is using its C implementation):

A three-line order weighs less than half as much and is processed about three times faster. At 1,200 orders per second (lesson 01-03) and dozens of internal calls per order, the difference translates into bandwidth, CPU and latency. And what this script does not measure is just as important: the .proto validated the types when the message was built (price_cents="14.50" would have failed immediately), whereas the dictionary accepts anything.

With this, inventory is the first real service in km0/services/. Its Dockerfile compiles the contract when the image is built, and docker-compose.yml gains a service:

The monolith, for now, keeps using its own internal inventory module; the strangler fig approach (01-06) consists of gradually redirecting its calls to this service. There is nothing technically special about that change (it means replacing a local call with InventoryClient) and we will not go into it; what is very special is that orders and inventory now have separate data, and that is the problem of Module 3.

• Reusing a field number. The most serious mistake with protobuf, because it produces no error at all: it produces corrupt data that is read with complete confidence. Always use reserved when removing a field.
• Changing the type of a field "because it's equivalent". int32 → string breaks; int32 → int64 works on the wire, but a large value written by the new side will be truncated on the old one. When in doubt, a new field with a new number.
• Money in float/double. Cents in an int64, or a decimal string if arbitrary precision is needed. We will keep repeating it right up to the final project.
• Trusting that "field absent" and "default value" can be told apart. In proto3 they cannot, except with optional. If quantity = 0 can be legitimate, use optional or validate on the server.
• One channel per call. grpc.insecure_channel opens an HTTP/2 connection with its handshake; create one per process (or a handful) and reuse it. One channel per call is HTTP/1.1 without keep-alive, with extra steps.
• No deadline. The timeout parameter is optional in the API and mandatory in practice. Without it, the call waits for ever, with everything we learnt in 01-04.
• Ignoring the status code and looking only at the text. e.details() is for people; e.code() is for programs. The text may change between server versions; the code does not.
• Editing the generated _pb2.py files. They are overwritten the next time the code is generated. Every change goes in the .proto.
• Tip: validate the compatibility of your .proto files in continuous integration with a tool such as buf breaking: it turns the rules of section 5 into an automatic check, and no incompatible change reaches production by oversight.
• Tip: when you design a message, think about version 3 before publishing version 1: keep the low numbers (1-15, which take a single tag byte) for the most frequent fields, use neutral names, and do not put into a message anything that belongs to another service.

The orders team needs a reservation to be able to be temporary (it expires after 15 minutes if it is not paid for, so as to release the last cheese if Anna abandons her basket) and also wants to remove order_id from the request, because from now on it will travel as metadata. Write the new version of the message respecting the compatibility rules, and explain what an old inventory server will see when it receives the new request, and what a new inventory will see when it receives an old request.

orders receives a request from Anna's app with an overall limit of 3 seconds, and to serve it, it first calls inventory (to reserve) and then payments (to charge). Explain why using timeout=3.0 in both gRPC calls is wrong, and write a function time_remaining(absolute_deadline) that computes the timeout to pass to each call. What should orders do if there are 50 ms left when it is about to call payments?

For each interaction, give the kind of gRPC call (unary, server streaming, client streaming or bidirectional) or say whether something else is a better fit (REST, messaging), and give the serialization format:

1. Lucy's app downloads a product page with its photo.
2. orders asks inventory for the stock of the 8 products in a basket.
3. van-3 sends 1 position per second to delivery during a 2-hour route, and at the end receives a summary of the kilometres driven.
4. analytics needs all the orders from "Grape Harvest Week" for an overnight report.
5. A customer support operator and a courier's app exchange short messages in real time about a delivery incident.

Solution 1:

order_id is removed by reserving its number (3) and its name; the new field takes number 5, never 3. We choose for the default value (0) to mean "previous behaviour", so that a request that does not send it behaves as before. An old inventory that receives the new request will see an empty order_id (the default string: its traceability log will print a blank order :, which is tolerable) and will ignore field 5, which it does not know: it will make a permanent reservation, which is degraded behaviour but not an error; the team must be aware that expiry does not work until inventory is deployed. A new inventory that receives an old request will see expires_in_seconds = 0 and make a permanent reservation, exactly what that client expected. No deployment needs to be coordinated, although the full functionality only exists once both are up to date.

Solution 2:

With timeout=3.0 on each call, the worst case is that inventory takes 2.9 s (within its limit) and payments another 2.9 s: orders would answer Anna in 5.8 s, almost twice what was promised, and the app would already have given up. The deadline must be a single, absolute one, computed when the request is received, and each call gets whatever is left:

With 50 ms remaining, the right thing to do is not to call payments: a call that is going to expire leaves the most dangerous operation (a charge) in the "nobody knows" state. Aborting beforehand is the version of "fail fast" that gRPC makes easy by making the remaining time explicit; gRPC servers can also check context.time_remaining() so as not to start work they will not be able to finish. Note the use of time.monotonic() (not time.time()): the deadline is a duration, not a wall-clock instant, and wall clocks jump (lesson 01-05).

Solution 3:

1. REST with JSON for the metadata and the photo as a separate HTTP resource (cacheable by a CDN). It is an external client, browser or app, and the content benefits from HTTP caching. gRPC in the browser requires gRPC-Web and brings no caching.
2. Unary, with a message carrying repeated string products: one call, one response with the 8 unit counts (coarse-grained, 02-02). Protobuf.
3. Client streaming: N positions → 1 summary. Protobuf; each position is ~25 bytes. Beware: if the mobile network is poor, an HTTP/2 stream over TCP suffers from head-of-line blocking (02-01), and MQTT (08-02) may be a better option for the mobile leg; gRPC streaming fits between the gateway and delivery.
4. No synchronous call at all: it is a large volume and a batch process. analytics should consume the order events (02-04) or read from the analytical store (Module 5), not ask orders for tens of thousands of records in one call (although technically server streaming would allow it, it would couple the analytical load to the transactional service: symptom 5 from 01-06). Format: Avro or Parquet for bulk data.
5. Bidirectional: messages in both directions, in any order, in real time. Protobuf. If one of the ends is a browser, the practical alternative is WebSockets (08-02), which is conceptually the same thing with a transport that browsers support natively.

This lesson has closed the circle opened in 02-02. Serialization decides how structures are turned into bytes, and that decision determines size, speed, type safety and the ability to evolve: text formats (JSON, XML) are readable and universal but heavy and schemaless; binary formats with a schema (Protocol Buffers, Avro) weigh less than half as much, are processed several times faster and, above all, have evolution rules (unique field numbers that are never reused, reserved when removing, new fields with tolerable default values) that make it possible to deploy orders and inventory independently. With contract-first, the .proto is the source of truth from which the code is generated. gRPC builds those schemas on top of HTTP/2 to offer a multiplexed channel, four kinds of call (unary and three forms of streaming), absolute deadlines that propagate, standard status codes and metadata. Kilometre Zero now has its first genuinely extracted service: inventory in services/inventory/server.py, with its contract in contracts/inventory.proto, a client in orders that translates each status code into a business decision, and a stream of stock changes. The measurement has confirmed the saving: a three-line order goes from 270 bytes in JSON to 97 in protobuf.

But everything done in this module so far is synchronous: orders calls, waits and receives. By the end of 01-06 it was clear that this is the right thing for reserving stock and the wrong thing for almost everything else: notifying analytics of a sale, planning the delivery or updating the catalogue indicator should not block the customer or depend on the recipient being alive at that very moment. For that, someone needs to store the message and deliver it when the recipient is able to take it: a broker. The next lesson, Messaging and Message Queues, introduces RabbitMQ and Apache Kafka, and with them Kilometre Zero's first asynchronous flow: the order.created event.