feat(framework): Enhance middleware pipeline and add engine logging

This commit introduces several improvements to the framework's core functionality.

Middleware Pipeline:
- Implemented conditional middleware execution with MiddlewareFilterAttribute, allowing middleware to run only for specific UpdateTypes.
- Introduced IMiddlewareConfig to provide strongly-typed configuration to middleware.
- Enhanced CommandContext with a Properties dictionary to enable data sharing and state management between middleware.

Engine Logging:
- Added detailed debug logs for the start and stop events of BotPollingEngine and BotWebhookEngine.
- Added information logs to track the startup of each individual bot client in both polling and webhook modes.

Author: azhe403

.serena/memories/commands.md

@@ -0,0 +1,40 @@
+
+# Adding a New Command
+
+To add a new command, you can create a new class that inherits from `BotCommandController` and add methods with the `[Command]` attribute. For example:
+
+```csharp
+public class SampleCommands : BotCommandController
+{
+    [Command("ping")]
+    public async Task Ping()
+    {
+        await SendMessageText("Pong!");
+    }
+}
+```
+
+## Command Attributes
+
+The framework provides several attributes for defining commands:
+
+-   `[Command("...")]`: Defines a command that is triggered by a specific string.
+-   `[TextCommand("...")]`: Defines a command that is triggered by a specific text message.
+-   `[Callback("...")]`: Defines a command that is triggered by a callback query.
+-   `[DefaultCommand]`: Defines a command that is executed when no other command matches.
+-   `[InlineQuery]`: Defines a command that is triggered by an inline query.
+-   `[UpdateCommand]`: Defines a command that is triggered by a specific update type.
+-   `[TypedCommand]`: Defines a command that is triggered by a specific message type.
+
+## Command Context
+
+The `BotCommandController` base class provides a `Context` property that allows you to access the current request and send a response. The `CommandContext` object contains information about the incoming update, such as the message, callback query, or inline query.
+
+## Sending Responses
+
+The `BotCommandController` base class provides several methods for sending responses:
+
+-   `SendMessageText(...)`: Sends a text message.
+-   `SendMessage(...)`: Sends a message with more options, such as a reply markup.
+-   `AnswerCallbackQuery(...)`: Answers a callback query.
+-   `AnswerInlineQuery(...)`: Answers an inline query.

.serena/memories/core.md

@@ -14,4 +14,6 @@
   - `AddZiziBotTelegramBot()` does assembly scanning for controllers + middleware and selects engine based on `BotEngine.EngineMode`.
   - `UseZiziBotTelegramBot()` maps webhook endpoints (if `WebApplication`) and starts the selected `IBotEngine`.
   - Each update is processed in an async DI scope via `BotEngineHandler` -> `BotUpdateHandler`.
-- Docs artifact: `CODE_WIKI.md` at repo root (human-facing, comprehensive).
+- Docs artifact: `CODE_WIKI.md` at repo root (human-facing, comprehensive).
+- Project structure: `mem:structure`
+- Adding new commands: `mem:commands`

.serena/memories/structure.md

@@ -0,0 +1,29 @@
+
+# Project Structure
+
+The solution (`ZiziBot.TelegramBot.sln`) contains two main projects:
+
+1.  **`ZiziBot.TelegramBot.Framework`**: A .NET library that provides the core framework for building command-based Telegram bots. It targets `net8.0`, `net9.0`, and `net10.0`.
+2.  **`ZiziBot.TelegramBot.Sample`**: A .NET web project that serves as a sample implementation of the framework. It references the framework project and runs on `net10.0`.
+
+## Framework Project
+
+The `ZiziBot.TelegramBot.Framework` project contains the following key components:
+
+-   **`Attributes`**: Custom attributes used to define commands and their properties.
+-   **`Delegates`**: Delegate types used for command execution.
+-   **`Engines`**: The core polling and webhook engines for receiving updates from Telegram.
+-   **`Extensions`**: Extension methods for client and endpoint setup.
+-   **`Handlers`**: Handlers for processing bot updates.
+-   **`Helpers`**: Helper classes for various tasks.
+-   **`Interfaces`**: Interfaces for middleware and other components.
+-   **`Models`**: Data models for configuration, context, and other objects.
+
+## Sample Project
+
+The `ZiziBot.TelegramBot.Sample` project demonstrates how to use the framework and includes the following:
+
+-   **`Commands`**: Sample command classes that inherit from `BotCommandController`.
+-   **`Middlewares`**: Sample middleware implementations.
+-   **`Program.cs`**: The main entry point of the application, where the bot is initialized and configured.
+-   **`appsettings.json`**: Configuration file for the bot, including bot tokens and other settings.

ZiziBot.TelegramBot.Framework/Attributes/MiddlewareFilterAttribute.cs

@@ -0,0 +1,10 @@
+using System;
+using Telegram.Bot.Types.Enums;
+
+namespace ZiziBot.TelegramBot.Framework.Attributes;
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+public class MiddlewareFilterAttribute(UpdateType updateType) : Attribute
+{
+    public UpdateType UpdateType { get; } = updateType;
+}

ZiziBot.TelegramBot.Framework/Engines/BotPollingEngine.cs

@@ -1,4 +1,4 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 using Telegram.Bot;
 using Telegram.Bot.Polling;
 using ZiziBot.TelegramBot.Framework.Handlers;
@@ -17,6 +17,7 @@ BotEngineHandler botEngineHandler
 {
     public async Task Start(BotClientItem clients)
     {
+        logger.LogInformation("Starting polling for bot: {Name}", clients.Name);
         try
         {
             if (botClientCollection.Items.Exists(x => x.Name == clients.Name))
@@ -27,7 +28,11 @@ public async Task Start(BotClientItem clients)
 
             await clients.Client.DeleteWebhook();
 
-            clients.Client.StartReceiving(botEngineHandler.UpdateHandler, ErrorHandler);
+            clients.Client.StartReceiving(
+                botEngineHandler.UpdateHandler,
+                ErrorHandler,
+                new ReceiverOptions(),
+                clients.CancellationTokenSource?.Token ?? CancellationToken.None);
             botClientCollection.Items.Add(clients);
         }
         catch (Exception exception)
@@ -38,6 +43,7 @@ public async Task Start(BotClientItem clients)
 
     public async Task Start()
     {
+        logger.LogDebug("Starting polling engine...");
         var clients = botTokenConfigs.Select(x => BotClientItem.Create(x.Name, new TelegramBotClientOptions(x.Token)));
 
         foreach (var client in clients)
@@ -65,6 +71,14 @@ public async Task Stop(IEnumerable<string> names)
         }
     }
 
+    public async Task StopEngine()
+    {
+        logger.LogDebug("Stopping polling engine...");
+
+        var botNames = botClientCollection.Items.Select(x => x.Name).ToList();
+        await Stop(botNames);
+    }
+
     private Task ErrorHandler(ITelegramBotClient botClient, Exception exception, HandleErrorSource errorSource, CancellationToken token)
     {
         logger.LogError(exception, "Bot polling engine error. Source: {Source}", errorSource);

ZiziBot.TelegramBot.Framework/Engines/BotWebhookEngine.cs

@@ -1,9 +1,10 @@
-using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging;
 using Telegram.Bot;
 using ZiziBot.TelegramBot.Framework.Interfaces;
 using ZiziBot.TelegramBot.Framework.Models;
 using ZiziBot.TelegramBot.Framework.Models.Configs;
 using ZiziBot.TelegramBot.Framework.Models.Constants;
+using ZiziBot.TelegramBot.Framework.Models.Enums;
 
 namespace ZiziBot.TelegramBot.Framework.Engines;
 
@@ -16,16 +17,23 @@ BotEngineConfig botEngineConfig
 {
     public async Task Start(BotClientItem clients)
     {
+        logger.LogInformation("Starting webhook for bot: {Name}", clients.Name);
         try
         {
             if (botClientCollection.Items.Exists(x => x.Name == clients.Name))
             {
-                logger.LogWarning("Bot polling engine is already running");
+                logger.LogWarning("Bot webhook engine is already running for bot: {Name}", clients.Name);
                 return;
             }
 
             await clients.Client.DeleteWebhook();
 
+            if (string.IsNullOrWhiteSpace(botEngineConfig.WebhookUrl))
+            {
+                logger.LogError("WebhookUrl is not configured. Path: {ConfigPath}:WebhookUrl", BotEngineConfig.ConfigPath);
+                return;
+            }
+
             var webhookUrl = botEngineConfig.WebhookUrl + "/" + ValueConst.WebHookPath + "/" + clients.BotToken;
             logger.LogDebug("Setting up Webhook url for Bot {BotId} to {WebhookUrl}", clients.Client.BotId, webhookUrl);
 
@@ -35,12 +43,13 @@ public async Task Start(BotClientItem clients)
         }
         catch (Exception exception)
         {
-            logger.LogError(exception, "Error starting Polling bot. Name: {Name}", clients.Name);
+            logger.LogError(exception, "Error starting Webhook bot. Name: {Name}", clients.Name);
         }
     }
 
     public async Task Start()
     {
+        logger.LogDebug("Starting webhook engine...");
         var clients = botTokenConfigs.Select(x => BotClientItem.Create(x.Name, new TelegramBotClientOptions(x.Token)));
 
         foreach (var client in clients)
@@ -51,11 +60,32 @@ public async Task Start()
 
     public Task Stop(string name)
     {
-        throw new NotImplementedException();
+        var client = botClientCollection.Items.Find(x => x.Name == name);
+        
+        if (client == null)
+            return Task.CompletedTask;
+
+        botClientCollection.Items.Remove(client);
+        
+        return client.Client.DeleteWebhook();
     }
 
     public Task Stop(IEnumerable<string> names)
     {
-        throw new NotImplementedException();
+        return Task.WhenAll(names.Select(Stop));
+    }
+
+    public async Task StopEngine()
+    {
+        logger.LogDebug("Stopping webhook engine...");
+
+        if (botEngineConfig.EngineMode != BotEngineMode.Webhook)
+        {
+            logger.LogInformation("Bot engine is not in webhook mode, skipping webhook engine shutdown");
+            return;
+        }
+
+        var botNames = botClientCollection.Items.Select(x => x.Name).ToList();
+        await Stop(botNames);
     }
 }