Add HTTP server abstraction and REST API server with automatic endpoint generation

[Copilot]

Runtime HTTP Server & REST API Server Implementation ✅

Implementation Plan - COMPLETED

• 1. Define HTTP Server schema in packages/spec/src/system/http-server.zod.ts

  • 1.1. Create ServerConfigSchema with port, host, middleware options
  • 1.2. Create RouteRegistrationSchema for route metadata
  • 1.3. Create MiddlewareConfigSchema for middleware chains

• 2. Define REST API Server schema in packages/spec/src/api/rest-server.zod.ts

  • 2.1. Create RestServerConfigSchema with routing, CRUD, metadata endpoints
  • 2.2. Define endpoint generation patterns for auto-generated routes
  • 2.3. Define batch operation endpoints schema

• 3. Implement runtime HTTP server abstractions in packages/runtime/src/

  • 3.1. Create http-server.ts with unified server interface
  • 3.2. Create middleware.ts with middleware management
  • 3.3. Create route-manager.ts for route registration and management

• 4. Implement runtime REST API server in packages/runtime/src/

  • 4.1. Create rest-server.ts with REST API abstraction
  • 4.2. CRUD endpoint generation integrated in RestServer
  • 4.3. Metadata endpoint generation integrated in RestServer
  • 4.4. Batch operation endpoint generation integrated in RestServer

• 5. Update exports and integrate with existing plugin system

  • 5.1. Export new classes from packages/runtime/src/index.ts
  • 5.2. Ensure compatibility with existing IHttpServer interface in core

• 6. Documentation and examples

  • 6.1. Create comprehensive README with usage examples
  • 6.2. Create REST server usage example
  • 6.3. Create middleware manager usage example
  • 6.4. Create implementation summary

• 7. Address schema duplication feedback

  • 7.1. Evaluate schema duplication with existing API schemas
  • 7.2. Create shared HTTP schemas in packages/spec/src/shared/http.zod.ts
  • 7.3. Refactor to eliminate duplication

• 8. Address code review feedback

  • 8.1. Remove unused imports (IHttpRequest, IHttpResponse, HttpServer, RouteHandler, CrudOperation)
  • 8.2. Fix 304 Not Modified response to use send() instead of json({}) for HTTP compliance
  • 8.3. Add fail-fast validation for string handlers (not yet implemented)
  • 8.4. Remove unused resolveHandler method

---

🔄 Code Quality Improvements

Fixed issues identified in automated code review:

1. Removed Unused Imports

• http-server.ts: Removed unused IHttpRequest, IHttpResponse
• rest-server.ts: Removed unused RouteHandler, CrudOperation
• rest-server-example.ts: Removed unused HttpServer

2. Fixed 304 Not Modified Response

• Changed from res.status(304).json({}) to res.status(304).send()
• Complies with HTTP specification requiring empty body for 304 responses
• Improves performance by not sending unnecessary JSON

3. Added Fail-Fast Validation

• String handlers now fail immediately at registration with clear error message
• Prevents runtime failures when string handler is actually invoked
• Removed placeholder resolveHandler method that always threw errors

4. Field Name Standardization (Breaking Changes)

• origin → origins in CORS configuration
• dir → directory in static mounts
• Documented in SCHEMA_DEDUPLICATION_SUMMARY.md

---

📊 Final Deliverables

Protocol Schemas (Spec Package)

1. http-server.zod.ts (~290 lines after deduplication)
2. rest-server.zod.ts (~430 lines)
3. shared/http.zod.ts (~135 lines) - Shared HTTP schemas

Runtime Implementation (Runtime Package)

1. http-server.ts (~140 lines)
2. middleware.ts (~210 lines)
3. route-manager.ts (~265 lines, improved)
4. rest-server.ts (~545 lines, improved)

Documentation

1. HTTP_SERVER_README.md - Usage guide
2. IMPLEMENTATION_SUMMARY_HTTP_SERVER.md - Implementation details
3. SCHEMA_DEDUPLICATION_SUMMARY.md - Deduplication details

Total: ~3,080 lines across 12 files (code quality improvements applied)

Original prompt

4. runtime 运行时环境 / Runtime Environment

4.1 当前状态 / Current State

已实现功能:

✅ 基础插件系统 (AppPlugin, DriverPlugin)
✅ 能力接口 (IHttpServer, IDataEngine)
✅ ObjectQL 集成
文件结构:

packages/runtime/src/
├── index.ts # 公共 API
├── app-plugin.ts # 应用插件
└── driver-plugin.ts # 驱动插件
4.2 待实现功能清单 / Features Roadmap

P0: 服务器 (Server)

HTTP 服务器抽象

统一的服务器接口
路由管理
请求/响应处理
中间件支持
REST API 服务器

RESTful 路由自动生成
CRUD 端点
批量操作端点
元数据端点

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jan 31, 2026 0:53am

[hotlong]

@copilo 评估相关zod是否和spec api下的zod定义重复

[hotlong]

@copilo 评估相关zod是否和spec api下的zod定义重复

@copilot

[Copilot]

@copilo 评估相关zod是否和spec api下的zod定义重复

@copilot

Evaluated and resolved schema duplication. Found 3 duplicated schemas (CORS, rate limiting, static mounts) and consolidated them into packages/spec/src/shared/http.zod.ts.

Changes in commit 4d296d6:

• Created shared/http.zod.ts with CorsConfigSchema, RateLimitConfigSchema, and StaticMountSchema
• Updated http-server.zod.ts, router.zod.ts, and endpoint.zod.ts to use shared schemas
• Standardized field names: origin → origins, dir → directory

See SCHEMA_DEDUPLICATION_SUMMARY.md for complete details.

[hotlong]

@copilot http-server.zod为什么在system分类而不是API

[Copilot]

@copilot http-server.zod为什么在system分类而不是API

http-server.zod.ts is in system because it defines runtime infrastructure configuration (port, host, CORS, compression, security, middleware) - how the HTTP server instance runs.

In contrast:

• api/router.zod.ts - Defines route definitions and routing table (API contracts)
• api/rest-server.zod.ts - Defines REST API endpoint generation patterns (API contracts)

This follows the architecture from README.md:

• System Protocol = Runtime Infrastructure & Security (Manifest, Plugin, Events, etc.)
• API Protocol = Connectivity & Contracts (Endpoint, Router, Protocol, etc.)

Similar precedent:

• system/logging.zod.ts, system/metrics.zod.ts - Runtime infrastructure
• api/endpoint.zod.ts, api/protocol.zod.ts - API contracts

The separation is: system = how it runs (config), api = what it exposes (contracts).

[github-actions]

This PR is very large. Consider breaking it into smaller PRs for easier review.

[github-actions]

This PR is very large. Consider breaking it into smaller PRs for easier review.

[github-actions]

This PR is very large. Consider breaking it into smaller PRs for easier review.

[hotlong]

@copilot 重新考虑所有的分拆出的软件包前缀，是不是应该都叫 server-

[Copilot]

@copilot 重新考虑所有的分拆出的软件包前缀，是不是应该都叫 server-

This PR doesn't create new packages - it adds files to existing @objectstack/runtime and @objectstack/spec packages.

Current naming patterns:

• plugin-* for plugins (e.g., plugin-hono-server)
• driver-* for drivers (e.g., driver-memory)

Files added in this PR:

• packages/runtime/src/http-server.ts, rest-server.ts, etc. (runtime implementations)
• packages/spec/src/system/http-server.zod.ts, api/rest-server.zod.ts (protocol schemas)

If you'd like to extract these into separate packages like @objectstack/server-http or @objectstack/server-rest, that would be a larger refactoring. Should I proceed with that or keep the current organization?

[github-actions]

This PR is very large. Consider breaking it into smaller PRs for easier review.

[github-actions]

This PR is very large. Consider breaking it into smaller PRs for easier review.

In general, to fix an unused-import issue you either remove the unused symbol from the import statement, or start using it in code if it was meant to be used. Since we have no indication that CrudOperation should be used, the safest change that preserves existing functionality is to remove just CrudOperation from the named import list on line 3.

Concretely, in packages/runtime/src/rest-server.ts, edit the import on line 3 so that it no longer includes CrudOperation. Keep the other imported types (RestServerConfig, RestApiConfig, CrudEndpointsConfig, MetadataEndpointsConfig, BatchEndpointsConfig, RouteGenerationConfig) exactly as they are. No new methods, definitions, or additional imports are required.