# 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 @id any <command @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 @id any <session-running>> .

# Assertion. The driver interprets these as a request to execute TIOCSWINSZ
# with the minima of all concurrently asserted values.
PtyResize = <pty @id any <resize @columns int @rows int>> .

# Assertion. The driver asserts this to report the current size of the tty.
PtySize = <pty @id any <size @columns int @rows int>> .

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

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