From cbb0be9137365ceeee82ac9d735d72eed93786d7 Mon Sep 17 00:00:00 2001 From: Stevan Freeborn <65925598+StevanFreeborn@users.noreply.github.com> Date: Sat, 24 May 2025 12:53:31 -0500 Subject: [PATCH] chore: add README.md --- README.md | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..aaeb651 --- /dev/null +++ b/README.md @@ -0,0 +1,212 @@ +# Steve's Bot ๐Ÿค– + +This is a Discord bot built with .NET 9, designed to be a full-featured and extensible solution for having my own assistant in my [Discord server](https://discord.stevanfreeborn.com). + +## โœจ Features + +- **Custom Discord Gateway Client**: Full-featured implementation with: + - WebSocket connection management + - Automatic heartbeat handling + - Session resumption and reconnection logic + - Event-driven architecture +- **Observability**: Built-in telemetry with OpenTelemetry support +- **Resilient Architecture**: Graceful error handling and automatic recovery +- **Containerized Deployment**: Ready for Docker deployment + +## ๐Ÿš€ Quick Start + +### Prerequisites + +- [.NET 9 SDK](https://dotnet.microsoft.com/download) +- Discord Bot Token (from [Discord Developer Portal](https://discord.com/developers/applications)) + +### Configuration + +1. Copy the example configuration: + + ```powershell + Copy-Item src/StevesBot.Worker/appsettings.Example.json src/StevesBot.Worker/appsettings.Development.json + ``` + +2. Update `appsettings.Development.json` with your Discord bot credentials: + + ```json + { + "DiscordClientOptions": { + "ApiUrl": "https://discord.com/api/", + "AppToken": "YOUR_BOT_TOKEN_HERE", + "Intents": 512 + } + } + ``` + +### Running the Bot + +#### Using VS Code Tasks + +```powershell +# Build the project +dotnet build src/StevesBot.sln + +# Run the bot +dotnet run --project src/StevesBot.Worker +``` + +#### Using Docker + +```powershell +# Build the Docker image +docker build -t steves-bot src/ + +# Run the container +docker run -d --name steves-bot steves-bot +``` + +## ๐Ÿ—๏ธ Architecture + +### Project Structure + +```txt +src/ +โ”œโ”€โ”€ StevesBot.Worker/ # Main bot application +โ”‚ โ”œโ”€โ”€ Discord/ # Discord client implementation +โ”‚ โ”‚ โ”œโ”€โ”€ Gateway/ # WebSocket gateway client +โ”‚ โ”‚ โ”œโ”€โ”€ Rest/ # REST API client +โ”‚ โ”‚ โ””โ”€โ”€ Shared/ # Common Discord models +โ”‚ โ”œโ”€โ”€ Handlers/ # Event handlers +โ”‚ โ”œโ”€โ”€ Telemetry/ # Observability setup +โ”‚ โ”œโ”€โ”€ Threading/ # Async utilities +โ”‚ โ””โ”€โ”€ WebSockets/ # WebSocket abstractions +โ””โ”€โ”€ StevesBot.Worker.Tests/ # Comprehensive test suite +``` + +### Key Components + +- **DiscordGatewayClient**: Custom WebSocket client for Discord Gateway API +- **Worker**: Background service that manages the bot lifecycle +- **WebSocket Management**: Custom WebSocket factory and connection handling +- **AsyncLock**: Thread-safe async locking mechanism + +## ๐Ÿ”ง Configuration + +### Discord Client Options + +| Setting | Description | Required | +|----------------------------------|-----------------------------------------|----------| +| `DiscordClientOptions__ApiUrl` | Discord API base URL | Yes | +| `DiscordClientOptions__AppToken` | Bot token from Discord Developer Portal | Yes | +| `DiscordClientOptions__Intents` | Discord Gateway intents | Yes | + +### Telemetry Options + +| Setting | Description | Required | +|----------------------------|------------------------|----------| +| `SeqOptions__ServerUrl` | Seq logging server URL | No | +| `SeqOptions__ApiKey` | Seq API key | No | +| `SeqOptions__ApiKeyHeader` | Seq API key header | NO | + +## ๐Ÿงช Testing + +The project includes a comprehensive test suite with both unit and integration tests: + +```powershell +# Run all tests +dotnet test src/StevesBot.sln + +# Run with coverage +dotnet test src/StevesBot.sln --collect:"XPlat Code Coverage" +``` + +### Test Coverage + +- **Unit Tests**: Extensive coverage of Discord Gateway client, event handling, and utilities +- **Integration Tests**: WebSocket connection and Discord API integration +- **Mock-based Testing**: Isolated testing with proper dependency injection + +## ๐ŸŒŸ Discord Gateway Features + +Steve's Bot implements a full-featured Discord Gateway client with: + +### Connection Management + +- Automatic connection establishment +- Session resumption on disconnection +- Graceful reconnection with exponential backoff + +### Heartbeat System + +- Automatic heartbeat sending +- Heartbeat acknowledgment tracking +- Connection health monitoring + +### Event Handling + +- Type-safe event deserialization +- Extensible event handler system +- Proper error handling and logging + +### Resilience + +- Automatic reconnection on connection loss +- Session state preservation +- Proper cleanup on shutdown + +## ๐Ÿ“Š Observability + +The bot includes comprehensive observability features: + +- **Structured Logging**: JSON-formatted logs with contextual information +- **OpenTelemetry**: Distributed tracing and metrics +- **Error Tracking**: Detailed error logging and alerting + +## ๐Ÿณ Deployment + +### Docker Deployment + +The project includes a multi-stage Dockerfile for optimized production builds: + +```dockerfile +# Build stage with .NET SDK +FROM mcr.microsoft.com/dotnet/sdk:9.0 AS base +# ... build steps ... + +# Runtime stage with optimized ASP.NET runtime +FROM mcr.microsoft.com/dotnet/aspnet:9.0 +# ... runtime setup ... +``` + +### Configuration for Production + +Use environment variables or configuration providers for production secrets. + +## ๐Ÿค Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add some amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +### Development Guidelines + +- Follow the existing code style and patterns +- Add comprehensive tests for new features +- Update documentation for API changes +- Ensure all tests pass before submitting PR + +## ๐Ÿ“„ License + +This project is licensed under the terms found in the [LICENSE.md](LICENSE.md) file. + +## ๐Ÿ”— Links + +- [Discord Developer Portal](https://discord.com/developers/applications) +- [Discord API Documentation](https://discord.com/developers/docs) +- [.NET Documentation](https://docs.microsoft.com/en-us/dotnet/) +- [OpenTelemetry .NET](https://opentelemetry.io/docs/instrumentation/net/) + +--- + +Built with โค๏ธ using .NET 9 and a lot of coffee โ˜• + +*Steve's Bot - Helping Stevan and friends since 2025* ๐Ÿš€