{"id":26513210,"url":"https://github.com/paulsonlegacy/conexia","last_synced_at":"2025-03-21T04:27:47.168Z","repository":{"id":275211149,"uuid":"925387364","full_name":"paulsonlegacy/conexia","owner":"paulsonlegacy","description":"A Python library for resolving network information via STUN servers, and designed for seamless integration with backend frameworks.","archived":false,"fork":false,"pushed_at":"2025-02-17T09:41:38.000Z","size":94,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-17T10:31:35.002Z","etag":null,"topics":["backend-api","connection","ip","network","python","stun"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulsonlegacy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-31T19:29:06.000Z","updated_at":"2025-02-17T09:41:41.000Z","dependencies_parsed_at":"2025-02-17T10:36:49.194Z","dependency_job_id":null,"html_url":"https://github.com/paulsonlegacy/conexia","commit_stats":null,"previous_names":["paulsonlegacy/stun-ip-resolver","paulsonlegacy/conexio","paulsonlegacy/conexia"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulsonlegacy%2Fconexia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulsonlegacy%2Fconexia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulsonlegacy%2Fconexia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulsonlegacy%2Fconexia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulsonlegacy","download_url":"https://codeload.github.com/paulsonlegacy/conexia/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244736172,"owners_count":20501431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend-api","connection","ip","network","python","stun"],"created_at":"2025-03-21T04:27:46.668Z","updated_at":"2025-03-21T04:27:47.152Z","avatar_url":"https://github.com/paulsonlegacy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **📜 conexia**  \n\nA Python library for fetching and caching a device's real **public IP address** using STUN (Session Traversal Utilities for NAT) servers. Supports **Redis, SQLite, File-based, and In-Memory caching** for fast lookups.\n\n📌 **Why Use This?**  \n\n- Identifies real **public IP address** even behind NAT.\n- Optional caching feature\n- Provides **multiple cache backends** (Redis, SQLite, File, Memory).\n- Provide middleware support for Django and Flask\n- Implement caching mechanisms for performance optimization\n- Additional network parameters in fetched stun info - region, country, cordinates, timezone, ISP info etc\n\n---\n\n## **📦 Installation**  \n\n```bash\npip install conexia\n```\n\nor install from source: \n\n```bash\ngit clone https://github.com/paulsonlegacy/conexia.git\ncd conexia\npip install .\n```\n\n---\n\n## **⚡ Usage**\n### **Basic Example**\n```python\nfrom conexia.core import STUNClient\n\n# Initialize engine\nclient = STUNClient()\n\n# Fetch full network info\nnetwork_info = client.get_network_info()\n\n# Fetch IP\nip = client.get_public_ip()\n\n# Fetch port\nport = client.get_public_port()\n\n# Fetch NAT type\nnat_type = client.get_nat_type()\n\n# Fetch city\ncity = client.get_city()\n\n# Fetch region\nregion = client.get_region()\n\n# Fetch country\ncountry = client.get_country()\n\n# Fetch continent\ncontinent = client.get_continent()\n\n# Fetch cordinate\ncordinate = client.get_cordinate()\n\n# Fetch ISP info\nisp_info = client.get_isp_info()\n\n# Fetch timezone\ntimezone = client.get_timezone()\n\n# Print full data\nprint(network_info)\n```\n\n**Or run via command line after installation**\n\n```\nconexia\n```\n\n📌 **Output (Example)**  \n```json\n{\n    'user_id': '667bd38c-e702-4295-9650-3afe5bacc361', \n    'data': {\n        'ip': '102.90.100.117', \n        'port': 10134, \n        'nat_type': 'Full Cone', \n        'city': 'Port Harcourt', \n        'region': 'Rivers State', \n        'country': 'NG',\n        'continent': 'Africa',\n        'cord': '4.7774,7.0134', \n        'isp_info': 'MTN NIGERIA Communication limited', \n        'timezone': 'Africa/Lagos'\n        }, \n    'timestamp': 1739771764.9438107\n}\n```\n\n*NB - User ID is optional as it is automatically generated if not provided*\n\n---\n\n## **🔌 Integrating with Django**\n\n1️⃣ Install the package\n\n```bash\npip install conexia\n```\n\n2️⃣ Enable the STUN Middleware in settings.py \nModify settings.py to activate the middleware and configure caching options:\n\n```python\n# settings.py\nMIDDLEWARE = [\n    \"django.middleware.security.SecurityMiddleware\",\n    \"django.contrib.sessions.middleware.SessionMiddleware\",\n    \"django.middleware.common.CommonMiddleware\",\n    \"django.middleware.csrf.CsrfViewMiddleware\",\n    \"django.contrib.auth.middleware.AuthenticationMiddleware\",\n    \"django.contrib.messages.middleware.MessageMiddleware\",\n    \"django.middleware.clickjacking.XFrameOptionsMiddleware\",\n    \n    # ✅ Add Conexia Middleware\n    \"conexia.middleware.django.STUNMiddleware\",\n]\n\n# STUN Configuration\nSTUN_CACHE_BACKEND = \"sqlite\"  # Options: \"memory\", \"file\", \"sqlite\", \"redis\"\nSTUN_CACHE_TTL = 300  # Cache expiry in seconds\n```\n\n3️⃣ Access STUN data inside Django Views \nOnce the middleware is enabled, every request object will have the following attributes: \n\n```python\nfrom django.http import JsonResponse\n\ndef sample_view(request):\n    return JsonResponse({\n        \"ip\": request.ip,\n        \"port\": request.port,\n        \"nat_type\": request.nat_type,\n        \"city\": request.city,\n        \"region\": request.region,\n        \"country\": request.country,\n        \"continent\": request.continent,\n        \"timezone\": request.timezone\n    })\n```\n\n---\n\n## **🌐 Integrating with Flask**\n\n### 📌 Flask Integration Via Middleware\n\n1️⃣ Install Flask and Conexia if you haven’t already\n\n```bash\npip install flask conexia\n```\n\n2️⃣ Create app.py with the STUN middleware\n\n```python\nfrom flask import Flask, jsonify, g\nfrom conexia.core import STUNClient\nfrom stun_middleware import STUNMiddleware  # Import the middleware\n\napp = Flask(__name__)\n\n# Attach STUN Middleware with configurable options\nSTUNMiddleware(\n    app, \n    cache_backend=\"redis\",  # Change cache backend if needed (file, memory, etc.)\n    ttl=300  # Set TTL for STUN data caching\n)\n\n@app.route(\"/get_ip\")\ndef get_ip():\n    return jsonify({\n        \"user_id\": g.get(\"user_id\"),\n        \"ip\": g.get(\"ip\"),\n        \"port\": g.get(\"port\"),\n        \"nat_type\": g.get(\"nat_type\"),\n        \"city\": g.get(\"city\"),\n        \"region\": g.get(\"region\"),\n        \"country\": g.get(\"country\"),\n        \"continent\": g.get(\"continent\"),\n        \"timezone\": g.get(\"timezone\")\n    })\n\nif __name__ == \"__main__\":\n    app.run(debug=True)  # Runs synchronously with Flask's built-in server\n```\n\n3️⃣ Run the Server \nRun the application using Flask's built-in WSGI server:\n\n```bash\npython app.py\n```\n\nFlask will start at:\n\n```bash\nhttp://127.0.0.1:5000\n```\n\n4️⃣ Test API in Browser or Postman \nYou can test the STUN attributes by making a request:\n\n```bash\nhttp://127.0.0.1:5000/get_ip\n```\n\nExample response:\n\n```json\n{\n'ip': '102.90.100.117', \n'port': 10134, \n'nat_type': 'Full Cone', \n'city': 'Port Harcourt', \n'region': 'Rivers State', \n'country': 'NG',\n'continent': 'Africa',\n'timezone': 'Africa/Lagos'\n}\n```\n\n### ✅ Alternative: Using Flask Hooks for STUN Info\n\nIf you prefer adding STUN information manually before each request, you can do:\n\n```python\nfrom flask import Flask, g, request\nfrom conexia.core import STUNClient\n\napp = Flask(__name__)\nstun_client = STUNClient(backend=\"redis\", ttl=300)\n\n@app.before_request\ndef attach_stun_data():\n    user_id = request.args.get(\"user_id\", \"default_id\")\n    stun_info = stun_client.get_network_info(user_id)\n    g.ip = stun_info['data']['ip']\n    g.port = stun_info['data']['port']\n    g.nat_type = stun_info['data']['nat_type']\n    g.user_id = user_id  # Store user ID in Flask's request context\n\n@app.route(\"/get_ip\")\ndef get_ip():\n    return jsonify({\n        \"ip\": g.get(\"ip\"),\n        \"port\": g.get(\"port\"),\n        \"nat_type\": g.get(\"nat_type\"),\n        \"user_id\": g.get(\"user_id\")\n    })\n\nif __name__ == \"__main__\":\n    app.run(debug=True)\n```\n\nThis approach attaches STUN data before every request without requiring custom middleware.\n\n**Conclusion:** \n\n✅ Middleware automatically attaches STUN data \n\n✅ Flask hooks can be used as an alternative \n\n✅ Works natively with Flask (no async needed) \n\n---\n\n## **💾 Available Cache Backends**\n\n| Cache Backend | Description |\n|--------------|------------|\n| `memory` | Uses in-memory cache (Fast but not persistent). |\n| `file` | Saves cached data in `cache.json` (Persistent across restarts). |\n| `sqlite` | Uses an SQLite database for efficient storage. |\n| `redis` | Uses Redis for distributed caching. |\n\nNB - Default is *file*\n\n---\n\n## **🔧 Clearing Cache**\n\nClear cache for a specific user ID:  \n```python\nstun_client.clear_cache(user_id=\"device123\")\n```\n\nClear **all** cached data:\n\n```python\nstun_client.clear_cache()\n```\n\n---\n\n## **📜 License**\n\nThis project is licensed under the MIT License.\n\n---\n\n## **👨‍💻 Contributing**\n\n1️⃣ **Fork the repository**  \n2️⃣ **Clone your fork**  \n\n```bash\ngit clone https://github.com/paulsonlegacy/conexia.git\ncd conexia\n```\n\n3️⃣ **Create a feature branch** \n\n```bash\ngit checkout -b feature-name\n```\n\n4️⃣ **Submit a pull request!** 🚀\n\n---\n\n## **🙌 Acknowledgments**\n\n🎉 **This library is specially dedicated to my mom - Monica A. Bosah, whose support made this possible; and to Engr. Hussein Nasser who not only sparked the idea that birthed this library through his backend engineering course on Udemy, but impacted in me alot through his wealth of knowledge, thinking and approach to solving problems** ❤️ \n\n---\n\n## **🚀 Next Steps**\n\n- [ ] Implement a simple WebSocket signaling server.\n- [ ] Extend conexia to generate ICE candidates \u0026 SDP.\n- [ ] Test peer-to-peer chat by exchanging SDP via WebSocket.\n- [ ] Package a CLI tool to allow remote users to connect and chat.\n- [ ] Remote file sharing.\n\n---\n\n### **💡 Want More Features?**\n\nIf you have feature suggestions or bugs, open an issue on **[GitHub](https://github.com/paulsonlegacy/conexia/issues)**! 🚀  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulsonlegacy%2Fconexia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulsonlegacy%2Fconexia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulsonlegacy%2Fconexia/lists"}