feat: Shared bot (#173)

Author: Paillat-dev

readme.md

@@ -179,6 +179,11 @@ bot:
 If Redis cache is requested but no configuration is provided, Botkit will fall back to
 memory cache with a warning.
 
+When the bot and backend run in the same process (`use.bot` and `use.backend` both
+enabled), Botkit uses a single `CustomBot` instance so in-memory cache and Discord
+state are shared. Use Redis if you run multiple processes or containers and need a
+shared cache across them.
+
 ## Creating Extensions
 
 Extensions are in truth just python located in the `src/extensions` directory. When

src/start.py

@@ -9,19 +9,50 @@
 """
 
 import asyncio
+import contextlib
 
+from fastapi import FastAPI
+
+from src import custom
 from src.config import config
+from src.config.models import BotConfig
 from src.log import logger
-from src.startup import (
-    load_extensions,
-    run_startup_functions,
-    setup_and_start_backend,
-    setup_and_start_bot,
+from src.startup import load_extensions, run_startup_functions
+from src.startup.backend import (
+    create_backend_app,
+    run_backend_only,
+    serve_backend,
+    setup_backend_extensions,
 )
-from src.startup.backend import create_backend_app, create_backend_bot
+from src.startup.bot import create_bot, run_bot_connection, setup_bot, start_bot
 from src.utils import unzip_extensions
 
 
+async def run_bot_and_backend(
+    bot: custom.Bot,
+    app: FastAPI,
+    bot_config: BotConfig,
+) -> None:
+    """Run the Discord gateway and backend API on one shared bot instance."""
+    try:
+        async with bot:  # https://github.com/Pycord-Development/pycord/issues/2958
+            serve_task = asyncio.create_task(serve_backend(app, config.backend))
+            try:
+                await run_bot_connection(
+                    bot,
+                    bot_config.token,
+                    bot_config.rest,
+                    bot_config.public_key,
+                )
+            finally:
+                serve_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await serve_task
+    except Exception as e:  # noqa: BLE001
+        logger.critical("An error occurred while running the bot and backend together.")
+        logger.debug("", exc_info=e)
+
+
 async def start(run_bot: bool | None = None, run_backend: bool | None = None) -> None:
     """Start the bot and/or backend server based on configuration.
 
@@ -47,21 +78,38 @@ async def start(run_bot: bool | None = None, run_backend: bool | None = None) ->
 
     bot_functions, back_functions, startup_functions, translations = load_extensions()
 
-    coros: list[asyncio.Task[None]] = []
+    start_bot_extensions = bool(bot_functions and run_bot)
+    start_backend_server = bool(back_functions and run_backend)
 
-    if bot_functions and run_bot:
-        coros.append(asyncio.create_task(setup_and_start_bot(bot_functions, translations, config.bot)))
-
-    if back_functions and run_backend:
-        coros.append(asyncio.create_task(setup_and_start_backend(back_functions)))
-
-    if not coros:
+    if not start_bot_extensions and not start_backend_server:
         logger.error("Nothing to start, exiting...")
         return
 
+    app = None
+    bot = create_bot(config.bot)
+    if start_bot_extensions:
+        setup_bot(bot, bot_functions, translations, config.bot)
+    if start_backend_server:
+        app = create_backend_app()
+        setup_backend_extensions(app, bot, back_functions)
+
     if startup_functions:
-        app = create_backend_app() if (back_functions and run_backend) else None
-        bot = create_backend_bot() if (back_functions and run_backend) else None
         await run_startup_functions(startup_functions, app, bot)
 
-    await asyncio.gather(*coros)
+    if start_bot_extensions and start_backend_server:
+        if config.bot.rest:
+            logger.critical(
+                "REST bot mode and the Botkit backend cannot run together in one process. "
+                "Disable bot.rest or use.backend."
+            )
+            return
+        if app is None:
+            logger.error("Backend app was not initialized, exiting...")
+            return
+        await run_bot_and_backend(bot, app, config.bot)
+    elif start_bot_extensions:
+        await start_bot(bot, config.bot.token, config.bot.rest, config.bot.public_key)
+    elif app is None:
+        logger.error("Backend app was not initialized, exiting...")
+    else:
+        await run_backend_only(app, bot, config.bot.token, config.backend)

src/startup/__init__.py

@@ -8,15 +8,19 @@
 """
 
 from src.startup.backend import (
+    run_backend_only,
     run_startup_functions,
+    serve_backend,
     setup_and_start_backend,
 )
 from src.startup.bot import setup_and_start_bot
 from src.startup.loader import load_extensions
 
 __all__ = [
     "load_extensions",
+    "run_backend_only",
     "run_startup_functions",
+    "serve_backend",
     "setup_and_start_backend",
     "setup_and_start_bot",
 ]

src/startup/backend.py

@@ -19,6 +19,8 @@
 if TYPE_CHECKING:
     from collections.abc import Awaitable
 
+    from src import custom
+
 
 def create_backend_app() -> FastAPI:
     """Create a FastAPI application for the backend server.
@@ -30,17 +32,15 @@ def create_backend_app() -> FastAPI:
     return FastAPI(title="Botkit Backend")
 
 
-def create_backend_bot() -> discord.Bot:
-    """Create a minimal Discord bot for the backend server.
-
-    The backend server needs a bot instance for certain operations,
-    but it doesn't need the full custom bot setup.
-
-    Returns:
-        A basic Discord bot with default intents
+def create_backend_bot() -> "custom.Bot":
+    """Create a bot for backend-only mode.
 
+    Deprecated in favor of :func:`src.startup.bot.create_bot`, which applies cache
+    and other bot configuration. Kept for backward compatibility.
     """
-    return discord.Bot(intents=discord.Intents.default())
+    from src.startup.bot import create_bot  # noqa: PLC0415
+
+    return create_bot(config.bot)
 
 
 def setup_backend_extensions(
@@ -80,55 +80,93 @@ async def run_startup_functions(
     await asyncio.gather(*startup_coros)
 
 
-async def start_backend(app: FastAPI, bot: discord.Bot, token: str, backend_config: BackendConfig) -> None:
+def _uvicorn_config(app: FastAPI, backend_config: BackendConfig) -> uvicorn.Config:
+    return uvicorn.Config(
+        app=app,
+        host=backend_config.host,
+        port=backend_config.port,
+        access_log=backend_config.access_log,
+        server_header=backend_config.server_header,
+        log_config=None,
+    )
+
+
+async def serve_backend(app: FastAPI, backend_config: BackendConfig) -> None:
+    """Run the FastAPI app with Uvicorn (no Discord login)."""
+    await uvicorn.Server(_uvicorn_config(app, backend_config)).serve()
+
+
+async def run_backend_only(
+    app: FastAPI,
+    bot: discord.Bot,
+    token: str,
+    backend_config: BackendConfig,
+) -> None:
+    """Log in to Discord and serve the backend (backend-only mode)."""
+    try:
+        if not bot.user:
+            await bot.login(token)
+        await serve_backend(app, backend_config)
+    except Exception as e:  # noqa: BLE001
+        logger.critical("An error occurred while starting the backend server.")
+        logger.debug("", exc_info=e)
+
+
+async def start_backend(
+    app: FastAPI,
+    bot: discord.Bot,
+    token: str,
+    backend_config: BackendConfig,
+    *,
+    login: bool = True,
+) -> None:
     """Start the backend server with Uvicorn.
 
     Args:
         app: The FastAPI application to serve
-        bot: The Discord bot instance (for login)
-        token: Discord bot token
+        bot: The Discord bot instance
+        token: Discord bot token (used when ``login`` is True)
         backend_config: Backend server settings
+        login: When True, log in before serving (backend-only). When False, the caller
+            is responsible for authentication (combined bot + backend mode).
 
     """
     try:
-        await bot.login(token)
-        uvicorn_config = uvicorn.Config(
-            app=app,
-            host=backend_config.host,
-            port=backend_config.port,
-            access_log=backend_config.access_log,
-            server_header=backend_config.server_header,
-            log_config=None,
-        )
-
-        await uvicorn.Server(uvicorn_config).serve()
+        if login and not bot.user:
+            await bot.login(token)
+        await serve_backend(app, backend_config)
     except Exception as e:  # noqa: BLE001
         logger.critical("An error occurred while starting the backend server.")
         logger.debug("", exc_info=e)
 
 
 async def setup_and_start_backend(
     back_functions: WebserverFunctionList,
+    bot: "custom.Bot | None" = None,
 ) -> None:
-    """Create, configure, and start the backend server.
-
-    This is a convenience function that combines backend app creation,
-    bot creation, extension setup, and server startup.
+    """Configure and start the backend server.
 
     Args:
         back_functions: List of (setup_webserver_function, config) tuples for extensions
+        bot: Optional existing bot instance. When omitted, a new bot is created via
+            :func:`src.startup.bot.create_bot`.
 
     """
+    from src.startup.bot import create_bot  # noqa: PLC0415
+
     app = create_backend_app()
-    bot = create_backend_bot()
+    if bot is None:
+        bot = create_bot(config.bot)
     setup_backend_extensions(app, bot, back_functions)
-    await start_backend(app, bot, config.bot.token, config.backend)
+    await run_backend_only(app, bot, config.bot.token, config.backend)
 
 
 __all__ = [
     "create_backend_app",
     "create_backend_bot",
+    "run_backend_only",
     "run_startup_functions",
+    "serve_backend",
     "setup_and_start_backend",
     "setup_backend_extensions",
     "start_backend",

src/startup/bot.py

@@ -78,6 +78,45 @@ def configure_bot_features(bot: custom.Bot, config: BotConfig) -> None:
         bot._pending_application_commands = []  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
 
 
+def setup_bot(
+    bot: custom.Bot,
+    bot_functions: SetupFunctionList,
+    translations: list[ExtensionTranslation],
+    config: BotConfig,
+) -> None:
+    """Configure extensions and feature flags on an existing bot instance."""
+    setup_bot_extensions(bot, bot_functions, translations)
+    configure_bot_features(bot, config)
+
+
+async def run_bot_connection(
+    bot: custom.Bot,
+    token: str,
+    rest_config: RestConfig,
+    public_key: str | None = None,
+) -> None:
+    """Connect the bot to Discord without managing the client context manager.
+
+    The caller must enter ``async with bot`` when connection lifecycle is shared
+    (for example when running the backend in the same process).
+    """
+    if isinstance(bot, custom.CustomRestBot):
+        if not public_key:
+            raise TypeError("CustomRestBot requires a public key to start.")
+        start_kwargs: dict[str, Any] = {
+            "token": token,
+            "public_key": public_key,
+            "health": rest_config.health,
+            "uvicorn_options": {
+                "host": rest_config.host,
+                "port": rest_config.port,
+            },
+        }
+        await bot.start(**start_kwargs)
+    else:
+        await bot.start(token)
+
+
 async def start_bot(bot: custom.Bot, token: str, rest_config: RestConfig, public_key: str | None = None) -> None:
     """Start the bot with appropriate configuration.
 
@@ -92,23 +131,8 @@ async def start_bot(bot: custom.Bot, token: str, rest_config: RestConfig, public
 
     """
     try:
-        if isinstance(bot, custom.CustomRestBot):
-            if not public_key:
-                raise TypeError("CustomRestBot requires a public key to start.")  # noqa: TRY301
-            start_kwargs: dict[str, Any] = {
-                "token": token,
-                "public_key": public_key,
-                "health": rest_config.health,
-                "uvicorn_options": {
-                    "host": rest_config.host,
-                    "port": rest_config.port,
-                },
-            }
-            async with bot:  # https://github.com/Pycord-Development/pycord/issues/2958
-                await bot.start(**start_kwargs)
-        else:
-            async with bot:
-                await bot.start(token)
+        async with bot:  # https://github.com/Pycord-Development/pycord/issues/2958
+            await run_bot_connection(bot, token, rest_config, public_key)
     except discord.LoginFailure as e:
         logger.critical("Failed to log in, is the bot token valid?")
         logger.debug("", exc_info=e)
@@ -134,15 +158,16 @@ async def setup_and_start_bot(
 
     """
     bot = create_bot(config)
-    setup_bot_extensions(bot, bot_functions, translations)
-    configure_bot_features(bot, config)
+    setup_bot(bot, bot_functions, translations, config)
     await start_bot(bot, config.token, config.rest, config.public_key)
 
 
 __all__ = [
     "configure_bot_features",
     "create_bot",
+    "run_bot_connection",
     "setup_and_start_bot",
+    "setup_bot",
     "setup_bot_extensions",
     "start_bot",
 ]