The line protocol: PRICE requests and their answers

A program that another program calls needs an interface that is smaller than either program. This project has one, and it is a line protocol: one request on standard input, one answer on standard output, one line each. There is no framing to get wrong, no length prefix, no state between requests, and the whole interface fits on a page of text.

The same three functions are reached three ways in this set: a Haskell executable that a Python service starts, the same logic in a shared library that Python loads with ctypes, and a test suite that drives the first of those. All three speak the protocol described here, which is why the answers in the pages that follow are the same lines in the same order.

One line in, one line out

A request is a single line of ASCII: the word PRICE, a SKU and a quantity, separated by single spaces. An answer is a single line too: OK with the total and the formatted amount, or ERR with a code and a message for a human. A newline ends both, and nothing else is ever written to standard output.

PRICE <sku> <quantity> OK <total cents> <total formatted> ERR <code> <message>

The constraints are part of the grammar, not a matter of taste: the SKU is one of three words, the quantity is one to three digits and at least 1, and the line has three fields and nothing else. Anything that does not fit is E_SYNTAX, which is the answer that never guesses.

The grammar and the codes

Three SKUs and their unit prices in cents. Cents, not euros, because money that is added as a floating point number is money that is wrong in the last digit on some orders, and a price list is exactly the place where that is not acceptable.

SKU Unit price What it is
tea 250 cents a box of tea
coffee 975 cents a bag of coffee
cake 400 cents a cake

One rule sits on top of the multiplication: an order of 2000 cents or more gets ten percent off. The arithmetic is integer arithmetic on cents, so the rule is exact and testable: gross * 9 `div` 10. A three-coffee order is 2925 cents gross and 2632 cents after the discount, because 2632.5 truncates down.

Three codes, each with one meaning, so that a caller can decide without parsing the message:

The answers, as printed

The core of the next page is a program that reads lines until the input ends. Eight lines, one of each shape, through a pipe:

printf 'PRICE tea 3\nPRICE coffee 3\nPRICE cake 1\nPRICE gold 1\nPRICE tea 0\nPRICE tea 1000\nPRICE tea\nHELLO WORLD\n' | ./core

OK 750 7.50
OK 2632 26.32
OK 400 4.00
ERR E_SKU unknown sku: gold
ERR E_QTY quantity out of range: 0
ERR E_QTY quantity out of range: 1000
ERR E_SYNTAX expected: PRICE <sku> <quantity>
ERR E_SYNTAX expected: PRICE <sku> <quantity>

The three good lines show the two branches of the discount rule: 750 is under 2000 and 2632 is over it, and the third is a single cake. The five failures are two unknown or out-of-range fields and three lines that are not requests at all, and each one is answered rather than dropped, which is what lets a caller log a bad request with the rest.

Why text at the boundary

Text costs something: every answer is formatted, and every request is parsed. A shared library would pass integers and be faster, and this set measures both ways on the timing page. What the text buys is worth the cost in three places.

It is debuggable. A request is a line that a developer can type into a terminal, and an answer is a line that can be pasted into a bug report. The whole protocol of this project fits in the block above, and no tool is needed to read it.

It does not share a type system. A C ABI can pass an int64_t and a pointer, and the two sides have to agree about the buffer, the ownership and the encoding by hand. A line has none of those questions: it is bytes with a newline, and the last page of this set shows what the buffer contract costs when the two sides are a Haskell library and Python.

It versions itself. A new answer shape, a new command word or an extra field at the end of a line is a change a client can survive, because an old client reads the fields it knows. A binary struct is a change that breaks every caller at once.

What is built on it

The next page writes the core: a pure module that turns a line into a line and an executable that loops over standard input. The page after that wraps the executable in an HTTP service, and the third one calls the same function through a shared library.

The Haskell lesson behind the program is standard input and output, and the project hub is A Haskell core in a modern project.

The session above was run with GHC 9.10.3 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev