django-iran-ip 0.2.0

A professional Django package for IP detection with Iran network support

Django Iran IP

یک پکیج حرفه‌ای Django برای شناسایی و مدیریت IP کاربران، با پشتیبانی ویژه از شبکه‌های ایرانی و CDNهای محلی.

ویژگی‌ها

• ✅ شناسایی خودکار IP از هدرهای مختلف (Arvancloud، Cloudflare، و...)
• ✅ پشتیبانی از CDNهای ایرانی (ابرآروان، دراک)
• ✅ Fallback به سرویس‌های خارجی در صورت عدم دسترسی به هدر
• ✅ کش هوشمند برای کاهش درخواست‌های API
• ✅ شناسایی IP‌های ایرانی
• ✅ Geolocation و شناسایی ISP
• ✅ Rate limiting بر اساس IP
• ✅ اعتبارسنجی IP
• ✅ پشتیبانی کامل از IPv4
• ✅ Middleware آماده برای Django
• ✅ سازگار با Django 4.2+ و Python 3.10+

نصب

pip install django-iran-ip

یا با Poetry:

poetry add django-iran-ip

راه‌اندازی سریع

1. اضافه کردن به INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    # ...
    'django_iran_ip',
]

2. اضافه کردن Middleware

# settings.py
MIDDLEWARE = [
    # ...
    'django_iran_ip.contrib.django.middleware.IranIPMiddleware',
]

3. استفاده در View

from django.http import JsonResponse

def my_view(request):
    client_ip = request.client_ip
    
    return JsonResponse({
        'ip': client_ip,
        'is_valid': request.client_ip_valid,
        'type': request.client_ip_type,
        'is_iran': getattr(request, 'is_iran_ip', None),
    })

استفاده بدون Middleware

from django_iran_ip.contrib.django.utils import get_client_ip

def my_view(request):
    client_ip = get_client_ip(request)
    return JsonResponse({'ip': client_ip})

تنظیمات پیشرفته

# settings.py

# استراتژی‌های شناسایی IP (به ترتیب اولویت)
IRAN_IP_STRATEGIES = [
    'django_iran_ip.core.strategies.HeaderStrategy',
    'django_iran_ip.core.strategies.ServiceStrategy',
]

# سرویس‌های خارجی برای دریافت IP
IRAN_IP_SERVICE_URLS = [
    "https://api.ipify.org",
    "https://ifconfig.me/ip",
    "https://icanhazip.com",
]

# استفاده از سرویس‌های ایرانی
IRAN_IP_USE_IRAN_SERVICES = True

# فعال‌سازی کش
IRAN_IP_ENABLE_CACHE = True
IRAN_IP_CACHE_DURATION = 3600  # 1 ساعت

# تایم‌اوت درخواست‌ها
IRAN_IP_REQUEST_TIMEOUT = 3.0

# اعتبارسنجی IP
IRAN_IP_VALIDATE_IP = True

# بررسی IP ایرانی
IRAN_IP_CHECK_IRAN_IP = True

# مسدود کردن IP‌های غیر ایرانی (اختیاری)
IRAN_IP_BLOCK_NON_IRAN_IP = False

# فعال‌سازی Geolocation
IRAN_IP_ENABLE_GEOLOCATION = True

# سطح لاگ
IRAN_IP_LOG_LEVEL = 'INFO'  # DEBUG, INFO, WARNING, ERROR

# اولویت هدرها
IRAN_IP_HEADER_PRIORITY = [
    'HTTP_AR_REAL_IP',       # ابرآروان
    'HTTP_X_REAL_IP',        # دراک
    'HTTP_CF_CONNECTING_IP', # کلودفلر
    'HTTP_X_FORWARDED_FOR',
    'REMOTE_ADDR',
]

🛡️ امنیت و جلوگیری از جعل IP (Anti-Spoofing)

از نسخه 0.2.0، این پکیج به مکانیزم پیشرفته Chain of Trust مجهز شده است تا از حملات جعل IP (IP Spoofing) جلوگیری کند.

• ✅ تشخیص هوشمند IP واقعی حتی در پشت Cloudflare، ArvanCloud و Load Balancerها.
• ✅ قابلیت تعریف TRUSTED_PROXIES برای امنیت حداکثری.
• ✅ الگوریتم Right-to-Left برای نادیده گرفتن هدرهای جعلی (X-Forwarded-For).

📖 برای مطالعه مستندات کامل امنیتی و نحوه پیکربندی، اینجا کلیک کنید

استفاده پیشرفته

1. شناسایی IP ایرانی

from django_iran_ip.core.validators import IranIPChecker

checker = IranIPChecker()
is_iran = checker.is_iran_ip("5.22.10.20")  # True
print(f"IP is from Iran: {is_iran}")

2. دریافت اطلاعات جغرافیایی

from django_iran_ip.core.validators import IPGeolocation

geo = IPGeolocation()
info = geo.get_location("8.8.8.8")
print(info)
# {
#     'country': 'United States',
#     'country_code': 'US',
#     'city': 'Mountain View',
#     'isp': 'Google LLC',
#     'timezone': 'America/Los_Angeles'
# }

3. اعتبارسنجی IP

from django_iran_ip.core.validators import IPValidator

validator = IPValidator()
print(validator.is_valid_ipv4("192.168.1.1"))  # True
print(validator.is_private_ip("192.168.1.1"))  # True
print(validator.get_ip_type("8.8.8.8"))  # "public"

4. استفاده از استراتژی‌های سفارشی

from django_iran_ip.core.resolver import IPResolver
from django_iran_ip.core.strategies import HeaderStrategy, ServiceStrategy

# استفاده از استراتژی خاص
resolver = IPResolver(strategies=[
    HeaderStrategy(),
    ServiceStrategy(timeout=5.0)
])

ip = resolver.get_client_ip(request)

5. دریافت اطلاعات کامل

from django_iran_ip.core.resolver import IPResolver

resolver = IPResolver()
info = resolver.get_client_info(request)
print(info)
# {
#     'ip': '5.22.10.20',
#     'strategy_used': 'HeaderStrategy',
#     'is_valid': True
# }

Middleware‌های اضافی

1. Logging Middleware

# settings.py
MIDDLEWARE = [
    'django_iran_ip.contrib.django.middleware.IranIPLoggingMiddleware',
    # ...
]

2. Rate Limiting Middleware

# settings.py
MIDDLEWARE = [
    'django_iran_ip.contrib.django.middleware.IranIPRateLimitMiddleware',
    # ...
]

# تنظیمات Rate Limit
IRAN_IP_RATE_LIMIT = 100  # تعداد درخواست
IRAN_IP_RATE_PERIOD = 3600  # بازه زمانی (ثانیه)

مثال‌های کاربردی

محدود کردن دسترسی به IP‌های ایرانی

from django.http import HttpResponseForbidden
from django_iran_ip.core.validators import IranIPChecker

def iran_only_view(request):
    checker = IranIPChecker()
    
    if not checker.is_iran_ip(request.client_ip):
        return HttpResponseForbidden("فقط کاربران ایرانی مجاز هستند")
    
    return render(request, 'template.html')

نمایش اطلاعات کاربر

def user_info_view(request):
    context = {
        'ip': request.client_ip,
        'is_iran': getattr(request, 'is_iran_ip', False),
        'geo': getattr(request, 'client_geo', {}),
    }
    return render(request, 'user_info.html', context)

CDN‌های پشتیبانی شده

• ✅ ابرآروان (Arvancloud)
• ✅ دراک (Derak)
• ✅ کلودفلر (Cloudflare)
• ✅ Akamai
• ✅ و سایر CDNهای استاندارد

عیب‌یابی

IP شناسایی نمی‌شود

1. بررسی کنید Middleware به درستی اضافه شده است
2. سطح لاگ را به DEBUG تغییر دهید:

   IRAN_IP_LOG_LEVEL = 'DEBUG'
   

3. در لاگ‌ها بررسی کنید کدام استراتژی در حال اجرا است

IP اشتباه شناسایی می‌شود

اولویت هدرها را بررسی کنید. برای CDN‌های ایرانی:

IRAN_IP_HEADER_PRIORITY = [
    'HTTP_AR_REAL_IP',       # ابرآروان را اول قرار دهید
    'HTTP_X_REAL_IP',
    'HTTP_CF_CONNECTING_IP',
    'REMOTE_ADDR',
]

مشارکت

مشارکت‌ها همیشه خوش‌آمد هستند! لطفاً:

1. مخزن را Fork کنید
2. یک branch جدید بسازید (git checkout -b feature/amazing-feature)
3. تغییرات خود را commit کنید (git commit -m 'Add amazing feature')
4. به branch خود push کنید (git push origin feature/amazing-feature)
5. یک Pull Request باز کنید

لایسنس

MIT License - برای جزئیات بیشتر فایل LICENSE را ببینید.

پشتیبانی

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Documentation

تغییرات نسخه‌ها

نسخه 0.1.0

• اولین انتشار
• پشتیبانی از شناسایی IP از هدرهای مختلف
• Fallback به سرویس‌های API
• پشتیبانی از CDN‌های ایرانی
• کش هوشمند
• Middleware آماده

---

ساخته شده با ❤️ برای جامعه توسعه‌دهندگان ایرانی