What a protocol specification must pin down

A protocol is a contract, not a program

Every protocol so far arrived as a finished thing. HTTP was already specified; you read the specification, opened a socket, and obeyed. Assignment 3 turns that around: you define the protocol, and someone else — a marker holding nothing but your document and a telnet client — has to drive your server correctly on the first try. That is the real test of a specification. It is not a description of your program. It is a contract between two programs written by two people who never speak.

A contract like that has to be complete before either half exists, because both halves are written against it in parallel. Anything you leave out, the two halves will fill in differently — and the failure will not be an exception. It will be a hang.

The eight decisions

Every application protocol, from the four-line daytime service to HTTP/2, answers the same eight questions. A specification that answers all eight is implementable; one that misses any is not.

1. Transport and port. TCP or UDP, and which port number. TCP whenever the messages must all arrive, in order — which for a text protocol is always.
2. Framing. Where one message ends and the next begins. There are only three answers in practice: a line terminator, a length declared up front, or a reserved delimiter.
3. Character encoding. The exact bytes-to-characters rule, named: US-ASCII, UTF-8. 'Whatever the JVM does' is not an answer — it means your protocol changes when the marker's machine has a different default locale.
4. Message grammar, per direction. Exactly what the client may send and exactly what the server may send. Not 'a number', but one line containing one or more decimal digits and nothing else.
5. The state set. Every situation the connection can be in, with one initial state and one terminal state.
6. The transition rules. For every (state, event) pair: what the server does, and where it goes next.
7. The error catalogue. The response to every input the grammar forbids, in every state.
8. Who closes, and when. One side must be responsible, and an idle connection needs a stated timeout so the other side cannot pin a thread forever.

The two everyone skips

Framing and the error catalogue — and they fail the same way, the worst way: silence. If the client sends a line the server does not consider terminated, the server blocks in read while the client blocks waiting for a reply. Nothing throws, nothing logs, both sides simply stop. A missing error rule does the same thing one step later: an input you never planned for leaves the handler in a state with no exit.

Worked example — the eight questions, answered for HTTP

You know one protocol well enough to audit it, so audit HTTP/1.1. Transport: TCP, port 80 (443 under TLS). Framing: the request line and the headers are \r\n-terminated and the header section ends with a blank line; the body is framed separately, by Content-Length or by chunked encoding. Encoding: the start line and headers are ASCII; the body declares its own charset in Content-Type. Grammar: METHOD path HTTP/1.1 then Name: value lines from the client, HTTP/1.1 code reason then headers from the server. States: request line → headers → optional body → response, repeated while the connection is kept alive. Transitions: read one request, write one response. Errors: the whole 4xx/5xx catalogue — 400 for a malformed request line, 404 for a missing resource, 501 for a method the server does not implement. Who closes: whoever sends Connection: close, or the server after its keep-alive idle timeout.

Every one of those has an answer, which is exactly why you could hand-write a request in module 5 and get a response back. Your PoD specification has to be that complete — the third column of the figure below is the assignment.