sync-upstream-gateway

Sync Upstream Gateway Implementation

Used to align the lobehub-gateway-go Go implementation with the protocol behavior of the upstream LobeHub gateway reference implementation.

When to use

When the task requires "sync upstream", "align protocol", or "catch up with the latest LobeHub implementation"
When the task specifies a LobeHub tag or commit and requires the Go implementation to align to that version
When the upstream device-gateway / agent-gateway has protocol changes that need to be evaluated and synced to this repository

Background

This repository is a Go rewrite of the upstream TypeScript implementation,The protocol baseline is fixed in the "Alignment Target" section of README.md to two commits：

device-gateway at <commit>
agent-gateway at <commit>

Upstream reference repositories (AGENTS.md convention):

Upstream	Repository	Default branch	Purpose
Device Gateway	`github.com/lobehub-biz/device-gateway`	`main`	Device gateway protocol reference
Agent Gateway	`github.com/lobehub-biz/agent-gateway`	`master`	Agent gateway protocol reference
Application-side	`github.com/lobehub/lobehub`	`main`	Client invocation convention reference

Application-side key paths to verify:

packages/device-gateway-client
packages/agent-gateway-client
src/server/agent-hono/handlers

Reference checkout locations (for reference only, not part of this project's source code）：

device-gateway/、agent-gateway/ — under the project root directory, already ignored by .gitignore — under the project root directory, already ignored by .gitignore
lobehub/ — the project root'sparent level（../lobehub/), to avoid polluting this project's workspace

Version conventions (from AGENTS.md)

By default, follow the protocol baseline fixed in the README; when the task specifies a LobeHub tag or commit, that version takes precedence.
Only track main or canary。
Describe the final behavior, interfaces, configuration, and constraints for developers and users; record the evolution process only in the changelog or migration guide.

Sync process

1. Determine the target version

Two paths, determined by the task:

Path A — Align to a specified tag/commit (default): Get the target tag or commit from the task.
Path B — Catch up with the latest upstream: Take the device-gateway of main HEAD、agent-gateway of master HEAD. Only use when the task explicitly requires tracking the latest.

If the task does not specify and does not require catching up,by default continue using the README-fixed baseline and do not proactively sync; you should first confirm intent with the user.

2. Prepare the upstream reference checkout

Clone under the project root directory (the directory is already ignored by .gitignore ):

git clone https://github.com/lobehub-biz/device-gateway device-gateway
git clone https://github.com/lobehub-biz/agent-gateway agent-gateway
git clone --depth 1 https://github.com/lobehub/lobehub ../lobehub   # 应用侧，clone 到上一级，按需

Switch to the target version according to the path:

Path A:cd device-gateway && git checkout <target-commit-or-tag>, and likewise for agent-gateway.
Path B: keep the default branch and git pull to the latest.

3. Read the current baseline

From README.md and README.zh-CN.md 's "Alignment Target" section, read the currently fixed two commits as the starting point for the diff.

4. Diff protocol changes

Compare current baseline → target version for changes affecting the public protocol, focusing on:

HTTP routes (paths, methods, status codes)
Request/response JSON schema (field names, types, nullability, default values)
WebSocket message format and event names
Authentication behavior (SERVICE_TOKEN, JWKS/JWT validation)
Routing semantics, timeout behavior
Type definitions (src/types.ts）

Explicitly excluded(README "Alignment Target" declaration, not synchronized):

admin APIs
metrics
Durable Object storage or WebSocket hibernation
Multi-instance coordination
geo reporting、admin reporting

Implementation location comparison:

Upstream file	This repository's location
`device-gateway/src/*.ts`	`device-gateway-go/internal/gateway/`
`agent-gateway/src/*.ts`	`agent-gateway-go/internal/gateway/`

5. Verify the application-side client protocol

In ../lobehub/ verify how the client calls the gateway, and confirm that the interfaces exposed by this repository are consistent with the client conventions:

packages/device-gateway-client
packages/agent-gateway-client
src/server/agent-hono/handlers

If it is found that the client depends on interfaces not implemented by this repository, add them to the alignment checklist and handle them by priority.

6. Update the Go implementation

Update based on the diff results device-gateway-go / agent-gateway-go 's internal/gateway/ implementation. Follow the existing code style and in-memory single-instance design,do not introduce：

Cloudflare Workers / Durable Objects bindings
External runtime dependencies such as Redis, PostgreSQL, NATS, etc.

7. Update the protocol baseline

If aligned to a new version, update README.md and README.zh-CN.md 's two "Alignment Target" commits to the actual commits of the target version.

8. Verification

# 根模块（统一二进制）
go build -o gateway ./cmd/gateway
go test ./...

# 各子模块独立验证
cd agent-gateway-go && go test ./... && cd ..
cd device-gateway-go && go test ./... && cd ..

Add or update test cases for newly added/changed protocol behavior.

9. Record changes

In docs/release_notes/ or the changelog, record the contents of this protocol alignment: the version aligned to, changed interfaces/messages, behavior differences, and migration notes.Describe only the final behavior and constraints; do not record the intermediate exploration process。

Completion criteria

The README baseline commit has been updated (if the version changed)
go test ./... and the two submodule tests pass
go build -o gateway ./cmd/gateway succeeded
Changes have been written into release notes / changelog
No excluded platform features or external dependencies have been introduced