Import documentation: v3/Tele2Rub/GEMINI.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
2026-09-18 23:14:03 +03:30
parent fc16c47343
commit fc53d6f073
1 changed files with 48 additions and 0 deletions
@@ -0,0 +1,48 @@
+# Tele2Rub
+
+## Project Overview
+**Tele2Rub** is a Python-based utility bot that automatically forwards files and direct download URLs from Telegram to a Rubika account's Saved Messages. It is designed with a lightweight queue system to prevent crashes and handle large files (up to 2GB) efficiently. The project is an optimized version of the original `caffeinexz/Tele2Rub`.
+
+### Architecture & Components
+- **`telebot.py`**: A Telegram bot built with `pyrogram`. It listens for incoming files or direct download links from the user, downloads the media locally to a `downloads/` folder, and registers the upload task into a local queue.
+- **`rub.py`**: A worker script built with `rubpy`. It constantly polls the task queue, optionally processes the file (e.g., zipping it with a password if "Safe Mode" is enabled via `pyzipper`), and uploads the file to Rubika's Saved Messages.
+- **`main.py`**: The main entry point that spawns and manages both the Telegram bot (`telebot.py`) and the Rubika worker (`rub.py`) as concurrent subprocesses.
+- **Queue System**: Uses JSON Lines (`.jsonl`) files stored in the `queue/` directory (`tasks.jsonl`, `status.jsonl`, `cancelled.jsonl`, etc.) to track pending, processing, and failed uploads.
+
+## Building and Running
+
+### Prerequisites
+- Python 3.10+
+- Telegram API ID and API Hash (from my.telegram.org)
+- Telegram Bot Token (from BotFather)
+- Rubika Session
+
+### Setup Instructions
+1. **Clone & Virtual Environment**:
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate
+   ```
+2. **Install Dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. **Configuration**:
+   Create a `.env` file in the project root with the following variables:
+   ```env
+   API_ID=your_api_id
+   API_HASH=your_api_hash
+   BOT_TOKEN=your_bot_token
+   RUBIKA_SESSION=rubsession
+   ```
+4. **Run the Project**:
+   ```bash
+   python main.py
+   ```
+   *(On the first run, the Rubika worker will prompt for your phone number and SMS code to generate the session file).*
+
+## Development Conventions
+- **Queue Files**: State is managed via text files in the `queue/` directory. Be careful with concurrent reads/writes; the system primarily relies on simple file appends and whole-file rewrites.
+- **Safe Mode**: Users can toggle a safe mode that encrypts files into a password-protected `.zip` before uploading to Rubika, handled using `pyzipper`.
+- **Error Handling**: The Rubika upload logic contains transient error handling (e.g., for 502/503 errors) and retries up to 3 times with exponential backoff.
+- **Cleanups**: Downloaded and compressed files are cleaned up asynchronously upon successful upload or fatal error.