From 0922e661110a8a896f281c72eae3f78084297fdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C5=8Dshin?= Date: Thu, 1 Apr 2021 04:01:04 +0000 Subject: [PATCH] khan: thinking intensifies --- pkg/urbit/vere/io/khan.c | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/pkg/urbit/vere/io/khan.c b/pkg/urbit/vere/io/khan.c index aba5f4bf2..f19e4fee8 100644 --- a/pkg/urbit/vere/io/khan.c +++ b/pkg/urbit/vere/io/khan.c @@ -94,13 +94,36 @@ _khan_conn_cb(uv_stream_t* sem_u, c3_i tas_i) // 3. peek, arvo // 4. poke, arvo // - // For 1, we support a few simple text commands: - // ok - says "ok" (basic health test) - // dump - dumps runtime stat counters in simple machine/human-readable format + // For 1, the driver itself parses and responds to a few basic text-mode + // commands: + // `ok`: driver responds with "ok\n" (basic health test) + // `dump`: dumps runtime stat counters in simple machine/human-readable format // // There is not yet a use case for 2. // - // For 3 and 4, we speak the language documented in the khan vane in arvo. + // For 3 and 4, we speak a binary protocol using jammed nouns, as (to be) + // documented in pkg/arvo/sys/vane/khan.hoon. + // + // The transition to arvo is signalled by a 0x80 (i.e. byte with MSB high) at + // the start of a line (i.e. as first character, or immediately following a + // '\n'.) Everything after that is simply forwarded to arvo, and responses + // forwarded back, for the rest of the duration of the connection. + // + // Some alternate protocol designs: + // + // a. Forward everything to arvo. + // b. Add a command that sends a single-shot jammed noun, which receives a + // single-shot response. + // c. Listen on two or more different sockets. + // + // (a) is undesirable since we don't want to sync the runtime stats with + // arvo. Continuous sync would add unnecessary load, and on-demand sync would + // add unnecessary implementation complexity in the form of extra round-trips + // between arvo and the runtime. (b) is probably fine, but I'm not smart + // enough to know how to tell from the runtime when a jammed noun has + // finished sending without base64-encoding it or something. (c) is tedious; + // the same effect can be achieved by just opening two connections to the + // socket, keeping one in text mode, and sending a 0x80 over the other. } /* u3_khan(): initialize control plane socket.