From 8bed51d4d1b5960189f651117fd112693bfe1fab Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonyg@leastfixedpoint.com>
Date: Fri, 24 Nov 2023 10:53:48 +0100
Subject: [PATCH] Document and slightly simplify pty.prs

---
 protocols/schema-bundle.bin |  7 ++++---
 protocols/schemas/pty.prs   | 33 ++++++++++++++++++++++++++-------
 src/main.rs                 | 17 +++++++++++------
 3 files changed, 41 insertions(+), 16 deletions(-)

diff --git a/protocols/schema-bundle.bin b/protocols/schema-bundle.bin
index 68a1bd2..1ecedfb 100644
--- a/protocols/schema-bundle.bin
+++ b/protocols/schema-bundle.bin
@@ -1,4 +1,5 @@
-´³bundle·µ³pty„´³schema·³version°

³definitions·³Chunk´³atom³
-ByteString„³PtySize´³rec´³lit³pty-size„´³tupleµ´³named³id³any„´³named³columns´³atom³
SignedInteger„„´³named³rows´³atom³
SignedInteger„„„„„³PtyInput´³rec´³lit³	pty-input„´³tupleµ´³named³id³any„´³named³data´³refµ„³Chunk„„„„„³	PtyOutput´³rec´³lit³
-pty-output„´³tupleµ´³named³id³any„´³named³data´³refµ„³Chunk„„„„„³
+´³bundle·µ³pty„´³schema·³version°

³definitions·³PtySize´³rec´³lit³pty-size„´³tupleµ´³named³id³any„´³named³columns´³atom³
SignedInteger„„´³named³rows´³atom³
SignedInteger„„„„„³PtyInput´³rec´³lit³	pty-input„´³tupleµ´³named³id³any„´³named³data´³atom³
+ByteString„„„„„³	PtyOutput´³rec´³lit³
+pty-output„´³tupleµ´³named³id³any„´³named³data´³atom³
+ByteString„„„„„³
 PtySession´³rec´³lit³pty-session„´³tupleµ´³named³id³any„´³named³commandLine´³refµ„³CommandLine„„„„„³CommandLine´³tuplePrefixµ´³named³command³any„„´³named³args´³seqof³any„„„³PtySessionRunning´³rec´³lit³pty-session-running„´³tupleµ´³named³id³any„„„„„³embeddedType€„„„„
\ No newline at end of file
diff --git a/protocols/schemas/pty.prs b/protocols/schemas/pty.prs
index 85edf8a..d7217ea 100644
--- a/protocols/schemas/pty.prs
+++ b/protocols/schemas/pty.prs
@@ -1,17 +1,36 @@
+# Protocol for interacting with processes attached to pseudoterminals.
+#
+# syndicate-pty-driver publishes a dataspace into its parent and engages in
+# this protocol over that dataspace.
+
 version 1 .
 
+# Assert PtySession with a fresh ID (management of these is out-of-scope;
+# use UUIDs?) to allocate a PTY on the machine the driver is running on,
+# and spawn a subprocess attached to it running CommandLine.
+#
 PtySession = <pty-session @id any @commandLine CommandLine> .
+#
+# A CommandLine is a non-empty sequence of pieces which, "stringified",
+# will form the command line used to create a subprocess. Each element of
+# the CommandLine is "stringified" as follows:
+#
+#  - a String is used as-is (no quotes or escaping)
+#  - a Symbol's associated string is used as-is (no quotes or escaping)
+#  - anything else is formatted to a string using the Preserves text syntax.
+#
 CommandLine = [@command any @args any ...] .
 
+# Asserted by the driver when a PtySession request has resulted in a
+# running and ready session.
+#
 PtySessionRunning = <pty-session-running @id any> .
 
-# Message, driver interprets it as a request to execute TIOCSWINSZ
+# Message. The driver interprets it as a request to execute TIOCSWINSZ.
 PtySize = <pty-size @id any @columns int @rows int> .
 
-# To the subprocess
-PtyInput = <pty-input @id any @data Chunk> .
+# Message. Causes `data` to be delivered by the driver to the subprocess via the pty.
+PtyInput = <pty-input @id any @data bytes> .
 
-# From the subprocess
-PtyOutput = <pty-output @id any @data Chunk> .
-
-Chunk = bytes .
+# Message. `data` was received by the driver from the subprocess via the pty.
+PtyOutput = <pty-output @id any @data bytes> .
diff --git a/src/main.rs b/src/main.rs
index 403f5ea..1745430 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -34,7 +34,7 @@ preserves_schema::define_language!(language(): Language<AnyValue> {
     main: crate::schemas::Language,
 });
 
-use schemas::pty::{PtySession, PtySessionRunning, Chunk, PtyOutput};
+use schemas::pty::{PtySession, PtySessionRunning, PtyOutput};
 
 fn stringify(v: &AnyValue) -> Result<String, ActorError> {
     match v.value() {
@@ -109,10 +109,15 @@ fn pty_session(t: &mut Activation, local_ds: Arc<Cap>, s: PtySession<AnyValue>)
                 terminate_pid(t, &child_pid)
             }));
 
-            on_message!(t, local_ds, language(), <pty-input #(&s.id) $body: Chunk>, |_t| {
-                tracing::trace!(?body, "sending to child");
-                // TODO: use async here
-                parent_w.write_all(&body.0[..])?;
+            on_message!(t, local_ds, language(), <pty-input #(&s.id) $body>, |_t| {
+                match body.value().as_bytestring() {
+                    Some(bytes) => {
+                        tracing::trace!(?bytes, "sending to child");
+                        // TODO: use async here
+                        parent_w.write_all(&bytes[..])?;
+                    }
+                    None => tracing::info!(?body, "received unexpected item as pty-input"),
+                }
                 Ok(())
             });
 
@@ -166,7 +171,7 @@ fn pty_session(t: &mut Activation, local_ds: Arc<Cap>, s: PtySession<AnyValue>)
                         if !facet.activate(&read_account, None, |t| {
                             local_ds.message(t, language(), &PtyOutput {
                                 id: s.id.clone(),
-                                data: Chunk(buf[0..n].to_vec()),
+                                data: buf[0..n].to_vec(),
                             });
                             Ok(())
                         }) {