Skip to content

feat: add HTTP Server and Python HTTP Client (T2 & T4)#109

Merged
MaojiaSheng merged 9 commits intomainfrom
feature/server_client
Feb 9, 2026
Merged

feat: add HTTP Server and Python HTTP Client (T2 & T4)#109
MaojiaSheng merged 9 commits intomainfrom
feature/server_client

Conversation

@qin-ctx
Copy link
Collaborator

@qin-ctx qin-ctx commented Feb 9, 2026

Description

实现 Server/Client 架构,为 OpenViking 提供 HTTP Server 服务和 Python SDK HTTP 模式。

对应 Issue #48 中的:

  • T2 - HTTP Server Implementation:基于 FastAPI 实现完整的 HTTP API 服务,支持 API Key 认证、CORS、健康检查等
  • T4 - Python SDK HTTP Mode:扩展现有 Python SDK,新增 HTTP Client 模式,支持同步/异步两种调用方式,API 与本地模式完全一致

Related Issue

Ref #48 (T2: HTTP Server Implementation, T4: Python SDK HTTP Mode)

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test update

Changes Made

Server (T2)

  • 新增 openviking/server/ 模块,基于 FastAPI 实现 HTTP API Server
    • app.py - FastAPI 应用创建与中间件配置(CORS、错误处理、请求日志)
    • auth.py - API Key 认证(支持 X-API-Key Header 和 Bearer Token)
    • bootstrap.py - Server 启动引导(uvicorn)
    • config.py - Server 配置管理(配置文件 / 环境变量 / CLI 参数)
    • routers/ - 10 个路由模块:resources, filesystem, search, sessions, content, relations, observer, pack, system, debug
  • 新增 openviking/__main__.py,支持 python -m openviking serve CLI 启动

Client (T4)

  • 新增 openviking/client/ 模块,抽象 Client 层
    • base.py - Client 抽象基类,定义统一接口
    • local.py - 本地模式 Client(封装原有 Service 层调用)
    • http.py - HTTP 模式 Client(通过 httpx 访问远程 Server)
    • session.py - Session 管理
  • AsyncOpenViking 新增 url / api_key 参数,根据参数自动选择 LocalClient 或 HTTPClient
  • HTTP 模式不使用单例,本地模式保持单例行为不变

文档

  • 重构 API 文档结构(中英文),统一编号,新增 Server 相关 API 文档
  • 新增 getting-started/03-quickstart-server.md Server 快速开始
  • 新增 guides/ 下部署、认证、监控指南
  • configuration/ 目录迁移至 guides/ 并扩展内容

示例

测试

  • 新增 tests/server/ 共 11 个测试文件,覆盖全部 Server API 路由、认证、错误场景、健康检查
  • 新增 tests/integration/test_http_integration.py 端到端 HTTP 集成测试
  • 新增 tests/server/test_http_client_sdk.py HTTP Client SDK 测试

Testing

  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have tested this on the following platforms:
    • Linux
    • macOS
    • Windows

Checklist

  • My code follows the project's coding style
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

Additional Notes

  • Server 默认端口 1933,支持通过 --port、配置文件或环境变量修改
  • API Key 认证为可选,/health 端点始终免认证
  • HTTP Client 与本地 Client API 完全一致,切换只需将 path= 改为 url=
  • 详细设计文档:server-cli-design.md

…cumentation

  - Implement FastAPI-based HTTP server (openviking/server/) with REST API
  - Add client abstraction layer (LocalClient, HTTPClient, BaseClient)
  - Add CLI entry point (python -m openviking serve)
  - Fix bugs: session.session_id, link/unlink param names, hmac.compare_digest
  - Restructure docs: remove numbered prefixes, add guides/, rewrite API reference
    with both Python SDK and HTTP API (curl) examples (en/zh)
  - Add quickstart-server, deployment, authentication, monitoring guides
  - Update examples and design docs to reflect implementation
@CLAassistant
Copy link

CLAassistant commented Feb 9, 2026

CLA assistant check
All committers have signed the CLA.

@MaojiaSheng MaojiaSheng merged commit 3165ffa into main Feb 9, 2026
1 of 3 checks passed
@MaojiaSheng MaojiaSheng deleted the feature/server_client branch February 9, 2026 13:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants