Rust · Chapter 25 of 26

A TCP service

By the end of this chapter you can write a network service with tokio: listen on a port, give every connection its own task, read and answer one line at a time, speak a protocol of JSON lines with serde, answer a bad line with an error without hanging up, and share state between connections. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Concurrency and services
  • 4 tasks
  • Rust
  • In the all labs plan

The first 2 chapters of Rust are free. This one comes with the all labs plan.

Why you need this

Every box has, until now, sent its shift once, at the end. Ishita wants more: each box keeps one connection open to the plant's service all day, sends every can the moment it is weighed, and can ask for a rate or a society's summary at any time. At 6 am all 120 boxes connect, and the service must answer each of them in milliseconds, while every other box is connected too. A box on a village network sometimes sends half a line, or garbage after a power flicker: the service must say so and keep the connection, because Lakhan cannot drive to the village to reconnect a box.

You have every piece but the network. Chapter 18 turned values into JSON and back; chapter 22 shared state between threads; chapters 23 and 24 ran many tasks on a few threads. A Rust program that only calls functions cannot be reached by a box in Napad. This chapter puts a TCP listener in front of them: the plant's service as a real server.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    rates.rs: a server that answers rate requests

    Write the async function serve_rates(listener: TcpListener). It accepts every connection on the listener it is given, for ever, and starts a task for each one, so that many boxes can be connected at once. A box sends one JSON request a line and gets one JSON reply a line, ending with a line break:

    {"type":"rate","kind":"cow","fat":41,"snf":86} gets {"type":"rate","kind":"cow","per_litre":3032}

    per_litre is fat * fat_paise + snf * snf_paise from doodh::rate(kind), or 0 when fat or snf is below that chart's minimum. Any other line (not JSON, a kind that is not cow or buffalo, a missing field) gets {"type":"error","message":"..."} with a message saying what was wrong, and the connection stays open for the next line.

    The Check connects two boxes at once. On the first it asks cow 41 and 86 (3032), buffalo 64 and 91 (4016) and buffalo 45 and 90 (0, below the minimum fat), then sends hello, a goat and a cow with no fat or snf (three errors), then cow 40 and 85 (2980). On the second it asks cow 35 and 82 (2760). The order of the fields in a reply does not matter.

  2. Task 2

    ledger.rs: pourings from many boxes, one set of totals

    Write the async function serve_pours(listener: TcpListener, totals: Totals), where Totals is Arc<Mutex<HashMap<String, Total>>> and Total has pourings: u32, ml: u64 and paise: u64 (both given in ledger.rs). Like serve_rates, it runs a task for each connection, one JSON line in and one out. Every connection pours into the same totals, the ones it is given, keyed by society id:

    {"type":"pour","society":"S014","kind":"cow","ml":5150,"fat":42,"snf":86} gets {"type":"poured","society":"S014","paise":15780,"total":15780}

    paise is what the can earns, (ml * per_litre + 500) / 1000, with per_litre as in Task 1 (0 below a minimum). total is the society's paise so far, after this can. The can adds 1 to the society's pourings, its ml to ml and its paise to paise. A society that does not exist and any bad line get {"type":"error","message":"..."} and change nothing.

    The Check pours S002's and S005's mornings from two connections at the same time, then S002's evening from the second connection: every reply's paise and total must match Tuesday's data, and the totals must then say S002 64 pourings and 2080241 paise, S005 33 pourings, with their ml, and have no other entry (it also sends a cut-off line and a pouring for S999, both errors).

  3. Task 3

    service.rs: the whole service, with a summary

    Write the async function serve(listener: TcpListener, totals: Totals), the plant's service: a task for each connection, one JSON line in and one out, with three kinds of request. rate is answered as in Task 1, pour as in Task 2 (into the totals it is given), and summary is new:

    {"type":"summary","society":"S001"} gets {"type":"summary","society":"S001","pourings":406,"ml":3532350,"paise":12415897} after all of S001's Tuesday.

    A society with no pourings yet gets 0 for pourings, ml and paise. A society that does not exist, a request of another type and any line that is not JSON get {"type":"error","message":"..."}.

    The Check pours S001's morning from one connection and its evening from another, every reply checked as in Task 2, then from a third connection asks for S001's summary (above), S002's (all 0), S999's, a line summary S001 and a request of type refund (three errors), and a buffalo rate at 64 and 91 (4016). You may call your functions from rates.rs and ledger.rs.

  4. Task 4 · interview question

    Interview: greet.rs, one box at a time

    When a box connects it says hello and its box id, and Lakhan's serve_greetings(listener: TcpListener) greets it with its society's name, one line in, one line out:

    hello B2002 gets welcome B2002, Boriavi Milk Society

    hello B9999 gets unknown box B9999

    namaste gets say hello and your box id

    It answers the first box. But while that box stays connected, the next box says hello and waits: it is answered only when the first box hangs up. At 6 am all 120 boxes connect and stay connected all day.

    Fix it so every box is answered at once, whoever else is connected. The Check keeps Boriavi's box connected while Napad's says hello B2014 (welcome B2014, Napad Milk Society, within 1 second), then connects all 120 boxes at once and every one must get its welcome within 3 seconds.

    Farhan will ask: why a task for each connection, and not a thread?

What you will learn

  • TcpListener and TcpStream: listen on an address, accept a connection, talk over it.
  • A task per connection: so every box is answered, whoever else is connected.
  • BufReader and lines: read a connection one line at a time (AsyncBufReadExt), and write_all to answer (AsyncWriteExt).
  • JSON lines: one serde message a line, one reply a line, and an error reply for a bad line.
  • Shared state between connections: Arc<Mutex<..>>, and why a guard must not be held across an .await.

More in Concurrency and services

Build "A TCP service" yourself

DoodhSetu runs the milk collection boxes of 120 village societies around Anand. The old box program crashed on an empty line, and you rebuild it in Rust. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Rust are free. This one comes with the all labs plan.