kryten-robot 1.3.0

CyTube to NATS bridge connector - publishes CyTube events to NATS message bus

Kryten-Robot

Kryten-Robot is a CyTube to NATS bridge connector that connects to CyTube chat servers via Socket.IO and publishes all events to a NATS message bus. This enables building distributed microservice architectures around CyTube channels.

Overview

Kryten-Robot acts as the central bridge between CyTube and your microservices:

• Connects to CyTube servers via Socket.IO
• Publishes all CyTube events to NATS with structured subjects
• Subscribes to command subjects to control CyTube
• Maintains connection health with automatic reconnection
• Tracks channel state (users, playlist, emotes)
• Exposes state query API via NATS request/reply

Architecture

┌─────────────┐         ┌──────────────┐         ┌─────────────────┐
│   CyTube    │◄───────►│ Kryten-Robot │◄───────►│   NATS Server   │
│   Server    │ Socket  │   (Bridge)   │  Pub/   │                 │
└─────────────┘  .IO    └──────────────┘  Sub    └─────────────────┘
                                                          ▲
                                                          │
                    ┌─────────────────────────────────────┴──────────┐
                    │                                                 │
              ┌─────▼──────┐    ┌──────────────┐    ┌──────────────┐
              │ kryten-cli │    │kryten-       │    │  Your Custom │
              │  (Control) │    │userstats     │    │ Microservice │
              └────────────┘    └──────────────┘    └──────────────┘

Features

• ✅ Full CyTube Event Coverage: All Socket.IO events published to NATS
• ✅ Unified Command Pattern: Single subject per service (kryten.robot.command)
• ✅ State Management: Real-time tracking of users, playlist, emotes
• ✅ State Query API: Request/reply for current channel state
• ✅ Connection Resilience: Automatic reconnection with exponential backoff
• ✅ Health Monitoring: HTTP health endpoint for orchestration
• ✅ Correlation IDs: Distributed tracing support
• ✅ Structured Logging: JSON logs with correlation context

Installation

From PyPI

pip install kryten-robot

As systemd Service (Linux)

For production deployments on Linux with systemd:

# Clone the repository
git clone https://github.com/grobertson/kryten-robot.git
cd kryten-robot

# Run installation script (requires root)
sudo bash install.sh

The installer will:

• Create system user and directories
• Set up Python virtual environment
• Install kryten-robot from PyPI
• Configure systemd service
• Create example config file

See systemd/README.md for detailed setup instructions.

From Source

git clone https://github.com/grobertson/kryten-robot.git
cd kryten-robot
pip install -e .

With Poetry

uv add kryten-robot

Quick Start

1. Create Configuration File

Create config.json:

{
  "cytube": {
    "domain": "cytu.be",
    "channel": "your-channel",
    "user": "your-bot-username",
    "password": "your-bot-password"
  },
  "nats": {
    "servers": ["nats://localhost:4222"],
    "user": null,
    "password": null,
    "max_reconnect_attempts": 60,
    "reconnect_time_wait": 2
  },
  "health": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 28080
  },
  "commands": {
    "enabled": true
  },
  "logging": {
    "format": "text",
    "correlation_id": true
  },
  "log_level": "INFO"
}

2. Run Kryten-Robot

# Using the installed command
kryten-robot config.json

# Or with Python module
python -m kryten config.json

# With custom log level
kryten-robot config.json --log-level DEBUG

3. Verify Operation

Check health endpoint:

curl http://localhost:28080/health

Expected response:

{
  "status": "healthy",
  "cytube_connected": true,
  "nats_connected": true,
  "channel": "your-channel",
  "uptime_seconds": 42.5
}

NATS Subject Structure

Event Publishing

All CyTube events are published to:

kryten.events.cytube.{channel}.{event_name}

Examples:

• kryten.events.cytube.420grindhouse.chatmsg - Chat messages
• kryten.events.cytube.420grindhouse.adduser - User joins
• kryten.events.cytube.420grindhouse.userleave - User leaves
• kryten.events.cytube.420grindhouse.changeMedia - Video changes

Command Subscription

Kryten-Robot accepts commands on:

kryten.robot.command

Command payload:

{
  "service": "robot",
  "command": "state.userlist",
  "correlation_id": "optional-trace-id"
}

Available commands:

• state.emotes - Get all channel emotes
• state.playlist - Get current playlist
• state.userlist - Get all users in channel
• state.user - Get specific user info (requires username param)
• state.profiles - Get all user profiles
• state.all - Get complete channel state
• system.health - Get system health status
• system.channels - Get list of connected channels
• system.version - Get Kryten-Robot version

Configuration Reference

CyTube Section

Field	Type	Required	Description
domain	string	Yes	CyTube server domain (e.g., "cytu.be")
channel	string	Yes	Channel name to connect to
user	string	Yes	Bot account username
password	string	Yes	Bot account password

NATS Section

Field	Type	Required	Default	Description
servers	array	Yes	-	NATS server URLs
user	string	No	null	NATS authentication user
password	string	No	null	NATS authentication password
max_reconnect_attempts	int	No	60	Max reconnection attempts
reconnect_time_wait	int	No	2	Seconds between reconnect attempts

Health Section

Field	Type	Required	Default	Description
enabled	bool	No	true	Enable HTTP health endpoint
host	string	No	"0.0.0.0"	Health endpoint bind address
port	int	No	28080	Health endpoint port

Commands Section

Field	Type	Required	Default	Description
enabled	bool	No	true	Enable command subscriber

Logging Section

Field	Type	Required	Default	Description
format	string	No	"text"	Log format: "text" or "json"
correlation_id	bool	No	true	Include correlation IDs

Root Level

Field	Type	Required	Default	Description
log_level	string	No	"INFO"	Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL

Running as a Service

Systemd (Linux)

See systemd/README.md for complete systemd service configuration.

Quick setup:

sudo cp systemd/kryten-robot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable kryten-robot
sudo systemctl start kryten-robot

Windows Service

Use NSSM (Non-Sucking Service Manager):

nssm install kryten-robot "C:\Python311\python.exe" "-m kryten config.json"
nssm set kryten-robot AppDirectory "C:\opt\kryten-robot"
nssm start kryten-robot

Development

Setup Development Environment

git clone https://github.com/grobertson/kryten-robot.git
cd kryten-robot

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest

With coverage:

pytest --cov=kryten --cov-report=html

Code Quality

# Format code
black kryten/

# Lint
ruff check kryten/

# Type checking
mypy kryten/

Integration Examples

Using kryten-py Library

from kryten import KrytenClient, KrytenConfig

config = KrytenConfig.from_json("config.json")

async with KrytenClient(config) as client:
    # Query current userlist
    response = await client.nats_request(
        "kryten.robot.command",
        {"service": "robot", "command": "state.userlist"}
    )
    
    if response["success"]:
        users = response["data"]["users"]
        print(f"Users online: {len(users)}")

Using kryten-cli

# Get current playlist
kryten list queue

# Get all users
kryten list users

# Get channel emotes
kryten list emotes

Architecture Documentation

• KRYTEN_ARCHITECTURE.md - System architecture and patterns
• STATE_QUERY_IMPLEMENTATION.md - State query API details
• LIFECYCLE_EVENTS.md - Lifecycle event handling
• AUDIT_LOGGING.md - Audit logging implementation

Troubleshooting

Connection Issues

Problem: Kryten-Robot won't connect to CyTube

• Verify credentials in config.json
• Check if channel name is correct
• Ensure CyTube server is accessible

Problem: NATS connection failures

• Verify NATS server is running: nats-server -v
• Check NATS server URL in config
• Test NATS connectivity: nats-cli pub test "hello"

Performance Issues

Problem: High memory usage

• Check for excessive event backlog
• Verify NATS consumers are processing events
• Monitor with health endpoint: curl http://localhost:28080/health

Problem: Events not being published

• Check log level is INFO or DEBUG
• Verify NATS subjects with nats-cli sub "kryten.events.>"
• Check correlation logs for event flow

Requirements

• Python 3.11 or higher
• NATS server 2.9.0 or higher
• CyTube server (any version with Socket.IO support)

Related Projects

• kryten-py - Python library for building Kryten microservices
• kryten-userstats - User statistics tracking service
• kryten-cli - Command-line control interface

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run tests and linting (pytest && black . && ruff check .)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: GitHub Repository

Changelog

v0.5.0 (2025-12-08)

Major Changes:

• ✅ Unified command pattern: All services now use kryten.{service}.command
• ✅ State query API: Request/reply interface for channel state
• ✅ Fixed startup banner bug with wildcard normalization
• ✅ PyPI packaging: Now installable via pip install kryten-robot

API Updates:

• Changed: Command subjects from kryten.commands.cytube.* to kryten.robot.command
• Added: State query commands (state.emotes, state.playlist, etc.)
• Added: System health command via NATS

Documentation:

• Added: KRYTEN_ARCHITECTURE.md with comprehensive architecture overview
• Updated: All examples to use unified command pattern
• Added: PyPI publication workflow

---

Built with ❤️ for the CyTube community