diff --git a/docs/api/health.md b/docs/api/health.md index d255f94..c86ac97 100644 --- a/docs/api/health.md +++ b/docs/api/health.md @@ -50,6 +50,6 @@ curl -fsS http://127.0.0.1:8080/version ## SDK 与运行限制 -对应 `Client.Liveness(ctx)` 和 `Client.Readiness(ctx)`,见 [SDK 接入](../sdk/README.md)。HTTP 503 返回 `*orbit.HTTPError`。 +对应 `Client.Liveness(ctx)`、`Client.Readiness(ctx)` 和 `Client.Version(ctx)`,见 [SDK 接入](../sdk/README.md)。HTTP 503 返回 `*orbit.HTTPError`。 ready 只表示数据库与迁移基础可用;不检查 Worker、任务积压、流程执行或业务效果。P1 启动时先校验迁移,缺失或 dirty 会拒绝启动;运行后数据库不可用时 ready 返回 503。SDK 默认请求超时为 10 秒,调用方可通过 context 设置更短期限。运行指标见[观测接口](observability.md),指标端点是否启用由 `ORBIT_METRICS_ADDR` 控制。 diff --git a/docs/reports/phase-7-regression-status.md b/docs/reports/phase-7-regression-status.md index 32b7920..fab96ce 100644 --- a/docs/reports/phase-7-regression-status.md +++ b/docs/reports/phase-7-regression-status.md @@ -7,7 +7,7 @@ | 检查 | 环境/命令 | 结果 | | --- | --- | --- | | 服务端单元与竞态、vet、构建 | Docker `golang:1.27.1`,仓库声明版本;`GOWORK=off go test -race ./... && go vet ./... && go build ./...` | PASS | -| SDK 与独立示例竞态、vet、构建 | Docker `golang:1.27.1`;SDK 全 module、全部示例、`orbit-load`、`orbit-exec-load`、`orbit-schedule-load`、`orbit-workflow-load`,以及 result-inbox/task-outbox | PASS | +| SDK 与独立示例竞态、vet、构建 | Docker `golang:1.27.1`;SDK 全 module、全部示例、`orbit-load`、`orbit-exec-load`、`orbit-schedule-load`、`orbit-workflow-load`,以及 result-inbox/task-outbox | PASS;健康/版本 SDK 契约包含 `Client.Version(ctx)`,返回协议身份且不暴露敏感响应 | | 容器发布物构建 | `make image`;宿主平台 linux/arm64;显式 `docker build --platform linux/amd64`;带 `VERSION`、`REVISION`、`BUILD_TIME` 构建参数的版本化镜像;镜像内 `GOWORK=off` | PASS;native 与 amd64 镜像均构建成功,包含 `orbit`、`orbit-migrate`、`orbit-admin`,运行用户为非 root;版本化 amd64 二进制包含注入的构建身份,`GET /version` 契约单测通过;无 DSN 时服务按预期拒绝启动 | | 当前协议门禁 | `make protocol-check` | PASS,当前 v1 契约同步 | | 历史 SDK / 服务端任务 API 双向演练 | Go 1.27.1、MySQL 8.4 一次性环境;`make mysql-compatibility`;历史提交 `a50d5fa` | PASS;旧服务端+当前 SDK、当前服务端+旧 SDK 均完成真实任务受理、幂等、查询、分页和取消;不是正式标签或全协议矩阵 | diff --git a/docs/sdk/README.md b/docs/sdk/README.md index 4777438..4fe4071 100644 --- a/docs/sdk/README.md +++ b/docs/sdk/README.md @@ -125,7 +125,7 @@ fmt.Println(cancelled.Task.State) | CreateSchedule / GetSchedule / ListSchedules | 计划受理、详情与队列分页 | [计划](../api/schedules.md) | | PublishSchedule / GetScheduleVersion | 不可变发布与历史版本 | [计划](../api/schedules.md) | | PauseSchedule / ResumeSchedule / ListScheduleOccurrences | 控制与触发记录 | [计划](../api/schedules.md) | -| Liveness / Readiness | Health | [健康](../api/health.md) | +| Liveness / Readiness / Version | Health / VersionInfo | [健康](../api/health.md) | | SubmitTask | SubmitTaskRequest / SubmitTaskResult | [任务](../api/tasks.md) | | GetTask | taskID / Task | [任务](../api/tasks.md) | | GetTaskSource | taskID / TaskSource,普通/恢复/计划及流程固定版本、历史激活与轮次 | [来源查询](../api/task-source.md) | diff --git a/sdk/go/client.go b/sdk/go/client.go index 62f7865..04d2d9a 100644 --- a/sdk/go/client.go +++ b/sdk/go/client.go @@ -27,6 +27,18 @@ type Health struct { Scope string `json:"scope,omitempty"` } +// VersionInfo 描述服务构建身份和当前协议版本,不包含主机、数据库或租户信息。 +type VersionInfo struct { + Version string `json:"version"` // Version 发布版本或本地开发标识。 + Revision string `json:"revision"` // Revision 不可变源码提交标识。 + BuiltAt string `json:"built_at"` // BuiltAt 构建时间。 + GoVersion string `json:"go_version"` // GoVersion 编译器版本。 + HTTPProtocolVersion string `json:"http_protocol_version"` // HTTPProtocolVersion HTTP接口主版本。 + WorkerProtocolVersion string `json:"worker_protocol_version"` // WorkerProtocolVersion Worker WebSocket子协议版本。 + EventProtocolVersion string `json:"event_protocol_version"` // EventProtocolVersion Event WebSocket子协议版本。 + WorkflowSchemaVersion int `json:"workflow_schema_version"` // WorkflowSchemaVersion 流程定义结构版本。 +} + // HTTPError exposes the status code without including sensitive response bodies. type HTTPError struct{ StatusCode int } @@ -53,6 +65,40 @@ func (c *Client) Liveness(ctx context.Context) (Health, error) { return c.health func (c *Client) Readiness(ctx context.Context) (Health, error) { return c.health(ctx, "/health/ready") } + +// Version returns build and protocol identity from the unauthenticated version endpoint. +func (c *Client) Version(ctx context.Context) (VersionInfo, error) { + req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/version", nil) + if err != nil { + return VersionInfo{}, err + } + req.Header.Set("Accept", "application/json") + response, err := c.http.Do(req) + if err != nil { + return VersionInfo{}, err + } + defer response.Body.Close() + if response.StatusCode != http.StatusOK { + return VersionInfo{}, &HTTPError{StatusCode: response.StatusCode} + } + const maxBody = 16 << 10 + body, err := io.ReadAll(io.LimitReader(response.Body, maxBody+1)) + if err != nil { + return VersionInfo{}, err + } + if len(body) > maxBody { + return VersionInfo{}, errors.New("Orbit version response exceeds limit") + } + var info VersionInfo + if err := json.Unmarshal(body, &info); err != nil { + return VersionInfo{}, fmt.Errorf("decode Orbit version response: %w", err) + } + if info.Version == "" || info.HTTPProtocolVersion == "" || info.WorkerProtocolVersion == "" || info.EventProtocolVersion == "" || info.WorkflowSchemaVersion == 0 { + return VersionInfo{}, errors.New("Orbit version response is missing identity") + } + return info, nil +} + func (c *Client) health(ctx context.Context, path string) (Health, error) { req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil) if err != nil { diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go index b392f78..ce8772d 100644 --- a/sdk/go/client_test.go +++ b/sdk/go/client_test.go @@ -15,6 +15,10 @@ func TestHealthContract(t *testing.T) { if r.Method != "GET" || r.Header.Get("Accept") != "application/json" { t.Error("incorrect request") } + if r.URL.Path == "/version" { + _, _ = w.Write([]byte(`{"version":"1.2.3","revision":"abc","built_at":"now","go_version":"go1.27.1","http_protocol_version":"1","worker_protocol_version":"1","event_protocol_version":"1","workflow_schema_version":1}`)) + return + } if r.URL.Path == "/health/live" { _, _ = w.Write([]byte(`{"status":"alive"}`)) return @@ -31,6 +35,10 @@ func TestHealthContract(t *testing.T) { if err != nil || live.Status != "alive" { t.Fatalf("%+v %v", live, err) } + info, err := client.Version(context.Background()) + if err != nil || info.Version != "1.2.3" || info.Revision != "abc" || info.WorkflowSchemaVersion != 1 { + t.Fatalf("version=%+v err=%v", info, err) + } _, err = client.Readiness(context.Background()) var status *orbit.HTTPError if !errors.As(err, &status) || status.StatusCode != 503 || strings.Contains(err.Error(), "secret") { diff --git a/sdk/go/examples/health/main.go b/sdk/go/examples/health/main.go index 3ca26ef..c1d48d9 100644 --- a/sdk/go/examples/health/main.go +++ b/sdk/go/examples/health/main.go @@ -29,5 +29,9 @@ func main() { if err != nil { log.Fatal(err) } - fmt.Printf("liveness=%s readiness=%s scope=%s\n", live.Status, ready.Status, ready.Scope) + version, err := client.Version(ctx) + if err != nil { + log.Fatal(err) + } + fmt.Printf("liveness=%s readiness=%s scope=%s version=%s revision=%s\n", live.Status, ready.Status, ready.Scope, version.Version, version.Revision) }