Sudoku Telnet Server

A multi-transport Sudoku game server built using the chuk-protocol-server framework.

Try It Now

A live demo server is running on Fly.io. Try it instantly:

# Connect via Telnet (IPv6)
telnet 2a09:8280:1::b8:274e:0 8023

# WebSocket connections
ws://sudoku-telnet-server.fly.dev:8025/ws

Once connected, type help to see available commands, or start easy to begin playing!

Features

• Classic Sudoku gameplay with three difficulty levels (easy, medium, hard)
• Multiple transport protocols:
  • Telnet (port 8023) - Classic telnet protocol
  • TCP (port 8024) - Raw TCP connections
  • WebSocket (port 8025) - Modern WebSocket protocol
  • WebSocket-Telnet (port 8026) - WebSocket with telnet negotiation
• Interactive text-based interface
• Hint system for when you're stuck
• Solution checker and auto-solver
• Automatic puzzle generation using backtracking algorithm
• Move tracking and validation
• Comprehensive test suite (50 tests, 94% coverage)
• Modern Python packaging with pyproject.toml
• GitHub Actions CI/CD workflows
• Docker and Fly.io deployment ready

Game Commands

Starting and Managing Games

• start [easy|medium|hard] - Start a new game (default: easy)
• show - Display the current grid
• help - Show all available commands
• quit - Exit the game

Playing the Game

• place <row> <col> <num> - Place a number on the grid
  • Example: place 1 5 7 (places 7 at row 1, column 5)
• clear <row> <col> - Clear a cell you've filled
• hint - Get a hint for the next move
• check - Check your progress
• solve - Show the solution (ends current game)

Quick Start

Prerequisites

• Python 3.11 or higher
• UV (recommended) or pip

Installation

From Source (Development)

Using UV (Recommended)

# Clone the repository
git clone https://github.com/YOUR_USERNAME/sudoku-telnet-server.git
cd sudoku-telnet-server

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install development dependencies
make dev-install

# Run the server
make run

Using pip

# Clone the repository
git clone https://github.com/YOUR_USERNAME/sudoku-telnet-server.git
cd sudoku-telnet-server

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

# Run the server
PYTHONPATH=. uv run --with chuk-protocol-server chuk-protocol-server server-launcher -c config.yaml

From PyPI (Production)

# Install from PyPI (when published)
pip install sudoku-telnet-server

# Run the server using the installed command
sudoku-server

# Or run with custom config
python -m chuk_protocol_server.server_launcher -c /path/to/config.yaml

Using Make (All Commands)

# See all available commands
make help

# Development workflow
make dev-install      # Install dev dependencies
make run              # Run the server
make test             # Run tests
make test-cov         # Run tests with coverage report
make check            # Run linting and type checking
make format           # Format code with ruff

# Docker workflow
make docker-build     # Build Docker image
make docker-run       # Run in Docker container

# Deployment
make fly-deploy       # Deploy to Fly.io
make fly-logs         # View Fly.io logs

Docker Setup

Build and run with Docker:

# Using Make
make docker-run

# Or manually
docker build -t sudoku-telnet-server .
docker run -p 8023:8023 -p 8024:8024 -p 8025:8025 -p 8026:8026 sudoku-telnet-server

Deployment to Fly.io

Using Make (Recommended)

# Deploy to Fly.io
make fly-deploy

# Check status
make fly-status

# View logs
make fly-logs

Manual Deployment

1. Install the Fly CLI: https://fly.io/docs/hands-on/install-flyctl/

2. Login to Fly:

fly auth login

3. Create and deploy the app:

# First deployment (creates the app)
fly launch --config fly.toml --now

# Subsequent deployments
fly deploy

4. Important: Allocate a public IP address for TCP services:

# Allocate IPv6 (free - recommended)
fly ips allocate-v6

# Optional: Allocate IPv4 (costs $2/month, only needed for IPv4-only clients)
# fly ips allocate-v4 --yes

# Verify IP is allocated
fly ips list

5. Check the status:

fly status

6. View logs:

fly logs

7. Connect to your Sudoku server:

# Get your app's IP address
fly ips list

# Connect via telnet using IPv6 (free tier)
telnet <your-ipv6> 8023

# WebSocket connections work with hostname
# ws://<your-app>.fly.dev:8025/ws

Note: TCP services (Telnet, raw TCP) require a public IP address on Fly.io. IPv6 is free and sufficient for most users. Only allocate IPv4 if you need to support IPv4-only clients ($2/month cost).

Connecting to the Server

Live Demo Server

A live instance is running on Fly.io (IPv6):

Telnet/TCP:

# Via Telnet
telnet 2a09:8280:1::b8:274e:0 8023

# Via TCP
nc 2a09:8280:1::b8:274e:0 8024

WebSocket:

ws://sudoku-telnet-server.fly.dev:8025/ws
ws://sudoku-telnet-server.fly.dev:8026/ws

Local Development

Via Telnet:

telnet localhost 8023

Via Netcat (TCP):

nc localhost 8024

Via WebSocket:

ws://localhost:8025/ws
ws://localhost:8026/ws

Game Rules

Sudoku is a logic-based number puzzle. The objective is to fill a 9×9 grid with digits so that:

1. Each row contains the digits 1-9 without repetition
2. Each column contains the digits 1-9 without repetition
3. Each 3×3 box contains the digits 1-9 without repetition

Some cells are pre-filled (these cannot be modified) and your task is to fill the remaining cells.

Difficulty Levels

• Easy: 35 cells removed from the solved puzzle
• Medium: 45 cells removed from the solved puzzle
• Hard: 55 cells removed from the solved puzzle

Example Gameplay

> start medium

==================================================
SUDOKU - MEDIUM MODE
==================================================
Fill the grid so that every row, column, and 3x3 box
contains the digits 1-9 without repetition.

Type 'help' for commands or 'hint' for a clue.
==================================================

    1 2 3   4 5 6   7 8 9
  -------------------------
1 | . . 3 | . 2 . | 6 . . |
2 | 9 . . | 3 . 5 | . . 1 |
3 | . . 1 | 8 . 6 | 4 . . |
  -------------------------
4 | . . 8 | 1 . 2 | 9 . . |
5 | 7 . . | . . . | . . 8 |
6 | . . 6 | 7 . 8 | 2 . . |
  -------------------------
7 | . . 2 | 6 . 9 | 5 . . |
8 | 8 . . | 2 . 3 | . . 9 |
9 | . . 5 | . 1 . | 3 . . |
  -------------------------
Moves made: 0
==================================================

> hint
Hint: Try placing 4 at row 1, column 1

> place 1 1 4
Number placed successfully!

> check
Empty cells: 50
All filled cells are correct so far!

Architecture

This server is built on the chuk-protocol-server framework, which provides:

• Multiple transport protocol support (Telnet, TCP, WebSocket, WS-Telnet)
• Telnet protocol negotiation (IAC, WILL, WONT, DO, DONT)
• WebSocket handling with ping/pong keepalive
• Connection management and monitoring
• Asynchronous I/O with Python asyncio

The Sudoku game logic (SudokuGame class) includes:

• Puzzle generation using backtracking algorithm
• Move validation according to Sudoku rules (row, column, 3x3 box)
• Automatic solution generation
• Difficulty-based cell removal (35/45/55 cells for easy/medium/hard)
• Hint system (suggests next valid move)
• Progress checking and validation

The game handler (SudokuHandler class) extends TelnetHandler and provides:

• Command parsing and validation
• Grid display with ANSI formatting
• Game state management
• Multi-game support per connection

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/YOUR_USERNAME/sudoku-telnet-server.git
cd sudoku-telnet-server

# Install development dependencies (with UV)
make dev-install

# Or with pip
pip install -e ".[dev]"

Testing

The project has comprehensive test coverage (94%, 50 tests):

# Run all tests
make test

# Run tests with coverage report
make test-cov

# Run tests in watch mode
make test-watch

# View coverage report in browser
make serve-coverage

Code Quality

The project uses modern Python tooling:

• Ruff: Fast linter and formatter (replaces black + flake8)
• MyPy: Static type checking
• Pytest: Testing framework with async support

# Run all checks (lint + typecheck + test)
make check

# Run linter
make lint

# Format code
make format

# Type checking
make typecheck

Running Example Clients

# Telnet client (automated mode)
make example-telnet

# Telnet client (interactive mode)
make example-telnet-interactive

# WebSocket client (automated mode)
make example-ws

# WebSocket client (solve mode - shows full solution)
make example-ws-solve

CI/CD

The project includes GitHub Actions workflows:

• test.yml: Runs tests on Ubuntu, Windows, macOS with Python 3.11, 3.12, 3.13
• publish.yml: Publishes to PyPI on release
• release.yml: Creates GitHub releases
• fly-deploy.yml: Auto-deploys to Fly.io on main branch push

Coverage threshold is set to 90% - builds fail if coverage drops below this.

Project Structure

sudoku-telnet-server/
├── src/
│   └── sudoku_telnet_server/
│       ├── __init__.py       # Package initialization
│       └── server.py         # Main server implementation (SudokuGame, SudokuHandler)
├── tests/
│   ├── test_sudoku_game.py   # Game logic tests (15 tests)
│   └── test_sudoku_handler.py # Handler tests (35 tests)
├── examples/
│   ├── simple_client.py      # Telnet client example
│   ├── websocket_client.py   # WebSocket client example
│   └── README.md             # Example usage guide
├── .github/
│   └── workflows/
│       ├── test.yml          # Multi-platform CI testing
│       ├── publish.yml       # PyPI publishing
│       ├── release.yml       # GitHub releases
│       └── fly-deploy.yml    # Fly.io deployment
├── pyproject.toml            # Modern Python project config (deps, tools, metadata)
├── config.yaml               # Multi-transport server configuration
├── Dockerfile                # Docker build instructions
├── fly.toml                  # Fly.io deployment config
├── Makefile                  # Development commands (run, test, lint, etc.)
├── MANIFEST.in               # Package distribution files
└── README.md                 # This file

Key Files

• src/sudoku_telnet_server/server.py (289 lines, 94% coverage)

  • SudokuGame: Core game logic, puzzle generation, validation
  • SudokuHandler: Command handling, display, game state
  • main(): Server entry point

• pyproject.toml: Modern Python packaging

  • Project metadata and dependencies
  • Tool configurations (ruff, mypy, pytest, coverage)
  • Entry point: sudoku-server command

• config.yaml: Multi-transport server configuration

  • Telnet (8023), TCP (8024), WebSocket (8025), WS-Telnet (8026)
  • Connection limits, timeouts, SSL settings
  • Handler class mapping

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and checks (make check)
5. Ensure coverage stays above 90% (make test-cov)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guide (enforced by ruff)
• Add type hints to all functions
• Write tests for new features
• Update documentation as needed
• Keep coverage above 90%

Troubleshooting

Server won't start

• Ensure chuk-protocol-server is installed: uv pip install chuk-protocol-server
• Check ports aren't already in use: lsof -i :8023,8024,8025,8026
• Verify Python version is 3.11+: python --version

Tests failing

• Install dev dependencies: make dev-install
• Clear cache: make clean
• Check Python version compatibility

Coverage too low

• Run coverage report: make test-cov
• View HTML report: make serve-coverage
• Add tests for uncovered code

License

MIT License - see the main chuk-protocol-server project for details.

Credits

• Built using the chuk-protocol-server framework
• Sudoku puzzle generation algorithm based on backtracking
• Uses modern Python tooling: UV, Ruff, MyPy, Pytest

Links

• chuk-protocol-server - Multi-transport server framework
• UV - Fast Python package manager
• Ruff - Fast Python linter and formatter
• Fly.io - Cloud deployment platform