87 lines
2 KiB
Markdown
87 lines
2 KiB
Markdown
# Hash of Wisdom
|
|
|
|
A TCP server implementing the "Word of Wisdom" concept with proof-of-work challenges to protect against DDoS attacks.
|
|
|
|
## Overview
|
|
|
|
The Hash of Wisdom server requires clients to solve computational puzzles (proof-of-work) before receiving wise quotes. This approach prevents spam and DDoS attacks by requiring clients to invest CPU time for each request.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
- Go 1.24.3+
|
|
- Docker (optional)
|
|
- [Task](https://taskfile.dev/) (optional, but recommended)
|
|
|
|
### Building
|
|
```bash
|
|
# Build server
|
|
go build -o hash-of-wisdom ./cmd/server
|
|
|
|
# Build client
|
|
go build -o client ./cmd/client
|
|
```
|
|
|
|
### Running
|
|
|
|
#### Using Task (Recommended)
|
|
```bash
|
|
# Most useful command - run all checks
|
|
task check
|
|
|
|
# Start server
|
|
task server -- -config config.yaml
|
|
|
|
# Connect client
|
|
task client -- --addr=localhost:8080
|
|
|
|
# Run tests
|
|
task test
|
|
|
|
# See coverage
|
|
task test-coverage
|
|
|
|
# See all available commands
|
|
task --list
|
|
```
|
|
|
|
#### Manual Commands
|
|
```bash
|
|
# Start server (uses config.yaml by default)
|
|
./hash-of-wisdom
|
|
|
|
# Or with custom config
|
|
./hash-of-wisdom -config /path/to/config.yaml
|
|
|
|
# Connect with client
|
|
./client -addr localhost:8080
|
|
|
|
# Run tests
|
|
go test ./...
|
|
```
|
|
|
|
### Using Docker
|
|
```bash
|
|
# Build image
|
|
docker build -t hash-of-wisdom .
|
|
|
|
# Run container
|
|
docker run -p 8080:8080 -p 8081:8081 hash-of-wisdom
|
|
```
|
|
|
|
### Monitoring
|
|
- Metrics: http://localhost:8081/metrics (Prometheus format with Go runtime stats)
|
|
- Profiling: http://localhost:8081/debug/pprof/
|
|
|
|
## Documentation
|
|
|
|
### Protocol & Implementation
|
|
- [Protocol Specification](docs/PROTOCOL.md) - Binary protocol definition
|
|
- [PoW Algorithm Analysis](docs/POW_ANALYSIS.md) - Algorithm selection rationale and comparison
|
|
- [Implementation Plan](docs/IMPLEMENTATION.md) - Development phases and progress
|
|
- [Package Structure](docs/PACKAGES.md) - Code organization and package responsibilities
|
|
- [Architecture Choices](docs/ARCHITECTURE.md) - Design decisions and patterns
|
|
|
|
### Production Readiness
|
|
- [Production Readiness Guide](docs/PRODUCTION_READINESS.md) - Requirements for production deployment
|