Device: Stream

The stream devices provide access to a standard data stream, a system clipboard, and arbitrary path-addressable remote systems.

The devices specification specifies two similar stream devices. The first stream device is called the local stream device, and the second stream device is called the remote stream device. Each stream device provides access to two bi-directional byte-oriented data streams.

Local bytestreams

Standard bytestream

The first half of the local stream device controls the standard bytestream.

The input channel of the standard bytestream will be connected to a standard input stream from which program-initiated data transmissions can be read. This stream is also known as ‘standard input’, or ‘stdin’.

The output channel of the standard bytestream will be connected to a standard output stream from which program-initiated data transmissions can be written. This stream is also known as ‘standard output’, or ‘stdout’.

If the host system provides a facility for the user to pass an unstructured string of textual arguments to the Bedrock system on launch, the full argument string should be pushed to the input queue of the standard bytestream as a UTF-8 encoded bytestring before the program starts. Such arguments are passed when launching a program from a command-line.

TODO: Encoded transmissions?

User bytestream

The second half of the local stream device controls the user bytestream.

The input channel of the user bytestream will be connected to an input stream from which user-initiated data transmissions can be read. On host systems with access to a system clipboard, a ‘paste’ operation will initiate an incoming transmission on the user bytestream containing the contents of the system clipboard.

The output channel of the user bytestream will be connected to an output stream from which user-initiated data transmissions can be read. On host systems with access to a system clipboard, the contents of an outgoing transmission on the user bytestream will be saved as a new entry on the system clipboard, with the clipboard always being ready to receive a new transmission.

If the system clipboard provided by the host system requires a data type to be associated with a new clipboard entry, a plain text data type will be used. TODO: What will happen if a user attempts to copy non-textual data? More research is required.

If the host system does not have access to a system clipboard, analogous functionality should be implemented within the Bedrock system implementation itself, using shared memory such that the clipboard is accessible by all Bedrock instances running under the same user on the system.

Remote bytestreams

TODO: Addressing, two streams, one for each half of the remote stream device

TODO: Add variant input/output connection port definitions for remote streams

TODO: Come up with better terms than remote-1 and remote-2

TODO: Path buffer

TODO: Paths are implementation defined. Where the host system has access to the internet, allow URLs as per RFC? Try to define URLs myself.

Address format is **implementation defined**. Probably. How bad would it be to define URLs here? I’d only need schemes, then the rest of the URL is implementation defined. Determine whether a scheme is supported by opening just the scheme as an address?

Support for different protocols. HTTP being raw message. Reference RFCs and other specifications. All internet protocols are just application protocols on top of TCP anyway.

Ports

Input connection

Reading a byte from this port will return the value 0xFF if a system is connected to the input channel of the associated bytestream, and will return zero otherwise.

Output connection

Reading a byte from this port will return the value 0xFF if a system is connected to the output channel of the associated bytestream, and will return zero otherwise.

Input transmission

The value of this port is a byte representing the state of a transmission on the input channel of the associated bytestream. A value of 0xFF indicates that this system is prepared to receive data, and that the connected system is permitted to start a new transmission. A value of 0x00 indicates that this system is not prepared to receive data, and that the connected system is not permitted to start a new transmission. All other values are invalid. The initial value of this port is 0x00.

Reading a byte from this port will return the value of this port.

Writing a non-zero byte to this port will set the value of this port to 0xFF, indicating that the connected system is permitted to start a new transmission. If no system is currently connected to the associated input channel, the value of this port will then be set back to 0x00.

When all bytes of an incoming transmission have been transmitted, the value of this port will be set to 0x00 by the connected system.

Any bytes received from the connected system while the value of this port is 0xFF will be pushed to the end of the input queue. If there is no space free in the output queue, the received byte will be discarded. Any bytes received from the connected system while the value of this port is 0x00 will be discarded.

Output transmission

The value of this port is a byte representing the state of a transmission on the output channel of the associated bytestream. A value of 0xFF indicates that the connected system is prepared to receive data, and that this system is permitted to start a new transmission. A value of 0x00 indicates that the connected system is not prepared to receive data, and that this system is not permitted to start a new transmission. All other values are invalid. The initial value of this port is implementation defined.

Reading a byte from this port will return the value of this port.

Writing a byte to this port will set the value of this port to 0x00, indicating that the transmission has ended.

Any bytes sent to the connected system while the value of this port is 0xFF will be pushed to the end of the output queue. If there is no space free in the output queue, the sent byte will be discarded. Any bytes sent to the connected system while the value of this port is 0x00 will be discarded.

Input queue

Reading a byte from this port will return a value representing the number of bytes waiting to be read from the input queue, saturating at bounds on underflow and overflow.

Writing a byte to this port will clear the input queue.

Output queue

Reading a byte from this port will return a value representing the number of bytes of free space available in the output queue, saturating at bounds on underflow and overflow.

Bytestream

This port is associated with two first-in first-out byte queues, an input queue and an output queue. The length of each queue is implementation defined.

Reading a byte from either port of the pair will return the value of the byte at the front of the associated input queue and then will remove that byte from the queue. If the associated input queue is empty, the value returned will be 0x00.

Writing a byte to either port of the pair will push the byte written to the back of the associated output queue. If there is no space free in the output queue, the byte written will be discarded.

System wake

This device will send a wake event to the system device when a byte is received from a connected system, or when an incoming transmission ends, or when a byte is consumed from an output queue by a connected system, or when a new outgoing transmission is permitted, or when a system connects or disconnects from a channel.