Document and slightly simplify pty.prs

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€„„„„

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> .

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(())
                         }) {