aiogram-webhook 0.2.0__tar.gz → 1.1.0__tar.gz

{aiogram_webhook-0.2.0 → aiogram_webhook-1.1.0}/PKG-INFO

@@ -1,35 +1,36 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.3
 Name: aiogram-webhook
-Version: 0.2.0
+Version: 1.1.0
 Summary: A python library for integrating webhook support with multiple web frameworks in aiogram. Organizes bot operation via webhooks for both single and multi-bot setups.
-Project-URL: Homepage, https://github.com/m-xim/aiogram-webhook
-Project-URL: Repository, https://github.com/m-xim/aiogram-webhook
-Project-URL: Issues, https://github.com/m-xim/aiogram-webhook/issues
-Project-URL: Documentation, https://github.com/m-xim/aiogram-webhook#readme
+Keywords: aiogram,telegram,webhook,fastapi,aiohttp,multibot
+Author: m-xim
 Author-email: m-xim <i@m-xim.ru>
 License: MIT
-License-File: LICENSE
-Keywords: aiogram,aiohttp,fastapi,multibot,telegram,webhook
-Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.10
+Classifier: Operating System :: OS Independent
 Requires-Dist: aiogram>=3.14.0
 Requires-Dist: yarl>=1.17.0
+Requires-Dist: aiohttp>=3.9.0 ; extra == 'aiohttp'
+Requires-Dist: ruff ; extra == 'dev'
+Requires-Dist: ty ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: pytest-asyncio ; extra == 'dev'
+Requires-Dist: httpx ; extra == 'dev'
+Requires-Dist: fastapi>=0.128.0 ; extra == 'fastapi'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/m-xim/aiogram-webhook
+Project-URL: Repository, https://github.com/m-xim/aiogram-webhook
+Project-URL: Issues, https://github.com/m-xim/aiogram-webhook/issues
+Project-URL: Documentation, https://github.com/m-xim/aiogram-webhook#readme
 Provides-Extra: aiohttp
-Requires-Dist: aiohttp>=3.9.0; extra == 'aiohttp'
 Provides-Extra: dev
-Requires-Dist: httpx; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: pytest-asyncio; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
-Requires-Dist: ty; extra == 'dev'
 Provides-Extra: fastapi
-Requires-Dist: fastapi>=0.128.0; extra == 'fastapi'
 Description-Content-Type: text/markdown
 
 # aiogram-webhook
@@ -74,37 +75,42 @@ from fastapi import FastAPI
 from aiogram import Bot, Dispatcher, Router
 from aiogram.filters import CommandStart
 from aiogram.types import Message
-from aiogram_webhook import SimpleEngine, FastApiWebAdapter
-from aiogram_webhook.routing import PathRouting
+from aiogram_webhook import SimpleEngine, FastApiWebAdapter, WebhookConfig
+from aiogram_webhook.routing import StaticRouting
 
 router = Router()
 
+
 @router.message(CommandStart())
 async def start(message: Message):
     await message.answer("OK")
 
+
 dispatcher = Dispatcher()
 dispatcher.include_router(router)
 bot = Bot("BOT_TOKEN")
 
-engine = SimpleEngine( # or other engine
+
+engine = SimpleEngine(
     dispatcher,
     bot,
     web_adapter=FastApiWebAdapter(),
-    routing=PathRouting(url="/webhook"),
+    routing=StaticRouting(url="https://example.com/webhook"),
+    webhook_config=WebhookConfig(allowed_updates=["message", "callback_query"], drop_pending_updates=True),
     # security=Security(...)
 )
 
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     engine.register(app)
-    await engine.set_webhook(
-        drop_pending_updates=True,
-        allowed_updates=("message", "callback_query"),
-    )
-    await engine.on_startup()
+    await engine.set_webhook()  # Uses webhook_config defaults
+    # Or override specific params:
+    # await engine.set_webhook(max_connections=100)
+    await engine.on_startup(app)
     yield
-    await engine.on_shutdown()
+    await engine.on_shutdown(app)
+
 
 app = FastAPI(lifespan=lifespan)
 ```
@@ -114,25 +120,33 @@ app = FastAPI(lifespan=lifespan)
 from aiogram import Bot, Dispatcher, Router
 from aiogram.filters import CommandStart
 from aiogram.types import Message
-from aiogram_webhook import SimpleEngine, FastApiWebAdapter
-from aiogram_webhook.routing import PathRouting
+from aiogram_webhook import SimpleEngine, AiohttpWebAdapter, WebhookConfig
+from aiogram_webhook.routing import StaticRouting
 from aiohttp import web
 
 router = Router()
 
+
 @router.message(CommandStart())
 async def start(message: Message):
     await message.answer("OK")
 
+
+async def on_startup(bot: Bot, webhook_engine: SimpleEngine) -> None:
+    await webhook_engine.set_webhook()
+
+
 dispatcher = Dispatcher()
 dispatcher.include_router(router)
+dispatcher.startup.register(on_startup)
 bot = Bot("BOT_TOKEN")
 
-engine = SimpleEngine( # or other engine
+engine = SimpleEngine(
     dispatcher,
     bot,
-    web_adapter=FastApiWebAdapter(),
-    routing=PathRouting(url="/webhook"),
+    web_adapter=AiohttpWebAdapter(),
+    routing=StaticRouting(url="https://example.com/webhook"),
+    webhook_config=WebhookConfig(allowed_updates=["message", "callback_query"]),
     # security=Security(...)
 )
 app = web.Application()
@@ -151,21 +165,23 @@ Used for serving a single Telegram bot. Suitable for most standard scenarios whe
 
 - Connects aiogram `Dispatcher` and `Bot` to the selected web framework (FastAPI, aiohttp, etc.)
 - Handles webhook requests for a single bot
-- Requires explicit dispatcher, bot, web_adapter, and routing (security is optional)
+- Requires explicit dispatcher, bot, web_adapter, and routing (security and webhook_config are optional)
 
 **Example:**
 ```python
 from aiogram import Bot, Dispatcher
-from aiogram_webhook import SimpleEngine, FastApiWebAdapter
-from aiogram_webhook.routing import PathRouting
+from aiogram_webhook import SimpleEngine, FastApiWebAdapter, WebhookConfig
+from aiogram_webhook.routing import StaticRouting
 
 bot = Bot("BOT_TOKEN")
 dispatcher = Dispatcher()
+
 engine = SimpleEngine(
     dispatcher,
     bot,
     web_adapter=FastApiWebAdapter(),
-    routing=PathRouting(url="/webhook"),
+    routing=StaticRouting(url="https://example.com/webhook"),
+    webhook_config=WebhookConfig(allowed_updates=["message", "callback_query"], drop_pending_updates=True),
     # security=Security(...)
 )
 ```
@@ -176,7 +192,7 @@ Allows you to serve multiple Telegram bots in a single application. Useful if yo
 
 - Allows serving multiple bots via a single endpoint
 - Uses the bot token for request routing
-- Requires dispatcher, web_adapter, routing, bot_settings (a dict with bot settings), security (optional)
+- Requires dispatcher, web_adapter, routing, bot_settings (optional), webhook_config (optional), and security (optional)
 
 **Example:**
 
@@ -185,11 +201,12 @@ from aiogram import Dispatcher, Router
 from aiogram.client.default import DefaultBotProperties
 from aiogram.types import Message
 from aiogram.filters import Command, CommandObject
-from aiogram_webhook import TokenEngine, FastApiWebAdapter
+from aiogram_webhook import TokenEngine, FastApiWebAdapter, WebhookConfig
 from aiogram_webhook.routing import PathRouting
 
 router = Router()
 
+
 @router.message(Command("addbot"))
 async def add_bot_handler(message: Message, command: CommandObject, webhook_engine: TokenEngine):
     token = command.args
@@ -199,14 +216,17 @@ async def add_bot_handler(message: Message, command: CommandObject, webhook_engi
     new_bot = await webhook_engine.set_webhook(token)
     await message.answer(f"Bot #{new_bot.id} started!")
 
+
 dispatcher = Dispatcher()
 dispatcher.include_router(router)
 
+
 engine = TokenEngine(
     dispatcher,
     web_adapter=FastApiWebAdapter(),
-    routing=PathRouting(url="/webhook/{bot_token}", param="bot_token"),
+    routing=PathRouting(url="https://example.com/webhook/{bot_token}"),
     bot_settings={"default": DefaultBotProperties(parse_mode="HTML")},
+    webhook_config=WebhookConfig(allowed_updates=["message", "callback_query"]),
     # security=Security(...)
 )
 ```
@@ -233,9 +253,74 @@ Adapters connect the engine to your web framework.
 
 ## 🛣️ Routing
 
-- **PathRouting** — static path or path with parameter (e.g. `/webhook/{bot_token}`)
-- **QueryRouting** — via query parameters (e.g. `/webhook?bot_token={bot_token}`)
-- **CustomRouting** — implement your own routing logic (see [routing examples](/src/aiogram_webhook/routing))
+aiogram-webhook provides several routing strategies to determine webhook URLs and extract bot tokens from requests:
+
+### BaseRouting (Abstract)
+Base class for all routing strategies. Defines the webhook URL template and provides the interface for extracting information from requests.
+
+### StaticRouting (Single-bot)
+Used with **SimpleEngine** for static webhook URLs without token extraction.
+- Returns the webhook URL as-is
+- No parameter extraction needed
+- Example: `https://example.com/webhook`
+
+```python
+from aiogram_webhook.routing import StaticRouting
+
+routing = StaticRouting(url="https://example.com/webhook")
+```
+
+### TokenRouting (Multi-bot, Abstract)
+Base class for token-based routing strategies. Used with **TokenEngine** to serve multiple bots.
+- Requires a URL template with a parameter placeholder (e.g. `{bot_token}`)
+- Extracts bot token from incoming requests
+- Automatically formats webhook URL using the bot token
+
+### PathRouting (Multi-bot)
+Extracts bot token from the URL path parameter.
+- Parameter is read from the path segment
+- Example: `https://example.com/webhook/123:ABC` → token extracted from path
+- Default parameter name: `"bot_token"`
+
+```python
+from aiogram_webhook.routing import PathRouting
+
+# Using default parameter name "bot_token"
+routing = PathRouting(url="https://example.com/webhook/{bot_token}")
+
+# Or with custom parameter name
+routing = PathRouting(url="https://example.com/webhook/{token}", param="token")
+```
+
+### QueryRouting (Multi-bot)
+Extracts bot token from URL query parameters.
+- Parameter is read from the query string
+- Example: `https://example.com/webhook?token=123:ABC` → token extracted from query
+- Default parameter name: `"bot_token"`
+
+```python
+from aiogram_webhook.routing import QueryRouting
+
+# Using default parameter name "bot_token"
+routing = QueryRouting(url="https://example.com/webhook")
+
+# Or with custom parameter name
+routing = QueryRouting(url="https://example.com/webhook", param="token")
+
+# Or with other parameters
+routing = QueryRouting(url="https://example.com/webhook?other=value")
+```
+
+### Custom Routing
+You can implement your own routing by inheriting from `BaseRouting` or `TokenRouting` and implementing the `webhook_point()` method (and `extract_token()` if using token-based routing).
+
+See [routing examples](/src/aiogram_webhook/routing) for implementation details.
+
+---
+
+## ⚙️ Webhook Configuration
+
+`WebhookConfig` allows you to set default parameters for the Telegram [`setWebhook`](https://core.telegram.org/bots/api#setwebhook) API call. All parameters are optional and can be overridden when calling `engine.set_webhook()`.
 
 ---
 
@@ -247,8 +332,8 @@ aiogram-webhook provides a flexible and extensible security system for processin
 from aiogram_webhook.security import Security, StaticSecretToken, IPCheck
 
 security = Security(
-    IPCheck(), # and other checks...
-    secret_token=StaticSecretToken("YOUR_SECRET_TOKEN")
+    IPCheck(),  # and other checks...
+    secret_token=StaticSecretToken("YOUR_SECRET_TOKEN"),
 )
 ```
 
@@ -284,6 +369,24 @@ You can implement your own class based on the `SecretToken` protocol. For exampl
 
 You can combine as many addresses and networks as needed. The check supports both IPv4 and IPv6.
 
+**Features:**
+- Automatic detection of client IP from direct connection or `X-Forwarded-For` header (for reverse proxy scenarios)
+- Works seamlessly with load balancers and reverse proxies
+
+**Example:**
+```python
+from aiogram_webhook.security import Security, IPCheck
+
+# Use default Telegram IP networks
+security = Security(IPCheck())
+
+# Add custom addresses/networks
+security = Security(IPCheck("192.168.1.0/24", "10.0.0.1"))
+
+# Disable default Telegram networks and use only custom ones
+security = Security(IPCheck("192.168.1.0/24", include_default=False))
+```
+
 ### Using a custom check
 You can create your own security check by implementing the `SecurityCheck` protocol. This allows you to define custom logic for validating incoming requests based on your specific requirements.
 See [checks examples](/src/aiogram_webhook/security/checks) for more details.

{aiogram_webhook-0.2.0 → aiogram_webhook-1.1.0}/README.md

@@ -40,37 +40,42 @@ from fastapi import FastAPI
 from aiogram import Bot, Dispatcher, Router
 from aiogram.filters import CommandStart
 from aiogram.types import Message
-from aiogram_webhook import SimpleEngine, FastApiWebAdapter
-from aiogram_webhook.routing import PathRouting
+from aiogram_webhook import SimpleEngine, FastApiWebAdapter, WebhookConfig
+from aiogram_webhook.routing import StaticRouting
 
 router = Router()
 
+
 @router.message(CommandStart())
 async def start(message: Message):
     await message.answer("OK")
 
+
 dispatcher = Dispatcher()
 dispatcher.include_router(router)
 bot = Bot("BOT_TOKEN")
 
-engine = SimpleEngine( # or other engine
+
+engine = SimpleEngine(
     dispatcher,
     bot,
     web_adapter=FastApiWebAdapter(),
-    routing=PathRouting(url="/webhook"),
+    routing=StaticRouting(url="https://example.com/webhook"),
+    webhook_config=WebhookConfig(allowed_updates=["message", "callback_query"], drop_pending_updates=True),
     # security=Security(...)
 )
 
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     engine.register(app)
-    await engine.set_webhook(
-        drop_pending_updates=True,
-        allowed_updates=("message", "callback_query"),
-    )
-    await engine.on_startup()
+    await engine.set_webhook()  # Uses webhook_config defaults
+    # Or override specific params:
+    # await engine.set_webhook(max_connections=100)
+    await engine.on_startup(app)
     yield
-    await engine.on_shutdown()
+    await engine.on_shutdown(app)
+
 
 app = FastAPI(lifespan=lifespan)
 ```
@@ -80,25 +85,33 @@ app = FastAPI(lifespan=lifespan)
 from aiogram import Bot, Dispatcher, Router
 from aiogram.filters import CommandStart
 from aiogram.types import Message
-from aiogram_webhook import SimpleEngine, FastApiWebAdapter
-from aiogram_webhook.routing import PathRouting
+from aiogram_webhook import SimpleEngine, AiohttpWebAdapter, WebhookConfig
+from aiogram_webhook.routing import StaticRouting
 from aiohttp import web
 
 router = Router()
 
+
 @router.message(CommandStart())
 async def start(message: Message):
     await message.answer("OK")
 
+
+async def on_startup(bot: Bot, webhook_engine: SimpleEngine) -> None:
+    await webhook_engine.set_webhook()
+
+
 dispatcher = Dispatcher()
 dispatcher.include_router(router)
+dispatcher.startup.register(on_startup)
 bot = Bot("BOT_TOKEN")
 
-engine = SimpleEngine( # or other engine
+engine = SimpleEngine(
     dispatcher,
     bot,
-    web_adapter=FastApiWebAdapter(),
-    routing=PathRouting(url="/webhook"),
+    web_adapter=AiohttpWebAdapter(),
+    routing=StaticRouting(url="https://example.com/webhook"),
+    webhook_config=WebhookConfig(allowed_updates=["message", "callback_query"]),
     # security=Security(...)
 )
 app = web.Application()
@@ -117,21 +130,23 @@ Used for serving a single Telegram bot. Suitable for most standard scenarios whe
 
 - Connects aiogram `Dispatcher` and `Bot` to the selected web framework (FastAPI, aiohttp, etc.)
 - Handles webhook requests for a single bot
-- Requires explicit dispatcher, bot, web_adapter, and routing (security is optional)
+- Requires explicit dispatcher, bot, web_adapter, and routing (security and webhook_config are optional)
 
 **Example:**
 ```python
 from aiogram import Bot, Dispatcher
-from aiogram_webhook import SimpleEngine, FastApiWebAdapter
-from aiogram_webhook.routing import PathRouting
+from aiogram_webhook import SimpleEngine, FastApiWebAdapter, WebhookConfig
+from aiogram_webhook.routing import StaticRouting
 
 bot = Bot("BOT_TOKEN")
 dispatcher = Dispatcher()
+
 engine = SimpleEngine(
     dispatcher,
     bot,
     web_adapter=FastApiWebAdapter(),
-    routing=PathRouting(url="/webhook"),
+    routing=StaticRouting(url="https://example.com/webhook"),
+    webhook_config=WebhookConfig(allowed_updates=["message", "callback_query"], drop_pending_updates=True),
     # security=Security(...)
 )
 ```
@@ -142,7 +157,7 @@ Allows you to serve multiple Telegram bots in a single application. Useful if yo
 
 - Allows serving multiple bots via a single endpoint
 - Uses the bot token for request routing
-- Requires dispatcher, web_adapter, routing, bot_settings (a dict with bot settings), security (optional)
+- Requires dispatcher, web_adapter, routing, bot_settings (optional), webhook_config (optional), and security (optional)
 
 **Example:**
 
@@ -151,11 +166,12 @@ from aiogram import Dispatcher, Router
 from aiogram.client.default import DefaultBotProperties
 from aiogram.types import Message
 from aiogram.filters import Command, CommandObject
-from aiogram_webhook import TokenEngine, FastApiWebAdapter
+from aiogram_webhook import TokenEngine, FastApiWebAdapter, WebhookConfig
 from aiogram_webhook.routing import PathRouting
 
 router = Router()
 
+
 @router.message(Command("addbot"))
 async def add_bot_handler(message: Message, command: CommandObject, webhook_engine: TokenEngine):
     token = command.args
@@ -165,14 +181,17 @@ async def add_bot_handler(message: Message, command: CommandObject, webhook_engi
     new_bot = await webhook_engine.set_webhook(token)
     await message.answer(f"Bot #{new_bot.id} started!")
 
+
 dispatcher = Dispatcher()
 dispatcher.include_router(router)
 
+
 engine = TokenEngine(
     dispatcher,
     web_adapter=FastApiWebAdapter(),
-    routing=PathRouting(url="/webhook/{bot_token}", param="bot_token"),
+    routing=PathRouting(url="https://example.com/webhook/{bot_token}"),
     bot_settings={"default": DefaultBotProperties(parse_mode="HTML")},
+    webhook_config=WebhookConfig(allowed_updates=["message", "callback_query"]),
     # security=Security(...)
 )
 ```
@@ -199,9 +218,74 @@ Adapters connect the engine to your web framework.
 
 ## 🛣️ Routing
 
-- **PathRouting** — static path or path with parameter (e.g. `/webhook/{bot_token}`)
-- **QueryRouting** — via query parameters (e.g. `/webhook?bot_token={bot_token}`)
-- **CustomRouting** — implement your own routing logic (see [routing examples](/src/aiogram_webhook/routing))
+aiogram-webhook provides several routing strategies to determine webhook URLs and extract bot tokens from requests:
+
+### BaseRouting (Abstract)
+Base class for all routing strategies. Defines the webhook URL template and provides the interface for extracting information from requests.
+
+### StaticRouting (Single-bot)
+Used with **SimpleEngine** for static webhook URLs without token extraction.
+- Returns the webhook URL as-is
+- No parameter extraction needed
+- Example: `https://example.com/webhook`
+
+```python
+from aiogram_webhook.routing import StaticRouting
+
+routing = StaticRouting(url="https://example.com/webhook")
+```
+
+### TokenRouting (Multi-bot, Abstract)
+Base class for token-based routing strategies. Used with **TokenEngine** to serve multiple bots.
+- Requires a URL template with a parameter placeholder (e.g. `{bot_token}`)
+- Extracts bot token from incoming requests
+- Automatically formats webhook URL using the bot token
+
+### PathRouting (Multi-bot)
+Extracts bot token from the URL path parameter.
+- Parameter is read from the path segment
+- Example: `https://example.com/webhook/123:ABC` → token extracted from path
+- Default parameter name: `"bot_token"`
+
+```python
+from aiogram_webhook.routing import PathRouting
+
+# Using default parameter name "bot_token"
+routing = PathRouting(url="https://example.com/webhook/{bot_token}")
+
+# Or with custom parameter name
+routing = PathRouting(url="https://example.com/webhook/{token}", param="token")
+```
+
+### QueryRouting (Multi-bot)
+Extracts bot token from URL query parameters.
+- Parameter is read from the query string
+- Example: `https://example.com/webhook?token=123:ABC` → token extracted from query
+- Default parameter name: `"bot_token"`
+
+```python
+from aiogram_webhook.routing import QueryRouting
+
+# Using default parameter name "bot_token"
+routing = QueryRouting(url="https://example.com/webhook")
+
+# Or with custom parameter name
+routing = QueryRouting(url="https://example.com/webhook", param="token")
+
+# Or with other parameters
+routing = QueryRouting(url="https://example.com/webhook?other=value")
+```
+
+### Custom Routing
+You can implement your own routing by inheriting from `BaseRouting` or `TokenRouting` and implementing the `webhook_point()` method (and `extract_token()` if using token-based routing).
+
+See [routing examples](/src/aiogram_webhook/routing) for implementation details.
+
+---
+
+## ⚙️ Webhook Configuration
+
+`WebhookConfig` allows you to set default parameters for the Telegram [`setWebhook`](https://core.telegram.org/bots/api#setwebhook) API call. All parameters are optional and can be overridden when calling `engine.set_webhook()`.
 
 ---
 
@@ -213,8 +297,8 @@ aiogram-webhook provides a flexible and extensible security system for processin
 from aiogram_webhook.security import Security, StaticSecretToken, IPCheck
 
 security = Security(
-    IPCheck(), # and other checks...
-    secret_token=StaticSecretToken("YOUR_SECRET_TOKEN")
+    IPCheck(),  # and other checks...
+    secret_token=StaticSecretToken("YOUR_SECRET_TOKEN"),
 )
 ```
 
@@ -250,6 +334,24 @@ You can implement your own class based on the `SecretToken` protocol. For exampl
 
 You can combine as many addresses and networks as needed. The check supports both IPv4 and IPv6.
 
+**Features:**
+- Automatic detection of client IP from direct connection or `X-Forwarded-For` header (for reverse proxy scenarios)
+- Works seamlessly with load balancers and reverse proxies
+
+**Example:**
+```python
+from aiogram_webhook.security import Security, IPCheck
+
+# Use default Telegram IP networks
+security = Security(IPCheck())
+
+# Add custom addresses/networks
+security = Security(IPCheck("192.168.1.0/24", "10.0.0.1"))
+
+# Disable default Telegram networks and use only custom ones
+security = Security(IPCheck("192.168.1.0/24", include_default=False))
+```
+
 ### Using a custom check
 You can create your own security check by implementing the `SecurityCheck` protocol. This allows you to define custom logic for validating incoming requests based on your specific requirements.
 See [checks examples](/src/aiogram_webhook/security/checks) for more details.