⚡ TWP (Telegram Worker Proxy) Core

پروژه TWP (Telegram Worker Proxy) یک هسته سبک، ماژولار و متن‌باز برای انتقال ترافیک پروتکل MTProto تلگرام از طریق شبکه توزیع‌شده Cloudflare Workers است.

این مخزن به عنوان هسته مرجع (Reference Core Implementation) و مستندات پروتکل عمل می‌کند و به توسعه‌دهندگان، سازندگان کلاینت‌های تلگرام و مدیران شبکه این امکان را می‌دهد تا بدون نیاز به سرورهای سنتی VPS، ارتباطی امن، ضد فیلتر و پرسرعت را میان کلاینت‌های تلگرام و دیتاسنترهای رسمی برقرار کنند.

sequenceDiagram
    autonumber
    participant Client as 🖥️ Telegram Client (TWP Core Socket)
    participant Worker as ☁️ Cloudflare Worker (worker.js)
    participant DC as 🏢 Telegram Datacenter (149.154.167.x)

    Note over Client,Worker: لایه امن TLS روی پورت استاندارد ۴۴۳
    Client->>Worker: 1. WSS Handshake (GET /?ip=<DC_IP>&port=443)
    Worker-->>Client: 2. 101 Switching Protocols
    Worker->>DC: 3. TCP Connect (cloudflare:sockets)
    
    loop تبادل بسته‌های MTProto
        Client->>Worker: 4. RFC 6455 Binary Frame (Masked MTProto Payload)
        Worker->>DC: 5. Raw TCP Byte Stream
        DC-->>Worker: 6. Raw TCP Byte Stream (MTProto Response)
        Worker-->>Client: 7. RFC 6455 Binary Frame (Unmasked MTProto Response)
    end

موتور سرور یک اسکریپت مستقل جاوااسکریپت برای محیط رانتایم Cloudflare Workers است. این موتور:

1. ارتباط وب‌سوکت دوطرفه امن (Full-Duplex WSS) را با کلاینت برقرار می‌کند.
2. با استفاده از ماژول استاندارد cloudflare:sockets، یک سوکت خام TCP به IP و پورت دیتاسنتر مورد نظر تلگرام باز می‌کند.
3. با استفاده از بافرهای ArrayBuffer و مدیریت هوشمند جریان داده، پکت‌ها را با کمترین تأخیر ممکن (Zero-Copy Streaming) بین دو سوکت رد و بدل می‌کند.
4. در صورت اتصال مرورگر به آدرس ورکر، یک صفحه وب سبک برای تست وضعیت و مشخصات سرور نمایش می‌دهد.

# ۱. کلون کردن ریپازیتوری
git clone https://github.com/your-username/TWP.git
cd TWP

# ۲. ورود به اکانت کلادفلر
npx wrangler login

# ۳. استقرار فوری
npx wrangler deploy

یا کپی کردن مستقیم محتوای worker.js در ویرایشگر داشبورد Cloudflare.

توسعه‌دهندگان کلاینت‌های تلگرام (شامل Telegram Desktop، تلگرام‌های غیررسمی اندروید، ربات‌ها و ابزارهای واسط) می‌توانند از کدهای آماده پوشه client/src/ استفاده کنند:

• mtproto_worker_socket.h: تعریف کلاس سوکت کلاینت با متدهای استاندارد AbstractSocket.
• mtproto_worker_socket.cpp: پیاده‌سازی کامل استتار فریم‌ها، ماسک تصادفی ۴ بایتی، و تبدیل دیتای خام به WSS.
• integration_guide.md: راهنمای گام‌به‌گام تزریق کد به پروژه‌های مبتنی بر Qt / C++.

پروتکل TWP ساختار صوری یا شمای لینک ثابتی به کلاینت‌ها تحمیل نمی‌کند؛ معیار اصلی، انطباق پارامترهای تنظیمی کلاینت با لایه ورودی موتور worker.js و هندشیک استاندارد WebSocket است. کلاینت‌ها و برنامه‌های واسط مختارند پارامترهای اتصال را از طریق هر فرمت آدرس‌دهی استاندارد (مانند الگوهای مرسوم RFC 3986 یا لینک‌های سفارشی کلاینت) دریافت و پردازش نمایند.

برای جزئیات دقیق هندشیک ارتقای پروتکل (RFC 6455 Upgrade) و ساختار فریم‌بندی باینری به docs/PROTOCOL.md مراجعه فرمایید.

TWP (Telegram Worker Proxy) is an open-source, modular, high-performance reference core designed to tunnel Telegram MTProto network traffic through the Cloudflare Workers globally distributed serverless edge via secure WebSockets (WSS).

This repository serves as both the Reference Core Implementation and the Official Protocol Specification, enabling developers, custom Telegram client maintainers, and network engineers to establish secure, censorship-resistant, low-latency connections to official Telegram Datacenters without requiring traditional VPS servers.

• Zero VPS Cost: Runs entirely on Cloudflare Workers serverless edge (free tier compatible).
• DPI-Immune Transport: Pure HTTPS / WSS traffic over standard Port 443 with TLS 1.3 encryption (RFC 6455 binary framing).
• Global Anycast Routing: Automatically routes through the nearest Cloudflare edge PoP (200+ cities globally).
• Zero-Copy Streaming: High-efficiency binary bridging between cloudflare:sockets TCP streams and WebSocket frames.

sequenceDiagram
    autonumber
    participant Client as 🖥️ Telegram Client (TWP Core Socket)
    participant Worker as ☁️ Cloudflare Worker (worker.js)
    participant DC as 🏢 Telegram Datacenter (149.154.167.x)

    Note over Client,Worker: Secure TLS 1.3 Session over Port 443
    Client->>Worker: 1. WSS Handshake (GET /?ip=<DC_IP>&port=443)
    Worker-->>Client: 2. 101 Switching Protocols
    Worker->>DC: 3. Direct TCP Connect (cloudflare:sockets)
    
    loop MTProto Packet Stream
        Client->>Worker: 4. RFC 6455 Binary Frame (Masked MTProto Payload)
        Worker->>DC: 5. Raw TCP Byte Stream
        DC-->>Worker: 6. Raw TCP Byte Stream (MTProto Response)
        Worker-->>Client: 7. RFC 6455 Binary Frame (Unmasked MTProto Response)
    end

# 1. Clone repository
git clone https://github.com/Qorvhex/TWP.git
cd TWP

# 2. Authenticate with Cloudflare
npx wrangler login

# 3. Deploy worker
npx wrangler deploy

1. Log in to Cloudflare Dashboard.
2. Navigate to Workers & Pages > Create application > Create Worker.
3. Replace the default template with worker.js and click Save and deploy.
4. (Optional) Add a secret under Settings > Variables and Secrets named SECRET for access control.

Developers of custom Telegram clients (Telegram Desktop, Android forks, and bridge apps such as Bifrost) can integrate the reference C++ implementation from client/src/:

• mtproto_worker_socket.h: Socket header matching Telegram's AbstractSocket interface.
• mtproto_worker_socket.cpp: RFC 6455 frame obfuscation, 4-byte cryptographic masking, and raw-to-WSS conversion.
• integration_guide.md: Step-by-step injection guide for Qt/C++ Telegram codebases.

The TWP core does not enforce a rigid URI scheme; clients are free to use any standard URI convention (e.g., RFC 3986 or custom deep links) as long as the parameters match the inputs expected by worker.js:

جهت دریافت آخرین اخبار، به‌روزرسانی‌های هسته TWP، آموزش‌ها و آی‌پی‌های تمیز کلادفلر به کانال رسمی تلگرام بپیوندید:

این هسته تحت مجوز MIT License منتشر شده است و هرگونه استفاده، توسعه یا ادغام آن در کلاینت‌های تجاری و متن‌باز بلامانع است.