IvoryScript applications

Contents

1 iss (Ivory System Session)

The application iss provides a command-line interface for executing scripts within the Ivory System. It reads a sequence of one or more scripts from standard input and processes them. Each script is expected to be terminated by a newline unless the last character of a line is a backslash (\). In such a case, the script continues onto the next line, allowing multi-line scripts to be submitted.

Scripts are executed sequentially, with the output being written to standard output, preserving the same newline termination conventions.

A special syntax is provided for reading scripts from a file:

:file "<filename>"

This syntax allows a script to be submitted from a specified file, where <filename> is the path to the file containing the script. This command does not conflict with valid IvoryScript syntax, as there is no prefix form for the : operator in IvoryScript.

Summary of features:

  • Reads and executes scripts from standard input.

  • Supports multi-line scripts via the backslash (\) character at the end of a line.

  • Outputs results to standard output, respecting line ending conventions.

  • Supports reading and executing scripts from a file using the special syntax :file "<filename>".

2 isss (Ivory System Socket Server)

The isss application is a long-running server intended to act as a proxy between client sockets and multiple worker processes running iss. It is designed for environments where multiple clients need to interact with multiple Ivory System sessions in parallel, allowing for communication between clients and iss processes.

Protocol overview:

The isss server uses a simple text protocol for managing sessions and handling script execution. Below is a summary of the key commands used in this protocol:

  • START SESSION: Initiates a new session and returns a session ID to the client.

    Response: SESSION: <session id>

  • SESSION: <session id>: Selects a session by its ID for further interaction.

    Response: ACK (acknowledgment if successful)

  • READY: Indicates that the iss worker is ready to accept new input. The prompt for new input from iss is written to stderr, and isss monitors this to maintain the ready state. On a new client connection, or when there is a change in the ready state, isss reports this status to the client. A typical use of this is to enable or disable the script submission button in a console environment.

  • SEND: Sends script data to the selected session for execution.

    Response: Script is processed, and results are queued for the client.

  • RECEIVE: Receives the script output.

    Response: Script output returned from the server.

  • END: Terminates the session.

    Response: None

  • RECEIVE: ON/OFF: Toggles whether the client will receive script output for the selected session. This is particularly useful when multiple clients are connected to the same session. For example, the Ivory System online console uses this feature to manage Server-Sent Events (SSE) for asynchronous output handling.

Example workflow:

  1. Client initiates a session: START SESSION

  2. Server responds with: SESSION: <session id>

  3. Client selects the session: SESSION: <session id>

  4. Client receives the ready state: READY

  5. Client sends a script: SEND

  6. Client receives the script output: RECEIVE

  7. Client ends the session: END

Additional features:

  • Multiple clients can connect to the same session and toggle receiving script output independently using the RECEIVE: ON/OFF command.

  • isss monitors the ready state of iss workers by detecting the prompt written to stderr when iss is ready for new input. This state is communicated to clients, which can use it to control interface elements such as enabling/disabling script submission buttons.

  • Primarily used for environments requiring asynchronous script output, such as the SSE mechanism in the Ivory System online console.

Currently, isss is only available as a Linux version.

Summary of features:

  • Acts as a proxy between clients and multiple iss worker processes.

  • Manages multiple client sessions with the Ivory System.

  • Simple protocol for session control, script execution, and output retrieval.

  • Monitors the ready state of iss workers to notify clients when input can be submitted.

  • Supports enabling/disabling script output for individual clients in multi-client scenarios.