The line protocol: a request and an answer
A protocol is the contract between the core and whatever calls it. This one is deliberately small: one line of text in, one line of text out, no JSON and no headers. The reason is not laziness. A line protocol is the cheapest thing to call from a shell, from a test and from a process that reads standard input, and every language can produce it without a library.
The request
Three pairs, space separated, in any order:
request := "sku=" name SP "qty=" integer SP "unit=" amount
answer := "ok" SP amount SP amount SP amount
| "err" SP message
name := 1..20 of [A-Za-z0-9]
integer := 1..100
amount := 0.01..10000, two decimals
sku=pen qty=2 unit=1.50
ok 3.00 0.60 3.60
err qty must be 1 to 100
- sku is one to twenty characters, letters and digits only. It is the identifier the caller uses, and the core does not know what it means.
- qty is an integer from 1 to 100. A quantity of zero is not a free order, it is a mistake.
- unit is a decimal from 0.01 to 10000, written with a point. The core reads it with the invariant culture, so a comma is an error on every machine.
The answer
An accepted request answers with ok and three amounts: the subtotal, the tax at twenty percent and the total, each with two decimals and each rounded to the cent before the next step. The four requests below were run against the built program, and the answer of each is the line under it:
dotnet src/Cli/bin/Release/net10.0/Cli.dll "sku=pen qty=2 unit=1.50"
dotnet src/Cli/bin/Release/net10.0/Cli.dll "sku=paper qty=10 unit=0.25"
dotnet src/Cli/bin/Release/net10.0/Cli.dll "sku=pen qty=0 unit=1.50"
dotnet src/Cli/bin/Release/net10.0/Cli.dll "pen 2 1.50"
ok 3.00 0.60 3.60
ok 2.50 0.50 3.00
err qty must be 1 to 100
err format expected key=value
The errors
A rejected request answers with err and a message that names the field and the rule. The message is part of the protocol: a caller can show it to a person and a test can compare it.
| Request | Answer | Why |
|---|---|---|
| sku=pen qty=0 unit=1.50 | err qty must be 1 to 100 | the quantity is outside the range |
| sku=pen qty=2 unit=0 | err unit must be 0.01 to 10000 | the price is outside the range |
| sku=pen qty=2 | err format expected sku= qty= unit= | a pair is missing |
| pen 2 1.50 | err format expected key=value | a part has no equals sign |
| sku=pe-n qty=2 unit=1.50 | err sku must be 1 to 20 letters or digits | the identifier has a dash |
Why a line
- One line is one unit of work, which makes the three calling ways of this group comparable: a process that takes an argument, a process that reads a line, and an HTTP body are all the same request.
- A line is readable in a log and in a test. The test table of the C# page is a list of requests and answers, which is the smallest test that covers a parser.
- The cost is a strict format: no field may contain a space, and an escape would be a protocol of its own. A real system with free text would use JSON or a length-prefixed frame, and the core would keep the same validator.
- Amounts are decimal in the core and formatted with the invariant culture, so a caller in any locale gets the same three numbers. A protocol that let the locale decide would be a bug that appears only on some machines.
The next page is the core itself: the parser, the validator and the pricing function, with the project file that makes it a class library.
Exercises
- Add a discount pair to the protocol and decide whether it is a percentage or an amount.
- Write the grammar of a batch request that carries several lines at once.
- Change the tax to a rate in the request and say what a caller can do with it.
- Explain why the answer of an error is still one line and not a stack trace.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
How many parts does a request line have?
Answer
Three key=value pairs
sku, qty and unit, in any order.
-
What does an accepted request answer?
Answer
ok and three amounts: subtotal, tax and total
The measured line is ok 3.00 0.60 3.60.
-
What does this program print?
Console.WriteLine("ok 3.00 0.60 3.60");Answer
ok 3.00 0.60 3.60
Two units at 1.50 is the measured answer.
-
What does the core answer for a quantity of zero?
Answer
err qty must be 1 to 100
The measured answer for that request is the error line.
-
What does this program print?
Console.WriteLine("err format expected key=value");Answer
err format expected key=value
A part without an equals sign is the format error.
-
Why is the unit price read with the invariant culture?
Answer
So a comma is an error on every machine and the answer is the same
The page names the locale bug the rule prevents.
-
What does this program print?
Console.WriteLine("ok 2.50 0.50 3.00");Answer
ok 2.50 0.50 3.00
Ten at 0.25 is 2.50 and the tax is 0.50.
-
Why is a line protocol a good fit for three different callers?
Answer
A command argument, a stdin line and an HTTP body are all one line
The group compares exactly those three callers.
-
What does this program print?
var line = "sku=pen qty=2 unit=1.50"; Console.WriteLine(line.Split(' ').Length == 3);Answer
True
The parsed line is a valid request, so the check is true.
-
What is the cost of the format?
Answer
No field may contain a space, and free text needs another framing
The page says a real system with free text would use JSON or a frame.
The C# code on this page was built with the .NET SDK 10.0.303 and the Python code was run with Python 3.14.10, on Alpine Linux 3.24.3 (x86_64, four processors) in a Docker container.
Article author: Arthur Isaev