Stevan/steves-bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README.md

Browse Source
This commit is contained in:
Stevan Freeborn
2025-06-04 15:33:50 -05:00
parent 8c800ce658
commit 17b5bdea73
1 changed files with 89 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+89 -30
View File
@@ -1,17 +1,32 @@
# Steve's Bot 🤖 # 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). This is a comprehensive Discord bot platform 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 ## ✨ Features
### Core Bot Platform
- **Custom Discord Gateway Client**: Full-featured implementation with: - **Custom Discord Gateway Client**: Full-featured implementation with:
- WebSocket connection management - WebSocket connection management
- Automatic heartbeat handling - Automatic heartbeat handling
- Session resumption and reconnection logic - Session resumption and reconnection logic
- Event-driven architecture - Event-driven architecture
- **Shared Library**: Common Discord REST client and telemetry components
- **Observability**: Built-in telemetry with OpenTelemetry support - **Observability**: Built-in telemetry with OpenTelemetry support
- **Resilient Architecture**: Graceful error handling and automatic recovery - **Resilient Architecture**: Graceful error handling and automatic recovery
- **Containerized Deployment**: Ready for Docker deployment
### YouTube Integration
- **YouTube Webhook Service**: Web API for receiving YouTube notifications
- **Live Stream Detection**: Automatic detection and Discord notifications for live streams
- **PubSubHubbub Integration**: YouTube webhook subscription management
- **Stream Deduplication**: Prevents duplicate notifications using in-memory store
### Deployment & Operations
- **Multi-Service Architecture**: Separate worker and webhook services
- **Containerized Deployment**: Docker containers with Docker Compose orchestration
- **Production Ready**: Environment-specific configuration and logging
## 🚀 Quick Start ## 🚀 Quick Start
@@ -19,13 +34,16 @@ This is a Discord bot built with .NET 9, designed to be a full-featured and exte
- [.NET 9 SDK](https://dotnet.microsoft.com/download) - [.NET 9 SDK](https://dotnet.microsoft.com/download)
- Discord Bot Token (from [Discord Developer Portal](https://discord.com/developers/applications)) - Discord Bot Token (from [Discord Developer Portal](https://discord.com/developers/applications))
- For YouTube integration: YouTube Data API v3 key from [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
### Configuration ### Configuration
#### Worker Service (Discord Bot)
1. Copy the example configuration: 1. Copy the example configuration:
```powershell ```powershell
Copy-Item src/StevesBot.Worker/appsettings.Example.json src/StevesBot.Worker/appsettings.Development.json Copy-Item src/src/StevesBot.Worker/appsettings.Example.json src/src/StevesBot.Worker/appsettings.Development.json
``` ```
2. Update `appsettings.Development.json` with your Discord bot credentials: 2. Update `appsettings.Development.json` with your Discord bot credentials:
@@ -40,26 +58,29 @@ This is a Discord bot built with .NET 9, designed to be a full-featured and exte
} }
``` ```
### Running the Bot #### Webhook Service (YouTube Integration)
1. Copy the example configuration:
```powershell
Copy-Item src/src/StevesBot.Webhook/appsettings.Example.json src/src/StevesBot.Webhook/appsettings.Development.json
```
2. Update with your API keys and callback URLs for YouTube integration.
### Running the Services
#### Using VS Code Tasks #### Using VS Code Tasks
```powershell ```powershell
# Build the project # Build the entire solution
dotnet build src/StevesBot.sln dotnet build src/StevesBot.sln
# Run the bot # Run the Discord bot worker
dotnet run --project src/StevesBot.Worker dotnet run --project src/src/StevesBot.Worker
```
#### Using Docker # Run the YouTube webhook service (in separate terminal)
dotnet run --project src/src/StevesBot.Webhook
```powershell
# Build the Docker image
docker build -t steves-bot src/
# Run the container
docker run -d --name steves-bot steves-bot
``` ```
## 🏗️ Architecture ## 🏗️ Architecture
@@ -68,28 +89,58 @@ docker run -d --name steves-bot steves-bot
```txt ```txt
src/ src/
├── StevesBot.Worker/ # Main bot application ├── src/
│ ├── Discord/ # Discord client implementation │ ├── StevesBot.Library/ # Shared library components
│ │ ├── Gateway/ # WebSocket gateway client │ │ ├── Discord/ # Common Discord REST client
│ │ ├── Rest/ # REST API client │ │ └── Telemetry/ # Shared telemetry setup
│ │ └── Shared/ # Common Discord models │ ├── StevesBot.Worker/ # Discord bot worker service
│ ├── Handlers/ # Event handlers │ │ ├── Discord/ # Discord Gateway client implementation
│ ├── Telemetry/ # Observability setup │ │ │ ├── Gateway/ # WebSocket gateway client
│ ├── Threading/ # Async utilities │ │ │ ├── Rest/ # REST API client
│ └── WebSockets/ # WebSocket abstractions │ │ │ └── Shared/ # Common Discord models
└── StevesBot.Worker.Tests/ # Comprehensive test suite │ │ ├── Handlers/ # Discord event handlers
│ │ ├── Telemetry/ # Worker-specific telemetry
│ │ ├── Threading/ # Async utilities
│ │ └── WebSockets/ # WebSocket abstractions
│ └── StevesBot.Webhook/ # YouTube webhook service
│ ├── YouTube/ # YouTube integration components
│ │ ├── Data/ # YouTube API models
│ │ ├── Handlers/ # Webhook request handlers
│ │ └── Tasks/ # Background tasks
│ └── Telemetry/ # Webhook-specific telemetry
├── tests/ # Comprehensive test suites
│ ├── StevesBot.Library.Tests/ # Shared library tests
│ ├── StevesBot.Worker.Tests/ # Worker service tests
│ └── StevesBot.Webhook.Tests/ # Webhook service tests
├── compose.yml # Docker Compose configuration
├── StevesBot.Worker.Dockerfile # Worker service container
└── StevesBot.Webhook.Dockerfile # Webhook service container
``` ```
### Key Components ### Key Components
#### Discord Bot Worker
- **DiscordGatewayClient**: Custom WebSocket client for Discord Gateway API - **DiscordGatewayClient**: Custom WebSocket client for Discord Gateway API
- **Worker**: Background service that manages the bot lifecycle - **Worker**: Background service that manages the bot lifecycle
- **WebSocket Management**: Custom WebSocket factory and connection handling - **WebSocket Management**: Custom WebSocket factory and connection handling
- **AsyncLock**: Thread-safe async locking mechanism - **AsyncLock**: Thread-safe async locking mechanism
#### YouTube Webhook Service
- **NotificationHandler**: Processes YouTube webhook notifications
- **SubscriptionWorker**: Manages YouTube PubSubHubbub subscriptions
- **YouTubeDataApiClient**: Integrates with YouTube Data API v3
- **LastPostedStreamStore**: Prevents duplicate stream notifications
#### Shared Library
- **DiscordRestClient**: Reusable Discord REST API client
- **Telemetry Infrastructure**: OpenTelemetry setup and instrumentation
## 🔧 Configuration ## 🔧 Configuration
### Discord Client Options ### Discord Worker Options
| Setting | Description | Required | | Setting | Description | Required |
|----------------------------------|-----------------------------------------|----------| |----------------------------------|-----------------------------------------|----------|
@@ -97,6 +148,17 @@ src/
| `DiscordClientOptions__AppToken` | Bot token from Discord Developer Portal | Yes | | `DiscordClientOptions__AppToken` | Bot token from Discord Developer Portal | Yes |
| `DiscordClientOptions__Intents` | Discord Gateway intents | Yes | | `DiscordClientOptions__Intents` | Discord Gateway intents | Yes |
### YouTube Webhook Options
| Setting | Description | Required |
|----------------------------------------|---------------------------------------|----------|
| `YouTubeClientOptions__BaseUrl` | YouTube Data API base URL | Yes |
| `YouTubeClientOptions__ApiKey` | YouTube Data API v3 key | Yes |
| `SubscriptionOptions__CallbackUrl` | Webhook callback URL | Yes |
| `SubscriptionOptions__TopicUrl` | YouTube channel topic URL | Yes |
| `PubSubClientOptions__BaseUrl` | PubSubHubbub hub URL | Yes |
| `DiscordNotificationOptions__ChannelId` | Discord channel for notifications | Yes |
### Telemetry Options ### Telemetry Options
| Setting | Description | Required | | Setting | Description | Required |
@@ -112,9 +174,6 @@ The project includes a comprehensive test suite with both unit and integration t
```powershell ```powershell
# Run all tests # Run all tests
dotnet test src/StevesBot.sln dotnet test src/StevesBot.sln
# Run with coverage
dotnet test src/StevesBot.sln --collect:"XPlat Code Coverage"
``` ```
### Test Coverage ### Test Coverage