node-rust-pty

A high-performance, cross-platform PTY (pseudoterminal) implementation for Node.js, built with Rust and N-API.

Table of Contents

- Features
- Installation
- Usage
- API Reference
- Platform Support
- Building from Source
- Testing
- Benchmarks
- Contributing
- License

Features

- Cross-platform support (macOS and Linux)
- High-performance Rust implementation
- Node.js bindings using N-API
- PTY multiplexing for managing multiple sessions
- Asynchronous I/O operations
- Configurable logging levels
- Environment variable management
- Shell changing capability
- Graceful shutdown and force kill options

Installation

To install node-rust-pty, run the following command in your project directory:

``bash
npm install node-rust-pty
`

This package includes prebuilt binaries for supported platforms. If a prebuilt binary is not available for your platform, it will attempt to build from source during installation.

Usage

Here's a basic example of how to use node-rust-pty:

`javascript
const { PtyHandle } = require('node-rust-pty');

async function main() {
const pty = PtyHandle.new();
const multiplexer = pty.multiplexerHandle;

// Create a new session
const sessionId = await multiplexer.createSession();

// Write to the session
await multiplexer.sendToSession(sessionId, Buffer.from('echo "Hello, PTY!"\n').toJSON().data);

// Read from the session
const output = await multiplexer.readFromSession(sessionId);
console.log(output);

// Close the PTY
await pty.close();
}

main().catch(console.error);
`

API Reference

$3

The PtyHandle class represents the main PTY interface.

#### Static Methods

- static new(): PtyHandle - Creates a new PtyHandle instance.

#### Instance Methods

- read(): Promise - Reads data from the PTY.
- write(data: string): Promise - Writes data to the PTY.
- resize(cols: number, rows: number): Promise - Resizes the PTY window.
- execute(command: string): Promise - Executes a command in the PTY.
- close(): Promise - Closes the PTY gracefully.
- forceKill(forceTimeoutMs: number): Promise - Forcefully kills the PTY process.
- pid(): Promise - Retrieves the process ID of the PTY.
- killProcess(signal: number): Promise - Sends a signal to the PTY process.
- waitpid(options: number): Promise - Waits for the PTY process to change state.
- closeMasterFd(): Promise - Closes the master file descriptor of the PTY.
- setEnv(key: string, value: string): Promise - Sets an environment variable for the PTY process.

#### Properties

- multiplexerHandle: MultiplexerHandle - Provides access to the MultiplexerHandle for managing PTY sessions.

$3

The MultiplexerHandle class manages multiple PTY sessions.

#### Static Methods

- static new(): MultiplexerHandle - Creates a new MultiplexerHandle instance.

#### Instance Methods

- createSession(): Promise - Creates a new PTY session and returns its ID.
- sendToSession(sessionId: number, data: Array): Promise - Sends data to a specific session.
- sendToPty(data: Uint8Array): Promise - Sends data directly to the PTY.
- broadcast(data: Uint8Array): Promise - Broadcasts data to all active sessions.
- readFromSession(sessionId: number): Promise - Reads data from a specific session.
- readAllSessions(): Promise> - Reads data from all active sessions.
- removeSession(sessionId: number): Promise - Removes a specific session.
- mergeSessions(sessionIds: Array): Promise - Merges multiple sessions into one.
- splitSession(sessionId: number): Promise - Splits a session into two separate sessions.
- setEnv(key: string, value: string): Promise - Sets an environment variable for the PTY process.
- changeShell(shellPath: string): Promise - Changes the shell of the PTY process.
- status(): Promise - Retrieves the current status of the PTY process.
- setLogLevel(level: string): Promise - Sets the logging level for the PTY process.
- closeAllSessions(): Promise - Closes all active sessions.
- shutdownPty(): Promise - Gracefully shuts down the PTY process and closes all sessions.

$3

#### SplitSessionResult

`typescript
interface SplitSessionResult {
session1: number;
session2: number;
}
`

#### SessionData

`typescript
interface SessionData {
sessionId: number;
data: string;
}
`

$3

The PtyMultiplexer class is an alternative implementation of the multiplexer functionality.

#### Constructor

- constructor(ptyProcess: object)

#### Methods

- createSession(): number
- sendToSession(sessionId: number, data: Buffer): void
- broadcast(data: Buffer): void
- readFromSession(sessionId: number): Buffer
- readAllSessions(): Array
- removeSession(sessionId: number): void
- mergeSessions(sessionIds: Array): void
- splitSession(sessionId: number): number[]
- setEnv(key: string, value: string): void
- changeShell(shellPath: string): void
- status(): string
- setLogLevel(level: string): void
- closeAllSessions(): void
- shutdownPty(): void
- forceShutdownPty(): void
- distributeOutput(): Promise
- readFromPty(): Promise
- dispatchOutput(output: Buffer): Promise

Note: The PtyMultiplexer class provides similar functionality to MultiplexerHandle but with some differences in method signatures and return types.

Platform Support

node-rust-pty currently supports the following platforms:

- macOS (x64, arm64)
- Linux (x64)

Support for Windows is planned for future releases.

Building from Source

To build node-rust-pty from source, you'll need:

- Rust (latest stable version)
- Node.js (v10 or later)
- Python (for node-gyp)
- A C++ compiler (gcc, clang, or MSVC)

Follow these steps:

1. Clone the repository:
`bash
git clone https://github.com/layerdynamics/node-rust-pty.git
cd node-rust-pty
`

2. Install dependencies:
`bash
npm install
`

3. Build the project:
`bash
npm run build
`

Testing

To run the test suite:

`bash
npm test
`

This will run both JavaScript and Rust tests. The test suite uses AVA for JavaScript tests and the built-in Rust test framework.

Benchmarks

Benchmarks are available to measure the performance of key operations. To run the benchmarks:

`bash
npm run bench
``

Contributing

Contributions to node-rust-pty are welcome! Please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Write tests for your changes
4. Implement your changes
5. Run the test suite and ensure all tests pass
6. Submit a pull request with a clear description of your changes

Please adhere to the existing code style and add appropriate documentation for new features.

License

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.

In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to

---

Created and maintained by @layerdynamics