graphxr-database-proxy 1.0.0__tar.gz

graphxr_database_proxy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kineviz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphxr_database_proxy-1.0.0/MANIFEST.in

@@ -0,0 +1,28 @@
+# 包含静态文件
+recursive-include src/graphxr_database_proxy/static *
+
+# 包含文档文件
+include README.md
+include LICENSE
+include *.md
+
+# 包含配置文件
+include pyproject.toml
+include requirements.txt
+
+# 包含示例和文档
+recursive-include examples *.py
+recursive-include doc *.md
+
+# 排除不需要的文件
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *~
+global-exclude .git*
+global-exclude .env*
+prune .venv
+prune __pycache__
+prune .pytest_cache
+prune node_modules
+prune frontend/node_modules
+prune frontend/.webpack-cache

graphxr_database_proxy-1.0.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: graphxr-database-proxy
+Version: 1.0.0
+Summary: GraphXR Database Proxy - Secure middleware for connecting GraphXR to databases
+Author-email: Sean Li <sean@kineviz.com>, Kineviz <support@kineviz.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Kineviz/graphxr-database-proxy
+Project-URL: Documentation, https://docs.kineviz.com/graphxr-database-proxy
+Project-URL: Repository, https://github.com/Kineviz/graphxr-database-proxy
+Project-URL: Bug Tracker, https://github.com/Kineviz/graphxr-database-proxy/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: google-cloud-spanner>=3.40.0
+Requires-Dist: google-auth-oauthlib>=1.0.0
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: ui
+Requires-Dist: aiofiles>=23.0.0; extra == "ui"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: graphxr-database-proxy[dev,ui]; extra == "all"
+Dynamic: license-file
+
+# GraphXR Database Proxy
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)](https://fastapi.tiangolo.com)
+
+> **Language**: [English](https://github.com/Kineviz/graphxr-database-proxy/readme.md) | [中文](https://github.com/Kineviz/graphxr-database-proxy/readme.zh.md)
+
+A secure middleware that connects [GraphXR](https://www.kineviz.com/graphxr) to various backend databases with zero trust architecture.
+
+## Features
+
+- **Zero Trust Security**: Strict authentication and authorization at the proxy layer
+- **Direct Browser Connectivity**: REST/GraphQL APIs for efficient data access
+- **Multi-Database Support**: Spanner Graph, Neo4j, and more
+- **Open Source**: Fully auditable and customizable
+- **Pure Python**: Easy to deploy and maintain
+
+## ⚡ Quick Start for Spanner Graph
+
+1. Run the following commands to start graphxr-database-proxy (requires [uv](https://docs.astral.sh/uv/), [node.js](https://nodejs.org/en/download/))
+
+```
+git clone https://github.com/Kineviz/graphxr-database-proxy.git
+cd graphxr-database-proxy
+uv venv
+source .venv/bin/activate # or .venv/bin/activate on Windows
+uv pip install -e ".[ui]"
+uv pip install -r requirements.txt
+cd frontend && npm install && npm run build && cd -
+graphxr-proxy --ui 
+```
+
+2. Visit http://localhost:9080/
+3. Click "Create New Project"
+4. Project Name: "Test"
+5. Database Type: "Google Cloud Spanner"
+6. Authentication Type: "Service Account"
+7. Upload the credential file you exported from GCP Console or gcloud CLI. [Export Instructions](https://github.com/Kineviz/try-graphxr-spannergraph#)
+8. Select "Instance ID" e.g. "demo"
+9. Select "Database ID" e.g. "cymbal"
+10. Select "Property Graph" e.g. "ECommerceGraph"
+11. Click "Create"
+12. For the new project, under Actions, copy the API URL. e.g. "http://localhost:9080/api/spanner/Test"
+13. Go back to GraphXR's Create Project wizard and paste the API URL into GraphXR for a project with a "Database Proxy" database type.
+
+## Other ways to start graphxr-database-proxy
+
+### Install
+
+```bash
+# Install from PyPI
+pip install graphxr-database-proxy[ui]
+
+# Or from source
+git clone https://github.com/Kineviz/graphxr-database-proxy.git
+cd graphxr-database-proxy
+uv venv
+source .venv/bin/activate # or .venv/bin/activate on Windows
+uv pip install -e ".[ui]"
+uv pip install -r requirements.txt
+cd frontend && npm install && npm run build && cd -
+pip install -e .[ui]
+```
+
+### Configure & Run
+
+**Option 1: Web UI (Recommended)**
+```bash
+graphxr-proxy --ui
+```
+> Open http://localhost:9080/admin for configuration
+
+**Option 2: Python Code**
+```python
+from graphxr_database_proxy import DatabaseProxy
+
+proxy = DatabaseProxy()
+
+service_account_json = {
+    "type": "service_account",
+    "project_id": "your-gcp-project-id",
+    "private_key": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n",
+    "client_email": "your-service-account@your-gcp-project-id.iam.gserviceaccount.com",
+    ...
+}
+
+project_id = proxy.add_project(
+    project_name="project_name",
+    database_type="spanner",
+    project_id="gcp-project-id", 
+    instance_id="spanner-instance-id",
+    database_id="spanner-database-id",
+    credentials=service_account_json,  
+    graph_name="graph_name"  # Optional
+)
+
+proxy.start(
+    host="0.0.0.0",     
+    port=9080,          
+    show_apis=True     
+)
+```
+
+## 🐳 Docker
+
+```bash
+docker run -d -p 9080:9080 \
+--name graphxr-database-proxy \
+-v ${HOME}/graphxr-database-proxy/config:/app/config \
+kineviz/graphxr-database-proxy:latest
+```
+> You can visit http://localhost:9080/admin for configuration after starting the container.
+
+
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- 🐛 [Issue Tracker](https://github.com/Kineviz/graphxr-database-proxy/issues)
+- 📧 Email: support@kineviz.com
+
+---
+
+**Built with ❤️ by [Kineviz](https://www.kineviz.com)**

graphxr_database_proxy-1.0.0/doc/DEV_GUIDE.md

@@ -0,0 +1,60 @@
+# Development Environment Guide
+
+> **Language**: [English](https://github.com/Kineviz/graphxr-database-proxy/doc/DEV_GUIDE.md) | [中文](https://github.com/Kineviz/graphxr-database-proxy/doc/DEV_GUIDE.zh.md)
+
+## 🚀 Quick Start
+
+### One-Click Development Environment
+```bash
+npm run dev            # Start both frontend and backend (recommended)
+```
+This command will start:
+- **Backend Server** (Python FastAPI): http://localhost:9080
+- **Frontend Development Server** (React): http://localhost:3002
+
+### Start Services Separately
+```bash
+npm run dev:backend    # Start backend only
+npm run dev:frontend   # Start frontend only
+```
+
+
+## 🔧 Development Environment Features
+
+### Hot Reload
+- **Python Code Changes**: Backend server automatically restarts
+- **React Component Changes**: Browser automatically refreshes, maintains state
+- **Configuration File Changes**: Automatically detects and restarts appropriate services
+
+### Monitored File Types
+- **Backend**: `.py`, `.json`, `.toml`, `.txt` files
+- **Frontend**: `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss` files
+
+### Port Configuration
+- **Backend API**: 9080
+- **Frontend Development Server**: 3002 (automatically proxies API to 9080)
+- **API Documentation**: http://localhost:9080/docs
+
+## 🐛 Development Debugging
+
+### View Logs
+Development environment displays detailed log information:
+- **Backend Logs**: uvicorn + FastAPI request logs
+- **Frontend Logs**: webpack build and hot reload logs
+
+### Restart Services
+In the nodemon console, type `rs` to manually restart the backend service.
+
+### Common Issues
+1. **Port Conflict**: Ensure ports 9080 and 3002 are not occupied by other programs
+2. **Virtual Environment**: Ensure `.venv` directory exists and contains correct Python environment
+3. **Dependency Installation**: Run `npm install` to ensure all dependencies are installed
+
+## 📁 Project Structure
+```
+├── src/                    # Python backend source code
+├── frontend/               # React frontend source code
+├── config/                 # Configuration files
+├── nodemon.json           # nodemon configuration
+└── package.json           # npm scripts and dependencies
+```

graphxr_database_proxy-1.0.0/doc/DEV_GUIDE.zh.md

@@ -0,0 +1,60 @@
+# 开发环境指南
+
+> **语言**: [English](DEV_GUIDE.md) | [中文](DEV_GUIDE.zh.md)
+
+## 🚀 快速开始
+
+### 一键启动开发环境
+```bash
+npm run dev            # 同时启动前后端 (推荐)
+```
+这个命令会同时启动：
+- **后端服务器** (Python FastAPI): http://localhost:9080
+- **前端开发服务器** (React): http://localhost:3002
+
+### 分别启动服务
+```bash
+npm run dev:backend    # 只启动后端
+npm run dev:frontend   # 只启动前端
+```
+
+
+## 🔧 开发环境特性
+
+### 热重载 (Hot Reload)
+- **Python 代码修改**: 后端服务器自动重启
+- **React 组件修改**: 浏览器自动刷新，保持状态
+- **配置文件修改**: 自动检测并重启相应服务
+
+### 监控的文件类型
+- **后端**: `.py`, `.json`, `.toml`, `.txt` 文件
+- **前端**: `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss` 文件
+
+### 端口配置
+- **后端 API**: 9080
+- **前端开发服务器**: 3002 (自动代理API到9080)
+- **API 文档**: http://localhost:9080/docs
+
+## 🐛 开发调试
+
+### 查看日志
+开发环境会显示详细的日志信息：
+- **后端日志**: uvicorn + FastAPI 请求日志
+- **前端日志**: webpack 构建和热重载日志
+
+### 重启服务
+在nodemon控制台输入 `rs` 可以手动重启后端服务。
+
+### 常见问题
+1. **端口占用**: 确保9080和3002端口没有被其他程序占用
+2. **虚拟环境**: 确保`.venv`目录存在且包含正确的Python环境
+3. **依赖安装**: 运行`npm install`确保所有依赖已安装
+
+## 📁 项目结构
+```
+├── src/                    # Python 后端源码
+├── frontend/               # React 前端源码
+├── config/                 # 配置文件
+├── nodemon.json           # nodemon 配置
+└── package.json           # npm 脚本和依赖
+```

graphxr_database_proxy-1.0.0/doc/FRONTEND_INTEGRATION.md

@@ -0,0 +1,183 @@
+# 前端文件集成指南
+
+GraphXR Database Proxy 支持将前端文件打包到 Python 包中，这样安装包后就能直接访问完整的 Web UI。
+
+## 🏗️ 构建流程
+
+### 1. 前端构建和打包
+
+```bash
+# 构建前端并复制到 Python 包
+python scripts/build_frontend.py
+
+# 构建完整包（包含前端）
+python scripts/publish.py build
+```
+
+### 2. 自动化构建
+
+发布脚本会自动处理前端构建：
+
+```bash
+# 发布到 TestPyPI（包含前端构建）
+python scripts/publish.py test
+
+# 发布到 PyPI（包含前端构建）
+python scripts/publish.py prod
+```
+
+## 📁 文件结构
+
+### 开发时
+```
+frontend/
+├── src/           # 前端源码
+├── dist/          # 前端构建输出
+└── package.json
+
+src/graphxr_database_proxy/
+├── static/        # 复制的前端文件（构建时生成）
+└── main.py        # FastAPI 应用
+```
+
+### 发布后
+```
+graphxr_database_proxy/
+├── static/        # 打包的前端文件
+│   ├── index.html
+│   ├── main.js
+│   ├── vendors.js
+│   └── ...
+└── main.py
+```
+
+## 🚀 使用方式
+
+### 作为包使用
+
+```python
+from graphxr_database_proxy import DatabaseProxy
+from graphxr_database_proxy.main import app
+
+# 创建代理
+proxy = DatabaseProxy()
+
+# 启动服务（包含 Web UI）
+proxy.start()
+```
+
+### 命令行使用
+
+```bash
+# 安装包
+pip install graphxr-database-proxy
+
+# 启动服务（包含 Web UI）
+graphxr-proxy --host 0.0.0.0 --port 9080
+```
+
+访问 http://localhost:9080 查看 Web UI。
+
+## 🔧 静态文件服务
+
+FastAPI 应用会自动检测静态文件位置：
+
+1. **生产环境**: 使用包内的 `static/` 目录
+2. **开发环境**: 使用 `frontend/dist/` 目录
+3. **回退**: 显示提示信息
+
+### 代码示例
+
+```python
+# main.py 中的静态文件配置
+static_dir = Path(__file__).parent / "static"
+frontend_dist = Path(__file__).parent.parent.parent / "frontend" / "dist"
+
+# 优先使用打包的静态文件
+if static_dir.exists() and any(static_dir.iterdir()):
+    app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+    
+    @app.get("/{full_path:path}")
+    async def serve_frontend(full_path: str):
+        index_file = static_dir / "index.html"
+        if index_file.exists():
+            return FileResponse(str(index_file))
+```
+
+## 🧪 测试验证
+
+```bash
+# 测试包的完整性（包括静态文件）
+python scripts/test_package.py
+```
+
+测试会验证：
+- ✅ 静态文件是否正确包含
+- ✅ FastAPI 应用是否正常工作
+- ✅ 路由是否正确配置
+
+## 📦 包配置
+
+### pyproject.toml
+```toml
+[tool.setuptools.package-data]
+"graphxr_database_proxy" = ["static/*", "static/**/*"]
+```
+
+### MANIFEST.in
+```
+# 包含静态文件
+recursive-include src/graphxr_database_proxy/static *
+```
+
+## 🔄 开发工作流
+
+1. **开发前端**
+   ```bash
+   cd frontend
+   npm run dev  # 开发模式
+   ```
+
+2. **构建前端**
+   ```bash
+   python scripts/build_frontend.py
+   ```
+
+3. **测试完整包**
+   ```bash
+   python scripts/publish.py build
+   python scripts/test_package.py
+   ```
+
+4. **发布**
+   ```bash
+   python scripts/publish.py test   # 测试发布
+   python scripts/publish.py prod   # 正式发布
+   ```
+
+## 📝 注意事项
+
+1. **文件大小**: 包含前端后，包大小会增加到约 1.7MB
+2. **构建依赖**: 需要 Node.js 环境来构建前端
+3. **版本同步**: 前端和后端版本需要保持同步
+4. **缓存清理**: 构建前会自动清理旧的静态文件
+
+## 🆘 故障排除
+
+### 前端文件缺失
+```bash
+# 重新构建前端
+python scripts/build_frontend.py
+```
+
+### 包大小异常
+```bash
+# 检查包内容
+python -m zipfile -l dist/graphxr_database_proxy-*.whl | grep static
+```
+
+### 静态文件访问失败
+```bash
+# 测试包完整性
+python scripts/test_package.py
+```