WSChat

An extensible chat protocol (yes i will strip out the AI slop but it helps with dev ok?)

License:

MPL v2

🚀 Quick Start

Server

# Start server with defaults
python start_server.py

# Custom configuration  
python start_server.py --host 0.0.0.0 --port 9000 --debug

✨ Features

👑 Administration

• User Management: Kick users, view statistics, manage connections
• Channel Control: Create, delete, purge messages, set topics
• Server Monitoring: Real-time message monitoring, connection tracking
• Announcements: Broadcast messages to all users

💬 Rich Communication

• Multi-Channel: Create and join unlimited channels
• User Profiles: Bio, status, custom colors, away messages
• Message History: Persistent chat history with search
• Real-time Updates: Instant message delivery and notifications

🎨 Multiple Clients

• Enhanced Client: Rich UI with split panes, colors, real-time updates
• Simple Client: Basic terminal interface for all systems
• Web Support: Protocol ready for web client implementation

🔧 Developer Friendly

• Modular Design: Plugin-based command system (cogs)
• Easy Extension: Add new commands and features easily
• Protocol Compliant: Full WSChat v1 specification implementation
• Comprehensive Logging: Debug and monitoring capabilities

🛠️ Installation & Setup

Requirements

• Python 3.8+
• websockets library

Server Setup

# Clone repository
git clone <repository-url>
cd wschat

# Install dependencies
pip install -r requirements.txt

# Start server
python start_server.py

📚 Documentation

• spec.md - WSChat v1 protocol specification
• the literal source code (it's not unreadable trust)

🏗️ Architecture

Server Components

• main.py - Core server and connection handling
• models.py - Data models and protocol definitions
• cogmanager.py - Plugin system for commands
• cogs/ - Individual command modules
  • channels.py - Channel management
  • admin.py - Administrative commands
  • fun.py - Games and entertainment
  • utility.py - Utility commands
  • stub_profile.py - User profile management

Management Tools

• start_server.py - Enhanced server launcher
• reaper.py - Idle user management

🔌 Protocol Support

Implements the complete WSChat v1 protocol:

• Authentication and user management
• Channel operations (join, leave, send, history)
• Real-time messaging with metadata
• Error handling and connection management
• Extensible command system
• Admin and moderation tools

🤝 Contributing

The codebase is designed for easy extension:

1. Add new commands: Create files in cogs/ directory
2. Protocol enhancements: Update models.py and spec.md

Adding a New Server Command

# cogs/my_command.py
from cogmanager import register
from models import Context

@register("MYCOMMAND")
async def my_handler(ctx: Context):
    await ctx.send("Hello from my command!")
    await ctx.confirm()

📜 License

See the repository license for usage terms.

---

Ready to chat? Start the server and connect with friends! 🎉