# 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.
#
# When PtySession is retracted, the driver will terminate the subprocess
# (via SIGHUP first, SIGTERM if that doesn't work, and ultimately SIGKILL)
# and close the associated PTY.
#
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. The driver interprets it as a request to execute TIOCSWINSZ.
PtySize = <pty-size @id any @columns int @rows int> .

# Message. Causes `data` to be delivered by the driver to the subprocess via the pty.
PtyInput = <pty-input @id any @data bytes> .

# Message. `data` was received by the driver from the subprocess via the pty.
PtyOutput = <pty-output @id any @data bytes> .