Eve Protocols
A protocol is an agreement about how two machines talk: who speaks first, what a message looks like, how an error is reported. Eve uses two. HTTP for browsers, REST clients and files; EWP, the Eve Wire Protocol, between Eve machines. Both carry the same data model.
Not designed yet. EWP is an idea from the review of the design (RNW-R04), not a decision. The frame layout below is a starting point for discussion (Q-028).
Two protocols, one data model
| Use | Protocol | Bodies |
|---|---|---|
| browsers, REST clients, HTML pages, files | HTTP/1.1 and HTTP/2 (HTTP/3 later) | JSON, HTML, bytes |
| an Eve client calls an Eve server; server to server data | EWP over TCP and TLS (QUIC later); over WebSocket for browsers | Eve values, batches of a stream |
HTTP
HTTP is the language of the web. In Eve an HTTP service is a driver with routes: each route names an aspect that receives a request and writes a response (see Serving HTTP). A page body is Html (see Templates), a data body is JSON.
Status and errors
A status of 400 or more is an error value: the client script handles it in recover like any other error, with the status in $error.code. A server aspect that raises an error answers 500; expect on a request answers 400.
EWP: the Eve Wire Protocol
EWP is a small binary protocol of frames. One connection carries many calls at the same time.
frame = length (4 bytes) | type (1) | stream id (4) | flags (1) | payload
| Type | Meaning |
|---|---|
HELLO | version, capabilities and authentication |
APPLY | apply an aspect on the remote machine: name, arguments, deadline, idempotency key |
RESULT | the output parameters (@) of the aspect |
ERROR | code, message, line and data of an error |
BATCH | a slice of a stream, with a sequence number |
CREDIT | how many batches the receiver accepts: the network form of the capacity of a channel |
CANCEL, PING, CLOSE | stop a call, check the line, end the connection |
- Back-pressure: a sender sends only as many batches as the receiver granted with
CREDIT, likesendwaits on a full channel (see Channels); - Resume: after a broken connection the client sends the number of the last batch it acknowledged, and the stream goes on from there: this is a checkpoint of a pipeline, on the wire;
- Payload: a self-describing binary form of Eve values, starting from CBOR (RFC 8949), and a column layout for tables so that tools can read them without a conversion.
Data formats
| Format | Used for | Status |
|---|---|---|
| JSON | REST bodies, configuration, records: type Json | planned, level 3 |
| CSV | files of rows with a header: type Csv | planned, level 3 |
| DAT, XML | fixed width data and XML: types Dat, Xml | planned, level 3 |
| HTML | pages, from templates: types Html, Htmlt | planned, 0.6 |
| CBOR and columns | EWP payloads | idea |
Not designed yet. The whole of EWP: the frame, the types, the encoding of values, security, versions. HTTP/3 and WebSocket are later.
TODO: answer Q-028 and write the one example that crosses the line: a client driver applies a remote aspect and receives a stream, with the server written in serve mode.
TODO: describe authentication (tokens as secrets, certificates) and what a server may expose: only aspects that are listed in the project file.
TODO: write the versioning rule: what a server does with a client that speaks a newer or an older EWP.
TODO: add the table of error codes that cross the network (
$err_net, time-out, refused, cancelled) next to the table of Exceptions.Read next: Server