Merge pull request 'v0.3.0' (#28) from dev into main

Reviewed-on: #28

README.md

@@ -73,6 +73,34 @@ Mandatory keys to modify:
 
 After all of that you're good to go! Happy using :)
 
+## Caching
+
+Although general database access speed is fast, caching might become helpful for
+bigger servers with many bot interactions. Currently, Redis and Memcached are supported.
+
+Configuration happens through the config key `caching`.
+
+Set `caching.type` to the service of you choice ("redis" or "memcached") and then update
+the URI to access the service. It's Redis' default URI format for Redis and "address:port"
+for Memcached.
+
+Which one should I choose?
+
+| Service   | Read/write speed | Config flexibility |
+|-----------|------------------|--------------------|  
+| Redis     | High             | Very flexible      |
+| Memcached | Very high        | Basic              |
+
+> Performance difference between Redis and Memcached is generally quite low, so your setup
+> should normally depend more on the configuration flexibility than on raw speed.
+
+## Debugging
+
+There's a config key `debug` that can be set to `true` for debugging purposes.
+
+It should be set to `false` in production, otherwise log becomes very verbose and might
+contain data that shouldn't normally be logged.
+
 ## Docker [Experimental]
 
 As an experiment, Docker deployment option has been added.

classes/holo_bot.py

@@ -1,6 +1,20 @@
+import logging
+from logging import Logger
+
+from libbot.cache.classes import CacheMemcached, CacheRedis
+from libbot.cache.manager import create_cache_client
 from libbot.pycord.classes import PycordBot
 
+logger: Logger = logging.getLogger(__name__)
+
 
 class HoloBot(PycordBot):
+    cache: CacheMemcached | CacheRedis | None = None
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
+        self._set_cache_engine()
+
+    def _set_cache_engine(self) -> None:
+        if "cache" in self.config and self.config["cache"]["type"] is not None:
+            self.cache = create_cache_client(self.config, self.config["cache"]["type"])

classes/holo_user.py

@@ -1,14 +1,15 @@
 import logging
 from logging import Logger
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 from bson import ObjectId
 from discord import User, Member
+from libbot.cache.classes import Cache
 from libbot.utils import config_get
 from pymongo.results import InsertOneResult
 
 from errors import UserNotFoundError
-from modules.database import col_warnings, col_users
+from modules.database import col_users
 
 logger: Logger = logging.getLogger(__name__)
 
@@ -29,74 +30,55 @@ class HoloUser:
 
     @classmethod
     async def from_user(
-        cls, user: User | Member, allow_creation: bool = True
+        cls,
+        user: User | Member,
+        allow_creation: bool = True,
+        cache: Optional[Cache] = None,
     ) -> "HoloUser":
         """Get an object that has a proper binding between Discord ID and database
 
         ### Args:
             * `user` (User | Member): Object from which an ID can be extracted
+            * `allow_creation` (bool, optional): Whether to allow creation of a new user record if none found. Defaults to True.
+            * `cache` (Cache, optional): Cache engine to get the cache from
 
         ### Raises:
             * `UserNotFoundError`: User with such ID does not seem to exist in database
         """
-        db_entry: Dict[str, Any] | None = await col_users.find_one({"user": user.id})
+        if cache is not None:
+            cached_entry: Dict[str, Any] | None = cache.get_json(f"user_{user.id}")
+
+            if cached_entry is not None:
+                return cls(**cached_entry)
+
+        db_entry: Dict[str, Any] | None = await col_users.find_one({"id": user.id})
 
         if db_entry is None:
             if not allow_creation:
                 raise UserNotFoundError(user=user, user_id=user.id)
 
-            db_entry = {
+            db_entry = HoloUser.get_defaults(user.id)
-                "user": user.id,
-                "custom_role": None,
-                "custom_channel": None,
-            }
 
             insert_result: InsertOneResult = await col_users.insert_one(db_entry)
 
-            db_entry["_id"] = insert_result.inserted_id()
+            db_entry["_id"] = insert_result.inserted_id
 
-        db_entry["id"] = db_entry.pop("user")
+        if cache is not None:
+            cache.set_json(f"user_{user.id}", db_entry)
 
         return cls(**db_entry)
 
     @classmethod
     async def from_id(cls, user_id: int) -> "HoloUser":
-        return NotImplemented
+        raise NotImplementedError()
 
-    async def get_warnings(self) -> int:
+    async def _set(self, key: str, value: Any, cache: Optional[Cache] = None) -> None:
-        """Get number of warnings user has
-
-        ### Returns:
-            * `int`: Number of warnings
-        """
-        warns: Dict[str, Any] | None = await col_warnings.find_one({"user": self.id})
-
-        return 0 if warns is None else warns["warns"]
-
-    async def warn(self, count: int = 1, reason: str = "Not provided") -> None:
-        """Warn and add count to warns number
-
-        ### Args:
-            * `count` (int, optional): Count of warnings to be added. Defaults to 1.
-        """
-        warns: Dict[str, Any] | None = await col_warnings.find_one({"user": self.id})
-
-        if warns is not None:
-            await col_warnings.update_one(
-                {"_id": self._id},
-                {"$set": {"warns": warns["warns"] + count}},
-            )
-        else:
-            await col_warnings.insert_one(document={"user": self.id, "warns": count})
-
-        logger.info("User %s was warned %s times due to: %s", self.id, count, reason)
-
-    async def _set(self, key: str, value: Any) -> None:
         """Set attribute data and save it into the database
 
         ### Args:
             * `key` (str): Attribute to be changed
             * `value` (Any): Value to set
+            * `cache` (Cache, optional): Cache engine to write the update into
         """
         if not hasattr(self, key):
             raise AttributeError()
@@ -107,40 +89,99 @@ class HoloUser:
             {"_id": self._id}, {"$set": {key: value}}, upsert=True
         )
 
-        logger.info("Set attribute %s of user %s to %s", key, self.id, value)
+        self._update_cache(cache)
 
-    async def _remove(self, key: str) -> None:
+        logger.info("Set attribute '%s' of user %s to '%s'", key, self.id, value)
+
+    async def _remove(self, key: str, cache: Optional[Cache] = None) -> None:
         """Remove attribute data and save it into the database
 
         ### Args:
             * `key` (str): Attribute to be removed
+            * `cache` (Cache, optional): Cache engine to write the update into
         """
         if not hasattr(self, key):
             raise AttributeError()
 
-        setattr(self, key, None)
+        default_value: Any = HoloUser.get_default_value(key)
+
+        setattr(self, key, default_value)
 
         await col_users.update_one(
-            {"_id": self._id}, {"$unset": {key: None}}, upsert=True
+            {"_id": self._id}, {"$set": {key: default_value}}, upsert=True
         )
 
-        logger.info("Removed attribute %s of user %s", key, self.id)
+        self._update_cache(cache)
 
-    async def set_custom_channel(self, channel_id: int) -> None:
+        logger.info("Removed attribute '%s' of user %s", key, self.id)
-        await self._set("custom_channel", channel_id)
 
-    async def set_custom_role(self, role_id: int) -> None:
+    def _get_cache_key(self) -> str:
-        await self._set("custom_role", role_id)
+        return f"user_{self.id}"
 
-    async def remove_custom_channel(self) -> None:
+    def _update_cache(self, cache: Optional[Cache] = None) -> None:
-        await self._remove("custom_channel")
+        if cache is None:
+            return
 
-    async def remove_custom_role(self) -> None:
+        user_dict: Dict[str, Any] = self._to_dict()
-        await self._remove("custom_role")
 
-    async def purge(self) -> None:
+        if user_dict is not None:
-        """Completely remove user data from database. Will not remove transactions logs and warnings."""
+            cache.set_json(self._get_cache_key(), user_dict)
+        else:
+            self._delete_cache(cache)
+
+    def _delete_cache(self, cache: Optional[Cache] = None) -> None:
+        if cache is None:
+            return
+
+        cache.delete(self._get_cache_key())
+
+    @staticmethod
+    def get_defaults(user_id: int | None = None) -> Dict[str, Any]:
+        return {
+            "id": user_id,
+            "custom_role": None,
+            "custom_channel": None,
+        }
+
+    @staticmethod
+    def get_default_value(key: str) -> Any:
+        if key not in HoloUser.get_defaults():
+            raise KeyError(f"There's no default value for key '{key}' in HoloUser")
+
+        return HoloUser.get_defaults()[key]
+
+    def _to_dict(self) -> Dict[str, Any]:
+        return {
+            "_id": self._id,
+            "id": self.id,
+            "custom_role": self.custom_role,
+            "custom_channel": self.custom_channel,
+        }
+
+    async def set_custom_channel(
+        self, channel_id: int, cache: Optional[Cache] = None
+    ) -> None:
+        await self._set("custom_channel", channel_id, cache=cache)
+
+    async def set_custom_role(
+        self, role_id: int, cache: Optional[Cache] = None
+    ) -> None:
+        await self._set("custom_role", role_id, cache=cache)
+
+    async def remove_custom_channel(self, cache: Optional[Cache] = None) -> None:
+        await self._remove("custom_channel", cache=cache)
+
+    async def remove_custom_role(self, cache: Optional[Cache] = None) -> None:
+        await self._remove("custom_role", cache=cache)
+
+    async def purge(self, cache: Optional[Cache] = None) -> None:
+        """Completely remove user data from database. Only removes the user record from users collection.
+
+        ### Args:
+            * `cache` (Cache, optional): Cache engine to write the update into
+        """
         await col_users.delete_one({"_id": self._id})
+        self._delete_cache(cache)
 
     @staticmethod
     async def is_moderator(member: User | Member) -> bool:

cogs/analytics.py

@@ -56,7 +56,7 @@ class Analytics(commands.Cog):
             # Insert entry into the database
             await col_analytics.insert_one(
                 {
-                    "user": message.author.id,
+                    "user_id": message.author.id,
                     "channel": message.channel.id,
                     "content": message.content,
                     "stickers": stickers,

cogs/custom_channels.py

@@ -47,7 +47,9 @@ class CustomChannels(commands.Cog):
 
         Command to create a custom channel for a user.
         """
-        holo_user_ctx: HoloUser = await HoloUser.from_user(ctx.user)
+        holo_user_ctx: HoloUser = await HoloUser.from_user(
+            ctx.user, cache=self.client.cache
+        )
 
         # Return if the user is using the command outside of a guild
         if not hasattr(ctx.author, "guild"):
@@ -100,7 +102,9 @@ class CustomChannels(commands.Cog):
             manage_channels=True,
         )
 
-        await holo_user_ctx.set_custom_channel(created_channel.id)
+        await holo_user_ctx.set_custom_channel(
+            created_channel.id, cache=self.client.cache
+        )
 
         await ctx.respond(
             embed=Embed(
@@ -136,7 +140,9 @@ class CustomChannels(commands.Cog):
 
         Command to change properties of a custom channel.
         """
-        holo_user_ctx: HoloUser = await HoloUser.from_user(ctx.user)
+        holo_user_ctx: HoloUser = await HoloUser.from_user(
+            ctx.user, cache=self.client.cache
+        )
 
         custom_channel: TextChannel | None = ds_utils.get(
             ctx.guild.channels, id=holo_user_ctx.custom_channel
@@ -182,7 +188,9 @@ class CustomChannels(commands.Cog):
         """Command /customchannel remove [<confirm>]
 
         Command to remove a custom channel. Requires additional confirmation."""
-        holo_user_ctx: HoloUser = await HoloUser.from_user(ctx.user)
+        holo_user_ctx: HoloUser = await HoloUser.from_user(
+            ctx.user, cache=self.client.cache
+        )
 
         # Return if the user does not have a custom channel
         if holo_user_ctx.custom_channel is None:
@@ -211,7 +219,7 @@ class CustomChannels(commands.Cog):
                     color=Color.FAIL,
                 )
             )
-            await holo_user_ctx.remove_custom_channel()
+            await holo_user_ctx.remove_custom_channel(cache=self.client.cache)
             return
 
         # Return if the confirmation is missing
@@ -227,7 +235,7 @@ class CustomChannels(commands.Cog):
 
         await custom_channel.delete(reason="Власник запросив видалення")
 
-        await holo_user_ctx.remove_custom_channel()
+        await holo_user_ctx.remove_custom_channel(cache=self.client.cache)
 
         try:
             await ctx.respond(

cogs/data.py

@@ -14,7 +14,6 @@ from libbot.utils import config_get, json_write
 from classes.holo_bot import HoloBot
 from classes.holo_user import HoloUser
 from enums import Color
-from modules.database import col_users
 from modules.utils_sync import guild_name
 
 logger: Logger = logging.getLogger(__name__)
@@ -90,17 +89,19 @@ class Data(commands.Cog):
                     {
                         "id": member.id,
                         "nick": member.nick,
-                        "username": f"{member.name}#{member.discriminator}",
+                        "username": member.name,
                         "bot": member.bot,
                     }
                 )
 
             # Temporary file must be written synchronously,
             # otherwise it will not be there when ctx.respond() is be called
+            # TODO Find a way to give this file to Pycord without FS operations
             json_write(users, Path(f"tmp/{uuid}"))
 
             await ctx.respond(file=File(Path(f"tmp/{uuid}"), filename="users.json"))
 
+    # TODO Deprecate this command
     @data.command(
         name="migrate",
         description="Мігрувати всіх користувачів до бази",
@@ -164,20 +165,7 @@ class Data(commands.Cog):
                 if member.bot:
                     continue
 
-                if (await col_users.find_one({"user": member.id})) is None:
+                await HoloUser.from_user(member, cache=self.client.cache)
-                    user: Dict[str, Any] = {}
-                    defaults: Dict[str, Any] = await config_get("user", "defaults")
-
-                    user["user"] = member.id
-
-                    for key in defaults:
-                        user[key] = defaults[key]
-
-                    await col_users.insert_one(document=user)
-
-                    logging.info(
-                        "Added DB record for user %s during migration", member.id
-                    )
 
         await ctx.respond(
             embed=Embed(

cogs/logger.py

@@ -1,6 +1,5 @@
 import logging
 from logging import Logger
-from typing import Dict, Any
 
 from discord import Member, Message, TextChannel, MessageType
 from discord import utils as ds_utils
@@ -8,6 +7,7 @@ from discord.ext import commands
 from libbot.utils import config_get
 
 from classes.holo_bot import HoloBot
+from classes.holo_user import HoloUser
 from modules.database import col_users
 
 logger: Logger = logging.getLogger(__name__)
@@ -25,16 +25,7 @@ class Logger(commands.Cog):
             and (message.author.bot is False)
             and (message.author.system is False)
         ):
-            if (await col_users.find_one({"user": message.author.id})) is None:
+            await HoloUser.from_user(message.author, cache=self.client.cache)
-                user: Dict[str, Any] = {}
-                defaults: Dict[str, Any] = await config_get("user", "defaults")
-
-                user["user"] = message.author.id
-
-                for key in defaults:
-                    user[key] = defaults[key]
-
-                await col_users.insert_one(document=user)
 
         if (
             (message.type == MessageType.thread_created)
@@ -69,30 +60,21 @@ class Logger(commands.Cog):
             id=await config_get("rules", "channels", "text"),
         )
 
-        if welcome_chan is None:
-            logger.warning("Could not find a welcome channel by its id")
-
         if (
             (member != self.client.user)
             and (member.bot is False)
             and (member.system is False)
         ):
-            await welcome_chan.send(
+            if welcome_chan is not None and rules_chan is not None:
-                content=(await config_get("welcome", "messages")).format(
+                await welcome_chan.send(
-                    mention=member.mention, rules=rules_chan.mention
+                    content=(await config_get("welcome", "messages")).format(
+                        mention=member.mention, rules=rules_chan.mention
+                    )
                 )
-            )
+            else:
+                logger.warning("Could not find a welcome and/or rules channel by id")
 
-            if (await col_users.find_one({"user": member.id})) is None:
+            await HoloUser.from_user(member, cache=self.client.cache)
-                user: Dict[str, Any] = {}
-                defaults: Dict[str, Any] = await config_get("user", "defaults")
-
-                user["user"] = member.id
-
-                for key in defaults:
-                    user[key] = defaults[key]
-
-                await col_users.insert_one(document=user)
 
 
 def setup(client: HoloBot) -> None:

config_example.json

@@ -22,16 +22,20 @@
         "port": 27017,
         "name": "holo_discord"
     },
+    "cache": {
+        "type": null,
+        "memcached": {
+            "uri": "127.0.0.1:11211"
+        },
+        "redis": {
+            "uri": "redis://127.0.0.1:6379/0"
+        }
+    },
     "logging": {
         "size": 512,
         "location": "logs"
     },
-    "defaults": {
+    "defaults": {},
-        "user": {
-            "custom_role": null,
-            "custom_channel": null
-        }
-    },
     "categories": {
         "custom_channels": 0
     },

main.py

@@ -12,8 +12,15 @@ from classes.holo_bot import HoloBot
 from modules.migrator import migrate_database
 from modules.scheduler import scheduler
 
+if not Path("config.json").exists():
+    print(
+        "Config file is missing: Make sure the configuration file 'config.json' is in place.",
+        flush=True,
+    )
+    sys.exit()
+
 logging.basicConfig(
-    level=logging.INFO,
+    level=logging.INFO if not config_get("debug") else logging.DEBUG,
     format="%(name)s.%(funcName)s | %(levelname)s | %(message)s",
     datefmt="[%X]",
 )
@@ -41,12 +48,6 @@ with contextlib.suppress(ImportError):
 
 
 def main() -> None:
-    if not Path("config.json").exists():
-        logger.error(
-            "Config file is missing: Make sure the configuration file 'config.json' is in place."
-        )
-        sys.exit()
-
     # Perform migration if command line argument was provided
     if args.migrate:
         logger.info("Performing migrations...")

migrations/202502092252.py

@@ -0,0 +1,63 @@
+import logging
+from logging import Logger
+
+from libbot.utils import config_set, config_delete
+from mongodb_migrations.base import BaseMigration
+
+logger: Logger = logging.getLogger(__name__)
+
+
+class Migration(BaseMigration):
+    def upgrade(self):
+        try:
+            config_set(
+                "cache",
+                {
+                    "type": None,
+                    "memcached": {"uri": "127.0.0.1:11211"},
+                    "redis": {"uri": "redis://127.0.0.1:6379/0"},
+                },
+                *[],
+            )
+        except Exception as exc:
+            logger.error(
+                "Could not upgrade the config during migration '%s' due to: %s",
+                __name__,
+                exc,
+            )
+
+        self.db.users.update_many(
+            {"user": {"$exists": True}},
+            {"$rename": {"user": "id"}},
+        )
+        self.db.analytics.update_many(
+            {"user": {"$exists": True}},
+            {"$rename": {"user": "user_id"}},
+        )
+        self.db.warnings.update_many(
+            {"user": {"$exists": True}},
+            {"$rename": {"user": "user_id"}},
+        )
+
+    def downgrade(self):
+        try:
+            config_delete("cache", *[])
+        except Exception as exc:
+            logger.error(
+                "Could not downgrade the config during migration '%s' due to: %s",
+                __name__,
+                exc,
+            )
+
+        self.db.users.update_many(
+            {"id": {"$exists": True}},
+            {"$rename": {"id": "user"}},
+        )
+        self.db.analytics.update_many(
+            {"user": {"$exists": True}},
+            {"$rename": {"user_id": "user"}},
+        )
+        self.db.warnings.update_many(
+            {"user": {"$exists": True}},
+            {"$rename": {"user_id": "user"}},
+        )

modules/database.py

@@ -2,9 +2,6 @@ from typing import Dict, Any
 
 from async_pymongo import AsyncClient, AsyncCollection, AsyncDatabase
 from libbot.utils import config_get
-from pymongo import MongoClient
-from pymongo.synchronous.collection import Collection
-from pymongo.synchronous.database import Database
 
 db_config: Dict[str, Any] = config_get("database")
 
@@ -23,18 +20,12 @@ con_string: str = (
 )
 
 db_client: AsyncClient = AsyncClient(con_string)
-db_client_sync: MongoClient = MongoClient(con_string)
 
 # Async declarations per default
 db: AsyncDatabase = db_client.get_database(name=db_config["name"])
 
 col_users: AsyncCollection = db.get_collection("users")
-col_warnings: AsyncCollection = db.get_collection("warnings")
 col_analytics: AsyncCollection = db.get_collection("analytics")
 
-# Sync declarations as a fallback
+# Update indexes
-sync_db: Database = db_client_sync.get_database(name=db_config["name"])
+db.dispatch.get_collection("users").create_index("id", unique=True)
-
-sync_col_users: Collection = sync_db.get_collection("users")
-sync_col_warnings: Collection = sync_db.get_collection("warnings")
-sync_col_analytics: Collection = sync_db.get_collection("analytics")

requirements.txt

@@ -5,7 +5,9 @@ requests>=2.32.2
 aiofiles~=24.1.0
 apscheduler>=3.10.0
 async_pymongo==0.1.11
-libbot[speed,pycord]==4.0.2
+libbot[speed,pycord,cache]==4.1.0
 mongodb-migrations==1.3.1
+pymemcache~=4.0.0
+redis~=5.2.1
 ujson~=5.10.0
 WaifuPicsPython==0.2.0

validation/analytics.json

@@ -1,14 +1,14 @@
 {
     "$jsonSchema": {
         "required": [
-            "user",
+            "user_id",
             "channel",
             "content",
             "stickers",
             "attachments"
         ],
         "properties": {
-            "user": {
+            "user_id": {
                 "bsonType": "long",
                 "description": "Discord ID of user"
             },
@@ -17,7 +17,10 @@
                 "description": "Discord ID of a channel"
             },
             "content": {
-                "bsonType": ["null", "string"],
+                "bsonType": [
+                    "null",
+                    "string"
+                ],
                 "description": "Text of the message"
             },
             "stickers": {
@@ -40,7 +43,7 @@
                         "format": {
                             "bsonType": "array"
                         },
-                        "user": {
+                        "user_id": {
                             "bsonType": "string"
                         }
                     }

validation/users.json

@@ -1,12 +1,12 @@
 {
     "$jsonSchema": {
         "required": [
-            "user",
+            "id",
             "custom_role",
             "custom_channel"
         ],
         "properties": {
-            "user": {
+            "id": {
                 "bsonType": "long",
                 "description": "Discord ID of user"
             },

validation/warnings.json

@@ -1,18 +0,0 @@
-{
-    "$jsonSchema": {
-        "required": [
-            "user",
-            "warnings"
-        ],
-        "properties": {
-            "user": {
-                "bsonType": "long",
-                "description": "Discord ID of user"
-            },
-            "warnings": {
-                "bsonType": "int",
-                "description": "Number of warnings on count"
-            }
-        }
-    }
-}