Implement server-side batch operations, metadata caching, and view storage APIs

[Copilot]

Client aligned to PR #380 API spec but server implementation was missing. This adds the server-side protocol methods and HTTP routes.

Protocol Extensions

Interface (packages/spec/src/api/protocol.ts)

• Batch operations: batchData, createManyData, updateManyData, deleteManyData
• Metadata caching: getMetaItemCached with ETag support
• View storage: createView, getView, listViews, updateView, deleteView

Implementation (packages/objectql/src/protocol.ts)

• Batch ops support atomic transactions with per-record error reporting
• ETag generation using browser-compatible hash (removed Node crypto dependency)
• View storage uses in-memory Map (DB-agnostic interface)

HTTP Routes

Added 10 endpoints in packages/plugins/plugin-hono-server/src/hono-plugin.ts:

// Batch operations
POST /api/v1/data/:object/batch
POST /api/v1/data/:object/{createMany,updateMany,deleteMany}

// Enhanced metadata with ETag
GET /api/v1/meta/:type/:name  // Returns 304 if If-None-Match matches

// View storage CRUD
GET/POST /api/v1/ui/views
GET/PATCH/DELETE /api/v1/ui/views/:id

Critical Fixes

Hono adapter body parsing (adapter.ts): Request body was parsed twice, leaving empty object. Now parses JSON first, falls back to parseBody only for non-JSON content types.

Browser compatibility (protocol.ts): Replaced crypto.createHash() with simple string hash function to work in browser environments.

Example Usage

// Batch create with atomic transaction
const response = await fetch('/api/v1/data/contact/batch', {
  method: 'POST',
  body: JSON.stringify({
    operation: 'create',
    records: [{ data: { name: 'Alice' } }, { data: { name: 'Bob' } }],
    options: { atomic: true, returnRecords: true }
  })
});

// Metadata caching
const r1 = await fetch('/api/v1/meta/object/contact');
const etag = r1.headers.get('ETag');
const r2 = await fetch('/api/v1/meta/object/contact', {
  headers: { 'If-None-Match': etag }
});
// Returns 304 if unchanged

// View storage
await fetch('/api/v1/ui/views', {
  method: 'POST',
  body: JSON.stringify({
    name: 'active_contacts',
    object: 'contact',
    type: 'list',
    query: { where: { status: 'active' } }
  })
});

All responses conform to schemas in batch.zod.ts, cache.zod.ts, view-storage.zod.ts. Errors use StandardErrorCode from errors.zod.ts.

Original prompt

任务：为 ObjectStack 服务端实现 PR #380 的批量操作、元数据缓存和视图存储 API

背景

客户端已对齐 PR #380 的 API 规范，但服务端实现滞后。需要扩展协议接口、实现业务逻辑并注册 HTTP 路由。

需要修改的文件

1. packages/spec/src/api/protocol.ts

扩展 IObjectStackProtocol 接口，添加：

batchData(object: string, request: BatchUpdateRequest): Promise
createManyData(object: string, records: any[]): Promise<any[]>
updateManyData(object: string, request: UpdateManyRequest): Promise
deleteManyData(object: string, request: DeleteManyRequest): Promise
getMetaItemCached(type: string, name: string, cacheRequest?: MetadataCacheRequest): Promise
View storage methods: createView, getView, listViews, updateView, deleteView
2. packages/objectql/src/protocol.ts

在 ObjectStackProtocolImplementation 类中实现上述方法：

批量操作需要支持 atomic 事务（如果底层 driver 支持）
元数据缓存需要计算 ETag（可用 MD5 hash）并检查 ifNoneMatch
错误处理需要返回标准化的错误格式（参考 packages/spec/src/api/errors.zod.ts）
3. packages/plugins/plugin-hono-server/src/hono-plugin.ts

在 start() 方法中注册新路由：

// Batch operations
this.server.post('/api/v1/data/:object/batch', async (req, res) => { ... });
this.server.post('/api/v1/data/:object/createMany', async (req, res) => { ... });
this.server.post('/api/v1/data/:object/updateMany', async (req, res) => { ... });
this.server.post('/api/v1/data/:object/deleteMany', async (req, res) => { ... });

// Metadata caching (enhance existing route)
this.server.get('/api/v1/meta/:type/:name', async (req, res) => {
// Check If-None-Match header, return 304 if matches
});

// View storage
this.server.post('/api/v1/ui/views', async (req, res) => { ... });
this.server.get('/api/v1/ui/views/:id', async (req, res) => { ... });
this.server.get('/api/v1/ui/views', async (req, res) => { ... });
this.server.patch('/api/v1/ui/views/:id', async (req, res) => { ... });
this.server.delete('/api/v1/ui/views/:id', async (req, res) => { ... });
技术要求

所有请求/响应需要符合 packages/spec/src/api/batch.zod.ts、cache.zod.ts、view-storage.zod.ts 中的 schema
错误响应使用 StandardErrorCode 和 ErrorCategory（参考 errors.zod.ts）
批量操作的 atomic: true 模式需要支持事务回滚（如果 driver 支持）
ETag 生成使用内容的 MD5 hash，格式为 "" 或 W/""
View storage 需要持久化（可先用内存存储，后续扩展到数据库）
验证步骤

TypeScript 编译通过
使用 @objectstack/client 测试所有新 API 端点
验证批量操作的 atomic 和 non-atomic 模式
验证 ETag 缓存（304 响应）
验证标准化错误格式
编码规范

遵循 ObjectStack 命名约定：配置属性用 camelCase，机器名用 snake_case
使用 Zod schema 进行请求验证
添加详细的日志记录（使用 ctx.logger）
参考现有 CRUD 实现的错误处理模式

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jan 30, 2026 11:51am

[Copilot]

Pull request overview

This pull request implements server-side support for batch operations, metadata caching with ETag support, and view storage APIs to align with the client-side specifications introduced in PR #380. The implementation adds protocol method definitions, concrete implementations, and HTTP route handlers across three packages.

Changes:

• Extended the ObjectStack protocol interface with 9 new methods for batch operations, cached metadata retrieval, and view storage
• Implemented batch data operations (create, update, delete, upsert) with configurable atomic transaction semantics
• Added ETag-based metadata caching using a browser-compatible hash function
• Created in-memory view storage with CRUD operations and filtering capabilities
• Fixed Hono adapter body parsing issue that was causing empty request bodies
• Registered 10 new HTTP endpoints for the added functionality

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 24 comments.

File	Description
packages/spec/src/api/protocol.ts	Extended IObjectStackProtocol interface with method signatures for batch operations, cached metadata, and view storage
packages/objectql/src/protocol.ts	Implemented protocol methods including batch processing logic, ETag-based caching, and in-memory view storage with a simple hash function
packages/plugins/plugin-hono-server/src/hono-plugin.ts	Added HTTP route handlers for batch endpoints, enhanced metadata endpoint with caching headers, and view storage CRUD endpoints
packages/plugins/plugin-hono-server/src/adapter.ts	Fixed request body parsing to handle JSON first, preventing double-parse issue that left empty bodies

[Copilot]

The upsert operation doesn't handle the externalId field specified in the BatchRecordSchema. According to the schema and batch.zod.ts documentation, upsert should support matching records by externalId, but the implementation only checks for record.id.

The schema defines externalId as 'External ID for upsert matching', which is a common pattern in data integration (matching on business keys instead of internal IDs). The implementation should check for externalId and perform appropriate matching logic.

[Copilot]

The view storage uses an in-memory Map which means all saved views will be lost when the server restarts. This violates the expectation of "saved views" being persistent.

While the PR description mentions this is "DB-agnostic interface" and uses in-memory storage temporarily, this should be clearly documented in the code. Consider adding a comment warning about the temporary nature and the need for future persistence implementation, or at minimum log a warning on startup indicating views are not persisted.

Suggested change

	private engine: IDataEngine;
	private viewStorage: Map<string, SavedView> = new Map();
	constructor(engine: IDataEngine) {
	this.engine = engine;
	private engine: IDataEngine;
	/**
	* Temporary in-memory storage for SavedView definitions.
	*
	* IMPORTANT:
	* - This implementation is NON-PERSISTENT: all views will be lost when the
	* process restarts.
	* - It exists only as a DB-agnostic placeholder for the protocol surface.
	* - Replace with a durable backing store (e.g. SQL/NoSQL) when wiring this
	* protocol into a production environment.
	*/
	private viewStorage: Map<string, SavedView> = new Map();
	constructor(engine: IDataEngine) {
	this.engine = engine;
	// Warn at runtime so operators understand that saved views are not durable.
	// This avoids surprising data loss when the server process is restarted.
	console.warn(
	'[ObjectStackProtocol] Saved views are stored in-memory only and will be lost on restart. ' +
	'Configure a persistent backing implementation before using this in production.'
	);

[Copilot]

The error response format is inconsistent across routes. Some routes return structured ViewResponse/BatchUpdateResponse objects with success/error fields, while error cases return plain objects like {error: {code, message}} or just {error: e.message}.

This inconsistency makes it harder for clients to handle errors uniformly. According to the schemas in batch.zod.ts and view-storage.zod.ts, all responses should follow the standardized response format with success, error, and data fields.

[Copilot]

The listViews endpoint doesn't validate or sanitize query parameters before using them in filters. Query parameters from the URL are directly used to filter views without validation against the ListViewsRequestSchema.

While the risk is low since this is filtering in-memory data, it's inconsistent with the schema-based validation approach used elsewhere. Consider validating the request object against ListViewsRequestSchema before processing, especially if this will eventually query a database where injection attacks could be a concern.

[Copilot]

The updateView method spreads all updates into the existing view without validation. This could allow:

1. Overwriting immutable fields like createdBy or createdAt
2. Setting invalid values that don't conform to SavedViewSchema
3. Changing the object or type to invalid values

The implementation should either:

• Validate updates against UpdateViewRequestSchema before applying
• Explicitly list which fields can be updated
• Preserve system-managed fields (createdBy, createdAt, isSystem)

[Copilot]

The body parsing logic is fragile and may still fail for certain request types. The code attempts JSON parsing first, then falls back to parseBody, but both attempts catch and suppress errors without logging.

This could make debugging difficult when requests fail to parse. Consider:

1. Logging parse failures at debug level to help troubleshoot issues
2. Verifying this works correctly for multipart/form-data and other content types
3. Only calling parseBody for content types that actually need it (form-data, urlencoded)

Suggested change

	// Try to parse JSON body first if content-type is JSON
	if (c.req.header('content-type')?.includes('application/json')) {
	try {
	body = await c.req.json();
	} catch(e) {
	// If JSON parsing fails, try parseBody
	try {
	body = await c.req.parseBody();
	} catch(e2) {}
	}
	} else {
	// For non-JSON content types, use parseBody
	try {
	body = await c.req.parseBody();
	} catch(e) {}
	const contentType = c.req.header('content-type') || '';
	// Try to parse JSON body first if content-type is JSON
	if (contentType.includes('application/json')) {
	try {
	body = await c.req.json();
	} catch (e) {
	// Log JSON parse failures at debug level for troubleshooting
	console.debug?.(
	'[HonoHttpServer] Failed to parse JSON body',
	{ contentType, error: e }
	);
	}
	} else if (
	contentType.includes('multipart/form-data') ||
	contentType.includes('application/x-www-form-urlencoded')
	) {
	// For form-data and urlencoded content types, use parseBody
	try {
	body = await c.req.parseBody();
	} catch (e) {
	// Log parseBody failures at debug level for troubleshooting
	console.debug?.(
	'[HonoHttpServer] Failed to parse form body',
	{ contentType, error: e }
	);
	}

[Copilot]

The deleteView method returns a plain object with only success field, which doesn't match the pattern established by other view methods. According to the ViewStorageApiContracts in view-storage.zod.ts, deleteView should return an object conforming to the contract output type.

For consistency with getView, createView, updateView, and listViews, consider returning an error object when the view is not found, rather than just returning success: false. This would allow clients to distinguish between different failure scenarios.

[Copilot]

The lastModified timestamp always returns the current time (new Date().toISOString()) rather than the actual modification time of the metadata. This makes the Last-Modified header meaningless for caching purposes.

The lastModified should reflect when the metadata was actually last changed. Consider:

1. Tracking modification timestamps when metadata is registered in SchemaRegistry
2. Using a static timestamp if metadata is immutable after registration
3. Omitting the lastModified field if not tracking actual modification times

Suggested change

lastModified: new Date().toISOString(),

[Copilot]

The HTTP route handlers for batch operations, metadata caching, and view storage lack test coverage. Integration or unit tests should verify:

• Request parsing and validation
• Status code mapping (200, 201, 304, 400, 404, 500)
• Header handling (ETag, Cache-Control, If-None-Match)
• Error response formatting
• Edge cases like missing request bodies or invalid parameters

[Copilot]

The simpleHash function lacks documentation about its limitations and why it was chosen. Given that this is a critical function for cache validation, it should include:

• A warning about collision probability
• Why crypto.createHash was avoided (browser compatibility)
• Recommendation to replace with stronger hash in production
• Link or reference to the algorithm being used