194 lines
5.2 KiB
Markdown
194 lines
5.2 KiB
Markdown
# Terminal Chat
|
|
|
|
A feature-rich terminal-based chat application built with Python and Textual, supporting channels, direct messages, and real-time communication.
|
|
|
|
## Features
|
|
|
|
- **Global and custom channels** - Create public or private channels
|
|
- **Direct messaging** - Private conversations between users
|
|
- **Color-coded users** - Each user gets a unique color
|
|
- **Rich terminal UI** - Built with Textual framework
|
|
- **Command-based interface** - Easy-to-use slash commands
|
|
- **Live user list** - See who's online in real-time
|
|
- **Private channels** - Invite-only channels with access control
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd ChatSSH
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
Run the chat application:
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
Or use the legacy entry point:
|
|
```bash
|
|
python server.py
|
|
```
|
|
|
|
You can optionally specify a username:
|
|
```bash
|
|
python main.py --username YourName
|
|
```
|
|
|
|
### Hosting as a Server
|
|
|
|
To host the chat server that others can connect to via SSH:
|
|
|
|
```bash
|
|
python main.py --ssh --host 0.0.0.0 --port 8022
|
|
```
|
|
|
|
Options:
|
|
- `--ssh` - Enable SSH server mode
|
|
- `--host` - Host address to bind to (default: 0.0.0.0, listens on all interfaces)
|
|
- `--port` - Port number for SSH server (default: 8022)
|
|
- `--username` - Username for local client mode (not used in SSH mode)
|
|
|
|
### Connecting to the SSH Server
|
|
|
|
Once the server is running, users can connect using SSH:
|
|
|
|
```bash
|
|
ssh -p 8022 username@server-address
|
|
```
|
|
|
|
**Authentication:**
|
|
- **Password:** Any password will be accepted (or just press Enter)
|
|
- For demo purposes, authentication is permissive
|
|
- In production, implement proper authentication in `ssh_server.py`
|
|
|
|
**Example:**
|
|
```bash
|
|
# Connect to localhost
|
|
ssh -p 2222 alice@localhost
|
|
# When prompted for password, type anything or press Enter
|
|
|
|
# Connect from another machine
|
|
ssh -p 8022 bob@192.168.1.100
|
|
```
|
|
|
|
## Available Commands
|
|
|
|
| Command | Shortcut | Description |
|
|
|---------|----------|-------------|
|
|
| `/dm <user> [msg]` | `/d` | Send a direct message or switch to DM view |
|
|
| `/create <name> [private]` | `/new` | Create a new channel (optionally private) |
|
|
| `/join <name>` | `/j` | Join an existing channel |
|
|
| `/leave <name>` | `/l` | Leave a channel |
|
|
| `/invite <channel> <user>` | `/inv` | Invite a user to a channel |
|
|
| `/delete <name>` | `/del` | Delete a channel you created |
|
|
| `/switch <name>` | `/s` | Switch to a different channel |
|
|
| `/channels` | `/ch` | List all your channels |
|
|
| `/users` | `/u` | List all online users |
|
|
| `/clear` | `/c` | Clear local chat history |
|
|
| `/quit` | `/q` | Exit the application |
|
|
| `/help` | `/h` | Show help message |
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
ChatSSH/
|
|
├── constants.py # Color palettes and system constants
|
|
├── models.py # Data models (Channel, DirectMessage, UserConnection)
|
|
├── chat_server.py # Core chat server logic and state management
|
|
├── ui.py # Terminal UI components (Textual app)
|
|
├── main.py # Main entry point
|
|
├── server.py # Backwards-compatible wrapper
|
|
└── requirements.txt # Python dependencies
|
|
```
|
|
|
|
## Module Overview
|
|
|
|
### `constants.py`
|
|
Defines color schemes for users and system messages.
|
|
|
|
### `models.py`
|
|
Contains data models:
|
|
- `Channel` - Represents a chat channel with members and messages
|
|
- `DirectMessage` - Manages DM conversations between two users
|
|
- `UserConnection` - Handles user connection and message queuing
|
|
|
|
### `chat_server.py`
|
|
Core server logic:
|
|
- `ChatServer` - Central server managing users, channels, and messages
|
|
- User management (add/remove users, assign colors)
|
|
- Channel operations (create, delete, join, leave, invite)
|
|
- Message routing (channel messages, DMs, broadcasts)
|
|
|
|
### `ui.py`
|
|
Terminal user interface:
|
|
- `TerminalChatApp` - Main Textual application
|
|
- `ChatHistory` - Custom widget for displaying chat messages
|
|
- Command processing and view switching
|
|
- Real-time message updates
|
|
|
|
### `main.py`
|
|
Application entry point with command-line argument parsing.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.10+
|
|
- textual
|
|
- asyncio (built-in)
|
|
|
|
See `requirements.txt` for full dependency list.
|
|
|
|
## Development
|
|
|
|
The application uses a modular architecture for easy maintenance and extension:
|
|
|
|
1. **Constants** - Centralized configuration
|
|
2. **Models** - Clean data structures
|
|
3. **Server Logic** - Business logic separate from UI
|
|
4. **UI Layer** - Textual-based interface
|
|
|
|
To extend functionality:
|
|
- Add new commands in `ui.py` (`process_command` method)
|
|
- Implement server-side logic in `chat_server.py`
|
|
- Define data models in `models.py`
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
- `Ctrl+C` or `Ctrl+D` - Quit application
|
|
- `Ctrl+H` - Show help
|
|
- `Enter` - Send message
|
|
|
|
## Tips
|
|
|
|
- Start in the `#global` channel by default
|
|
- Use `/dm <user>` to switch to direct message mode
|
|
- Private channels require an invitation to join
|
|
- Channel creators can delete their channels
|
|
- Maximum 500 messages stored per channel/DM
|
|
|
|
## Future Enhancements
|
|
|
|
- SSH server support for remote connections
|
|
- Message persistence (database storage)
|
|
- User authentication
|
|
- File sharing
|
|
- Message reactions and threads
|
|
- Search functionality
|
|
|
|
## License
|
|
|
|
[Add your license here]
|
|
|
|
## Contributing
|
|
|
|
[Add contribution guidelines here]
|