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

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.

RequestAnswerWhy
sku=pen qty=0 unit=1.50err qty must be 1 to 100the quantity is outside the range
sku=pen qty=2 unit=0err unit must be 0.01 to 10000the price is outside the range
sku=pen qty=2err format expected sku= qty= unit=a pair is missing
pen 2 1.50err format expected key=valuea part has no equals sign
sku=pe-n qty=2 unit=1.50err sku must be 1 to 20 letters or digitsthe identifier has a dash

Why a line

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

  1. Add a discount pair to the protocol and decide whether it is a percentage or an amount.
  2. Write the grammar of a batch request that carries several lines at once.
  3. Change the tax to a rate in the request and say what a caller can do with it.
  4. 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.

  1. How many parts does a request line have?

    Answer

    Three key=value pairs

    sku, qty and unit, in any order.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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

Banner image