Merge pull request 'docs: 补充 Foundry 全仓中文源码与部署注释 [skip ci]' (#20) from codex/chinese-source-comments into main

Reviewed-on: #20
This commit was merged in pull request #20.
This commit is contained in:
2026-11-16 10:04:35 +00:00
123 changed files with 1279 additions and 3 deletions
+5
View File
@@ -1,12 +1,16 @@
# 示例值供部署配置参考,真实 .env/凭据不得提交。公共地址必须是 HTTPS 根 origin。
PUBLIC_ORIGIN=https://api.example.com
DATABASE_URL=postgresql://foundry:replace-me@postgres.internal:5432/foundry_auth
GOOGLE_CLIENT_ID=replace-me.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=replace-me
# 项目→固定前端回调白名单;生产 HTTPS,开发仅允许回环 HTTP,不能由请求任意指定。
FOUNDRY_PROJECTS='{"notes":"http://localhost:3000/auth/callback","board":"http://localhost:3001/auth/callback"}'
# 默认监听回环,容器发布时 release.sh 显式改为 0.0.0.0;PORT 仅决定内部 HTTP 监听。
HOST=127.0.0.1
PORT=8080
# Optional email verification through TLS SMTP.
# 邮件配置整组缺省可关闭,部分填写会启动失败;此示例只接受隐式 TLS 465。
SMTP_HOST=smtpdm.aliyun.com
SMTP_PORT=465
SMTP_USERNAME=noreply@notice.entroia.com
@@ -14,6 +18,7 @@ SMTP_PASSWORD=replace-me
SMTP_FROM=noreply@notice.entroia.com
# Optional Sign in with Slack.
# Slack 客户端 ID 与 Secret 必须成对配置,回调 URL 由 PUBLIC_ORIGIN 派生。
SLACK_CLIENT_ID=replace-me
SLACK_CLIENT_SECRET=replace-me
+5
View File
@@ -1,8 +1,10 @@
# 分支推送和 PR 检查:格式/编译、隔离数据库回归、固定版本 headless 客户端以及 HTTP smoke。
name: Foundry Go checks
on: [push, pull_request]
jobs:
check:
# 所有构建在此远程 runner 执行;脚本中的 Docker 挂载路径也基于它的工作区。
runs-on: ces-control
# Cold toolchain installation can exceed ten minutes on the existing runner.
timeout-minutes: 30
@@ -18,6 +20,7 @@ jobs:
test -z "$(gofmt -l cmd internal)"
go test -mod=readonly ./...
go build -mod=readonly -o bin/foundry ./cmd/foundry
# 仅 push 可使用已配置秘密做占位码探测,不能替代真实用户 OAuth 登录。
- name: Check Slack OAuth configuration and endpoint
if: gitea.event_name == 'push'
env:
@@ -69,6 +72,7 @@ jobs:
print("Negative control result:", control if control in known else "unclassified")
sys.exit("Slack client preflight could not verify the configured credentials")
PYSLACK
# 固定客户端提交避免服务端回归随外部默认分支漂移,下载不使用用户本机凭据。
- name: Fetch pinned headless HTTP integration client
env:
HEADLESS_CLIENT_REVISION: dcbbdad25de7c3b1d6bee317df6074da2c0642eb
@@ -82,6 +86,7 @@ jobs:
printf 'Pinned Endoleap client: %s\n' "$HEADLESS_CLIENT_REVISION"
- name: Verify schema migration and real headless HTTP client in an isolated database
run: HEADLESS_CLIENT_SOURCE="$PWD/.headless-client" bash deploy/check-schema.sh
# smoke 不依赖可连接数据库:healthz 只检查进程,缺 bearer 的 me 必须先返回 401。
- name: Smoke test HTTP routes
env:
PUBLIC_ORIGIN: https://api.example.com
+4
View File
@@ -1,3 +1,4 @@
# 仅 main 的相关路径变更触发发布;工作分支验证不应运行此生产切换。
name: Deploy Foundry Core
on:
push:
@@ -11,6 +12,7 @@ on:
- 'db/**'
- '.gitea/workflows/deploy.yml'
# 发布串行排队且不取消正在进行的路由/数据库操作。
concurrency:
group: foundry-core-main-deploy
cancel-in-progress: false
@@ -26,12 +28,14 @@ jobs:
with:
go-version-file: go.mod
cache: false
# 在远程 runner 生成无 CGO 二进制,供只读 slim 容器执行。
- name: Verify and build
run: |
set -eu
test -z "$(gofmt -l cmd internal)"
go test -mod=readonly ./...
CGO_ENABLED=0 go build -mod=readonly -o bin/foundry ./cmd/foundry
# secrets 仅注入进程环境,项目/引导 JSON 来自 Actions Variables,release 再检查内容。
- name: Deploy and verify backend readiness
env:
GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }}
+1
View File
@@ -1,3 +1,4 @@
# 本地配置可能含凭据,构建/文档生成目录不作为源码提交。
.env
/bin/
/api-docs/
+4
View File
@@ -636,3 +636,7 @@ not migrate it or cause an implicit PATCH.
#### Atomic member drop positions
`POST B/subgraphs/{frame}/members` additionally accepts optional `positions`, an object with exactly one `{x,y}` entry for each `node_ids` item, expressed in the **source board's local coordinates**. Both coordinates are required, finite and within ±1,000,000. Capabilities advertise `subgraphs.member_positions: true`. Omission preserves legacy behavior. Positions, ownership, edge/port conversion, versions and undo receipt commit in one transaction; no preceding coordinate PATCH is needed. Validation failures or stale versions perform zero writes. The positions participate in the idempotency payload digest; retries must keep the entire body and key unchanged. Undo restores the pre-drop snapshot, including original positions.
## 源码阅读注释
Go 实现、测试与部署脚本内的中文注释说明调用关系、事务、版本、身份和资源生命周期。历史 `db/*.sql` 由部署校验和锁定,逐迁移、逐表及约束说明集中在 [数据库注释索引](docs/database-comments.sql),保留历史 SQL 字节以兼容已部署数据库。`go.sum` 和协议 JSON fixture 保留机器可读原文,不插入注释。
+9
View File
@@ -1,3 +1,4 @@
// Foundry 进程装配入口:HTTP 服务连接认证、平台、研究库和 Codex Unix socket。
package main
import (
@@ -18,6 +19,7 @@ import (
"github.com/jackc/pgx/v5/stdlib"
)
// env 将空环境变量视为缺省;仅用于允许默认值的配置项。
func env(key, fallback string) string {
if value := os.Getenv(key); value != "" {
return value
@@ -25,10 +27,12 @@ func env(key, fallback string) string {
return fallback
}
// main 支持独立 codex-worker 模式,其余启动方式进入 HTTP API 服务。
func main() {
if len(os.Args) == 2 && os.Args[1] == "codex-worker" {
log.Fatal(codex.ServeWorker("/run/foundry-codex/worker.sock"))
}
// 公共 origin 只允许 HTTPS 根地址,回调路径由程序拼接,避免配置夹带查询或用户信息。
origin, err := url.Parse(os.Getenv("PUBLIC_ORIGIN"))
if err != nil || origin.Scheme != "https" || origin.Hostname() == "" || origin.User != nil ||
(origin.Path != "" && origin.Path != "/") || origin.RawQuery != "" || origin.Fragment != "" {
@@ -46,12 +50,14 @@ func main() {
if err != nil {
log.Fatal("Invalid DATABASE_URL")
}
// OpenDB 创建连接池,实际连接按需建立;HTTP 就绪检查再验证主库可用性。
db := stdlib.OpenDB(*config)
defer db.Close()
email, err := auth.EmailConfigFromEnv()
if err != nil {
log.Fatal(err)
}
// nil 邮件配置会直接返回;此后台任务使用进程级上下文,没有单独的优雅停机取消。
go email.Run(context.Background(), db)
slack, err := auth.SlackConfigFromEnv(origin.ResolveReference(&url.URL{Path: "/auth/slack/callback"}).String())
if err != nil {
@@ -62,6 +68,7 @@ func main() {
log.Fatal(err)
}
mux := http.NewServeMux()
// 研究数据使用可选、独立且只读的连接池;配置后必须在五秒启动探测内可访问。
var papers research.Repository
if researchDSN := os.Getenv("FOUNDRY_RESEARCH_DATABASE_URL"); researchDSN != "" {
researchConfig, err := pgx.ParseConfig(researchDSN)
@@ -88,6 +95,7 @@ func main() {
}
papers = repository
}
// 先注册具体业务路径,最后的根处理器承接认证及健康探测请求。
research.Register(mux, papers, callbacks)
if err := codex.Register(mux, callbacks, os.Getenv("FOUNDRY_CODEX_SOCKET"), os.Getenv("FOUNDRY_CODEX_GRANTS")); err != nil {
log.Fatal(err)
@@ -98,6 +106,7 @@ func main() {
}
platform.Register(mux, db, callbacks, origin.Scheme+"://"+origin.Host, onboarding, codex.NewCanvasClient(os.Getenv("FOUNDRY_CODEX_SOCKET")))
mux.Handle("/", handler)
// HOST 默认只监听回环,容器部署显式覆盖;较长写超时用于耗时业务响应。
server := &http.Server{
Addr: net.JoinHostPort(env("HOST", "127.0.0.1"), env("PORT", "8080")),
Handler: mux, ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 10 * time.Second,
+4
View File
@@ -1,5 +1,6 @@
#!/usr/bin/env bash
# Explicit remote-runner opt-in: invokes real models using the dedicated CLI login.
# 此脚本会编译测试并实际调用模型;只用于明确授权的专用远程 runner,普通检查不自动运行。
set -euo pipefail
umask 077
binary=$(realpath "$1")
@@ -9,6 +10,7 @@ login=${FOUNDRY_REAL_CODEX_HOME:-/opt/endoleap-infra/foundry/codex/home}
test -x "$binary"
test -s "$login/auth.json"
test -s "$login/models_cache.json"
# 随机命名 worker/数据库和临时 socket 目录,退出时一并清理,不复用生产队列。
suffix=$(openssl rand -hex 8)
database=foundry-real-db-$suffix
worker=foundry-real-worker-$suffix
@@ -24,6 +26,7 @@ docker exec "$database" psql -X -U postgres -v ON_ERROR_STOP=1 -c 'CREATE ROLE f
python3 deploy/migrate.py --container "$database" --database postgres --role foundry_fixture
# Only the CLI container sees the login. Core/tests receive the private socket,
# never the login, runtime configuration or Docker socket.
# 只有 CLI 容器只读读取专用登录和模型缓存,测试容器仅挂 socket,不能访问登录或 Docker socket。
docker run -d --name "$worker" --init --network bridge --user 1000:1000 \
--cap-drop ALL --security-opt no-new-privileges --read-only --pids-limit 128 --memory 1g \
--tmpfs /tmp:rw,nosuid,nodev,size=128m --tmpfs /work:ro,nosuid,nodev \
@@ -38,6 +41,7 @@ docker run -d --name "$worker" --init --network bridge --user 1000:1000 \
node:24-bookworm-slim /opt/foundry codex-worker >/dev/null
for attempt in {1..30}; do if [[ -S "$scratch/run/worker.sock" ]]; then break; fi; sleep 1; done
test -S "$scratch/run/worker.sock"
# 先等私有 socket 出现,再在 runner 编译并仅运行真实 worker 专项用例;与普通单元测试开关分离。
CGO_ENABLED=0 go test -mod=readonly -c -o bin/platform-real-tests ./internal/platform
docker run --rm --network "container:$database" --user 1000:1000 \
--read-only --cap-drop ALL --security-opt no-new-privileges \
+7
View File
@@ -1,6 +1,8 @@
#!/usr/bin/env bash
# 远程 runner 的数据库/集成检查,会编译测试二进制并运行容器;不能在未授权本地环境执行。
set -euo pipefail
# 随机隔离数据库容器不映射宿主端口,EXIT 时销毁;trust 认证只用于该临时网络命名空间。
container=foundry-schema-$(openssl rand -hex 8)
cleanup() { docker rm -f "$container" >/dev/null 2>&1 || true; }
trap cleanup EXIT
@@ -12,6 +14,7 @@ for attempt in {1..30}; do
sleep 1
done
psql() { docker exec -i "$container" psql -X -U postgres -v ON_ERROR_STOP=1; }
# 先安装最早认证版本并植入有效/过期旧会话,模拟部署前已有用户数据。
psql < db/001-auth.sql
psql <<'SQL'
INSERT INTO project_accounts(project,id,google_subject,email)
@@ -23,8 +26,10 @@ SQL
psql <<'SQLROLE'
CREATE ROLE foundry_fixture LOGIN;
SQLROLE
# 连续跑两次真实迁移器,验证旧基线接管和校验和重放,而不是仅验证全新数据库建表。
python3 deploy/migrate.py --container "$container" --database postgres --role foundry_fixture
python3 deploy/migrate.py --container "$container" --database postgres --role foundry_fixture
# SQL 断言旧 Google 绑定保留、过期会话不复活、绝对期限添加,再在回滚事务中验证资源与跨项目外键。
psql <<'SQL'
DO $$
BEGIN
@@ -68,6 +73,7 @@ ROLLBACK;
SQL
printf 'Migration preserved existing logins and enforced project isolation.\n'
psql < internal/research/testdata/corpus.sql
# runner 编译 Linux 静态测试程序,随后在同数据库网络空间用最小权限容器运行,源码不挂入测试容器。
for package in platform auth research; do
CGO_ENABLED=0 go test -mod=readonly -c -o "bin/$package-tests" "./internal/$package"
docker run --rm --network "container:$container" --user 1000:1000 \
@@ -81,6 +87,7 @@ done
# Run the actual pinned Endoleap runtime against this build's authenticated HTTP
# routes and the same disposable database. Only this remote container needs Node.
# 可选 pinned Endoleap 客户端需要 Node,额外运行一次真实 HTTP 客户端集成;未提供时跳过该阶段。
if [[ -n "${HEADLESS_CLIENT_SOURCE:-}" ]]; then
test -f "$HEADLESS_CLIENT_SOURCE/tests/headless/foundry.integration.mjs"
docker run --rm --network "container:$container" --user 1000:1000 \
+5
View File
@@ -1,4 +1,5 @@
#!/usr/bin/env bash
# 远程私有 worker 启动器;使用与 Core 同一二进制的 codex-worker 模式,CLI 和登录目录由运维预先提供。
set -euo pipefail
base=/opt/endoleap-infra
@@ -7,14 +8,18 @@ binary=$(realpath "$1")
test -x "$binary"
test -s "$dir/home/auth.json"
test -s "$dir/grants/projects.json"
# socket 目录归容器 uid 1000,socket 本身由服务设为 0600;不公布宿主 TCP 端口。
install -d -m 700 "$dir/run"
chown 1000:1000 "$dir/run"
# 可选目录声明已验证图片输出后端;没有此名单时不根据图片输入能力推测图片生成能力。
canvas_env=()
if [[ -s "$dir/canvas.env" ]]; then canvas_env=(--env-file "$dir/canvas.env"); fi
# The host operator supplies an isolated Codex home and starts a single worker.
# The Docker default bridge supplies egress independently of Foundry's network.
# 单 worker 使用独立 bridge 出网,根文件系统只读;临时任务写 /tmp,登录目录需允许 CLI 自身状态更新。
# CLI/二进制只读挂载,Core 只看到 socket,不共享本登录目录。
docker run -d --name foundry-codex-worker --restart unless-stopped --init \
--network bridge --user 1000:1000 --cap-drop ALL --security-opt no-new-privileges \
--read-only --pids-limit 128 --memory 1g --tmpfs /tmp:rw,nosuid,nodev \
+8
View File
@@ -1,5 +1,7 @@
#!/usr/bin/env python3
"""Apply checked migrations atomically from the trusted deployment runner."""
# 部署 runner 入口:组合所有尚未执行的迁移及授权为单个外层事务,失败整体回滚。
# db/*.sql 的校验和覆盖原始注释;历史文件不可仅为加注释而改写,中文对象说明见 docs/database-comments.sql。
import argparse
import hashlib
import os
@@ -7,6 +9,7 @@ from pathlib import Path
import re
import subprocess
# 数据库/角色会插入 SQL 标识符,先严格限制为小写标识;container 通过 argv 传给 docker。
parser = argparse.ArgumentParser()
parser.add_argument("--container", default=os.environ.get("FOUNDRY_POSTGRES_CONTAINER", "foundry-postgres"))
parser.add_argument("--database", default="foundry_auth")
@@ -19,6 +22,7 @@ migrations = sorted((Path(__file__).resolve().parent.parent / "db").glob("[0-9]*
if not migrations:
raise SystemExit("No migrations found")
# psql 遇错立即退出,固定 advisory 事务锁串行化同库部署,lock_timeout 防止无限等锁。
script = [
"\\set ON_ERROR_STOP on",
"BEGIN;",
@@ -33,6 +37,7 @@ for index, path in enumerate(migrations):
name = path.name
if not re.fullmatch(r"[0-9]+-[a-z0-9-]+\.sql", name):
raise SystemExit("Invalid migration name")
# 原文 SHA-256 与已执行记录逐字匹配,禁止同名历史迁移在部署后被静默修改。
checksum = hashlib.sha256(source.encode()).hexdigest()
tables.update(re.findall(r"CREATE TABLE ([a-z_]+)", source))
# The first deployed version predates migration tracking.
@@ -55,6 +60,7 @@ for index, path in enumerate(migrations):
"\\endif",
"\\else",
])
# 每份源文件显式 BEGIN/COMMIT;去除内层边界后放入外层统一事务,而非逐文件部分提交。
source = source.strip()
if not source.startswith("BEGIN;") or not source.endswith("COMMIT;"):
raise SystemExit("Migration must have explicit transaction boundaries")
@@ -63,12 +69,14 @@ for index, path in enumerate(migrations):
f"INSERT INTO foundry_schema_migrations(name,checksum) VALUES('{name}','{checksum}');",
"\\endif",
])
# 从受信任源码的 CREATE TABLE 清单补应用 DML 权限;identity 序列另授予使用/读取权限。
for table in sorted(tables):
script.append(f'GRANT SELECT,INSERT,UPDATE,DELETE ON TABLE "{table}" TO "{args.role}";')
script.extend([
f'GRANT USAGE,SELECT ON SEQUENCE link_clicks_id_seq TO "{args.role}";',
"COMMIT;",
])
# SQL 经标准输入交给容器内 psql,不把数据库密码或整段 SQL 拼成 shell 命令参数。
subprocess.run(
["docker", "exec", "-i", args.container, "sh", "-c",
'exec psql -X -U "${POSTGRES_USER:-postgres}" -d "$1" -v ON_ERROR_STOP=1', "sh", args.database],
+13
View File
@@ -1,4 +1,6 @@
#!/usr/bin/env bash
# 由 main 部署工作流在远程基础设施主机执行,参数一必须是已构建的 Foundry 二进制。
# 本脚本会迁移数据库、替换 worker 并启动候选服务,不能当作本地静态检查执行。
set -euo pipefail
umask 077
@@ -8,6 +10,7 @@ origin=https://api.foundry.entroia.com
candidate=foundry-core-candidate
network=endoleap-dev_default
# 必需凭据仅从环境传入,拒绝换行以保持容器环境参数边界,日志不打印值。
for name in GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET; do
value=${!name-}
if [[ -z "$value" || "$value" == *$'\n'* || "$value" == *$'\r'* ]]; then
@@ -16,6 +19,7 @@ for name in GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET; do
fi
done
# Accept formatted JSON from Actions Variables and never print its contents.
# 将 Actions 中可多行排版的 JSON 压为单行;这里只校验映射形状,URL 协议由服务启动继续验证。
FOUNDRY_PROJECTS=$(python3 - <<'PYCONFIG'
import json
import os
@@ -44,11 +48,14 @@ test -s "$foundry/database.env"
ca_bundle=/etc/ssl/certs/ca-certificates.crt
test -s "$ca_bundle"
docker network inspect "$network" >/dev/null
# 先运行全事务迁移及角色授权,迁移失败立即终止,不让新服务在半升级 schema 上启动。
python3 "$(dirname "$0")/migrate.py"
# 每次发布使用独立二进制目录供只读挂载;本脚本不清除旧 release 目录。
release=$(mktemp -d "$foundry/release.XXXXXXXX")
install -m 755 "$1" "$release/foundry"
export HOST=0.0.0.0 PORT=8080 PUBLIC_ORIGIN="$origin"
# 邮件/研究配置可选且从受保护文件加载;Slack 优先 Actions 环境,缺省才回退服务器文件。
mail_env=()
if [[ -s "$foundry/mail.env" ]]; then
mail_env=(--env-file "$foundry/mail.env")
@@ -73,6 +80,7 @@ elif [[ -s "$foundry/slack.env" ]]; then
fi
codex_mounts=()
codex_dir=$foundry/codex
# 存在 worker 配置才启用 IPC;worker 必须先与当前 Core 二进制协议对齐,启动失败恢复旧 worker。
if [[ -d "$codex_dir" ]]; then
# Core and its private worker must speak the same Canvas artifact protocol.
# Keep the previous container definition for exact startup rollback.
@@ -107,6 +115,7 @@ if [[ -d "$codex_dir" ]]; then
printf 'Canvas worker startup/catalog verification failed; previous worker restored.\n' >&2
exit 1
fi
# 目录探测成功后删除旧 worker 定义;后续候选/路由失败不会再恢复该 worker,回滚范围需据此理解。
if [[ -n "$worker_backup" ]]; then docker rm "$worker_backup" >/dev/null; fi
for attempt in {1..20}; do
[[ ! -S "$codex_dir/run/worker.sock" ]] || break
@@ -122,6 +131,7 @@ if [[ -d "$codex_dir" ]]; then
)
fi
# Core 只挂载 IPC/授权表,不挂载 CLI 登录;以非 root、只读根文件系统和裁剪能力运行。
docker run -d --name "$candidate" "${codex_mounts[@]}" "${mail_env[@]}" "${slack_env[@]}" "${research_env[@]}" --network "$network" \
--env-file "$foundry/database.env" -e HOST -e PORT -e PUBLIC_ORIGIN \
-e GOOGLE_CLIENT_ID -e GOOGLE_CLIENT_SECRET -e FOUNDRY_PROJECTS -e FOUNDRY_ONBOARDING \
@@ -132,11 +142,13 @@ docker run -d --name "$candidate" "${codex_mounts[@]}" "${mail_env[@]}" "${slack
--mount "type=bind,source=$release/foundry,target=/opt/foundry,readonly" \
node:24-bookworm-slim /opt/foundry >/dev/null
# 候选或路由失败时删除本次新 Core;旧 Core 由 route 成功探测后才停止。
cleanup_candidate() {
docker rm -f "${live:-$candidate}" >/dev/null 2>&1 || true
}
trap cleanup_candidate EXIT
# 容器内 smoke 只验证 CA 文件、数据库就绪及匿名请求被拒,不执行真实 OAuth 或付费模型。
docker exec "$candidate" node -e '
const assert = require("node:assert/strict");
const fs = require("node:fs");
@@ -166,6 +178,7 @@ docker exec "$candidate" node -e '
# Keep the previous running container until the new candidate has passed checks.
# Traefik reads the route atomically from its watched config directory.
# 使用容器 ID 前缀命名新 live,route.sh 负责原子路由写入、外部就绪检查和失败恢复路由。
id=$(docker inspect -f '{{.Id}}' "$candidate")
live=foundry-core-${id:0:12}
docker rename "$candidate" "$live"
+4
View File
@@ -1,3 +1,5 @@
-- 运维手动索引步骤:对已发布 research schema 执行,不能由只读服务角色调用,也不能包进事务。
-- 不属于 db/ 版本迁移;CREATE INDEX CONCURRENTLY 需要独立顶层语句,避免长时间阻塞语料读取。
-- Manual operator step against the published Paper Atlas schema, outside a
-- transaction. Core's SELECT-only runtime role must never execute this file.
-- These indexes support the actual author search and exact category filter;
@@ -6,8 +8,10 @@ SET lock_timeout = '2s';
SET statement_timeout = '20min';
SET maintenance_work_mem = '32MB';
SET max_parallel_maintenance_workers = 0;
-- (tag_id,paper_id) 支持纯主题页直接走关联索引,在 LIMIT 前避免读所有宽论文行。
CREATE INDEX CONCURRENTLY IF NOT EXISTS paper_tags_tag_paper
ON research.paper_tags(tag_id,paper_id);
-- simple 配置匹配作者查询的表达式,不对姓名做 english 词干化;索引表达式须与查询一致。
CREATE INDEX CONCURRENTLY IF NOT EXISTS papers_authors_search_gin
ON research.papers USING gin(to_tsvector('simple'::regconfig,authors_json));
-- After an interrupted concurrent build, inspect pg_index.indisvalid before
+7
View File
@@ -1,4 +1,5 @@
#!/usr/bin/env bash
# 远程部署的路由切换阶段,参数必须是本次已通过内部就绪检查的 Core 容器名。
set -euo pipefail
umask 077
cd /opt/endoleap-infra
@@ -8,12 +9,14 @@ live=$1
install -d -m 700 dev/foundry-edge
edge=dev/foundry-edge
route=$edge/foundry.yml
# 从现有动态配置提取旧容器;仅在新路由完成 HTTPS 探测后才停止它。
previous=
if [[ -f "$route" ]]; then
previous=$(sed -n 's@.*url: http://\(foundry-core-[a-f0-9]\{12\}\):8080.*@\1@p' "$route")
fi
backup=$(mktemp)
if [[ -f "$route" ]]; then cp "$route" "$backup"; fi
# EXIT trap 只恢复动态路由文件或删除新路由,不回滚已执行的数据库迁移/worker/Compose 配置。
rollback() {
if [[ -s "$backup" ]]; then
cp "$backup" "$edge/.restore"
@@ -25,6 +28,7 @@ rollback() {
}
trap rollback EXIT
# ACME 文件保存证书状态,限制权限;动态路由先写隐藏临时文件再 mv,避免 watcher 读到半文件。
touch "$edge/acme.json"
chmod 600 "$edge/acme.json"
cat > "$edge/.foundry.yml" <<YAML
@@ -49,6 +53,7 @@ http:
- url: http://$live:8080
YAML
mv "$edge/.foundry.yml" "$route"
# Compose 覆盖文件保持 Traefik 入口、证书与目录 provider 配置,不重建其他服务。
cat > foundry-edge.yml <<'YAML'
services:
traefik:
@@ -68,11 +73,13 @@ services:
YAML
docker compose -p endoleap-dev --env-file dev/env -f compose.yml -f dev.yml -f foundry-edge.yml up -d --no-deps traefik
# --resolve 在本机回环命中 Traefik,同时保留公开域名 Host/TLS 验证,探测真正的 HTTPS 路由。
curl --fail --silent --show-error --output /dev/null --max-time 6 \
--retry 15 --retry-delay 4 --retry-all-errors \
--resolve api.foundry.entroia.com:443:127.0.0.1 \
https://api.foundry.entroia.com/readyz
# HTTPS 就绪后解除回滚并删除备份;旧容器停止失败仅提示手工清理,不能误报新路由失败。
trap - EXIT
rm -f "$backup"
if [[ "$previous" =~ ^foundry-core-[a-f0-9]{12}$ && "$previous" != "$live" ]]; then
+115
View File
@@ -0,0 +1,115 @@
-- Foundry 数据库源码阅读注释索引(仅注释,不执行迁移)。
-- 历史 db/*.sql 的 SHA-256 由 deploy/migrate.py 原文计算并记录;即使只改注释,
-- 已部署库也会拒绝同名文件的新校验和。因此按迁移文件与对象名在此维护中文说明。
-- 顺序:001 认证 → 002 平台 → 003 快照 → 004 会话期限 → 005 子图事务 →
-- 006 资产 → 007 AI 队列 → 008 canonical 模型 → 009–011 AI 身份/回执/位置。
-- db/001-auth.sql:四张基础认证表在一个事务中安装。
-- project_accounts:账户身份以 (project,id) 为主键,Google subject 在项目内唯一。
-- 同一 Google 用户可在不同项目有不同账户,邮箱是可空资料,不作为跨提供方自动合并依据。
-- oauth_attempts:十分钟 OAuth 尝试;state/browser 保存摘要,frontend_challenge 绑定
-- 前端兑换证明,google_verifier 原文用于服务器向 Google 兑换 PKCE 授权码。
-- 回调通过 DELETE ... RETURNING 原子消费,外部兑换失败也不会恢复已消费尝试。
-- login_grants:一分钟一次性交换码只存 token_hash,复合外键保证账户属于同一项目。
-- project_sessions:bearer 明文只交客户端,数据库仅存摘要和期限;删除账户级联清会话。
-- 三个 expires_at 索引提供过期定位能力,本文件本身不创建定时清理任务。
-- db/002-platform.sql:扩展身份提供方与协作资源,保留旧 Google 账户/会话。
-- project_accounts:google_subject 放宽可空;username 在项目内按 lower 唯一,
-- display_name/avatar_url 是可由用户维护的资料,updated_at 由应用更新。
-- oauth_attempts.provider 默认 google 兼容已有行;Slack 增加 oidc_nonce 防止 ID token 重放。
-- account_identities:以项目/提供方/subject 唯一定位账户,迁入既有 Google subject;
-- 项目/提供方/account 唯一约束限定同一账户每提供方只有一个绑定。
-- email_credentials:已验证邮箱凭据,邮箱须小写,password_hash 是 bcrypt;
-- 项目/email 主键及项目/account 唯一性不允许多个凭据冒用同一邮箱或账户。
-- email_registrations:未验证注册单独保存密码摘要和验证码摘要,未确认前不建立账户;
-- 重发注册由应用在邮箱级事务锁下替换待验证记录及过期时间。
-- email_outbox:邮件与注册同事务写入,available_at/attempts 控制重试;lease_id/
-- lease_until 使后台 worker 可认领并在租约失效后恢复,sent_at 标成功。
-- 发送成功后应用清空 body;SMTP 成功与数据库标记不原子,不能宣称严格只投递一次。
-- auth_rate_limits:仅保存限频键摘要,固定窗口过期后由应用 upsert 重置次数。
-- onboarding_responses:项目/账户唯一完成记录,answers/result 必须 JSON 对象;
-- 配合账户行锁,使并发首次引导只能创建一次工作区并重放已存结果。
-- workspaces:所有者外键指向同项目账户;工作区行锁是角色/所有权变更共享的串行点。
-- workspace_members:每人每工作区一个角色,admin/editor/viewer 的写权限由应用解释;
-- owner 必须保留 admin 成员的规则由服务控制,表约束没有单独自动生成该成员。
-- materials:按项目/工作区隔离的可复用内容对象,kind 为受限类型;version 是素材
-- 内容/元数据的乐观版本,后续新增 canvas_version 与它分离。
-- material_modified/material_created/material_alphabetical:对应列表排序的复合索引。
-- material_opens:账户级最近打开时间,可反复 upsert,不修改素材正文;专用索引支持最近打开。
-- tags/material_tags:标签名在工作区内忽略大小写唯一;双复合外键阻止跨工作区关联,
-- 标签/素材删除级联清关联,应用负责让受影响素材版本递增。
-- board_layouts:旧布局引用可复用素材,位置/尺寸与内容独立;禁止引用自身,
-- “必须 board 且不可嵌套 board”及每板最多 2000 条由服务检查。
-- material_grants:显式 editor/viewer 素材权限,不存在素材级 admin 授予;
-- 根画布继承和归档祖先检查由 lockMaterial 的递归查询决定。
-- share_links:仅保存邀请摘要;可指工作区或单素材,单素材不允许 admin;
-- max_uses/use_count 是额度,expires_at/revoked_at 控制之后的兑换资格。
-- share_redemptions:同账户同链接只兑换一次;应用在持锁事务内插入成功后才加额度并提升角色。
-- link_clicks:公开点击独立于兑换计数,仅存 Referer origin,避免收集路径、查询和令牌。
-- bigint identity 支持递减 ID 分页;应用角色需单独授予序列 USAGE/SELECT。
-- db/003-canvas.sql:为 board 增加独立 canvas_version 和可空 canvas_document。
-- canvas_board_only 禁止非 board 保存快照;旧空文档在读取时投影为初始空 v1 图。
-- workspaces/materials 的 slug 先按名称/标题加 UUID 回填,再设 NOT NULL 和作用域唯一。
-- foundry_default_slug:仅 INSERT 且未给 slug 才派生值,名字更改不会隐式改 URL。
-- label 规范化并限长,空结果回退 canvas;触发器在两个表共享,因此区分 name/title。
-- db/004-session-lifetime.sql:加入 created_at 和九十天 absolute_expires_at 缺省。
-- 旧会话原始发行时间未知,绝对上限从迁移时开始,但原 expires_at 完全不变,
-- 已闲置过期的旧会话不会被此迁移复活。应用续期取 min(三十天后,绝对期限)。
-- db/005-canvas-subgraphs.sql:持久唯一所有权与多画布事务恢复信息。
-- canvas_subgraphs:Child 是主键中的唯一所有者身份,活跃 Parent/Frame 受部分唯一索引限制;
-- archived_at 保留恢复关系但从活跃树移除;migration_source 保存旧框迁移证据。
-- 父/子外键均 RESTRICT,不能删掉素材而留下无法解释的所有权记录。
-- foundry_check_subgraph:先锁工作区,确认两端是 board,再递归算祖先和后代,
-- 拒绝循环与深度超八;数据库触发器也保护绕过 HTTP 的维护写入。
-- canvas_transactions:账户/画布/动作/幂等键唯一,payload_hash 防止同键换体。
-- response_status/body 冻结重放结果;before_state、after_versions、relation_changes
-- 支持条件撤销;expires_at 七天及 undone_at 控制撤销有效性,不会自动倒退当前版本。
-- db/006-canvas-assets.sql:编码原图 bytea 与绑定同库事务提交,URL 与存储后端解耦。
-- canvas_assets:限制格式和二十 MiB 编码预算,上传者/工作区/幂等键唯一,digest 为原图摘要;
-- 完整像素预算与解码有效性由应用在写入前检查,不能只依赖 MIME 字符串。
-- canvas_asset_bindings:资产可被多个画布引用,主键去重;删除画布级联清绑定,
-- 有绑定资产不能直接删除。可读性按当前绑定画布授权判断,缓存字节不能作为权限证明。
-- db/007-canvas-ai.sql:run/step/event 与旧取消/显式应用回执。
-- canvas_ai_runs:冻结 plan/create_response,保存队列时间、取消位、租约与单调 last_seq;
-- pending 部分索引服务认领,active 索引服务活跃列表;expires_at 表示三十天保留期限。
-- canvas_ai_steps:每 run 的拓扑 ordinal、冻结输入、目标指纹、输出与应用版本;
-- 局部 board/node 活跃部分唯一索引防止同目标同时重复生成。
-- canvas_ai_events:以 run/seq 主键保证重放顺序;appendAIEvent 用同一 SQL 推进 last_seq。
-- canvas_ai_mutations:旧协议按 run/账户/动作/键冻结应用和取消结果;不同于 run 生成重试。
-- 租约过期不证明模型尚未执行,恢复把未知执行标为中断,只有明确 codex_busy 才允许回队。
-- db/008-canvas-model.sql:只安装 canonical schema,不自动迁移已有用户快照。
-- canvas_model_projects:每根显式迁移身份屏障,记录源版本表与 migration_id。
-- canvas_model_canvases:树关系、入口元素、独立版本及 archived;父/入口同时可空,
-- 无父只能是根;延迟外键允许入口元素与孩子关系在同批创建,提交时再验证。
-- canvas_model_active_entry 部分唯一索引防止一个活跃入口拥有多个子画布。
-- canvas_model_elements:主键 (project,element_id) 使身份跨工作区/树不可被抢占;
-- record 的 id/owner/incarnation 必须与索引列相符,删除记录保留 deleted_incarnation。
-- owner 外键延迟验证,支持同事务移动所有权;应用验证整个最终树和连接共同祖先。
-- canvas_model_identity_map:保留来源画布/结构/旧 ID 到稳定元素 ID 的完整一次性映射。
-- canvas_model_requests:账户作用域请求键、动作、摘要、状态与冻结回执,确定拒绝也可恢复。
-- canvas_model_operations:逻辑 ID 独立于传输 request_id 去重,外键延迟到同事务回执落库;
-- 只有应用成功才消费逻辑身份,拒绝前缀不能把其中操作标为已执行。
-- foundry_guard_canonical_canvas:已迁入树的 canvas_document/version 改写需事务内
-- foundry.canonical_writer=on,阻止旧写入路径覆盖权威身份。此标志是应用协作约定,不替代数据库角色权限。
-- db/009-canvas-ai-operations.sql:为 run 增加可空 logical_operation_id,旧行保持 NULL。
-- 部分唯一索引限定项目/工作区/账户下同逻辑操作只能准入一个 run,换传输键不能重复付费执行。
-- db/010-canvas-ai-receipts.sql:把传输回执从执行保留周期中分离。
-- canvas_ai_requests:允许 run.start/cancel/apply,保存 applied/not-applied 与原始请求身份;
-- 不以 run 外键级联删除,使 run 清理后仍可判定已知结果,工作区删除则整体清理。
-- applied 逻辑操作部分唯一:确定零效果拒绝可显式用新键重计划,已应用操作不能再次执行。
-- INSERT ... SELECT 从旧 canonical run 回填 accepted 回执,ON CONFLICT 保留已有记录。
-- 回执缺失只能回答 unknown,不能证明历史付费调用从未发生。
-- db/011-canvas-ai-target-location.sql:分离冻结来源与实际应用位置。
-- applied_board_id:结果写到 owner 移动后的目标画布,旧已应用行按原 board_id 回填。
-- canvas_ai_canonical_target_busy:按根/稳定节点/代数而非原 board 唯一限制活跃步骤,
-- owner-only 移动不能逃过 node_busy,再次删除/恢复的新代则由生命周期检查单独处理。
+4
View File
@@ -1,12 +1,16 @@
// Foundry Go 模块身份,internal 包的导入前缀必须与此一致。
module gitea.entroia.com/Zayden-Jung/foundry-core
// CI 从此读取工具链版本,避免开发和远程构建使用不同语言契约。
go 1.25.0
// 直接依赖提供 PostgreSQL 驱动/事务与图片解码缩放能力。
require (
github.com/jackc/pgx/v5 v5.7.6
golang.org/x/image v0.25.0
)
// 以下保留 Go 模块图要求的间接依赖;版本校验摘要由 go.sum 管理。
require (
github.com/jackc/pgpassfile v1.0.0 // indirect
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+22
View File
@@ -1,3 +1,4 @@
// Package auth 管理项目隔离的登录:提供方回调产生 grant,前端凭 verifier 换取 bearer 会话。
package auth
import (
@@ -19,9 +20,11 @@ import (
"time"
)
// 项目名限制为可用于路由的短标识;令牌格式对应 32 随机字节的无填充 base64url。
var projectName = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
var tokenPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{43}$`)
// service 共享数据库、回调白名单和外部 HTTP 客户端;passwordSlots 限制 bcrypt 并发。
type service struct {
db *sql.DB
projects map[string]*url.URL
@@ -33,13 +36,16 @@ type service struct {
slack *SlackConfig
}
// New 由进程入口调用,验证项目回调并返回独立认证路由;db 的关闭由调用方负责。
func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string, email *EmailConfig, slack *SlackConfig) (http.Handler, error) {
// 未注册邮箱也执行同成本密码比对,减少通过响应耗时区分账号存在性的差异。
dummy, err := bcrypt.GenerateFromPassword([]byte("foundry-invalid-login-placeholder"), bcrypt.DefaultCost)
if err != nil {
return nil, err
}
s := &service{db: db, email: email, slack: slack, passwordSlots: make(chan struct{}, 4), dummyPassword: dummy, projects: make(map[string]*url.URL), redirectURI: redirectURI, clientID: id, secret: secret,
google: &http.Client{Timeout: 10 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}}
// 回调固定在配置白名单,生产要求 HTTPS,开发仅允许回环主机使用 HTTP。
for name, raw := range callbacks {
u, err := url.Parse(raw)
if err != nil {
@@ -52,6 +58,7 @@ func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string
}
s.projects[name] = u
}
// healthz 仅说明进程可响应;readyz 查询账户表,覆盖连接与基础 schema 就绪性。
mux := http.NewServeMux()
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) { reply(w, 200, payload{"status": "ok"}) })
mux.HandleFunc("GET /readyz", s.wrap(func(w http.ResponseWriter, r *http.Request) error {
@@ -73,8 +80,10 @@ func New(db *sql.DB, callbacks map[string]string, redirectURI, id, secret string
}), nil
}
// payload 是小型 JSON 响应对象,nil 响应体用于 204 等无内容结果。
type payload map[string]any
// reply 必须在尚未写响应时调用;编码/网络错误当前由调用链忽略。
func reply(w http.ResponseWriter, status int, body payload) {
if body != nil {
w.Header().Set("Content-Type", "application/json")
@@ -85,11 +94,13 @@ func reply(w http.ResponseWriter, status int, body payload) {
}
}
// reject 已写出预期业务错误并返回 nil,避免 wrap 再次将它改写为 503。
func reject(w http.ResponseWriter, status int, code string) error {
reply(w, status, payload{"error": code})
return nil
}
// wrap 将未处理依赖错误统一返回 503,日志仅记录类型,避免泄露凭据和提供方响应。
func (s *service) wrap(handle func(http.ResponseWriter, *http.Request) error) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
if err := handle(w, r); err != nil {
@@ -99,17 +110,20 @@ func (s *service) wrap(handle func(http.ResponseWriter, *http.Request) error) ht
}
}
// token 生成可放入 Cookie、URL fragment 或请求头的随机凭据。
func token() string {
var value [32]byte
rand.Read(value[:])
return base64.RawURLEncoding.EncodeToString(value[:])
}
// digest 用于凭据落库摘要和 S256 challenge;不用于密码存储,密码使用 bcrypt。
func digest(value string) string {
sum := sha256.Sum256([]byte(value))
return base64.RawURLEncoding.EncodeToString(sum[:])
}
// project 先校验项目,再分派登录与会话动作;Origin 缺省的服务端请求仍可进入认证。
func (s *service) project(w http.ResponseWriter, r *http.Request) error {
project, action := r.PathValue("project"), r.PathValue("action")
frontend := s.projects[project]
@@ -150,11 +164,14 @@ func (s *service) project(w http.ResponseWriter, r *http.Request) error {
return nil
}
// oauthCookie 以随机 state 区分并行登录,__Host- 前缀配合 Secure、根路径和无 Domain。
func oauthCookie(state, value string, maxAge int) *http.Cookie {
return &http.Cookie{Name: "__Host-foundry-oauth-" + state, Value: value, Path: "/", MaxAge: maxAge,
Secure: true, HttpOnly: true, SameSite: http.SameSiteLaxMode}
}
// start 保存十分钟 OAuth 尝试;browser 绑定浏览器,verifier 用于 Google 端 PKCE。
// 前端 challenge 是另一层兑换证明,最终与 login_grants 绑定。
func (s *service) start(w http.ResponseWriter, r *http.Request, project string) error {
challenge := r.URL.Query().Get("challenge")
if !tokenPattern.MatchString(challenge) {
@@ -177,6 +194,7 @@ func (s *service) start(w http.ResponseWriter, r *http.Request, project string)
return nil
}
// googleJSON 同时用于 Google 和 Slack;客户端拒绝重定向,响应解码最多读取 1 MiB。
func (s *service) googleJSON(ctx context.Context, method, endpoint string, form url.Values, bearer string, result any) error {
var body io.Reader
if form != nil {
@@ -203,6 +221,7 @@ func (s *service) googleJSON(ctx context.Context, method, endpoint string, form
return json.NewDecoder(io.LimitReader(res.Body, 1<<20)).Decode(result)
}
// callback 原子删除 OAuth 尝试后换取 Google 身份;后续网络失败也不能重放该 state。
func (s *service) callback(w http.ResponseWriter, r *http.Request) error {
ctx := r.Context()
query := r.URL.Query()
@@ -232,6 +251,7 @@ func (s *service) callback(w http.ResponseWriter, r *http.Request) error {
}
http.SetCookie(w, oauthCookie(state, "", -1))
// 复制共享 URL 后再写 fragment,避免并发请求改动项目白名单;交换码不放查询参数。
destination := *frontend
code := query.Get("code")
if code == "" || query.Has("error") {
@@ -278,6 +298,7 @@ func (s *service) callback(w http.ResponseWriter, r *http.Request) error {
return nil
}
// exchange 在同一 SQL 中消费一次性 grant 并建会话;项目、challenge、期限必须全部匹配。
func (s *service) exchange(w http.ResponseWriter, r *http.Request, project string) error {
code, verifier := r.Header.Get("X-Foundry-Code"), r.Header.Get("X-Foundry-Verifier")
if !tokenPattern.MatchString(code) || !tokenPattern.MatchString(verifier) {
@@ -307,6 +328,7 @@ func (s *service) exchange(w http.ResponseWriter, r *http.Request, project strin
return nil
}
// account 的 me 分支校验并续期,logout 按项目删除摘要且允许重复注销返回 204。
func (s *service) account(w http.ResponseWriter, r *http.Request, project string, logout bool) error {
token, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
if !ok || !tokenPattern.MatchString(token) {
+12
View File
@@ -1,3 +1,4 @@
// 邮箱登录链路:注册写待验证记录和 outbox,确认链接才创建账户;登录直接校验 bcrypt。
package auth
import (
@@ -13,11 +14,14 @@ import (
"golang.org/x/crypto/bcrypt"
)
// emailAddress 统一大小写并拒绝显示名形式,只接受最多 254 字节的纯邮箱地址。
func emailAddress(value string) (string, bool) {
value = strings.ToLower(strings.TrimSpace(value))
address, err := mail.ParseAddress(value)
return value, err == nil && address.Address == value && len(value) <= 254
}
// emailBody 限制 16 KiB、拒绝未知字段及尾随 JSON;失败时已经写出 400。
func emailBody(w http.ResponseWriter, r *http.Request, input any) bool {
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 16384))
decoder.DisallowUnknownFields()
@@ -28,6 +32,7 @@ func emailBody(w http.ResponseWriter, r *http.Request, input any) bool {
return true
}
// rateLimit 将键摘要计入数据库十五分钟固定窗口,过期后第一次访问重新计数。
func (s *service) rateLimit(ctx context.Context, key string, limit int) (bool, error) {
var count int
err := s.db.QueryRowContext(ctx, `
@@ -40,6 +45,7 @@ RETURNING attempts
return count <= limit, err
}
// emailAction 由 project 路由调用;先限频,再以非阻塞信号量限制密码哈希占用。
func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, action string) error {
if action == "verify-email" {
return s.verifyEmail(w, r, project)
@@ -70,6 +76,7 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
w.Header().Set("Retry-After", "900")
return reject(w, 429, "rate_limited")
}
// 四个槽位都忙时立即返回 429,不让昂贵 bcrypt 请求无限排队。
select {
case s.passwordSlots <- struct{}{}:
defer func() { <-s.passwordSlots }()
@@ -87,6 +94,7 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
return err
}
passwordHash := []byte(hash)
// 不存在的账户使用启动时生成的 dummy 哈希,但无论密码比对结果如何均拒绝登录。
if missing {
passwordHash = s.dummyPassword
}
@@ -102,6 +110,8 @@ func (s *service) emailAction(w http.ResponseWriter, r *http.Request, project, a
return nil
}
// registerEmail 在邮箱级事务锁下更新三十分钟验证记录,邮件与记录共同提交。
// 已注册邮箱不写新邮件,仍返回相同 202,避免从此响应枚举账号。
func (s *service) registerEmail(w http.ResponseWriter, r *http.Request, project, email, password string) error {
hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
if err != nil {
@@ -147,6 +157,8 @@ INSERT INTO email_outbox(project,recipient,subject,body,expires_at) VALUES($1,$2
return nil
}
// verifyEmail 先定位邮箱再加同一事务锁,随后删除并返回有效记录以保证验证码一次性消费。
// 账户、邮箱凭据、会话都成功后才提交,任何失败交由 defer 回滚。
func (s *service) verifyEmail(w http.ResponseWriter, r *http.Request, project string) error {
var input struct {
Token string `json:"token"`
+3
View File
@@ -1,3 +1,4 @@
// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。
package auth
import (
@@ -12,6 +13,7 @@ import (
"testing"
)
// TestConcurrentRegistrationAndVerification 并发重发注册与消费原验证链接,允许任一先取得邮箱锁;最终只能留下一个凭据或一个待验证记录。
func TestConcurrentRegistrationAndVerification(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -45,6 +47,7 @@ func TestConcurrentRegistrationAndVerification(t *testing.T) {
if len(match) != 2 {
t.Fatal("missing verification link")
}
// 缓冲通道收集两条 goroutine 的结果;这里断言最终数据库一致性,不规定抢锁顺序。
done := make(chan error, 2)
go func() {
r := httptest.NewRequest("POST", "https://api.example.com/register", nil)
+9 -1
View File
@@ -1,3 +1,4 @@
// 本文件把 Google、Slack、邮箱等提供方身份归一为项目账户,并签发一次性交换码。
package auth
import (
@@ -8,7 +9,10 @@ import (
"strings"
)
// identityGrant 由已完成提供方验证的登录流程调用;subject 必须是该提供方的稳定身份。
// challenge 来自前端登录起点,后续 exchange 必须提交对应 verifier 才能换取会话。
func (s *service) identityGrant(ctx context.Context, project, provider, subject string, email *string, name, picture, challenge string) (string, error) {
// 外部资料仅作为初始显示信息:限制姓名长度,头像只接受无用户信息的 HTTPS URL。
name = strings.TrimSpace(name)
if len(name) > 160 {
name = ""
@@ -20,13 +24,15 @@ func (s *service) identityGrant(ctx context.Context, project, provider, subject
if err != nil {
return "", err
}
// 账户、身份关联和短期 grant 同事务提交;任一步失败都不遗留半注册账户。
defer tx.Rollback()
// Serialize first registration for the same provider identity.
// 事务级 advisory lock 串行化同项目、同提供方、同 subject 的首次注册;事务结束即释放。
if _, err = tx.ExecContext(ctx, "SELECT pg_advisory_xact_lock(hashtextextended($1,0))", project+":"+provider+":"+subject); err != nil {
return "", err
}
var account string
err = tx.QueryRowContext(ctx, "SELECT account_id::text FROM account_identities WHERE project=$1 AND provider=$2 AND subject=$3", project, provider, subject).Scan(&account)
// 身份不存在才建账户;不会仅凭相同邮箱自动合并不同提供方的身份。
if errors.Is(err, sql.ErrNoRows) {
var googleSubject *string
if provider == "google" {
@@ -44,6 +50,7 @@ SELECT $1,id,$2,$3,
}
_, err = tx.ExecContext(ctx, "INSERT INTO account_identities(project,provider,subject,account_id) VALUES($1,$2,$3,$4)", project, provider, subject, account)
} else if err == nil {
// 老账户保留已有显示名/头像,只补空值;非空提供方邮箱会更新账户邮箱。
_, err = tx.ExecContext(ctx, `
UPDATE project_accounts SET email=COALESCE($3,email),
display_name=CASE WHEN display_name='' THEN $4 ELSE display_name END,
@@ -55,6 +62,7 @@ UPDATE project_accounts SET email=COALESCE($3,email),
if err != nil {
return "", err
}
// 只落库交换码摘要,明文仅返回给回调方;一分钟期限和前端 challenge 限制兑换。
grant := token()
_, err = tx.ExecContext(ctx, "INSERT INTO login_grants VALUES($1,$2,$3,$4,now()+interval '1 minute')", digest(grant), project, account, challenge)
if err != nil {
+12
View File
@@ -1,3 +1,4 @@
// 邮件发送采用数据库 outbox:登录请求写队列,Run 后台轮询租约并通过 SMTP 投递。
package auth
import (
@@ -15,10 +16,12 @@ import (
"time"
)
// EmailConfig 是可选 SMTP 能力配置;Password 仅用于内存中的 SMTP 认证。
type EmailConfig struct {
Host, Port, Username, Password, From string
}
// EmailConfigFromEnv 允许整组缺省以关闭邮件登录;部分配置或非 465 TLS 配置会启动失败。
func EmailConfigFromEnv() (*EmailConfig, error) {
c := &EmailConfig{Host: os.Getenv("SMTP_HOST"), Port: os.Getenv("SMTP_PORT"), Username: os.Getenv("SMTP_USERNAME"), Password: os.Getenv("SMTP_PASSWORD"), From: os.Getenv("SMTP_FROM")}
if c.Host == "" && c.Port == "" && c.Username == "" && c.Password == "" && c.From == "" {
@@ -31,6 +34,8 @@ func EmailConfigFromEnv() (*EmailConfig, error) {
return c, nil
}
// send 同步发送一封纯文本邮件;拒绝头部换行,并用 TLS 主机名验证和连接期限约束网络操作。
// SMTP 调用不接收 context,Run 的取消要等当前发送结束或网络期限到达。
func (c *EmailConfig) send(recipient, subject, body string) error {
if strings.ContainsAny(recipient+subject, "\r\n") {
return errors.New("invalid mail headers")
@@ -69,6 +74,7 @@ func (c *EmailConfig) send(recipient, subject, body string) error {
return client.Quit()
}
// Run 由进程入口启动;每三秒最多认领一封,nil 配置直接返回,取消上下文停止后续轮询。
func (c *EmailConfig) Run(ctx context.Context, db *sql.DB) {
if c == nil {
return
@@ -86,6 +92,9 @@ func (c *EmailConfig) Run(ctx context.Context, db *sql.DB) {
}
}
}
// deliver 用 SKIP LOCKED 避开其他 worker 正在认领的行,两分钟租约允许进程失败后重试。
// SMTP 成功与数据库标记并非同一事务;标记失败时后续可能再次投递。
func (c *EmailConfig) deliver(ctx context.Context, db *sql.DB) error {
var id, lease, recipient, subject, body string
var attempts int
@@ -99,11 +108,14 @@ RETURNING id::text,lease_id::text,recipient,subject,body,attempts
if err != nil {
return err
}
// lease 是本轮所有权标记;回写时匹配它,避免旧 worker 覆盖租约到期后的新认领结果。
sendErr := c.send(recipient, subject, body)
if sendErr == nil {
// 成功后清空邮件正文,减少验证码在队列中的保留;收件人和投递记录仍保留。
_, err = db.ExecContext(ctx, "UPDATE email_outbox SET sent_at=now(),body='',lease_until=NULL,lease_id=NULL WHERE id=$1 AND lease_id=$2", id, lease)
return err
}
// attempts 在认领时递增:第一次失败延迟 60 秒,指数退避最多 3840 秒,最多尝试十次。
delay := 30 * (1 << min(attempts, 7))
_, err = db.ExecContext(ctx, "UPDATE email_outbox SET available_at=now()+$3*interval '1 second',lease_until=NULL,lease_id=NULL WHERE id=$1 AND lease_id=$2", id, lease, delay)
if err != nil {
+11
View File
@@ -1,3 +1,4 @@
// 本文件是认证与 platform/research 路由共享的会话入口:数据库同时检查项目、闲置期限和绝对期限。
package auth
import (
@@ -9,11 +10,16 @@ import (
"strings"
)
// SessionIdleSeconds 是每次有效访问可续期的闲置窗口,绝对期限仍由数据库列限制。
const SessionIdleSeconds = 30 * 24 * 60 * 60
// SessionExpiryHeader 向客户端返回本次续期后的剩余秒数,供其更新本地会话提示。
const SessionExpiryHeader = "X-Foundry-Session-Expires-In"
// ErrInvalidSession 区分凭据无效与数据库故障,调用方可据此选择 401 或服务错误。
var ErrInvalidSession = errors.New("invalid session")
// Session 只携带项目内账户和剩余有效期;原始 bearer token 不进入返回结构。
type Session struct {
AccountID string
ExpiresIn int64
@@ -21,11 +27,13 @@ type Session struct {
// AuthenticateSession atomically validates and renews a live session, bounded by
// its absolute deadline. Expired, revoked and wrong-project tokens never renew.
// AuthenticateSession 在单条 UPDATE 中检查项目、闲置和绝对期限,仅续期仍有效会话并返回剩余秒数。
func AuthenticateSession(ctx context.Context, db *sql.DB, project, authorization string) (Session, error) {
value, ok := strings.CutPrefix(authorization, "Bearer ")
if !ok || !tokenPattern.MatchString(value) {
return Session{}, ErrInvalidSession
}
// 单条 UPDATE 完成校验和续期,避免先查后写把已经撤销或过期的会话重新激活。
var session Session
err := db.QueryRowContext(ctx, `
UPDATE project_sessions
@@ -33,17 +41,20 @@ SET expires_at=LEAST(now()+interval '30 days',absolute_expires_at)
WHERE project=$1 AND token_hash=$2 AND expires_at>now() AND absolute_expires_at>now()
RETURNING account_id::text,GREATEST(0,FLOOR(EXTRACT(EPOCH FROM (expires_at-now()))))::bigint
`, project, digest(value)).Scan(&session.AccountID, &session.ExpiresIn)
// 无匹配行包含错误项目、已注销、闲置过期和绝对过期,统一隐藏具体原因。
if errors.Is(err, sql.ErrNoRows) {
return Session{}, ErrInvalidSession
}
return session, err
}
// WriteSessionHeaders 由 HTTP 调用方在写出响应体前执行;它本身不校验或续期。
func WriteSessionHeaders(w http.ResponseWriter, session Session) {
w.Header().Set(SessionExpiryHeader, strconv.FormatInt(session.ExpiresIn, 10))
}
// Authenticate preserves the existing API for clients that only need an account ID.
// Authenticate 供只需账户 ID 的旧调用方使用,同样会触发 AuthenticateSession 的续期。
func Authenticate(ctx context.Context, db *sql.DB, project, authorization string) (string, error) {
session, err := AuthenticateSession(ctx, db, project, authorization)
return session.AccountID, err
+5
View File
@@ -1,3 +1,4 @@
// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。
package auth
import (
@@ -14,6 +15,7 @@ import (
_ "github.com/jackc/pgx/v5/stdlib"
)
// sessionFixture 建随机项目账户,通过 t.Cleanup 级联删除相关数据并关闭连接池。
func sessionFixture(t *testing.T) (*sql.DB, string, string) {
t.Helper()
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
@@ -33,6 +35,7 @@ func sessionFixture(t *testing.T) (*sql.DB, string, string) {
return db, project, account
}
// TestSessionIdleAndAbsoluteExpiry 覆盖闲置/绝对过期与续期上限;过期记录的时间戳不得被认证请求更新。
func TestSessionIdleAndAbsoluteExpiry(t *testing.T) {
db, project, account := sessionFixture(t)
for _, test := range []struct {
@@ -85,6 +88,7 @@ func TestSessionIdleAndAbsoluteExpiry(t *testing.T) {
}
}
// TestSessionIsolationRevocationAndConcurrentRenewal 检查错误项目与坏凭据拒绝、四个并发续期受绝对期限限制、删除后不能重新续期。
func TestSessionIsolationRevocationAndConcurrentRenewal(t *testing.T) {
db, project, account := sessionFixture(t)
value := token()
@@ -116,6 +120,7 @@ func TestSessionIsolationRevocationAndConcurrentRenewal(t *testing.T) {
}
}
// TestOAuthExchangeIssuesLongLivedSessionAndMeReturnsRemainingLifetime 从真实 grant 兑换会话,检查三十天闲置/九十天绝对期限,以及 me 响应的续期头。
func TestOAuthExchangeIssuesLongLivedSessionAndMeReturnsRemainingLifetime(t *testing.T) {
db, project, account := sessionFixture(t)
code, verifier := token(), token()
+13
View File
@@ -1,3 +1,4 @@
// Slack OIDC 登录验证独立 ID token,再复用 identityGrant 和前端 grant 兑换协议。
package auth
import (
@@ -18,6 +19,7 @@ import (
"time"
)
// SlackConfig 保存可选客户端凭据以及由 mu 保护的签名公钥缓存。
type SlackConfig struct {
ClientID, Secret, RedirectURI string
mu sync.Mutex
@@ -25,6 +27,7 @@ type SlackConfig struct {
fetchedAt time.Time
}
// SlackConfigFromEnv 允许整组缺省以关闭 Slack;只配置一半会阻止服务启动。
func SlackConfigFromEnv(redirect string) (*SlackConfig, error) {
id, secret := os.Getenv("SLACK_CLIENT_ID"), os.Getenv("SLACK_CLIENT_SECRET")
if id == "" && secret == "" {
@@ -36,6 +39,7 @@ func SlackConfigFromEnv(redirect string) (*SlackConfig, error) {
return &SlackConfig{ClientID: id, Secret: secret, RedirectURI: redirect}, nil
}
// slackClaims 仅在验签、发行方/受众/时间和 nonce 校验后用于账户身份。
type slackClaims struct {
Issuer string `json:"iss"`
Subject string `json:"sub"`
@@ -50,6 +54,7 @@ type slackClaims struct {
Picture string `json:"picture"`
}
// slackKey 在互斥锁内加载并缓存 JWKS 一分钟;缓存期遇到未知 kid 直接拒绝,避免重复拉取。
func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, error) {
c := s.slack
c.mu.Lock()
@@ -73,6 +78,7 @@ func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, err
if err := s.googleJSON(ctx, "GET", "https://slack.com/openid/connect/keys", nil, "", &document); err != nil {
return nil, err
}
// 只接收可用于 RS256 签名的 RSA 公钥,并约束模数和指数大小。
keys := map[string]*rsa.PublicKey{}
for _, key := range document.Keys {
n, nErr := base64.RawURLEncoding.DecodeString(key.N)
@@ -93,6 +99,8 @@ func (s *service) slackKey(ctx context.Context, kid string) (*rsa.PublicKey, err
}
return nil, errors.New("unknown Slack signing key")
}
// verifySlack 限制 token 长度与算法,先验签再信任 payload;nonce 将身份绑定到本次登录。
func (s *service) verifySlack(ctx context.Context, value, nonce string) (slackClaims, error) {
var claims slackClaims
invalid := errors.New("invalid Slack identity token")
@@ -136,6 +144,8 @@ func (s *service) verifySlack(ctx context.Context, value, nonce string) (slackCl
}
return claims, nil
}
// startSlack 写十分钟尝试和 OIDC nonce,Cookie 采用 SameSite=None 以接收跨站 POST 回调。
func (s *service) startSlack(w http.ResponseWriter, r *http.Request, project string) error {
if s.slack == nil {
return reject(w, 503, "slack_not_configured")
@@ -159,6 +169,8 @@ VALUES($1,$2,$3,$4,'',now()+interval '10 minutes','slack',$5)
http.Redirect(w, r, "https://slack.com/openid/connect/authorize?"+query.Encode(), 302)
return nil
}
// slackCallback 接受 GET/POST,先一次性消费浏览器绑定的尝试,再向 Slack 兑换 ID token。
func (s *service) slackCallback(w http.ResponseWriter, r *http.Request) error {
if s.slack == nil {
return reject(w, 503, "slack_not_configured")
@@ -216,6 +228,7 @@ RETURNING project,frontend_challenge,oidc_nonce
if err != nil {
return err
}
// 团队和用户共同构成 subject;verifySlack 已拒绝冒号,避免拼接身份产生歧义。
grant, err := s.identityGrant(r.Context(), project, "slack", claims.Team+":"+claims.Subject, claims.Email, claims.Name, claims.Picture, challenge)
if err != nil {
return err
+9
View File
@@ -1,3 +1,4 @@
// 认证回归:数据库用例需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移的 fixture。
package auth
import (
@@ -21,6 +22,7 @@ import (
_ "github.com/jackc/pgx/v5/stdlib"
)
// signIdentity 为 fixture kid 生成 RS256 JWT;测试公钥缓存在内存,不访问 Slack JWKS。
func signIdentity(t *testing.T, key *rsa.PrivateKey, claims slackClaims) string {
t.Helper()
header := base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"RS256","kid":"fixture"}`))
@@ -36,6 +38,8 @@ func signIdentity(t *testing.T, key *rsa.PrivateKey, claims slackClaims) string
}
return value + "." + base64.RawURLEncoding.EncodeToString(sig)
}
// TestSlackIdentityVerification 使用本地 RSA 私钥签发样本,分别破坏发行方、受众、时间、nonce、签名及算法,仅有效样本可通过。
func TestSlackIdentityVerification(t *testing.T) {
key, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
@@ -76,6 +80,8 @@ func TestSlackIdentityVerification(t *testing.T) {
})
}
}
// TestSlackCallbackAndExchange 使用临时 HTTP 上游和真实测试库走 Slack 起点、POST 回调、grant 兑换;拒绝回调重放并保留用户已选资料。
func TestSlackCallbackAndExchange(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -184,8 +190,10 @@ func TestSlackCallbackAndExchange(t *testing.T) {
}
}
// rewriteTransport 只把测试外部调用改写到本地上游,保留路径和请求上下文。
type rewriteTransport struct{ destination string }
// RoundTrip 克隆请求后改目标,避免修改被测函数持有的原请求对象。
func (t rewriteTransport) RoundTrip(r *http.Request) (*http.Response, error) {
cloned := r.Clone(r.Context())
target, _ := url.Parse(t.destination)
@@ -193,6 +201,7 @@ func (t rewriteTransport) RoundTrip(r *http.Request) (*http.Response, error) {
return http.DefaultTransport.RoundTrip(cloned)
}
// TestGoogleIdentityKeepsLegacyAccount 依赖迁移 fixture 的旧 Google 身份与会话,验证新身份归一流程仍使用原账户且不删除旧会话。
func TestGoogleIdentityKeepsLegacyAccount(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
+12
View File
@@ -1,3 +1,4 @@
// 画布 AI 的私有 IPC 客户端与模型目录:平台侧只看到稳定模型 ID,执行后端保留在 worker 内。
package codex
import (
@@ -15,8 +16,10 @@ import (
"time"
)
// CanvasInputLimit 限制提示词字节数;图片另按解码后的总字节限制。
const CanvasInputLimit = 1 << 20
// CanvasModel 是过滤后的模型能力快照;Backend 不序列化,仅供 worker 启动 CLI。
type CanvasModel struct {
ID string `json:"id"`
Label string `json:"label"`
@@ -32,6 +35,7 @@ type CanvasModel struct {
// Only curated catalog fields leave the worker. Raw CLI cache metadata,
// local paths, authentication files and backend configuration stay private.
// workerCanvasModels 读取 worker 本地缓存,只公布 list 可见且支持文本/图像输入的条目。
func workerCanvasModels() ([]CanvasModel, error) {
raw, err := os.ReadFile("/home/node/.codex/models_cache.json")
if err != nil {
@@ -53,6 +57,7 @@ func workerCanvasModels() ([]CanvasModel, error) {
if entry.Visibility != "list" || entry.Slug == "" || strings.HasPrefix(entry.Slug, "-") || len(entry.Slug) > 128 {
continue
}
// 稳定散列生成公开 ID;标签可展示,实际 slug 不作为公开 Backend 字段输出。
sum := sha256.Sum256([]byte("codex-cli/" + entry.Slug))
inputs := []string{}
for _, value := range entry.Inputs {
@@ -72,6 +77,7 @@ func workerCanvasModels() ([]CanvasModel, error) {
}
result = append(result, CanvasModel{ID: "codex-" + hex.EncodeToString(sum[:16]), Label: label, Provider: "codex-cli", InputModalities: inputs, OutputModalities: []string{"text"}, Available: true, MaxExecutionMS: 90000, MaxInputBytes: CanvasInputLimit, ParametersSchema: map[string]any{"type": "object", "properties": map[string]any{}, "additionalProperties": false}, Backend: entry.Slug})
}
// 图片输出能力必须显式列入已验证后端名单,不能根据支持图片输入推断支持图片生成。
verified := map[string]bool{}
for _, id := range strings.Split(os.Getenv("FOUNDRY_CANVAS_IMAGE_MODELS"), ",") {
id = strings.TrimSpace(id)
@@ -95,8 +101,10 @@ func workerCanvasModels() ([]CanvasModel, error) {
return result, nil
}
// CanvasClient 通过固定 Unix socket 发送 HTTP;URL 主机名只是协议占位符,不进行 DNS 连接。
type CanvasClient struct{ client *http.Client }
// NewCanvasClient 在未配置 socket 时返回 nil,调用方法会转换为明确的不可用错误。
func NewCanvasClient(socket string) *CanvasClient {
if socket == "" {
return nil
@@ -106,6 +114,8 @@ func NewCanvasClient(socket string) *CanvasClient {
}}
return &CanvasClient{client: &http.Client{Transport: transport, Timeout: 182 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}}
}
// Models 限制目录响应为 256 KiB,只接受成功状态和完整 JSON,隐藏 worker 内部失败原因。
func (c *CanvasClient) Models(ctx context.Context) ([]CanvasModel, error) {
if c == nil {
return nil, errors.New("codex_unavailable")
@@ -135,6 +145,7 @@ func (c *CanvasClient) Models(ctx context.Context) ([]CanvasModel, error) {
return result.Models, nil
}
// CanvasTask 在 platform 调度器与 worker 之间传递提示、模型及可选图片;当前参数对象必须为空。
type CanvasTask struct {
OutputModality string `json:"output_modality,omitempty"`
Images []CanvasImage `json:"images,omitempty"`
@@ -143,6 +154,7 @@ type CanvasTask struct {
Parameters map[string]any `json:"parameters"`
}
// Generate 是只需文本的兼容入口;复用结构化输出校验,并拒绝图片结果。
func (c *CanvasClient) Generate(ctx context.Context, input CanvasTask) (string, error) {
output, err := c.GenerateOutput(ctx, input)
if err != nil {
+8
View File
@@ -1,3 +1,4 @@
// 画布生成的结构化 IPC 输出;图片以字节传到核心,再由平台资产流程验证和持久化。
package codex
import (
@@ -9,13 +10,17 @@ import (
"net/http"
)
// CanvasImageBytesLimit 限制原始图片总字节,响应上限另为 JSON/base64 编码留出空间。
const CanvasImageBytesLimit = 20 << 20
const canvasArtifactResponseLimit = 32 << 20
// CanvasImage 的 Data 在 JSON 中编码为 base64,仅用于私有 Unix 通道。
type CanvasImage struct {
MIME string `json:"mime_type"`
Data []byte `json:"data"`
}
// CanvasOutput 用 Kind 区分文本和图片,由 GenerateOutput 再校验形态与请求模态相符。
type CanvasOutput struct {
Kind string `json:"kind"`
Text string `json:"text,omitempty"`
@@ -24,6 +29,7 @@ type CanvasOutput struct {
// Encoded image bytes exist only on the private Unix IPC channel. Public Canvas
// jobs expose stable asset IDs/URLs and never serialize these bytes to browsers.
// GenerateOutput 先检查输入预算,再发送 IPC;映射稳定错误码,兼容旧 worker 的 result 文本字段。
func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (CanvasOutput, error) {
if c == nil {
return CanvasOutput{}, errors.New("codex_unavailable")
@@ -51,6 +57,7 @@ func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (Ca
return CanvasOutput{}, err
}
defer response.Body.Close()
// 多读一字节区分刚好达到上限与实际超限,防止截断响应被当成成功结果。
raw, err = io.ReadAll(io.LimitReader(response.Body, canvasArtifactResponseLimit+1))
if err != nil || len(raw) > canvasArtifactResponseLimit {
return CanvasOutput{}, errors.New("generation_failed")
@@ -80,6 +87,7 @@ func (c *CanvasClient) GenerateOutput(ctx context.Context, input CanvasTask) (Ca
return CanvasOutput{}, errors.New("generation_failed")
}
}
// 旧响应只允许回退到文本;图片请求缺少结构化图片时必须失败。
if result.Output == nil {
if input.OutputModality == "image" {
return CanvasOutput{}, errors.New("generation_failed")
+4
View File
@@ -1,3 +1,4 @@
// 本文件用临时目录和固定事件验证产物隔离及完成判定,不启动 CLI 或真实模型。
package codex
import (
@@ -7,6 +8,7 @@ import (
"testing"
)
// TestCanvasArtifactDirectoryIsolation 拒绝目录外图片、多张图片和软链接,只接收生成目录内唯一图片。
func TestCanvasArtifactDirectoryIsolation(t *testing.T) {
root := t.TempDir()
generated := filepath.Join(root, "generated_images")
@@ -48,6 +50,8 @@ func TestCanvasArtifactDirectoryIsolation(t *testing.T) {
t.Fatal("symlink escaped job output directory")
}
}
// TestCanvasAgentCompletionRequiresSuccessfulTurn 拒绝仅有部分文本或完成后报错的流,接受成功结束的流。
func TestCanvasAgentCompletionRequiresSuccessfulTurn(t *testing.T) {
if _, ok := canvasAgentText([]byte("{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",\"text\":\"partial\"}}\n")); ok {
t.Fatal("partial generation accepted")
+12
View File
@@ -1,3 +1,4 @@
// worker 侧画布执行:每次任务新建临时 CODEX_HOME,按模态启动 CLI 并提取完成结果。
package codex
import (
@@ -16,6 +17,7 @@ import (
"time"
)
// executeCanvasTask 由共享执行槽保护;模型已从目录选出,但仍须核对请求模态和输入图片。
func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask, model CanvasModel) {
imageOutput := input.OutputModality == "image"
if input.OutputModality != "" && input.OutputModality != "text" && !imageOutput {
@@ -32,6 +34,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
}
ctx, cancel := context.WithTimeout(r.Context(), duration)
defer cancel()
// 临时目录承载认证软链接、输入图片和生成产物;成功与所有失败路径都由 defer 删除。
job, err := os.MkdirTemp("", "foundry-canvas-")
if err != nil {
fail(w, 503, "codex_unavailable")
@@ -43,11 +46,13 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
fail(w, 503, "codex_unavailable")
return
}
// 关闭 shell、应用、插件等能力;文本模型还关闭图片生成,画布模式忽略用户配置与规则。
args := []string{"--ask-for-approval", "never", "--disable", "shell_tool", "--disable", "apps", "--disable", "plugins", "--disable", "multi_agent", "--disable", "hooks", "--disable", "memories", "-c", `web_search="disabled"`}
if !imageOutput {
args = append(args, "--disable", "image_generation")
}
args = append(args, "exec", "--json", "--sandbox", "read-only", "--skip-git-repo-check", "--ephemeral", "--ignore-user-config", "--ignore-rules", "--model", model.Backend)
// 对图片内容嗅探 MIME,而非仅信任传入类型;只允许已知栅格格式并限制总大小。
total := 0
for i, image := range input.Images {
total += len(image.Data)
@@ -80,6 +85,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
cmd.Dir = "/work"
cmd.Env = []string{"PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/home/node", "CODEX_HOME=" + home, "SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt"}
cmd.Stdin = strings.NewReader(prompt)
// 独立进程组使请求取消/超时可杀掉 CLI 及其子进程,避免残留后台任务。
cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
cmd.Cancel = func() error {
err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
@@ -103,6 +109,7 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
fail(w, 502, "generation_failed")
return
}
// CLI 退出零还不够:事件流必须完成且无错误,图片结果还需从专用产物目录读取。
text, completed := canvasAgentText(output.buffer.Bytes())
if !completed {
fail(w, 502, "generation_failed")
@@ -122,6 +129,8 @@ func executeCanvasTask(w http.ResponseWriter, r *http.Request, input CanvasTask,
}
writeJSON(w, 200, map[string]any{"output": result})
}
// canvasAgentText 逐行读取 JSON 事件,保留最后一条 agent_message;任何坏行或失败事件均拒绝。
func canvasAgentText(raw []byte) (string, bool) {
result := ""
completed := false
@@ -148,6 +157,9 @@ func canvasAgentText(raw []byte) (string, bool) {
}
return result, completed
}
// readCanvasGeneratedImage 只遍历本次 generated_images,拒绝软链接、非常规文件和多张候选图片。
// 此处只做格式嗅探与字节限制;完整解码和尺寸验证由平台资产接收流程负责。
func readCanvasGeneratedImage(root string) (*CanvasImage, error) {
var result *CanvasImage
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
+10
View File
@@ -1,3 +1,4 @@
// 公开文本生成代理:用项目专属凭据授权后,把受限任务通过 Unix IPC 转发给 worker。
package codex
import (
@@ -16,16 +17,19 @@ import (
"time"
)
// 公开请求 32 KiB、返回 512 KiB;worker 执行期限九十秒,IPC 客户端另留两秒收尾。
const (
maxRequest = 32 << 10
maxOutput = 512 << 10
timeout = 90 * time.Second
)
// task 仅允许 prompt,公开调用方不能传 sandbox、工具配置或可执行参数。
type task struct {
Prompt string `json:"prompt"`
}
// writeJSON 统一输出 JSON 并禁用缓存,内部调用者须在此之前完成状态码选择。
func writeJSON(w http.ResponseWriter, status int, value any) {
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Cache-Control", "no-store")
@@ -33,10 +37,12 @@ func writeJSON(w http.ResponseWriter, status int, value any) {
_ = json.NewEncoder(w).Encode(value)
}
// fail 将依赖或授权失败转换为稳定错误码,避免向公开 API 泄露本地路径和配置。
func fail(w http.ResponseWriter, status int, code string) {
writeJSON(w, status, map[string]string{"error": code})
}
// readTask 限制 JSON 大小、未知字段、尾随值与空白 prompt;失败时已写响应。
func readTask(w http.ResponseWriter, r *http.Request, limit int64) (task, bool) {
var input task
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, limit))
@@ -59,6 +65,7 @@ func readTask(w http.ResponseWriter, r *http.Request, limit int64) (task, bool)
// Register enables the public endpoint only when both configuration files are supplied.
// Each credential digest belongs to exactly one project.
// Register 在两项配置齐备时挂载路由,凭据文件每次请求重新读取以支持撤销。
func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile string) error {
if socket == "" && grantsFile == "" {
return nil
@@ -91,6 +98,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile
fail(w, 503, "codex_unavailable")
return
}
// 凭据是 32 字节十六进制值;将摘要与授权表恒定时间比较,再核对目标项目作用域。
hash := sha256.Sum256(key)
var scope string
for digest, project := range grants {
@@ -113,6 +121,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile
if !ok {
return
}
// IPC 只发送解析后的任务体,不转发公开 Authorization 头;连接目的地固定为配置的 socket。
body, _ := json.Marshal(input)
req, err := http.NewRequestWithContext(r.Context(), http.MethodPost, "http://codex/exec", bytes.NewReader(body))
if err != nil {
@@ -129,6 +138,7 @@ func Register(mux *http.ServeMux, projects map[string]string, socket, grantsFile
return
}
defer resp.Body.Close()
// worker 响应必须在预算内且为合法 JSON;保留其状态与 Retry-After,隐藏传输错误细节。
data, err = io.ReadAll(io.LimitReader(resp.Body, maxOutput+1))
if err != nil || len(data) > maxOutput || !json.Valid(data) {
fail(w, 502, "invalid_codex_response")
+3
View File
@@ -1,3 +1,4 @@
// 公开代理回归使用临时 Unix socket 假 worker,不访问外部服务或真实 CLI。
package codex
import (
@@ -13,6 +14,7 @@ import (
"testing"
)
// TestProjectAuthorizationAndForwarding 检查缺凭据/跨项目拒绝、严格任务体、大小限制及授权文件即时撤销。
func TestProjectAuthorizationAndForwarding(t *testing.T) {
dir := t.TempDir()
socket := filepath.Join(dir, "worker.sock")
@@ -20,6 +22,7 @@ func TestProjectAuthorizationAndForwarding(t *testing.T) {
if err != nil {
t.Fatal(err)
}
// 假 worker 要求代理已移除 Authorization,只回显 prompt,用于确认最小化转发契约。
worker := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/exec" || r.Header.Get("Authorization") != "" {
fail(w, 500, "unexpected_worker_request")
+12
View File
@@ -1,3 +1,4 @@
// Package codex 在核心 API 与受限 CLI worker 间通过 Unix socket 通信,隔离公开凭据与本地执行环境。
package codex
import (
@@ -15,16 +16,19 @@ import (
"time"
)
// executable 指向部署容器预装 CLI,不从请求或 PATH 选择可执行文件。
const executable = "/opt/codex/node_modules/.bin/codex"
var errOutputLimit = errors.New("Codex output limit exceeded")
// outputBuffer 对 CLI stdout 累计限额;超限标记用于进程结束后选择稳定错误响应。
type outputBuffer struct {
buffer bytes.Buffer
exceeded bool
limit int
}
// Write 实现 io.Writer,默认使用公共输出限制,画布事件流可另设更大内部预算。
func (b *outputBuffer) Write(p []byte) (int, error) {
limit := b.limit
if limit == 0 {
@@ -37,6 +41,7 @@ func (b *outputBuffer) Write(p []byte) (int, error) {
return b.buffer.Write(p)
}
// ServeWorker 由 main 的 codex-worker 模式调用,重建 0600 socket,只允许一个生成任务同时执行。
func ServeWorker(socket string) error {
syscall.Umask(0077)
if err := os.Remove(socket); err != nil && !errors.Is(err, os.ErrNotExist) {
@@ -50,6 +55,7 @@ func ServeWorker(socket string) error {
if err := os.Chmod(socket, 0600); err != nil {
return err
}
// 文本 /exec 与 /canvas/exec 共享一个槽位;忙时立即 429,目录读取不占执行槽。
slot := make(chan struct{}, 1)
mux := http.NewServeMux()
mux.HandleFunc("POST /exec", func(w http.ResponseWriter, r *http.Request) {
@@ -87,6 +93,7 @@ func ServeWorker(socket string) error {
fail(w, 503, "codex_unavailable")
return
}
// 仅按公开 ID 匹配当前目录,再在 worker 内取 Backend,调用方不能任意指定 CLI 模型名。
var selected *CanvasModel
for _, model := range models {
if model.ID == input.ModelID {
@@ -112,7 +119,10 @@ func ServeWorker(socket string) error {
return server.Serve(listener)
}
// execute 为旧文本入口保留默认模型选择,实际进程生命周期集中在 executeModel。
func execute(w http.ResponseWriter, r *http.Request, prompt string) { executeModel(w, r, prompt, "") }
// executeModel 用请求期限约束 CLI,禁用外部工具能力;失败仅公开错误码,不转发 stderr。
func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string) {
ctx, cancel := context.WithTimeout(r.Context(), timeout)
defer cancel()
@@ -126,6 +136,7 @@ func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string)
cmd.Dir = "/work"
cmd.Env = []string{"PATH=/usr/local/bin:/usr/bin:/bin", "HOME=/home/node", "CODEX_HOME=/home/node/.codex", "SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt"}
cmd.Stdin = strings.NewReader(prompt)
// Setpgid 配合负 PID kill 终止整个进程组;WaitDelay 约束取消后的输出管道等待。
cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
cmd.Cancel = func() error {
err := syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
@@ -146,6 +157,7 @@ func executeModel(w http.ResponseWriter, r *http.Request, prompt, model string)
case err != nil:
fail(w, 502, "codex_failed")
default:
// 只有合法事件流、成功结束事件及非空最终文本才能作为公开生成结果返回。
var result string
var completed bool
for _, line := range bytes.Split(bytes.TrimSpace(output.buffer.Bytes()), []byte("\n")) {
+20
View File
@@ -1,3 +1,4 @@
// 预览派生与进程内缓存:只缓存不可变图片字节,权限必须由调用方每次读取前另行检查。
package platform
import (
@@ -17,23 +18,30 @@ import (
"golang.org/x/image/draw"
)
// assetPreviewResult 只包含编码字节和 MIME,可与原图共用只读切片,禁止调用者原地修改。
type assetPreviewResult struct {
data []byte
mime string
}
// assetPreviewEntry 存储在 LRU 链表中,key 同时作为 map 索引,便于常数时间淘汰。
type assetPreviewEntry struct {
key string
value assetPreviewResult
}
// 缓存最多保留 32 MiB/128 项编码结果,互斥锁只覆盖索引操作,不覆盖解码缩放。
var previewMemory = struct {
sync.Mutex
entries map[string]*list.Element
order *list.List
bytes int
}{entries: make(map[string]*list.Element), order: list.New()}
// previewSlots 将所有预览完整解码限制为单并发,避免多个大图同时分配像素内存。
var previewSlots = make(chan struct{}, 1)
// previewWidth 仅接受原图或固定 1024 预览,不允许任意宽度组合造成无界缓存键。
func previewWidth(variant, width string) (int, error) {
if variant == "" && width == "" {
return 0, nil
@@ -46,6 +54,7 @@ func previewWidth(variant, width string) (int, error) {
// Cache only immutable bytes, after the caller checks current asset permission.
// Bound both decoded concurrency and retained encoded data.
// cachedAssetPreview 用原图摘要与宽度做键,命中即提升 LRU;等待执行槽可随请求取消。
func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width int) (assetPreviewResult, error) {
key := fmt.Sprintf("%x:%d", sha256.Sum256(encoded), width)
previewMemory.Lock()
@@ -75,6 +84,7 @@ func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width
if err != nil {
return result, err
}
// 单项过大仍可响应,但不留在缓存;其余按字节和项数双预算淘汰末尾最久未用项。
if len(result.data) > 8<<20 {
return result, nil
}
@@ -95,6 +105,7 @@ func cachedAssetPreview(ctx context.Context, encoded []byte, mime string, width
return result, nil
}
// makeAssetPreview 保留 GIF 动画和足够小的原图,其余应用 EXIF 后等比例缩至最长边预算。
func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResult, error) {
original := assetPreviewResult{encoded, mime}
// Keep animation intact. Original bytes remain the canonical AI/download input.
@@ -134,6 +145,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
draw.CatmullRom.Scale(resized, resized.Bounds(), source, source.Bounds(), draw.Src, nil)
var output bytes.Buffer
outputMime := "image/png"
// 不透明预览编码 JPEG 以减体积,透明预览保留 PNG;原图字节始终不被覆盖。
if resized.Opaque() {
err = jpeg.Encode(&output, resized, &jpeg.Options{Quality: 82})
outputMime = "image/jpeg"
@@ -143,6 +155,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
if err != nil {
return original, err
}
// 无需修正方向且重编码没有变小时直接用原图,避免更大派生文件。
if output.Len() >= len(encoded) && orientation == 1 {
return original, nil
}
@@ -151,6 +164,7 @@ func makeAssetPreview(encoded []byte, mime string, width int) (assetPreviewResul
// JPEG EXIF orientation is applied to previews instead of silently rotating a
// phone photograph after its EXIF metadata is removed by the image encoder.
// jpegOrientation 仅解析 JPEG APP1 中 TIFF 的 Orientation,逐层检查长度,异常/缺省均返回正常方向一。
func jpegOrientation(data []byte) int {
if len(data) < 4 || data[0] != 0xff || data[1] != 0xd8 {
return 1
@@ -206,11 +220,13 @@ func jpegOrientation(data []byte) int {
return 1
}
// orientedAsset 是只读坐标适配视图,不复制像素;5–8 方向旋转后宽高交换。
type orientedAsset struct {
image.Image
orientation int
}
// Bounds 报告纠正方向后的零起点矩形,供缩放器计算目标比例。
func (im orientedAsset) Bounds() image.Rectangle {
b := im.Image.Bounds()
if im.orientation >= 5 {
@@ -218,7 +234,11 @@ func (im orientedAsset) Bounds() image.Rectangle {
}
return image.Rect(0, 0, b.Dx(), b.Dy())
}
// ColorModel 继承原图颜色模型,实际像素读取交由 At 做反向坐标映射。
func (im orientedAsset) ColorModel() color.Model { return im.Image.ColorModel() }
// At 将显示坐标映回原图,再补 Bounds.Min,覆盖 EXIF 八种旋转/镜像组合。
func (im orientedAsset) At(x, y int) color.Color {
b := im.Image.Bounds()
w, h := b.Dx(), b.Dy()
+10
View File
@@ -1,3 +1,4 @@
// 画布与资产纯函数回归;测试说明对应实际断言,不依赖浏览器或真实模型。
package platform
import (
@@ -11,6 +12,7 @@ import (
"testing"
)
// TestAssetPreviewDownscalesWithoutChangingOriginal 生成 1600×900 不透明图,验证缩至 512×288、转 JPEG、体积变小且原图字节不变,并比对缓存结果。
func TestAssetPreviewDownscalesWithoutChangingOriginal(t *testing.T) {
source := image.NewNRGBA(image.Rect(0, 0, 1600, 900))
for y := 0; y < 900; y++ {
@@ -39,6 +41,8 @@ func TestAssetPreviewDownscalesWithoutChangingOriginal(t *testing.T) {
t.Fatal("cache result mismatch")
}
}
// TestAssetPreviewPreservesTransparencyAndAnimation 验证透明图继续用 PNG,GIF 分支直接保留传入字节;该 GIF 样本不验证真实动画解码。
func TestAssetPreviewPreservesTransparencyAndAnimation(t *testing.T) {
source := image.NewNRGBA(image.Rect(0, 0, 800, 400))
source.SetNRGBA(1, 1, color.NRGBA{255, 0, 0, 255})
@@ -62,6 +66,8 @@ func TestAssetPreviewPreservesTransparencyAndAnimation(t *testing.T) {
t.Fatal("GIF animation changed")
}
}
// TestAssetPreviewRejectsUnboundedWidths 验证公开参数仅接受原图或 1024 预览,拒绝任意宽度/未知变体;额外检查坏图片拒绝。
func TestAssetPreviewRejectsUnboundedWidths(t *testing.T) {
for _, value := range []string{"0", "1", "256", "512", "2048", "999999", "-1", "abc"} {
if _, err := previewWidth("preview", value); err == nil {
@@ -83,6 +89,8 @@ func TestAssetPreviewRejectsUnboundedWidths(t *testing.T) {
t.Fatal("malformed image accepted")
}
}
// TestAssetPreviewAppliesJPEGOrientation 手工插入小端 EXIF 方向六,验证缩图前旋转使最终尺寸由横向变为 128×256。
func TestAssetPreviewAppliesJPEGOrientation(t *testing.T) {
source := image.NewNRGBA(image.Rect(0, 0, 800, 400))
for y := 0; y < 400; y++ {
@@ -116,6 +124,8 @@ func TestAssetPreviewAppliesJPEGOrientation(t *testing.T) {
t.Fatalf("rotated dimensions %dx%d %v", config.Width, config.Height, err)
}
}
// TestAllAssetOrientationMappings 在八个方向视图中遍历像素,检查唯一红像素不丢失或重复;不逐点断言每种方向的完整布局。
func TestAllAssetOrientationMappings(t *testing.T) {
source := image.NewNRGBA(image.Rect(0, 0, 3, 2))
source.SetNRGBA(0, 0, color.NRGBA{255, 0, 0, 255})
+20
View File
@@ -1,3 +1,4 @@
// 不可变画布图片资产:上传原图字节并保留身份,读取时按当前绑定画布权限决定可见性。
package platform
import (
@@ -20,9 +21,11 @@ import (
_ "golang.org/x/image/webp"
)
// assetLimit 是单图编码字节上限,assetPixelLimit 在完整解码前限制像素分配预算。
const assetLimit = 20 << 20
const assetPixelLimit = 40_000_000
// assetInfo 是公开元数据,URL 稳定引用私有原图路由,不包含图片内容或上传者身份。
type assetInfo struct {
ID string `json:"id"`
MIME string `json:"mime_type"`
@@ -32,12 +35,14 @@ type assetInfo struct {
URL string `json:"url"`
}
// assetURL 将项目与工作区按路径段转义,所有绑定校验使用同一 URL 生成规则。
func (s *service) assetURL(project, workspace, id string) string {
return s.origin + "/projects/" + url.PathEscape(project) + "/workspaces/" + url.PathEscape(workspace) + "/assets/" + id
}
// Decode headers first and bound allocation before decoding the actual image.
// The MIME comes from the decoder, never from the filename or upload header.
// inspectAsset 先读取尺寸预算再完整解码,并比较两次识别格式/尺寸,拒绝截断或伪造头部图片。
func inspectAsset(encoded []byte) (string, int, int, error) {
config, format, err := image.DecodeConfig(bytes.NewReader(encoded))
if err != nil {
@@ -55,6 +60,9 @@ func inspectAsset(encoded []byte) (string, int, int, error) {
}
return "image/" + format, config.Width, config.Height, nil
}
// uploadAsset 分两次事务检查编辑权限:接收慢 multipart 正文和解码时不持有工作区锁。
// 幂等键限定在上传者/工作区,重复请求必须保持相同图片摘要和可选资源 ID。
func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -70,6 +78,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
reject(w, 400, "invalid_resource_id")
return nil
}
// 兼容旧版直接返回 assetInfo;指定 X-Resource-Id 的客户端获得带请求 ID 的 v2 应用回执。
respond := func(info assetInfo) {
if resourceID == "" {
reply(w, 201, info)
@@ -152,6 +161,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
reject(w, 403, "forbidden")
return nil
}
// 第二次取锁后重读权限和幂等记录,防止上传期间撤权或并发重试产生重复资产。
digest := sha256.Sum256(encoded)
hash := hex.EncodeToString(digest[:])
info := assetInfo{MIME: mime, Bytes: len(encoded), Width: width, Height: height}
@@ -192,6 +202,7 @@ func (s *service) uploadAsset(w http.ResponseWriter, r *http.Request, project, a
}
// A missing receipt is unknown: callers may only retry the same resource/key/bytes.
// assetOperation 在当前成员授权下查找本人上传回执;缺记录为 unknown,不能据此换键重传或判定零写入。
func (s *service) assetOperation(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -223,6 +234,9 @@ func (s *service) assetOperation(w http.ResponseWriter, r *http.Request, project
reply(w, 200, response{"protocol_version": 2, "request_id": key, "status": "applied", "asset": info})
return nil
}
// assetReadable 依赖调用方持有工作区锁:无绑定时只允许上传者/admin,有绑定时需至少一个绑定画布可读。
// 绑定可读性复用 lockMaterial,因此继承根画布权限并尊重子图归档状态。
func assetReadable(r *http.Request, tx *sql.Tx, project, workspace, id, account string) (bool, error) {
var uploader string
err := tx.QueryRowContext(r.Context(), `SELECT uploaded_by::text FROM canvas_assets WHERE project=$1 AND workspace_id=$2 AND id=$3`, project, workspace, id).Scan(&uploader)
@@ -273,6 +287,7 @@ func assetReadable(r *http.Request, tx *sql.Tx, project, workspace, id, account
}
// Metadata uses the same read policy as original bytes; it is not a persistent grant.
// getAssetMetadata 每次重新鉴权,读取不可变身份摘要后先提交释放锁,再写 JSON,不发放持久权限。
func (s *service) getAssetMetadata(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -318,6 +333,7 @@ func (s *service) getAssetMetadata(w http.ResponseWriter, r *http.Request, proje
return nil
}
// getAsset 同时服务原图与固定预览变体;先一致读取权限/字节,释放事务后才缩图或写响应。
func (s *service) getAsset(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -383,6 +399,7 @@ func (s *service) getAsset(w http.ResponseWriter, r *http.Request, project, acco
return err
}
// attachCanvasAssets 为文档内显式 assetId 或同工作区托管 URL 追加绑定;不删除旧绑定,调用方先验证权限。
func (s *service) attachCanvasAssets(r *http.Request, tx *sql.Tx, project, workspace, board string, raw json.RawMessage) error {
for _, data := range canvasNodeData(raw) {
id, _ := data["assetId"].(string)
@@ -406,6 +423,9 @@ func (s *service) attachCanvasAssets(r *http.Request, tx *sql.Tx, project, works
}
return nil
}
// validateCanvasAssets 对托管 URL 强制 ID/URL 一致并实时验证可读性,合法引用在同事务中建立当前画布绑定。
// 普通外部图片 URL 在此跳过,交给快照结构校验;它们不会成为私有资产绑定。
func (s *service) validateCanvasAssets(r *http.Request, tx *sql.Tx, project, workspace, account string, raw json.RawMessage) (bool, error) {
for _, data := range canvasNodeData(raw) {
id, explicit := data["assetId"].(string)
+2
View File
@@ -1,3 +1,4 @@
// 资产解码纯函数回归,编码小型真实栅格样本后检查格式与尺寸,不访问数据库。
package platform
import (
@@ -10,6 +11,7 @@ import (
"testing"
)
// TestAssetDecodersUseActualContent 验证 PNG/JPEG/GIF 从实际内容识别,拒绝截断样本和未支持的 SVG。
func TestAssetDecodersUseActualContent(t *testing.T) {
im := image.NewRGBA(image.Rect(0, 0, 3, 2))
im.Set(1, 1, color.RGBA{R: 255, A: 255})
+25
View File
@@ -1,3 +1,4 @@
// 画布快照协议的结构规范化与旧整文档 GET/PATCH;跨画布所有权变更必须走专用事务命令。
package platform
import (
@@ -13,20 +14,26 @@ import (
"unicode/utf8"
)
// canvasLimit 同时约束快照文档及该路由请求体预算,较大的嵌入图片也计算在内。
const canvasLimit = 5 << 20
var canvasColor = regexp.MustCompile(`^#[0-9a-fA-F]{6}$`)
var canvasID = regexp.MustCompile(`^[A-Za-z0-9_-]{1,128}$`)
var canvasIcon = regexp.MustCompile(`^[A-Z][A-Za-z0-9]{0,63}$`)
// canvasNumber 面向 JSON 解码后的 float64,拒绝非数、无穷和超出闭区间的值。
func canvasNumber(v any, low, high float64) bool {
n, ok := v.(float64)
return ok && !math.IsNaN(n) && !math.IsInf(n, 0) && n >= low && n <= high
}
// canvasString 按 Unicode 码点数限制展示文本,与请求体的字节预算分别约束。
func canvasString(v any, limit int) bool {
s, ok := v.(string)
return ok && utf8.RuneCountInString(s) <= limit
}
// canvasChoice 用于协议枚举白名单;缺省字段由调用处决定是否允许,不能自动匹配零值。
func canvasChoice(v any, choices ...string) bool {
for _, s := range choices {
if v == s {
@@ -35,6 +42,8 @@ func canvasChoice(v any, choices ...string) bool {
}
return false
}
// canvasFields 拒绝 nil 和未知键,但不要求所有允许键都存在;必填性由后续类型/值检查保证。
func canvasFields(m map[string]any, fields ...string) bool {
if m == nil {
return false
@@ -53,6 +62,9 @@ func canvasFields(m map[string]any, fields ...string) bool {
}
return true
}
// canvasImage 接受无用户信息的 HTTPS URL,或最多 2 MiB 且 MIME 嗅探相符的栅格 data URL。
// 此处不下载 HTTPS 图片,内嵌图也只做头部嗅探,不承担完整图片解码。
func canvasImage(v any) bool {
s, ok := v.(string)
if !ok {
@@ -71,6 +83,9 @@ func canvasImage(v any) bool {
}
return false
}
// normalizeCanvas 验证 v1/v2 文档,移除界面临时状态,再重编码为持久快照。
// 仅校验单文档结构;数据库所有权、模型能力与资产权限仍由保存流程另行检查。
func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
if len(raw) > canvasLimit {
return nil, false
@@ -95,6 +110,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
if v2 && (!canvasNumber(viewport["x"], -1e6, 1e6) || !canvasNumber(viewport["y"], -1e6, 1e6)) {
return nil, false
}
// 先收集节点类型和框端口,第二遍才检查 frameId/边引用,因此允许合法的前向引用。
kinds := map[string]string{}
framePorts := map[string]map[string]string{}
for _, v := range nodes {
@@ -102,6 +118,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
if !ok {
return nil, false
}
// 兼容前端 style 中的测量尺寸,但显式 width/height 优先;随后去除 selected/dragging 等临时状态。
if style, ok := n["style"].(map[string]any); ok {
if _, exists := n["width"]; !exists {
if v, exists := style["width"]; exists {
@@ -130,6 +147,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
}
_, w := n["width"]
_, h := n["height"]
// 普通节点与 v2 frame 使用不同尺寸预算,宽高必须同时缺省或同时合法。
low, high := float64(20), float64(3000)
if data, _ := n["data"].(map[string]any); v2 && data["kind"] == "frame" {
low, high = 32, 100000
@@ -189,6 +207,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
return nil, false
}
}
// validCanvasFrameExtensions 已检查端口对象形状,此处建立方向索引供边端点验证。
if kind == "frame" && v2 {
ports := map[string]string{}
if values, ok := d["ports"].([]any); ok {
@@ -249,6 +268,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
}
// Resolve memberships after all nodes so forward references are valid.
// Geometry never creates membership: only explicit frameId is persisted.
// 成员关系只由显式 frameId 决定,几何重叠不产生所有权;框本身不能成为框成员。
for _, value := range nodes {
data := value.(map[string]any)["data"].(map[string]any)
if id, exists := data["frameId"]; exists && kinds[id.(string)] != "frame" {
@@ -279,6 +299,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
if !ok {
return nil, false
}
// 边连接 frame 时必须使用已声明端口,源只能 output,目标只能 input。
if v2 && kinds[s] == "frame" {
handle, _ := e[key+"Handle"].(string)
direction := "input"
@@ -315,6 +336,7 @@ func normalizeCanvas(raw json.RawMessage) (json.RawMessage, bool) {
return out, err == nil
}
// canvas 读取时在发送响应体前释放事务;保存时将文档、资产绑定及 AI 目标失效一并提交。
func (s *service) canvas(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet && r.Method != http.MethodPatch {
reject(w, 405, "method_not_allowed")
@@ -390,6 +412,7 @@ func (s *service) canvas(w http.ResponseWriter, r *http.Request, project, accoun
reject(w, 409, "canvas_schema_upgrade_required")
return nil
}
// 已升级文档不可通过旧客户端降回 v1,避免丢失子图和端口等结构。
if previousSchema == 2 && canvasSchema(document) != 2 {
reject(w, 409, "canvas_schema_upgrade_required")
return nil
@@ -398,6 +421,7 @@ func (s *service) canvas(w http.ResponseWriter, r *http.Request, project, accoun
reject(w, 412, "version_conflict")
return nil
}
// 通过版本检查后仍须保持现有跨画布关系;普通快照不能自行创建或重定向所有权。
if valid, e := validateCanvasRelations(r, tx, project, workspace, material, previousDocument, document); e != nil {
return e
} else if !valid {
@@ -413,6 +437,7 @@ func (s *service) canvas(w http.ResponseWriter, r *http.Request, project, accoun
reject(w, 400, "invalid_asset_reference")
return nil
}
// 在相同事务中建立资产引用、使被删除/改变的 AI 目标失效,再推进独立的 canvas_version。
if err = s.attachCanvasAssets(r, tx, project, workspace, material, document); err != nil {
return err
}
+15
View File
@@ -1,3 +1,4 @@
// AI 步骤开始/完成的事务边界:执行前与回写前分别校验权限、租约和目标身份,防止迟到输出覆盖新状态。
package platform
import (
@@ -8,6 +9,8 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// startCanvasStep 持工作区锁解析目标当前 owner,再检查租约、编辑权限与内容指纹,成功才将 queued 改 running。
// 不可执行时先释放事务,再调用完成流程记录拒绝状态,避免嵌套事务互锁。
func (s *service) startCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan) (bool, error) {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
@@ -78,9 +81,13 @@ func (s *service) startCanvasStep(ctx context.Context, run canvasQueueRun, step
}
return true, nil
}
// finishCanvasStep 是文本/无输出失败路径的兼容包装,所有落库与事件逻辑集中在结构化完成函数。
func (s *service) finishCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, text, code string, started bool) (string, error) {
return s.finishCanvasStepOutput(ctx, run, step, codex.CanvasOutput{Kind: "text", Text: text}, code, started)
}
// finishCanvasStepOutput 在同一事务中保存输出、条件应用、步骤终态与事件;已终态或租约失效则直接保留旧结果。
func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, generated codex.CanvasOutput, code string, started bool) (string, error) {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
@@ -104,12 +111,14 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
if err != nil {
return "", err
}
// 取消、删除失效和其他完成者已写出的终态优先,迟到 worker 结果不得改回成功。
if oldStatus != "queued" && oldStatus != "running" {
return oldStatus, nil
}
if runStatus != "running" || !lease.Valid || lease.String != run.Lease {
return oldStatus, nil
}
// 统一映射依赖失败、内容冲突、取消与生成错误,run.cancel_requested 优先于局部生成结果。
status := "succeeded"
switch code {
case "dependency_failed":
@@ -139,6 +148,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
var appliedEvent response
var output any
var version any
// 生成成功才保存可供恢复的输出;内容指纹冲突时仍保留 output,但不覆盖当前节点。
if code == "" && started {
var outputID string
err = tx.QueryRowContext(ctx, `SELECT gen_random_uuid()::text`).Scan(&outputID)
@@ -177,6 +187,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
return "", err
}
}
// 仍使用原计划来源构造指纹,owner 变化由 canonical 稳定身份单独解析,拖动不造成假冲突。
if !identityOK || target == nil || canvasTargetFingerprint(step.BoardID, step.NodeID, target) != step.Fingerprint {
status, code = "conflict", "target_changed"
} else {
@@ -199,6 +210,7 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
}
}
}
// output 与 applied 是不同事件;换 owner 后的冲突附完整模型,客户端可定位当前显式应用目标。
if output != nil {
event := response{"step_id": step.ID, "board_id": eventBoard, "origin_board_id": step.BoardID, "canonical_root": step.CanonicalRoot, "target_incarnation": step.TargetIncarnation, "node_id": step.NodeID, "output": output}
if status == "conflict" && identityOK && step.CanonicalRoot != "" && eventBoard != step.BoardID {
@@ -249,6 +261,9 @@ func (s *service) finishCanvasStepOutput(ctx context.Context, run canvasQueueRun
}
return status, nil
}
// completeCanvasRun 从数据库步骤聚合实际终态而非信任内存 results;仍有活跃步骤则不提前结束 run。
// 仅当前租约可清空租约并写 run.completed,兼容部分成功、全冲突和取消。
func (s *service) completeCanvasRun(ctx context.Context, run canvasQueueRun, _ map[string]canvasStepResult) error {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
+5
View File
@@ -1,3 +1,4 @@
// 用户取消 AI run:立即冻结数据库终态与回执,worker 心跳在随后一秒级检查中停止在途调用。
package platform
import (
@@ -7,6 +8,7 @@ import (
"net/http"
)
// cancelCanvasAIRun 接受旧空体或完整 v2 身份;重试先返回原回执,再决定是否需要取消 queued/running 步骤。
func (s *service) cancelCanvasAIRun(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -107,6 +109,7 @@ func (s *service) cancelCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err = json.Unmarshal(rawPlan, &plan); err != nil {
return err
}
// 取消也要求所有步骤当前目标可编辑,目标移动后按新 owner 权限判断,不能借原 run 路径越权。
for _, step := range plan.Steps {
target, ok, e := resolveCanvasAITarget(r.Context(), tx, project, workspace, step)
if e != nil {
@@ -123,6 +126,7 @@ func (s *service) cancelCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
return rejectRequest(403, "forbidden")
}
}
// 已成功的步骤不回滚;只把仍活跃步骤设 cancelled,并为受影响边写 skipped 事件。
if status == "queued" || status == "running" {
_, err = tx.ExecContext(r.Context(), `UPDATE canvas_ai_runs SET status='cancelled',cancel_requested=true,completed_at=now() WHERE project=$1 AND workspace_id=$2 AND id=$3`, project, workspace, id)
if err != nil {
@@ -170,6 +174,7 @@ func (s *service) cancelCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err != nil {
return err
}
// 回执分别列出此前已经应用的版本与本次/既有取消步骤,避免把取消误解为撤销所有已生效结果。
applied, cancelledSteps := []any{}, []any{}
for rows.Next() {
var step, board, node, state string
+4
View File
@@ -1,3 +1,4 @@
// 节点 AI 配置结构校验与目标内容指纹,供快照保存、计划冻结和异步写回共享。
package platform
import (
@@ -5,6 +6,7 @@ import (
"strings"
)
// validCanvasAI 限定可生成节点类型及 AI 字段形状;这里只校验参数 JSON 预算,模型目录和参数支持另查。
func validCanvasAI(value any, kind string) bool {
if !canvasChoice(kind, "text", "script", "plain-text", "image", "plain-image") {
return false
@@ -46,6 +48,8 @@ func validCanvasAI(value any, kind string) bool {
// after a concurrent drag. The board is the immutable plan origin, not the
// current canonical owner; canonical target identity is checked separately.
// Content/configuration edits invalidate the result.
// canvasTargetFingerprint 绑定计划来源 board/node、内容与 AI 配置,故意忽略几何/样式以允许生成期间拖动。
// Canonical owner 迁移用稳定身份单独校验,不能把当前位置代入原计划 board 重新计算。
func canvasTargetFingerprint(board, node string, data map[string]any) string {
target := map[string]any{"board_id": board, "node_id": node, "kind": data["kind"], "ai": data["ai"]}
if canvasChoice(data["kind"], "image", "plain-image") {
@@ -1,3 +1,4 @@
// 用户确认应用冲突生成输出:不重新生成,只在当前目标代数、位置和版本均确认后写入已存结果。
package platform
import (
@@ -7,6 +8,7 @@ import (
"unicode/utf8"
)
// applyCanvasAIOutput 要求 conflict、尚未应用且 run 未取消;v2 显式绑定目标画布/incarnation 和逻辑操作身份。
func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -96,6 +98,7 @@ func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, pr
if err != sql.ErrNoRows {
return err
}
// 输出必须属于该 run 并与请求 node 匹配,不能拿另一输出 ID 或已应用结果重复写入。
var stepID, targetBoard, node, status string
var outputRaw, frozenRaw json.RawMessage
var applied sql.NullInt64
@@ -125,6 +128,7 @@ func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, pr
if canonical && (frozen.TargetIncarnation != input.TargetIncarnation || frozen.CanonicalRoot == "") {
return rejectRequest(409, "target_changed")
}
// 生成后 owner 可能改变,使用权威身份重新解析;请求确认的 TargetCanvasID 必须仍是当前位置。
targetBoard, identityOK, err := resolveCanvasAITarget(r.Context(), tx, project, workspace, frozen)
if err != nil {
return err
@@ -149,6 +153,7 @@ func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, pr
if snapshot.Version != expected {
return rejectRequest(412, "version_conflict")
}
// 显式应用允许覆盖已编辑的内容,但仍检查输出模态、字节/字符预算及图片当前可读性。
patch := response{}
switch output.Kind {
case "text":
@@ -190,6 +195,7 @@ func (s *service) applyCanvasAIOutput(w http.ResponseWriter, r *http.Request, pr
if target["kind"] != frozen.Kind {
return rejectRequest(409, "ownership_conflict")
}
// 通过共享窄字段 patch 保存,原几何和未知元数据不被旧输出快照回滚;应用版本与事件/回执同事务提交。
change, err := prepareCanvasAIPatch(r, tx, project, workspace, snapshot, node, patch)
if err != nil {
return rejectRequest(413, "canvas_too_large")
@@ -1,3 +1,4 @@
// 图片输入冻结与执行前装载:远程引用转为私有不可变资产,实际执行再次校验目标及资产权限。
package platform
import (
@@ -18,6 +19,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// canvasPublicIP 排除本地/私有/链路/保留测试网和已列元数据地址,IPv4 映射先 Unmap 再检查。
func canvasPublicIP(ip netip.Addr) bool {
ip = ip.Unmap()
if !ip.IsValid() || !ip.IsGlobalUnicast() || ip.IsPrivate() || ip.IsLoopback() || ip.IsLinkLocalUnicast() {
@@ -30,10 +32,15 @@ func canvasPublicIP(ip netip.Addr) bool {
}
return true
}
// canvasImageURL 仅允许短 HTTPS URL 且无用户信息,具体 DNS/IP 约束由 fetchCanvasImage 执行。
func canvasImageURL(raw string) bool {
u, err := url.Parse(raw)
return err == nil && u.Scheme == "https" && u.Hostname() != "" && u.User == nil && len(raw) < 2048
}
// fetchCanvasImage 每次连接解析并校验完整 DNS 结果,再直连已验证字面 IP,避免二次解析重绑定。
// 重定向仍需 HTTPS 且每次重新验证目标,响应字节和请求时间都有上限。
func fetchCanvasImage(ctx context.Context, src string) ([]byte, error) {
if !canvasImageURL(src) {
return nil, errors.New("invalid_image_input")
@@ -92,6 +99,8 @@ func fetchCanvasImage(ctx context.Context, src string) ([]byte, error) {
}
return data, nil
}
// freezeCanvasImage 已托管图片只重查可读性并保存 assetId;data/远程图完整检查后写不可变资产及来源画布绑定。
func (s *service) freezeCanvasImage(ctx context.Context, tx *sql.Tx, project, workspace, board, account string, content map[string]any) (map[string]any, error) {
id, _ := content["assetId"].(string)
src, _ := content["src"].(string)
@@ -141,6 +150,9 @@ func (s *service) freezeCanvasImage(ctx context.Context, tx *sql.Tx, project, wo
}
return map[string]any{"assetId": id}, nil
}
// hydrateCanvasTask 汇集自身冻结图、静态前驱和本轮前驱输出资产,去重后加载原图到私有 IPC task。
// 执行前重新解析 canonical owner/代数并核对编辑及资产权限,最多四图和二十 MiB。
func (s *service) hydrateCanvasTask(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, results map[string]canvasStepResult, task *codex.CanvasTask) error {
ids := []string{}
if id, _ := step.FrozenContent["assetId"].(string); id != "" {
@@ -1,3 +1,4 @@
// 图片抓取网络约束回归:直接检查地址分类和 URL 格式,并实际拒绝回环目标,不访问公网图片。
package platform
import (
@@ -7,6 +8,7 @@ import (
"time"
)
// TestCanvasImageFetchRejectsPrivateAndMetadataNetworks 覆盖私有/映射 IPv4/元数据/保留网段,确认公网样本分类可接受及非 HTTPS/带凭据 URL 被拒。
func TestCanvasImageFetchRejectsPrivateAndMetadataNetworks(t *testing.T) {
for _, raw := range []string{"127.0.0.1", "10.0.0.1", "169.254.169.254", "172.16.0.1", "192.168.1.1", "100.100.100.200", "168.63.129.16", "0.0.0.1", "198.18.0.1", "224.0.0.1", "255.255.255.255", "::1", "::ffff:127.0.0.1", "fe80::1", "fc00::1", "2001:db8::1"} {
if canvasPublicIP(netip.MustParseAddr(raw)) {
+6
View File
@@ -1,3 +1,4 @@
// AI 图片输出持久化与模型输入/输出模态能力检查。
package platform
import (
@@ -10,6 +11,8 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// persistCanvasImage 完整解码 worker 图片并核对 MIME,以 outputID 作为幂等键存原图。
// 先绑定 run 来源素材,使冲突输出在用户显式应用前仍能按原 run 权限读取。
func (s *service) persistCanvasImage(ctx context.Context, tx *sql.Tx, run canvasQueueRun, outputID string, image *codex.CanvasImage) (response, error) {
if image == nil || len(image.Data) == 0 || len(image.Data) > assetLimit {
return nil, errors.New("invalid_image_output")
@@ -32,6 +35,8 @@ func (s *service) persistCanvasImage(ctx context.Context, tx *sql.Tx, run canvas
}
return response{"output_id": outputID, "kind": "image", "assetId": id, "src": s.assetURL(run.Project, run.Workspace, id), "mime_type": mime, "bytes": len(image.Data), "width": width, "height": height}, nil
}
// canvasModelSupports 检查输出模态;支持图片输入并不意味着可生成图片。
func canvasModelSupports(model codex.CanvasModel, modality string) bool {
for _, value := range model.OutputModalities {
if value == modality {
@@ -41,6 +46,7 @@ func canvasModelSupports(model codex.CanvasModel, modality string) bool {
return false
}
// canvasModelAccepts 检查输入模态,准入阶段据此拒绝给纯文本输入模型喂图。
func canvasModelAccepts(model codex.CanvasModel, modality string) bool {
for _, value := range model.InputModalities {
if value == modality {
@@ -1,3 +1,4 @@
// 旧快照 AI 生命周期数据库回归:需隔离 PLATFORM_TEST_DATABASE_URL,生成由 Unix 假 worker 固定,不调用真实模型。
package platform
import (
@@ -23,6 +24,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// TestCanvasAIJobLifecycle 通过真实准入/认领/写回验证几何并发、内容冲突、取消、租约恢复、图片和传播失败分支。
func TestCanvasAIJobLifecycle(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -78,6 +80,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if err := png.Encode(&pngOutput, image.NewRGBA(image.Rect(0, 0, 3, 2))); err != nil {
t.Fatal(err)
}
// hooks 在 worker 已接收任务但尚未返回时注入并发变更;busyNext/failNext 分别模拟未执行忙碌和生成失败。
var imageInputs atomic.Int32
var busyNext atomic.Bool
var failNext atomic.Bool
@@ -175,6 +178,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
t.Errorf("concurrent fixture edit: %v", err)
}
}
// 同键准入只建一个任务,生成中拖动 x 应被保留,结果只更新文本并在最新版本上加一。
first := start(1, 1)
retry := start(1, 1)
if first["run_id"] != retry["run_id"] || first["canvas_version"] != float64(2) {
@@ -193,6 +197,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
t.Fatal("result overwrote geometry/style or failed to update text")
}
firstPath := base + "/ai/runs/" + first["run_id"].(string)
// 以小事件页回放整个运行,检查 seq 严格单调且最终 run.completed 可恢复。
after := int64(0)
completed := false
for page := 0; page < 30; page++ {
@@ -218,6 +223,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if !completed {
t.Fatal("terminal event not replayable")
}
// 正文并发编辑产生 conflict,输出仍可查询;旧协议显式应用失败后允许按当前版本再试。
second := start(4, 3)
hooks <- func() { mutate("{nodes,0,data,text}", `"user edit"`) }
execute(second["run_id"].(string))
@@ -244,6 +250,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if calls.Load() != 2 {
t.Fatal("cancelled queued run invoked worker")
}
// 人工让运行租约过期,恢复流程必须标 execution_interrupted,不能再次调用未知是否执行的模型。
fourth := start(8, 7)
run, err := s.claimCanvasRun(ctx)
if err != nil || run == nil || run.ID != fourth["run_id"] {
@@ -262,6 +269,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if recovered["status"] != "failed" || recovered["error"] != "execution_interrupted" || calls.Load() != 2 {
t.Fatal("uncertain execution was retried or misreported")
}
// 删除再创建同名节点不能使旧 running 步复活,迟到输出必须保持 cancelled。
fifth := start(9, 8)
removedRun, err := s.claimCanvasRun(ctx)
if err != nil || removedRun == nil || removedRun.ID != fifth["run_id"] {
@@ -299,6 +307,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
if len(active["runs"].([]any)) != 0 {
t.Fatal("terminal jobs returned as active")
}
// 图片输入先冻结为资产再装载,结果也存托管资产;节点原显示尺寸和可授权下载的原图都需保留。
imageDoc := call("GET", base, nil, 200, 0, "")["document"].(map[string]any)
imageDoc["nodes"] = append(imageDoc["nodes"].([]any), response{"id": "image-node", "type": "plainImage", "position": response{"x": 40, "y": 50}, "width": 240, "height": 160, "data": response{"kind": "plain-image", "title": "Image", "text": "", "src": "data:image/png;base64," + base64.StdEncoding.EncodeToString(pngOutput.Bytes())}})
call("PATCH", base, response{"document": imageDoc}, 200, 12, "")
@@ -336,6 +345,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
t.Fatal("image inputs were not frozen/hydrated through authorized assets")
}
// 首前驱成功后让下游收到 codex_busy,只回队下游;恢复不重复上游付费调用或版本推进。
chainDoc := call("GET", base, nil, 200, 0, "")["document"].(map[string]any)
chainDoc["nodes"].([]any)[1].(map[string]any)["data"].(map[string]any)["ai"] = response{"enabled": true, "modelId": "fixture-model", "prompt": "Use upstream result", "parameters": response{}}
call("PATCH", base, response{"document": chainDoc}, 200, 18, "")
@@ -366,6 +376,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
}
// Cancellation after worker admission must reject an otherwise successful late output.
// 生成中通过真实取消接口结束 run,随后即使假 worker 返回成功也不能再写回。
cancelRunning := start(22, 13)
cancelRunningPath := base + "/ai/runs/" + cancelRunning["run_id"].(string)
hooks <- func() {
@@ -377,6 +388,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
}
// Permission is checked again inside the final write transaction.
// 生成返回前删除成员权限,最终事务重查应拒绝输出应用;恢复权限仅为读取测试结果。
revoked := start(23, 15)
hooks <- func() {
if _, err := db.ExecContext(ctx, `DELETE FROM workspace_members WHERE project=$1 AND workspace_id=$2 AND account_id=$3`, project, workspace, account); err != nil {
@@ -393,6 +405,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
}
// A failed branch stops its dependents while its independent sibling finishes.
// 一支失败只跳过依赖者,独立兄弟仍可成功,run 汇总为 partially_succeeded。
branchSnapshot := aiPlanFixture([][2]string{{"a", "b"}, {"a", "c"}, {"b", "d"}}, nil, "")["board"]
var branchDoc any
if err := json.Unmarshal(branchSnapshot.Document, &branchDoc); err != nil {
@@ -412,6 +425,7 @@ func TestCanvasAIJobLifecycle(t *testing.T) {
t.Fatalf("partial failure lost independent branch: %+v %v", states, branchResult["status"])
}
// 含回边的图可以存储,但执行准入必须识别环,既不调用 worker 也不推进配置版本。
cyclic := call("GET", base, nil, 200, 0, "")
cyclicVersion := int64(cyclic["version"].(float64))
cyclicDoc := cyclic["document"].(map[string]any)
@@ -1,3 +1,4 @@
// 旧快照语义的 AI 生命周期失效,与节点删除/种类变化或子图关系更新处于同一事务。
package platform
import (
@@ -9,6 +10,8 @@ import (
// Deletion or kind/ownership changes revoke active steps in the same snapshot
// transaction. Recreating an identical node ID later cannot revive that step.
// invalidateCanvasAITargets 找出从本 board 消失或种类变化的节点,取消对应 queued/running 步骤并写事件。
// 仅视觉/正文编辑不在此取消,执行/写回时再由内容指纹检测冲突。
func invalidateCanvasAITargets(r *http.Request, tx *sql.Tx, project, workspace, board string, before, after json.RawMessage) error {
old, next := canvasNodeData(before), canvasNodeData(after)
removed := []string{}
@@ -71,6 +74,7 @@ func invalidateCanvasAITargets(r *http.Request, tx *sql.Tx, project, workspace,
return nil
}
// invalidateCanvasAISubtree 收集活跃后代并逐张模拟清空节点,使关系变更涉及的旧树任务失效;不删除实际文档。
func invalidateCanvasAISubtree(r *http.Request, tx *sql.Tx, project, workspace, child string) error {
rows, err := tx.QueryContext(r.Context(), `WITH RECURSIVE descendants(id,depth) AS(SELECT $3::uuid,0 UNION ALL SELECT s.child_board_id,d.depth+1 FROM descendants d JOIN canvas_subgraphs s ON s.project=$1 AND s.workspace_id=$2 AND s.parent_board_id=d.id AND s.archived_at IS NULL WHERE d.depth<8) SELECT m.id::text,COALESCE(m.canvas_document,'{"nodes":[]}'::jsonb) FROM descendants d JOIN materials m ON m.project=$1 AND m.workspace_id=$2 AND m.id=d.id ORDER BY m.id`, project, workspace, child)
if err != nil {
+4
View File
@@ -1,3 +1,4 @@
// AI run 列表使用创建时间/UUID 的复合游标,支持状态和活跃子图范围筛选。
package platform
import (
@@ -9,11 +10,13 @@ import (
"time"
)
// canvasRunCursor 用时间加 ID 处理同一时间创建的 run,不依赖不稳定的 OFFSET。
type canvasRunCursor struct {
Time time.Time `json:"created_at"`
ID string `json:"id"`
}
// listCanvasAIRuns 先查范围候选,再核对各 run 来源画布的可见性;返回列表不含冻结提示或原始输出文本。
func (s *service) listCanvasAIRuns(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -88,6 +91,7 @@ func (s *service) listCanvasAIRuns(w http.ResponseWriter, r *http.Request, proje
if err != nil {
return err
}
// SQL 多取一条判断后页;权限过滤可能使公开本页少于 limit,游标仍按扫描到的候选末尾前进。
hasMore := len(candidates) > limit
if hasMore {
candidates = candidates[:limit]
+25
View File
@@ -1,3 +1,4 @@
// AI 与 canonical 模型适配:稳定身份跟随 owner,窄字段 patch 保留未知组件 envelope 和无关几何。
package platform
import (
@@ -13,6 +14,7 @@ var errAIInvalidPatch = errors.New("invalid_ai_patch")
// The snapshot is an AI reader projection only. Canonical changes retain the
// original rows, including unknown envelopes, geometry and reference metadata.
// canvasAIChange 携带待保存快照及可选 canonical 前后模型,避免将兼容投影反写为权威模型。
type canvasAIChange struct {
Snapshot canvasSnapshot
Before *canvasModel
@@ -23,6 +25,8 @@ type canvasAIChange struct {
// Until a narrower read-set protocol exists, admission binds every active
// canvas in this canonical project. Archived versions are not graph inputs.
// Workspace locking keeps validation, plan freezing and admission atomic.
// validateCanvasAIVersions 暂要求 Expected 精确覆盖全部活跃 canonical 画布且当前 board 与 If-Match 一致。
// 归档版本不作为规划输入;完整 read-set 检查与冻结在同一工作区锁内。
func validateCanvasAIVersions(model canvasModel, board string, header int64, expected map[string]int64) string {
if len(expected) != len(model.Canvases) || expected[board] != header {
return "invalid_ai_versions"
@@ -39,6 +43,7 @@ func validateCanvasAIVersions(model canvasModel, board string, header int64, exp
return ""
}
// prepareModelAIPatch 仅在同 owner 的可执行 v1 节点副本修改 ai/text/src/assetId,推进该画布版本并验证全模型。
func prepareModelAIPatch(before canvasModel, board, node string, patch response) (canvasModel, error) {
element := before.Elements[node]
if element == nil || element["structure"] != "node" || element["ownerCanvasId"] != board || modelInt(element["dataVersion"]) != 1 || !canvasChoice(element["componentId"], "text", "script", "plain-text", "image", "plain-image") {
@@ -61,6 +66,8 @@ func prepareModelAIPatch(before canvasModel, board, node string, patch response)
}
return after, nil
}
// prepareCanvasAIPatch 按是否迁入 canonical 分派:前者改权威模型再生成投影,后者改快照副本再 normalize。
func prepareCanvasAIPatch(r *http.Request, tx *sql.Tx, project, workspace string, snapshot canvasSnapshot, node string, patch response) (canvasAIChange, error) {
change := canvasAIChange{Snapshot: snapshot}
root, err := canonicalRoot(r.Context(), tx, project, workspace, snapshot.BoardID)
@@ -123,12 +130,16 @@ func prepareCanvasAIPatch(r *http.Request, tx *sql.Tx, project, workspace string
change.Snapshot.Version++
return change, nil
}
// saveCanvasAIChange 根据 change 的模型形态选择持久化路径,复用调用方事务,不自行提交。
func (s *service) saveCanvasAIChange(r *http.Request, tx *sql.Tx, project, workspace, account string, change canvasAIChange) error {
if change.After == nil {
return s.saveCanvas(r, tx, project, workspace, change.Snapshot)
}
return s.saveCanvasModel(r, tx, project, workspace, account, *change.Before, *change.After, map[string]bool{change.Snapshot.BoardID: true})
}
// addCanonical 仅在 canonical 响应附格式、代数与当前 owner 局部模型,旧快照协议不增加这些字段。
func (change canvasAIChange) addCanonical(result response) {
if change.After == nil {
return
@@ -138,6 +149,7 @@ func (change canvasAIChange) addCanonical(result response) {
result["model"] = change.After.view(map[string]int64{board: change.Snapshot.Version})
}
// canvasAIIdentity 查当前 owner 下活跃且可执行的节点身份;旧图返回空根,非法目标返回零代数。
func canvasAIIdentity(ctx context.Context, tx *sql.Tx, project, workspace, board, node string) (string, int64, string, error) {
root, err := canonicalRoot(ctx, tx, project, workspace, board)
if err != nil || root == "" {
@@ -157,6 +169,8 @@ func canvasAIIdentity(ctx context.Context, tx *sql.Tx, project, workspace, board
}
return root, incarnation, kind, nil
}
// bindCanvasAIIdentities 在准入时给每步冻结根/代数,旧图仍保留 board-local 身份。
func bindCanvasAIIdentities(ctx context.Context, tx *sql.Tx, project, workspace string, plan *canvasAIPlan) error {
for i, step := range plan.Steps {
root, incarnation, kind, err := canvasAIIdentity(ctx, tx, project, workspace, step.BoardID, step.NodeID)
@@ -173,6 +187,7 @@ func bindCanvasAIIdentities(ctx context.Context, tx *sql.Tx, project, workspace
// Run URLs remain anchored at their admission board, even after that partition
// is archived. Canonical ownership grants are inherited from the same root.
// lockCanvasAIRunRoute 将 canonical 原 run 路径转到根级授权,原分区归档后仍可查询/取消该 run。
func lockCanvasAIRunRoute(ctx context.Context, tx *sql.Tx, project, workspace, board, account string) (string, string, error) {
root, err := canonicalRoot(ctx, tx, project, workspace, board)
if err != nil {
@@ -183,6 +198,8 @@ func lockCanvasAIRunRoute(ctx context.Context, tx *sql.Tx, project, workspace, b
}
return lockMaterial(ctx, tx, project, workspace, board, account)
}
// lockCanvasAIWorkspace 只取得工作区行锁;具体目标权限必须在后续独立检查。
func lockCanvasAIWorkspace(ctx context.Context, tx *sql.Tx, project, workspace string) error {
var id string
return tx.QueryRowContext(ctx, `SELECT id::text FROM workspaces WHERE project=$1 AND id=$2 FOR UPDATE`, project, workspace).Scan(&id)
@@ -190,6 +207,8 @@ func lockCanvasAIWorkspace(ctx context.Context, tx *sql.Tx, project, workspace s
// Caller holds the workspace lock. Frozen identity is stable; owner is resolved
// afresh at execution, hydration and write time, never written into the plan.
// resolveCanvasAITarget 在调用方持锁时重新解析当前 owner,要求同根、同代、同种类且 owner 未归档。
// 原计划 BoardID 不被更新,避免破坏步骤身份、指纹和重放结果。
func resolveCanvasAITarget(ctx context.Context, tx *sql.Tx, project, workspace string, step canvasAIStepPlan) (string, bool, error) {
if step.CanonicalRoot == "" {
root, err := canonicalRoot(ctx, tx, project, workspace, step.BoardID)
@@ -206,10 +225,14 @@ func resolveCanvasAITarget(ctx context.Context, tx *sql.Tx, project, workspace s
}
return board, incarnation == step.TargetIncarnation && incarnation > 0 && kind == step.Kind && version == 1, nil
}
// canvasAIIdentityMatches 是只关心有效性的包装,仍沿用完整 owner/生命周期检查。
func canvasAIIdentityMatches(ctx context.Context, tx *sql.Tx, project, workspace string, step canvasAIStepPlan) (bool, error) {
_, ok, err := resolveCanvasAITarget(ctx, tx, project, workspace, step)
return ok, err
}
// addTargetContext 同时返回原来源与当前应用上下文;owner 改变时附完整模型供客户端恢复新位置。
func (change canvasAIChange) addTargetContext(result response, step canvasAIStepPlan) {
change.addCanonical(result)
if step.CanonicalRoot != "" {
@@ -222,6 +245,8 @@ func (change canvasAIChange) addTargetContext(result response, step canvasAIStep
// Whole identity transitions cancel old jobs even when delete/restore happens
// in a single atomic batch and the compatibility projection looks identical.
// invalidateCanonicalAIIdentities 比较整代身份而非快照外观;删除/恢复同批或组件版本变化也取消旧任务。
// 纯 owner 移动不失效,后续执行/写回按稳定身份跟随新位置。
func invalidateCanonicalAIIdentities(r *http.Request, tx *sql.Tx, project, workspace string, before, after canvasModel) error {
removed := map[string][]any{}
for id, element := range before.Elements {
@@ -1,3 +1,4 @@
// Canonical AI 数据库集成回归:Unix 假 worker 只固定生成传输,权威模型、生命周期与回执均走真实事务。
package platform
import (
@@ -24,6 +25,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// TestCanonicalAIAdmissionAndLifecycle 需隔离 PLATFORM_TEST_DATABASE_URL,覆盖 owner 迁移、代数失效及 v2 确定拒绝恢复。
func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -75,6 +77,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if err = png.Encode(&pngBytes, image.NewRGBA(image.Rect(0, 0, 3, 2))); err != nil {
t.Fatal(err)
}
// worker 入口执行一次 hook,可精确在模型返回前注入内容、身份或所有权变化。
hooks := make(chan func(), 1)
var executions atomic.Int32
worker := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -156,6 +159,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
}
return model
}
// mutate 在持锁事务中改权威模型并同步投影,用于模拟其他客户端编辑,不绕过模型完整性校验。
mutate := func(edit func(*canvasModel)) {
t.Helper()
tx, e := db.BeginTx(ctx, nil)
@@ -214,6 +218,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
model.Elements["future"]["dataVersion"] = float64(12)
})
next := 6100
// 每次创建不同 request/operation ID,Expected 取全部活跃画布版本,排除已归档 scope。
command := func(board, target, model string, incarnation int64) (response, string) {
next += 2
key := modelTestID(next)
@@ -227,6 +232,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
}(), "node_id": target, "model_id": model, "prompt": "Generate", "parameters": response{}, "propagate": false}, key
}
start := func(board, target, model string, incarnation int64) response {
// 准入原响应可按相同键重放和查询;改 If-Match 或换键复用已准入逻辑操作必须拒绝。
input, key := command(board, target, model, incarnation)
return call("POST", base(board)+"/ai/runs", input, 202, read().Versions[board], key)
}
@@ -272,6 +278,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
t.Fatal("AI lost canonical fields, geometry or future records")
}
// A content conflict retains its output; explicit application is still a narrow canonical write.
// 内容冲突保留输出,显式应用仍是窄字段写;同键重放保留原模型/版本且可查询回执。
conflictRun := start(root, node, "text", 1)
hooks <- func() {
mutate(func(model *canvasModel) { model.Elements[node]["data"].(map[string]any)["text"] = "user edit" })
@@ -297,6 +304,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
}
call("POST", conflictPath+"/apply", applyInput, 409, expected+1, applyKey)
// Keep one unapplied old output, then replace the target incarnation atomically.
// 保存旧输出并让另一运行开始后升级 incarnation,旧完成回调与旧输出显式应用都不能冒领新一代。
stale := start(root, node, "text", 1)
hooks <- func() {
mutate(func(model *canvasModel) { model.Elements[node]["data"].(map[string]any)["text"] = "keep this" })
@@ -352,6 +360,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
t.Fatal("duplicate/cancelled/old execution called the model")
}
// Image output resolves a managed resource while retaining the element envelope.
// canonical 大几何与未知字段不受 legacy 限制回滚,图片输出成为可按权限下载的托管资产。
imageID := modelTestID(6300)
mutate(func(model *canvasModel) {
record := modelTestNode(imageID, root)
@@ -382,6 +391,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if ok, e := s.startCanvasStep(ctx, *moving, moving.Plan.Steps[0]); e != nil || !ok {
t.Fatalf("start move %v", e)
}
// 运行中把目标换 owner,新 owner 准入仍应识别 node_busy;原任务成功只推进当前位置版本。
child, frame := modelTestID(6301), modelTestID(6302)
mutate(func(model *canvasModel) {
entry := modelTestNode(frame, root)
@@ -419,6 +429,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if e = s.completeCanvasRun(ctx, *moving, nil); e != nil {
t.Fatal(e)
}
// 即使目标版本当前,祖先 read-set 陈旧也必须零效果拒绝;环境变化后原拒绝键不能重算。
staleInput, staleKey := command(child, imageID, "image", 1)
staleVersions := staleInput["expected_versions"].(map[string]int64)
staleVersions[root]-- // The target version is current; its ancestor context is not.
@@ -447,6 +458,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
delete(missingInput, "expected_versions")
call("POST", base(child)+"/ai/runs", missingInput, 400, read().Versions[child], missingKey)
// An explicit replan can reuse a logical operation after its known zero-effect rejection.
// 已知零效果允许显式新键重计划并复用逻辑操作;完成后再取消不得假装撤销成功结果。
replanned := response{}
for key, value := range staleInput {
replanned[key] = value
@@ -465,6 +477,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if read().Elements[imageID]["ownerCanvasId"] != child {
t.Fatal("child result moved its target back")
}
// 排队期间换 owner 并归档原分区,run 的原 URL 仍可读取/取消,执行写入当前根 owner。
queuedMove := start(child, imageID, "image", 1)
mutate(func(model *canvasModel) {
model.Elements[imageID]["ownerCanvasId"] = root
@@ -481,6 +494,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
t.Fatal("archived route lost cancellation identity")
}
// Content changes still conflict after a move; explicit application targets the current owner.
// 换 owner 同时改正文仍产生冲突;用户显式应用须确认当前 owner,不能写回冻结来源画布。
movedConflict := start(root, node, "text", 2)
hooks <- func() {
mutate(func(model *canvasModel) {
@@ -501,6 +515,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
if movedApplied["board_id"] != child || movedApplied["origin_board_id"] != root || read().Elements[node]["ownerCanvasId"] != child {
t.Fatal("explicit application wrote to the frozen owner")
}
// 删除已移动目标并记录墓碑,应使原任务在调用 worker 之前取消。
doomed := start(child, node, "text", 2)
mutate(func(model *canvasModel) {
record := model.Elements[node]
@@ -522,6 +537,7 @@ func TestCanonicalAIAdmissionAndLifecycle(t *testing.T) {
t.Fatal("deleting a moved target failed to revoke its old job")
}
// 换 owner 后把账户降为 viewer,执行前必须重新检查编辑资格且不增加模型调用次数。
revoked := start(root, imageID, "image", 1)
mutate(func(model *canvasModel) { model.Elements[imageID]["ownerCanvasId"] = child })
beforeRevoked := executions.Load()
@@ -1,3 +1,4 @@
// AI canonical 适配的纯回归:验证窄字段更新、未知组件保留和准入 read-set 版本,不运行真实生成。
package platform
import (
@@ -5,6 +6,7 @@ import (
"testing"
)
// TestCanonicalAIPatchPreservesOpaqueModelAndGeometry 检查大尺寸几何/未知 envelope 保留、输入不变,拒绝改 geometry、未知 dataVersion 和错误 owner。
func TestCanonicalAIPatchPreservesOpaqueModelAndGeometry(t *testing.T) {
before := modelTestDocument()
before.Elements["a"]["geometry"].(map[string]any)["width"] = float64(9000)
@@ -37,6 +39,7 @@ func TestCanonicalAIPatchPreservesOpaqueModelAndGeometry(t *testing.T) {
}
}
// TestCanonicalAIProjectionDoesNotExecuteFutureConnections 未来版本连接仍可保存在模型中,但不能被旧 AI 投影误当作可执行连线。
func TestCanonicalAIProjectionDoesNotExecuteFutureConnections(t *testing.T) {
model := modelTestDocument()
model.Elements["b"] = modelTestNode("b", modelRootID)
@@ -57,6 +60,8 @@ func TestCanonicalAIProjectionDoesNotExecuteFutureConnections(t *testing.T) {
}
}
// TestCanonicalAIAdmissionVersions 验证 Expected 精确覆盖活跃画布而排除归档版本,缺项/错头与陈旧版本使用不同错误码。
// 该用例仅测版本函数,构造模型并不满足完整树校验。
func TestCanonicalAIAdmissionVersions(t *testing.T) {
model := modelTestDocument()
model.Canvases[modelChildID] = modelCanvas{ID: modelChildID}
+5
View File
@@ -1,3 +1,4 @@
// 画布可用模型目录与保存时配置验证,模型能力来源是私有 worker 过滤后的目录。
package platform
import (
@@ -9,6 +10,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// canvasAIModels 要求 board 可读;worker 不可用时返回空目录及原因,不把基础能力发现变成请求失败。
func (s *service) canvasAIModels(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -47,6 +49,9 @@ func (s *service) canvasAIModels(w http.ResponseWriter, r *http.Request, project
reply(w, 200, response{"models": models, "image_generation": capability})
return nil
}
// validateCanvasAIModels 无 AI 配置则不访问 worker;存在配置时验证模型可用且参数对象为空。
// 禁用配置可不填模型 ID,但填入 ID 仍需有效;失败已经写响应,调用者应退出并回滚。
func (s *service) validateCanvasAIModels(w http.ResponseWriter, r *http.Request, raw json.RawMessage) bool {
data := canvasNodeData(raw)
configured := []map[string]any{}
+16
View File
@@ -1,3 +1,4 @@
// AI 执行计划的纯规划器:解析真实端点、选择传播范围、冻结静态内容并按依赖拓扑排序。
package platform
import (
@@ -7,6 +8,7 @@ import (
"strings"
)
// canvasAIStaticInput 保存不由本轮生成的输入内容及其逻辑边身份,后续编辑不会改变已经冻结的输入。
type canvasAIStaticInput struct {
EdgeID string `json:"logical_edge_id"`
BoardID string `json:"board_id"`
@@ -14,6 +16,8 @@ type canvasAIStaticInput struct {
Kind string `json:"kind"`
Content map[string]any `json:"content"`
}
// canvasAIStepPlan 固定来源、配置、内容指纹与依赖;canonical 根/incarnation 由准入阶段另行绑定。
type canvasAIStepPlan struct {
CanonicalRoot string `json:"canonical_root,omitempty"`
TargetIncarnation int64 `json:"target_incarnation,omitempty"`
@@ -30,19 +34,25 @@ type canvasAIStepPlan struct {
Status string `json:"status"`
Dependencies []string `json:"dependencies"`
}
// canvasAIEdgePlan 的 ID 由拥有者画布/边 ID 组成,端点是解析后的真实步骤复合 ID。
type canvasAIEdgePlan struct {
ID string `json:"logical_edge_id"`
Source string `json:"source_step_id"`
Target string `json:"target_step_id"`
}
// canvasAIPlan 是可持久化的确定执行输入,Versions 标明规划时读取的所有快照版本。
type canvasAIPlan struct {
Steps []canvasAIStepPlan `json:"steps"`
Edges []canvasAIEdgePlan `json:"edges"`
Versions map[string]int64 `json:"frozen_versions"`
}
// canvasNodeKey 在旧画布局部 ID 域内组合唯一键,canonical 元素仍保留原计划来源作为步骤身份。
func canvasNodeKey(board, node string) string { return board + "/" + node }
// buildCanvasAIPlan 只操作传入快照,不访问数据库;最多选择 64 步,拓扑最长路径不得超过 32。
func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string, propagate bool) (canvasAIPlan, error) {
plan := canvasAIPlan{Steps: []canvasAIStepPlan{}, Edges: []canvasAIEdgePlan{}, Versions: map[string]int64{}}
data := map[string]map[string]any{}
@@ -53,6 +63,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
}
}
var resolve func(string, string, string, string, int) (string, error)
// frame 的连接必须经方向匹配端口下钻到真实节点,图标等不可执行节点不能成为输入/目标。
resolve = func(board, node, handle, direction string, depth int) (string, error) {
if depth > 8 {
return "", errors.New("graph_limit_exceeded")
@@ -119,6 +130,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
for key := range outgoing {
sort.Slice(outgoing[key], func(i, j int) bool { return outgoing[key][i].ID < outgoing[key][j].ID })
}
// 根由显式请求执行;下游未启用 AI 或没有模型则记录 skipped 并停止从该节点继续传播。
selected := map[string]bool{}
skipped := map[string]bool{}
queue := []string{root}
@@ -149,6 +161,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
}
}
// Kahn's algorithm waits for every participating predecessor at a diamond.
// Kahn 入度等待所有参与前驱,菱形汇合只能在两支都处理完后出队,不能按首次访问就执行。
indegree := map[string]int{}
incoming := map[string][]string{}
depths := map[string]int{}
@@ -177,6 +190,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
content := canvasFrozenContent(d)
static := []canvasAIStaticInput{}
sort.Slice(allIncoming[id], func(i, j int) bool { return allIncoming[id][i].ID < allIncoming[id][j].ID })
// 本轮将生成的有效前驱作为动态依赖,其余入边内容冻结为静态输入,包括传播关闭时的前驱。
for _, edge := range allIncoming[id] {
if propagate && selected[edge.Source] && !skipped[edge.Source] {
continue
@@ -209,6 +223,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
}
}
}
// 有入度永远无法归零的已选节点表示执行环,拒绝整个计划而不是执行可排序前缀。
if len(plan.Steps) != len(selected) {
return plan, errors.New("execution_cycle")
}
@@ -216,6 +231,7 @@ func buildCanvasAIPlan(snapshots map[string]canvasSnapshot, board, node string,
return plan, nil
}
// canvasFrozenContent 只捕获语义输入:图片为引用身份,文本为正文,不含位置和纯展示样式。
func canvasFrozenContent(data map[string]any) map[string]any {
if canvasChoice(data["kind"], "image", "plain-image") {
return map[string]any{"src": data["src"], "assetId": data["assetId"]}
+10
View File
@@ -1,3 +1,4 @@
// AI 规划纯算法回归,覆盖传播范围、拓扑汇合、内容冻结与嵌套端口解析,不调用真实模型。
package platform
import (
@@ -6,6 +7,7 @@ import (
"testing"
)
// aiPlanFixture 从边对建立节点与执行开关,可指定一个未配置 AI 的中间节点来验证传播停止。
func aiPlanFixture(edges [][2]string, disabled map[string]bool, unconfigured string) map[string]canvasSnapshot {
ids := map[string]bool{"a": true}
for _, e := range edges {
@@ -28,6 +30,8 @@ func aiPlanFixture(edges [][2]string, disabled map[string]bool, unconfigured str
raw, _ := json.Marshal(map[string]any{"schema_version": 2, "nodes": nodes, "edges": values, "viewport": map[string]any{"x": 0, "y": 0, "zoom": 1}})
return map[string]canvasSnapshot{"board": {BoardID: "board", Version: 4, Document: raw}}
}
// TestAIPlanDiamondAndPropagationBoundaries 验证菱形末端只执行一次且等待两前驱,关闭传播/禁用边/无配置可截断遍历,环必须拒绝。
func TestAIPlanDiamondAndPropagationBoundaries(t *testing.T) {
graph := aiPlanFixture([][2]string{{"a", "b"}, {"a", "c"}, {"b", "d"}, {"c", "d"}}, nil, "")
plan, err := buildCanvasAIPlan(graph, "board", "a", true)
@@ -59,6 +63,9 @@ func TestAIPlanDiamondAndPropagationBoundaries(t *testing.T) {
t.Fatal("cycle accepted")
}
}
// TestAITargetFingerprintIgnoresVisualEdits 检查标题/样式不改指纹,正文或计划来源 board 改变则改指纹;JSON 键顺序不影响摘要。
// 同时覆盖超长提示和图标不允许 AI 配置,不把该用例视为 canonical owner 移动验证。
func TestAITargetFingerprintIgnoresVisualEdits(t *testing.T) {
data := map[string]any{"kind": "text", "text": "original", "title": "Title", "rotation": 0, "ai": map[string]any{"modelId": "fixture", "prompt": "prompt", "enabled": true}}
original := canvasTargetFingerprint("board", "node", data)
@@ -90,6 +97,7 @@ func TestAITargetFingerprintIgnoresVisualEdits(t *testing.T) {
}
}
// TestAIPlanFreezesAdditionalStaticInputs 从 x→a→b 的 a 启动,x 只作为冻结静态来源,不倒向执行;关闭传播仍保留输入。
func TestAIPlanFreezesAdditionalStaticInputs(t *testing.T) {
graph := aiPlanFixture([][2]string{{"x", "a"}, {"a", "b"}}, nil, "")
plan, err := buildCanvasAIPlan(graph, "board", "a", true)
@@ -111,6 +119,8 @@ func TestAIPlanFreezesAdditionalStaticInputs(t *testing.T) {
t.Fatal("static input not supplied to model")
}
}
// TestAIPlanLeavesChildThroughNestedPortChain 解析两层 frame port 到同一真实 deep 节点,边可有两条但目标步骤不重复,祖先版本也冻结。
func TestAIPlanLeavesChildThroughNestedPortChain(t *testing.T) {
raw := memberFixture(t)
child := "11111111-1111-4111-8111-111111111111"
+9
View File
@@ -1,3 +1,4 @@
// AI 运行详情、事件增量和准入回执查询;所有结果读取都重新检查当前资源权限。
package platform
import (
@@ -7,6 +8,7 @@ import (
"strconv"
)
// publicAIPlan 只公开计划结构、依赖及来源身份,静态输入标记 frozen_snapshot,不暴露冻结正文/图片。
func publicAIPlan(plan canvasAIPlan) response {
steps := []any{}
for _, step := range plan.Steps {
@@ -18,6 +20,8 @@ func publicAIPlan(plan canvasAIPlan) response {
}
return response{"steps": steps, "edges": plan.Edges, "frozen_versions": plan.Versions}
}
// getCanvasAIRun 按 after_seq 增量返回事件,查询步骤前按 canonical 稳定身份解析当前目标并检查权限。
func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -66,6 +70,7 @@ func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project
if err = json.Unmarshal(rawPlan, &plan); err != nil {
return err
}
// 目标可能已换 owner;解析失败退回计划来源做路由授权,避免查询绕过撤权或归档约束。
checked := map[string]bool{board: true}
for _, step := range plan.Steps {
target, ok, e := resolveCanvasAITarget(r.Context(), tx, project, workspace, step)
@@ -82,6 +87,7 @@ func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project
checked[target] = true
}
}
// 步骤输出剔除 text,仅返回元信息和可应用版本;AppliedBoard 反映实际写回位置而非原计划位置。
rows, err := tx.QueryContext(r.Context(), `SELECT id,COALESCE(applied_board_id,board_id)::text,node_id,status,error_code,applied_version,CASE WHEN output IS NULL THEN NULL ELSE output-'text' END FROM canvas_ai_steps WHERE project=$1 AND workspace_id=$2 AND run_id=$3 ORDER BY ordinal`, project, workspace, id)
if err != nil {
return err
@@ -134,6 +140,7 @@ func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project
rows.Close()
return err
}
// 事件页既限条数又限累计 data 字节;至少保留首事件,next_seq 仅推进到真正返回的最后事件。
if size+len(data) > 800<<10 && len(events) > 0 {
break
}
@@ -168,6 +175,8 @@ func (s *service) getCanvasAIRun(w http.ResponseWriter, r *http.Request, project
// Resolve admission by the original client key, before the caller knows a run ID.
// Absence is unknown, not a terminal proof that an earlier invocation had no effect.
// getCanvasAIAdmission 用原客户端键恢复准入结果,先查 v2 请求表,再兼容旧 run 的 create_response。
// 没有记录只说明 unknown,不构成确定零效果证明,客户端应保留原键继续恢复。
func (s *service) getCanvasAIAdmission(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
+16
View File
@@ -1,3 +1,4 @@
// 按执行相关边懒读取画布树,避免为一次 AI 操作扫描无关或无权限的子画布。
package platform
import (
@@ -8,6 +9,7 @@ import (
"strings"
)
// canvasAIReader 通过注入 Load/Parent 解耦数据库,缓存快照、解码文档和已知父关系,并记录实际用到的边。
type canvasAIReader struct {
Load func(string) (canvasSnapshot, error)
Parent func(string) (subgraphRelation, error)
@@ -18,6 +20,7 @@ type canvasAIReader struct {
used map[string]map[string]bool
}
// snapshot 每个 board 只加载/解码一次,返回同一捕获快照供本次计划复用。
func (reader *canvasAIReader) snapshot(board string) (canvasSnapshot, map[string]any, error) {
if snapshot, ok := reader.snapshots[board]; ok {
return snapshot, reader.documents[board], nil
@@ -34,6 +37,8 @@ func (reader *canvasAIReader) snapshot(board string) (canvasSnapshot, map[string
reader.documents[board] = doc
return snapshot, doc, nil
}
// parent 将无父行归一为空关系并缓存 parentKnown,避免根画布被反复查询。
func (reader *canvasAIReader) parent(board string) (subgraphRelation, error) {
if reader.parentKnown[board] {
return reader.parents[board], nil
@@ -50,6 +55,8 @@ func (reader *canvasAIReader) parent(board string) (subgraphRelation, error) {
reader.parents[board] = relation
return relation, nil
}
// node 返回已加载画布中的节点 data,缺失节点按所有权冲突处理,不凭同名跨画布寻找。
func (reader *canvasAIReader) node(board, node string) (map[string]any, error) {
_, doc, err := reader.snapshot(board)
if err != nil {
@@ -63,6 +70,8 @@ func (reader *canvasAIReader) node(board, node string) (map[string]any, error) {
}
return nil, errGraphOwnership
}
// resolve 按方向递归解开 frame port,并验证数据库父关系与文档 subgraph 相符,最多跨八层。
func (reader *canvasAIReader) resolve(board, node, handle, direction string, depth int) (string, error) {
if depth > 8 {
return "", errGraphCapacity
@@ -98,6 +107,7 @@ func (reader *canvasAIReader) resolve(board, node, handle, direction string, dep
// Follow only real edges and the port chains exposing this node. Empty or
// unrelated child boards are never traversed merely because their frame exists.
// edges 从真实节点沿其祖先暴露端口查入/出边;execution.enabled=false 的边不参与,结果按逻辑边 ID 去重排序。
func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvasAIEdgePlan, error) {
type exposure struct {
Board, Node, Handle string
@@ -161,6 +171,7 @@ func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvas
logical := canvasAIEdgePlan{ID: canvasNodeKey(current.Board, id), Source: source, Target: target}
found[logical.ID] = logical
}
// 向上只跟踪暴露当前节点/handle 的端口,不因看见其他 frame 就遍历其孩子。
relation, err := reader.parent(current.Board)
if err != nil {
return nil, err
@@ -194,6 +205,8 @@ func (reader *canvasAIReader) edges(board, node string, outgoing bool) ([]canvas
sort.Slice(result, func(i, j int) bool { return result[i].ID < result[j].ID })
return result, nil
}
// plan 每次重置缓存,收集根及可传播节点和其静态前驱,再把实际使用边交给纯拓扑规划器。
func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAIPlan, error) {
reader.snapshots = map[string]canvasSnapshot{}
reader.documents = map[string]map[string]any{}
@@ -235,6 +248,7 @@ func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAI
}
}
}
// 保留已读节点数据但裁去无关边,避免纯规划阶段解析未加载或无权限的邻接子图。
filtered := map[string]canvasSnapshot{}
for id, snapshot := range reader.snapshots {
doc := reader.documents[id]
@@ -255,6 +269,8 @@ func (reader *canvasAIReader) plan(board, node string, propagate bool) (canvasAI
}
return buildCanvasAIPlan(filtered, board, node, propagate)
}
// loadCanvasAIPlan 注入事务内权限检查与持锁快照读取;每个实际读取画布都要求编辑权限。
func loadCanvasAIPlan(r *http.Request, tx *sql.Tx, project, workspace, account string, parent canvasSnapshot, node string, propagate bool) (canvasAIPlan, error) {
reader := canvasAIReader{Load: func(board string) (canvasSnapshot, error) {
_, role, err := lockMaterial(r.Context(), tx, project, workspace, board, account)
@@ -1,3 +1,4 @@
// 懒读取回归通过注入快照计数 Load,证明范围选择没有隐式扫描无关子树。
package platform
import (
@@ -7,6 +8,7 @@ import (
"testing"
)
// readerFromSnapshots 从快照 subgraph 字段建立测试父关系,并给实际 Load 调用计数,不预填 reader 缓存。
func readerFromSnapshots(snapshots map[string]canvasSnapshot, loads map[string]int) *canvasAIReader {
parents := map[string]subgraphRelation{}
for board, snapshot := range snapshots {
@@ -32,6 +34,8 @@ func readerFromSnapshots(snapshots map[string]canvasSnapshot, loads map[string]i
return subgraphRelation{}, sql.ErrNoRows
}}
}
// TestAIReaderDoesNotLoadUnrelatedSubgraphs 在含 499 个无关 frame 的根上运行,传播开/关都只能加载根一次。
func TestAIReaderDoesNotLoadUnrelatedSubgraphs(t *testing.T) {
nodes := []any{map[string]any{"id": "a", "type": "material", "position": map[string]any{"x": 0, "y": 0}, "data": map[string]any{"kind": "text", "title": "A", "text": "input", "ai": map[string]any{"enabled": true, "modelId": "fixture", "prompt": "transform", "parameters": map[string]any{}}}}}
for i := 0; i < 499; i++ {
@@ -50,6 +54,8 @@ func TestAIReaderDoesNotLoadUnrelatedSubgraphs(t *testing.T) {
}
}
}
// TestAIReaderResolvesChildOutputAndFrozenPredecessor 从孩子 b 跨父端口传播到 outside,冻结 a 输入,同时不加载空兄弟子图。
func TestAIReaderResolvesChildOutputAndFrozenPredecessor(t *testing.T) {
raw := memberFixture(t)
child := "11111111-1111-4111-8111-111111111111"
+7
View File
@@ -1,3 +1,4 @@
// 可选真实模型回归:只有明确配置专用 worker socket 与隔离数据库才运行,会调用实际文本和图片生成。
package platform
import (
@@ -23,6 +24,8 @@ import (
// Opt in only on the confirmed remote runner with its dedicated CLI worker.
// Normal CI never invokes a paid/real model as a side effect of unit tests.
// TestCanvasAIRealWorker 选择配对文本/图片模型,走准入、认领、生成写回和授权下载,最后完整解码生成图片。
// 环境变量只是测试开关,执行前仍须确认专用远程 runner 和真实模型调用授权。
func TestCanvasAIRealWorker(t *testing.T) {
socket, dsn := os.Getenv("FOUNDRY_REAL_CODEX_SOCKET"), os.Getenv("PLATFORM_TEST_DATABASE_URL")
if socket == "" || dsn == "" {
@@ -34,6 +37,7 @@ func TestCanvasAIRealWorker(t *testing.T) {
if err != nil {
t.Fatal(err)
}
// 先选显式已验证图片输出条目,再按去掉 Image 后缀的标签寻找对应文本模型,缺能力直接失败。
var imageModel, textModel codex.CanvasModel
for _, model := range models {
if model.Available && canvasModelSupports(model, "image") {
@@ -119,6 +123,7 @@ func TestCanvasAIRealWorker(t *testing.T) {
}
return result
}
// 手动认领指定 run,避免后台轮询干扰;数据库必须隔离,否则最早队列任务可能不是本用例。
execute := func(id string) {
t.Helper()
run, err := s.claimCanvasRun(ctx)
@@ -132,6 +137,7 @@ func TestCanvasAIRealWorker(t *testing.T) {
t.Fatalf("real worker run %s: %s", result["status"], encoded)
}
}
// 文本用例只检查标记包含及原几何保留,不把模型自然语言差异当作精确输出契约。
textRun := call("POST", base+"/ai/runs", response{"node_id": "a", "model_id": textModel.ID, "prompt": "Return exactly the text CANVAS_V2_OK", "parameters": response{}, "propagate": false}, 202, 1, "20000000-0000-4000-8000-000000000001")
execute(textRun["run_id"].(string))
textSaved := call("GET", base, nil, 200, 0, "")
@@ -146,6 +152,7 @@ func TestCanvasAIRealWorker(t *testing.T) {
}
doc["nodes"] = append(doc["nodes"].([]any), response{"id": "real-image", "type": "plainImage", "position": response{"x": 40, "y": 50}, "width": 240, "height": 160, "data": response{"kind": "plain-image", "title": "Real image", "text": "", "src": "data:image/png;base64," + base64.StdEncoding.EncodeToString(input.Bytes())}})
call("PATCH", base, response{"document": doc}, 200, 3, "")
// 图片结果必须成为托管资产,保留节点显示尺寸;实际原图尺寸/格式由下载后的完整解码验证。
imageRun := call("POST", base+"/ai/runs", response{"node_id": "real-image", "model_id": imageModel.ID, "prompt": "Generate one image: a solid blue circle centered on a white square background, no text.", "parameters": response{}, "propagate": false}, 202, 4, "20000000-0000-4000-8000-000000000002")
execute(imageRun["run_id"].(string))
saved := call("GET", base, nil, 200, 0, "")
+11
View File
@@ -1,3 +1,4 @@
// AI 变更回执协议:在工作区锁内以 savepoint 隔离副作用,确定拒绝也冻结同一请求身份。
package platform
import (
@@ -6,6 +7,7 @@ import (
"net/http"
)
// canvasAIRequest 绑定请求键、逻辑操作、动作、来源画布和可选 run,Hash 固定原始有效载荷。
type canvasAIRequest struct {
Key, Hash, Action, Board, Run, Operation string
}
@@ -13,6 +15,8 @@ type canvasAIRequest struct {
// The workspace lock is acquired by the caller before this savepoint. Rejected
// requests roll back every staged effect and retain that lock while recording
// their zero-effect receipt, so a response can never race a second invocation.
// beginCanvasAIRequest 先重放同请求或拒绝身份复用,再查已应用逻辑操作,最后建立副作用 savepoint。
// 调用方必须先取得工作区锁;返回 true 表示已响应,nil request 兼容旧协议且不建立 savepoint。
func beginCanvasAIRequest(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account string, request *canvasAIRequest) (bool, error) {
if request == nil {
return false, nil
@@ -44,6 +48,8 @@ func beginCanvasAIRequest(w http.ResponseWriter, r *http.Request, tx *sql.Tx, pr
_, err = tx.ExecContext(r.Context(), `SAVEPOINT canvas_ai_effects`)
return false, err
}
// bindCanvasAIReceipt 将协议/请求/操作/动作身份写入公开回执,旧协议 nil request 不改响应。
func bindCanvasAIReceipt(body response, request *canvasAIRequest) {
if request == nil {
return
@@ -53,6 +59,8 @@ func bindCanvasAIReceipt(body response, request *canvasAIRequest) {
body["run_id"] = request.Run
}
}
// commitCanvasAIReceipt 把冻结结果与业务副作用一起提交;数据库提交成功后才确认给客户端。
func commitCanvasAIReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account string, request *canvasAIRequest, status int, outcome string, body response) error {
if request != nil {
bindCanvasAIReceipt(body, request)
@@ -71,6 +79,9 @@ func commitCanvasAIReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, p
reply(w, status, body)
return nil
}
// rejectCanvasAIRequest 回滚 savepoint 后的全部副作用,再保留工作区锁写 terminal not-applied 回执。
// 旧协议没有回执时只响应拒绝,由外层 defer 回滚整个事务。
func rejectCanvasAIRequest(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account string, request *canvasAIRequest, status int, code string) error {
if request == nil {
reject(w, status, code)
+4
View File
@@ -1,3 +1,4 @@
// 仅 worker 明确未开始执行的忙碌准入可持久回队;已完成步骤结果保留供恢复后继续。
package platform
import (
@@ -6,6 +7,7 @@ import (
"encoding/json"
)
// canvasRunResults 读取非 queued 终态与文本/资产输出;遇仍 running 步骤拒绝恢复,避免重复调用未定执行。
func (s *service) canvasRunResults(ctx context.Context, run canvasQueueRun) (map[string]canvasStepResult, error) {
rows, err := s.db.QueryContext(ctx, `SELECT id,status,output FROM canvas_ai_steps WHERE project=$1 AND workspace_id=$2 AND run_id=$3 ORDER BY ordinal`, run.Project, run.Workspace, run.ID)
if err != nil {
@@ -41,6 +43,8 @@ func (s *service) canvasRunResults(ctx context.Context, run canvasQueueRun) (map
// A 429 codex_busy response proves the worker did not invoke the CLI. Only this
// admission failure can return a step to the persistent queue for safe retry.
// requeueCanvasStep 核对当前 run 租约和取消位,将唯一 running 步退回 queued,并把 run 延迟五秒可认领。
// 返回 true 表示已提交回队,外层必须结束当前执行;旧结果和逻辑身份不会重建。
func (s *service) requeueCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan) (bool, error) {
tx, err := s.db.BeginTx(ctx, nil)
if err != nil {
+13
View File
@@ -1,3 +1,4 @@
// AI run 准入入口:冻结依赖和输入、验证模型及队列预算,再原子保存配置、run、steps、事件和回执。
package platform
import (
@@ -15,6 +16,7 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// appendAIEvent 用单条 SQL 原子递增 run.last_seq 并插入事件,序号与业务状态一起提交。
func appendAIEvent(rctx context.Context, tx *sql.Tx, project, workspace, run, kind string, data any) error {
raw, err := json.Marshal(data)
if err != nil {
@@ -23,6 +25,8 @@ func appendAIEvent(rctx context.Context, tx *sql.Tx, project, workspace, run, ki
_, err = tx.ExecContext(rctx, `WITH next AS (UPDATE canvas_ai_runs SET last_seq=last_seq+1 WHERE project=$1 AND workspace_id=$2 AND id=$3 RETURNING last_seq) INSERT INTO canvas_ai_events(project,workspace_id,run_id,seq,type,data) SELECT $1,$2,$3,last_seq,$4,$5 FROM next`, project, workspace, run, kind, raw)
return err
}
// createCanvasAIRun 接受旧快照协议或 canonical v2;先按原请求身份恢复结果,后续确定拒绝可冻结零效果回执。
func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -76,6 +80,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
reject(w, 413, "context_too_large")
return nil
}
// v2 的 If-Match 也是不可变请求的一部分,不能只换版本头重用原始准入键。
hash := payloadDigest(input)
if input.ProtocolVersion != 0 {
// The version header is part of the immutable canonical admission request.
@@ -91,6 +96,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err != nil {
return err
}
// 只有完整 v2 请求身份才建立副作用 savepoint;旧请求沿用原 run.create_response 幂等路径。
var receipt *canvasAIRequest
if input.ProtocolVersion == 2 && input.RequestID == key && uuidSlugPattern.MatchString(input.OperationID) && input.TargetIncarnation > 0 {
receipt = &canvasAIRequest{Key: key, Hash: hash, Action: "run.start", Board: board, Operation: input.OperationID}
@@ -158,6 +164,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if !canvasChoice(target["kind"], "text", "script", "plain-text", "image", "plain-image") {
return rejectRequest(422, "model_incompatible")
}
// canonical 目标必须显式提供当前 incarnation,旧树请求不能夹带 canonical 字段越过迁移屏障。
root, incarnation, _, err := canvasAIIdentity(r.Context(), tx, project, workspace, board, input.NodeID)
if err != nil {
return err
@@ -172,6 +179,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
} else if input.ProtocolVersion != 0 || input.RequestID != "" || input.TargetIncarnation != 0 || input.OperationID != "" || input.ExpectedVersions != nil {
return rejectRequest(409, "canonical_migration_required")
}
// 先在内存准备目标 AI 配置;所有规划与预算检查通过后才随 run 一起落库,拒绝不能泄漏配置更新。
change, err := prepareCanvasAIPatch(r, tx, project, workspace, parent, input.NodeID, response{"ai": map[string]any{"enabled": true, "modelId": input.ModelID, "prompt": input.Prompt, "parameters": input.Parameters, "propagate": input.Propagate}})
if err != nil {
return rejectRequest(400, "invalid_ai_request")
@@ -207,12 +215,14 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err = bindCanvasAIIdentities(r.Context(), tx, project, workspace, &plan); err != nil {
return err
}
// 规划结果绑定稳定目标身份后,再验证每步输出模态和所有静态/动态图片来源是否被所选模型支持。
stepKinds := map[string]string{}
for _, step := range plan.Steps {
stepKinds[step.ID] = step.Kind
}
freezeCtx, stopFreeze := context.WithTimeout(r.Context(), 10*time.Second)
defer stopFreeze()
// 同一来源图片只冻结一次,十秒总上下文限制外部抓取;入队后不再依赖可变化远程 URL。
frozenImages := map[string]map[string]any{}
for index, step := range plan.Steps {
if step.Status == "skipped" {
@@ -292,6 +302,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if len(prompt)+len(text) > model.MaxInputBytes {
return rejectRequest(413, "context_too_large")
}
// canonical 忙碌检查按根/稳定 ID/incarnation,owner 移动不能绕过同一目标的在途任务约束。
var busy bool
if step.CanonicalRoot != "" {
err = tx.QueryRowContext(r.Context(), `SELECT EXISTS(SELECT 1 FROM canvas_ai_steps WHERE project=$1 AND workspace_id=$2 AND frozen_input->>'canonical_root'=$3 AND node_id=$4 AND frozen_input->>'target_incarnation'=$5::bigint::text AND status IN('queued','running'))`, project, workspace, step.CanonicalRoot, step.NodeID, step.TargetIncarnation).Scan(&busy)
@@ -306,6 +317,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
}
}
// A project-scoped advisory lock makes the queue limit atomic across workspaces.
// 项目级事务锁跨工作区串行化队列计数与插入,防止多个工作区同时越过 128 活跃 run 上限。
_, err = tx.ExecContext(r.Context(), `SELECT pg_advisory_xact_lock(hashtextextended($1,0))`, project+"/canvas-ai-queue")
if err != nil {
return err
@@ -343,6 +355,7 @@ func (s *service) createCanvasAIRun(w http.ResponseWriter, r *http.Request, proj
if err = appendAIEvent(r.Context(), tx, project, workspace, id, "run.queued", response{"status": "queued"}); err != nil {
return err
}
// 拓扑顺序作为 ordinal 持久化;skipped 步也保存状态和初始事件,使查询能解释未执行原因。
for ordinal, step := range plan.Steps {
frozen, _ := json.Marshal(step)
_, err = tx.ExecContext(r.Context(), `INSERT INTO canvas_ai_steps(project,workspace_id,run_id,id,board_id,node_id,ordinal,status,model_id,frozen_input,target_fingerprint) VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)`, project, workspace, id, step.ID, step.BoardID, step.NodeID, ordinal, step.Status, step.ModelID, frozen, step.Fingerprint)
+23
View File
@@ -1,3 +1,4 @@
// 持久 AI 队列:跨 Core 实例串行认领、租约恢复、按冻结拓扑执行,并把结果交事务写回器。
package platform
import (
@@ -12,15 +13,20 @@ import (
"gitea.entroia.com/Zayden-Jung/foundry-core/internal/codex"
)
// canvasQueueRun 保存本轮认领租约,后续状态写入必须匹配 Lease,旧执行者不能冒充新认领者。
type canvasQueueRun struct {
Project, Workspace, Board, ID, Account, Lease string
Plan canvasAIPlan
}
// canvasStepResult 在调度进程内保存终态及可传给后继的文本/资产 ID,Output 承载 worker 的结构化生成结果。
type canvasStepResult struct {
Status, Text, AssetID string
Output codex.CanvasOutput
}
// runCanvasQueue 每秒尝试取得专用连接的 session advisory lock,持锁期间最多执行一个完整 run。
// 此锁与事务锁不同,需在同一连接显式释放,再将连接归还池。
func (s *service) runCanvasQueue(ctx context.Context) {
ticker := time.NewTicker(time.Second)
defer ticker.Stop()
@@ -48,6 +54,8 @@ func (s *service) runCanvasQueue(ctx context.Context) {
conn.Close()
}
}
// claimCanvasRun 先恢复过期租约,再用 SKIP LOCKED 选最早可用 run,原子设 running、租约并记录事件。
func (s *service) claimCanvasRun(ctx context.Context) (*canvasQueueRun, error) {
if err := s.recoverCanvasRuns(ctx); err != nil {
return nil, err
@@ -81,6 +89,9 @@ func (s *service) claimCanvasRun(ctx context.Context) (*canvasQueueRun, error) {
}
return &run, nil
}
// recoverCanvasRuns 对已过期 running 租约逐个加锁重查,运行中步骤失败、未开始步骤跳过,不自动重付费执行。
// 已有成功步骤则 run 标为 partially_succeeded,否则 failed,并补齐终态事件。
func (s *service) recoverCanvasRuns(ctx context.Context) error {
rows, err := s.db.QueryContext(ctx, `SELECT project,workspace_id::text,id::text FROM canvas_ai_runs WHERE status='running' AND lease_until<now()`)
if err != nil {
@@ -188,6 +199,8 @@ func (s *service) recoverCanvasRuns(ctx context.Context) error {
}
return nil
}
// executeCanvasRun 复用持久终态结果,按计划拓扑顺序逐步执行;前驱非成功则跳过依赖步骤。
func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
results, err := s.canvasRunResults(ctx, run)
if err != nil {
@@ -224,6 +237,7 @@ func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
results[step.ID] = canvasStepResult{Status: status}
continue
}
// 先从冻结引用装入图片并重查权限,再将步骤从 queued 改为 running,之后才调用真实生成。
if err = s.hydrateCanvasTask(ctx, run, step, results, &task); err != nil {
code := "model_incompatible"
if err.Error() == "context_too_large" {
@@ -245,6 +259,7 @@ func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
continue
}
generated, generationErr := s.generateCanvasStep(ctx, run, step, task)
// 只有明确未进入 CLI 的忙碌结果可安全回队;网络超时/中断不证明没有执行,不能盲重试。
if generationErr != nil && generationErr.Error() == "codex_busy" {
requeued, e := s.requeueCanvasStep(ctx, run, step)
if e != nil || requeued {
@@ -270,6 +285,7 @@ func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
code = "generation_failed"
}
}
// 输出格式与文本预算检查后再持锁写回;返回状态决定后继能否消费本次输出。
status, err := s.finishCanvasStepOutput(ctx, run, step, generated, code, true)
if err != nil {
return
@@ -284,6 +300,8 @@ func (s *service) executeCanvasRun(ctx context.Context, run canvasQueueRun) {
}
_ = s.completeCanvasRun(ctx, run, results)
}
// assembleCanvasTask 按计划边顺序合并成功上游结果、静态输入和当前冻结内容,整体 JSON 与最终前缀提示都检查预算。
func assembleCanvasTask(plan canvasAIPlan, step canvasAIStepPlan, results map[string]canvasStepResult) (codex.CanvasTask, error) {
incoming := []any{}
for _, edge := range plan.Edges {
@@ -318,6 +336,8 @@ func assembleCanvasTask(plan canvasAIPlan, step canvasAIStepPlan, results map[st
}
return task, nil
}
// generateCanvasStep 限制模型调用时长,每秒心跳续租并确认 run/step 仍活跃;撤销或丢租约时取消 IPC。
func (s *service) generateCanvasStep(ctx context.Context, run canvasQueueRun, step canvasAIStepPlan, task codex.CanvasTask) (codex.CanvasOutput, error) {
duration := 90 * time.Second
if step.MaxExecutionMS > 0 && step.MaxExecutionMS <= 180000 {
@@ -325,6 +345,7 @@ func (s *service) generateCanvasStep(ctx context.Context, run canvasQueueRun, st
}
callCtx, cancel := context.WithTimeout(ctx, duration)
defer cancel()
// 缓冲一项保证主循环因取消提前返回后,调用 goroutine 仍能发送收尾结果而不永久阻塞。
done := make(chan canvasStepResult, 1)
go func() {
output, err := s.canvasAI.GenerateOutput(callCtx, task)
@@ -356,4 +377,6 @@ func (s *service) generateCanvasStep(ctx context.Context, run canvasQueueRun, st
}
}
}
// queueRequest 为共用 HTTP 风格数据库辅助函数创建仅含 context 的请求,不用于公开路由解析。
func queueRequest(ctx context.Context) *http.Request { return (&http.Request{}).WithContext(ctx) }
@@ -1,3 +1,4 @@
// 调度器任务组装纯回归,不启动队列、数据库或真实 CLI。
package platform
import (
@@ -5,6 +6,7 @@ import (
"testing"
)
// TestCanvasTaskUsesStableIncomingEdgeOrderAndFrozenContent 验证冻结正文与两条有序前驱输出进入提示,组装后超过上下文字节限额必须报错。
func TestCanvasTaskUsesStableIncomingEdgeOrderAndFrozenContent(t *testing.T) {
step := canvasAIStepPlan{ID: "board/d", ModelID: "fixture", Config: map[string]any{"prompt": "summarize", "parameters": map[string]any{}}, FrozenContent: map[string]any{"text": "original"}}
plan := canvasAIPlan{Edges: []canvasAIEdgePlan{{ID: "edge-a", Source: "board/b", Target: step.ID}, {ID: "edge-b", Source: "board/c", Target: step.ID}}}
+4
View File
@@ -1,3 +1,4 @@
// 画布能力发现:公布静态协议支持与运行时模型可用性,供无界面客户端选择可用命令。
package platform
import (
@@ -6,6 +7,7 @@ import (
"time"
)
// canvasCapabilities 先验证 board 可读,再释放工作区锁探测 worker,避免外部调用延长数据库锁。
func (s *service) canvasCapabilities(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -27,6 +29,7 @@ func (s *service) canvasCapabilities(w http.ResponseWriter, r *http.Request, pro
if err = tx.Rollback(); err != nil {
return err
}
// 模型探测最多五秒;失败仍返回能力契约,但将 AI 标为不可用并给出稳定原因。
ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
defer cancel()
models, modelErr := s.canvasAI.Models(ctx)
@@ -43,6 +46,7 @@ func (s *service) canvasCapabilities(w http.ResponseWriter, r *http.Request, pro
if modelErr != nil {
ai["unavailable_reason"] = "codex_unavailable"
}
// 协议版本、规模预算和回执期限应与服务实现同步;available 单独反映当前 AI 后端状态。
reply(w, 200, response{
"contract_version": "canvas-headless-2026-11-07",
"canonical_model": response{"document_format_version": canvasModelFormat, "protocol_version": canvasModelProtocol, "explicit_migration": true, "stable_element_ids": true, "atomic_multi_canvas": true, "logical_operation_dedup": true, "legacy_snapshot_writes": false},
+15
View File
@@ -1,3 +1,4 @@
// 跨子图连线事务:从真实端点向共同祖先暴露端口,并在祖先画布上保存唯一逻辑边。
package platform
import (
@@ -11,11 +12,14 @@ import (
)
// Endpoints name real nodes, never transient projected copies or client-created ports.
// canvasConnectionEndpoint 引用真实所有者画布中的节点,公开请求不能把投影副本或临时端口当真实节点。
type canvasConnectionEndpoint struct {
Board string `json:"board_id"`
Node string `json:"node_id"`
Handle string `json:"handle"`
}
// canvasConnectionInput 包含两端真实位置、边配置与完整参与画布版本表。
type canvasConnectionInput struct {
Source canvasConnectionEndpoint `json:"source"`
Target canvasConnectionEndpoint `json:"target"`
@@ -27,6 +31,7 @@ type canvasConnectionInput struct {
}
// Paths run from a leaf board upwards to (but excluding) the coordinator.
// connectionPath 从叶画布向协调者向上追溯,不含协调者本身;循环、过深、归档或断链都视为所有权冲突。
func connectionPath(r *http.Request, tx *sql.Tx, project, workspace, coordinator, board string) ([]subgraphRelation, error) {
path := []subgraphRelation{}
seen := map[string]bool{}
@@ -51,6 +56,7 @@ func connectionPath(r *http.Request, tx *sql.Tx, project, workspace, coordinator
return path, nil
}
// connectionNode 查找已校验节点数组中的对象,返回引用以便后续原地追加端口。
func connectionNode(doc map[string]any, id string) map[string]any {
for _, value := range doc["nodes"].([]any) {
node := value.(map[string]any)
@@ -63,6 +69,7 @@ func connectionNode(doc map[string]any, id string) map[string]any {
// Reuse ports by logical endpoint, including legacy ports with non-derived IDs.
// A derived ID collision must never retarget an existing port.
// connectionPort 先按逻辑端点复用旧端口,否则由方向/节点/handle 派生 ID;同 ID 异目标不能覆盖。
func connectionPort(data map[string]any, node, handle, direction string) (string, bool, error) {
ports, _ := data["ports"].([]any)
sum := sha256.Sum256([]byte(direction + "/" + node + "/" + handle))
@@ -85,6 +92,7 @@ func connectionPort(data map[string]any, node, handle, direction string) (string
return id, true, nil
}
// exposeConnectionEndpoint 逐层把真实端点转成父 frame 的 port 端点,返回祖先映射及实际新增端口清单。
func exposeConnectionEndpoint(endpoint canvasConnectionEndpoint, direction string, path []subgraphRelation, documents map[string]map[string]any) (canvasConnectionEndpoint, []any, error) {
node := connectionNode(documents[endpoint.Board], endpoint.Node)
if node == nil {
@@ -117,6 +125,7 @@ func exposeConnectionEndpoint(endpoint canvasConnectionEndpoint, direction strin
return endpoint, created, nil
}
// createCanvasConnection 校验 v2、幂等键与编辑权限后收集参与者;所有快照校验通过才开始持久化。
func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -176,6 +185,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
reject(w, 403, "forbidden")
return nil
}
// 在已授权且持锁后先重放相同请求回执,避免重试因版本已推进而误判冲突。
action, hash := "create_connection", payloadDigest(input)
done, err := transactionRetry(w, r, tx, project, account, coordinator, action, key, hash)
if err != nil || done {
@@ -211,6 +221,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
}
}
// Require the lowest common ancestor, so the logical edge has one owner.
// 两侧路径在协调者以下不得还有共同子画布,否则协调者不是最低共同祖先,边会放错所有者。
left := map[string]bool{}
for _, relation := range paths[0] {
left[relation.Child] = true
@@ -225,6 +236,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
for id := range participants {
ids = append(ids, id)
}
// 稳定排序参与者,生成可重复的版本要求、快照与事务记录。
sort.Strings(ids)
before := []canvasSnapshot{}
snapshots := map[string]canvasSnapshot{}
@@ -250,6 +262,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
}
documents[id] = doc
}
// 版本表必须恰好覆盖所有参与者,缺漏返回 required_board_ids,陈旧版本返回 412。
if len(input.Expected) != len(ids) {
reply(w, 428, response{"error": "version_required", "details": response{"required_board_ids": ids}})
return nil
@@ -293,6 +306,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
mapped = append(mapped, exposed)
created = append(created, ports...)
}
// 保存的是映射后祖先端点,但回执同时保留原始 source/target,供调用方恢复逻辑身份。
edge := map[string]any{"id": input.Edge.ID, "source": mapped[0].Node, "sourceHandle": mapped[0].Handle, "target": mapped[1].Node, "targetHandle": mapped[1].Handle}
if input.Edge.Data != nil {
edge["data"] = input.Edge.Data
@@ -336,6 +350,7 @@ func (s *service) createCanvasConnection(w http.ResponseWriter, r *http.Request,
}
result := response{"transaction_id": id, "parent": snapshots[coordinator], "snapshots": updated, "connection": response{"board_id": coordinator, "edge": edge, "source": input.Source, "target": input.Target}, "created_ports": created, "undo_receipt": response{"transaction_id": id, "valid_for_seconds": 604800, "expires_at": expiry}}
encoded, _ := json.Marshal(result)
// before 快照和 after_versions 支持七天撤销;响应体与幂等摘要一同入库,提交后才对外确认。
prior, _ := json.Marshal(before)
after, _ := json.Marshal(versions)
_, err = tx.ExecContext(r.Context(), `INSERT INTO canvas_transactions(project,workspace_id,board_id,id,account_id,action,idempotency_key,payload_hash,response_status,response_body,before_state,after_versions) VALUES($1,$2,$3,$4,$5,$6,$7,$8,201,$9,$10,$11)`, project, workspace, coordinator, id, account, action, key, hash, encoded, prior, after)
@@ -1,3 +1,4 @@
// 跨画布连线数据库回归需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移测试库;未配置则跳过。
package platform
import (
@@ -17,6 +18,7 @@ import (
"testing"
)
// TestCanvasConnectionTransactions 在隔离 PostgreSQL 中走完整 HTTP 连线/撤销/重试链路,并验证拒绝请求与容量失败没有部分持久化。
func TestCanvasConnectionTransactions(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -69,6 +71,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
Register(mux, db, map[string]string{project: "https://app.example.com/auth/callback"}, "https://api.example.com", nil)
base := "/projects/" + project + "/workspaces/" + workspace + "/materials/"
path := func(board string) string { return base + board + "/canvas" }
// do 只组请求,call 再验证状态/解码;全部请求显式协商 v2,避免旧客户端丢失端口数据。
do := func(method, url, token string, body any, version int64, key string) *httptest.ResponseRecorder {
raw, _ := json.Marshal(body)
r := httptest.NewRequest(method, url, bytes.NewReader(raw))
@@ -97,6 +100,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
return out
}
key := func(n int) string { return fmt.Sprintf("a0000000-0000-4000-8000-%012d", n) }
// 每次从真实 GET 读取参与者当前版本,构造恰好覆盖端口链的 expected_versions。
versions := func(ids ...string) map[string]int64 {
t.Helper()
out := map[string]int64{}
@@ -128,6 +132,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
command := func(source, node, target, targetNode, id string, ids ...string) response {
return response{"source": response{"board_id": source, "node_id": node, "handle": "right"}, "target": response{"board_id": target, "node_id": targetNode, "handle": "left"}, "edge": response{"id": id, "data": response{"appearance": response{"color": "#123456", "width": 2}, "path": response{"type": "bezier-chain", "knots": []any{response{"id": "k", "position": response{"x": 200, "y": 300}, "in": response{"x": -20, "y": 0}, "out": response{"x": 20, "y": 0}, "mode": "symmetric"}}}}}, "expected_versions": versions(ids...)}
}
// 从嵌套叶节点连到根节点,需要中间与根两个端口;叶文档本身不得被投影逻辑改写。
firstBody := command(leaf, "deep", root, "a", "external", root, left, leaf)
beforeLeaf := call("GET", path(leaf), tokens[0], nil, 200, 0, "")["document"]
first := call("POST", path(root)+"/connections", tokens[0], firstBody, 201, 0, key(4))
@@ -152,6 +157,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
if len(parent["document"].(map[string]any)["edges"].([]any)) != 2 {
t.Fatal("existing edge lost")
}
// 撤销还原所有参与快照并移除新端口;再次执行应恢复同一稳定逻辑端点映射。
undo := call("POST", path(root)+"/transactions/"+first["transaction_id"].(string)+"/undo", tokens[0], response{"expected_versions": versions(root, left, leaf)}, 200, 0, key(5))
if len(undo["snapshots"].([]any)) != 3 {
t.Fatal("undo did not restore complete chain")
@@ -181,6 +187,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
t.Fatal("input chain reused output ports")
}
// Missing/stale participant versions, bad endpoints and permission failures are atomic.
// 收集拒绝前版本,随后缺版本、旧版本、非法端点及权限失败都必须保持整个向量不变。
stable := versions(root, left, leaf)
missing := command(leaf, "deep", root, "a", "missing", root, left)
required := call("POST", path(root)+"/connections", tokens[0], missing, 428, 0, key(10))
@@ -203,6 +210,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
t.Fatal("rejected transaction partially changed versions")
}
// The actual nested mapping is resolvable by the same reader used by AI propagation.
// 将真实保存的快照交给 AI reader,确认连接生成的端口链可解析回真实叶节点。
graph := map[string]canvasSnapshot{}
for _, board := range []string{root, left, leaf} {
read := call("GET", path(board), tokens[0], nil, 200, 0, "")
@@ -257,6 +265,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
t.Fatal("capabilities omitted connection transaction")
}
// Four simultaneous retries create exactly one edge/receipt and advance versions once.
// 四个同键请求同时放行,必须共用回执并让每个参与画布恰好递增一次。
concurrent := command(left, "l2", root, "a", "concurrent", root, left)
prior := versions(root, left)
start := make(chan struct{})
@@ -285,6 +294,7 @@ func TestCanvasConnectionTransactions(t *testing.T) {
}
}
// A full coordinator rejects the entire operation, including new leaf ports.
// 填满协调者边数再建新端口链,最终容量拒绝必须回滚叶端口、版本和事务记录。
snapshot := call("GET", path(root), tokens[0], nil, 200, 0, "")
doc := snapshot["document"].(map[string]any)
edges := []any{}
@@ -1,3 +1,4 @@
// 画布与资产纯函数回归;测试说明对应实际断言,不依赖浏览器或真实模型。
package platform
import (
@@ -6,6 +7,7 @@ import (
"testing"
)
// TestConnectionPortReuseCollisionAndCapacity 验证按逻辑端点复用历史 ID,输入输出分离,派生 ID 冲突不可换绑,容量耗尽也不部分改写端口表。
func TestConnectionPortReuseCollisionAndCapacity(t *testing.T) {
data := map[string]any{"ports": []any{map[string]any{"id": "custom-stable", "nodeId": "n", "handle": "left", "direction": "input"}}}
id, created, err := connectionPort(data, "n", "left", "input")
@@ -30,6 +32,7 @@ func TestConnectionPortReuseCollisionAndCapacity(t *testing.T) {
}
}
// TestConnectionExposureBuildsNestedDirectionChain 构造 leaf→middle→root 两层边界,检查逐层端口映射、同方向复用、反方向独立创建及叶节点文档不变。
func TestConnectionExposureBuildsNestedDirectionChain(t *testing.T) {
frame := func(child string) map[string]any {
return map[string]any{"id": "frame", "data": map[string]any{"kind": "frame", "subgraph": map[string]any{"boardId": child}, "ports": []any{}}}
@@ -1,3 +1,4 @@
// 可选端到端回归:在获授权远程环境使用真实 Endoleap Node runtime 对接 Foundry HTTP 和隔离数据库。
package platform
import (
@@ -19,6 +20,7 @@ import (
// Runs the real Endoleap runtime against authenticated Foundry HTTP and PostgreSQL.
// This opt-in is enabled by the existing remote schema runner, never local builds.
// TestHeadlessClientHTTPIntegration 需 FOUNDRY_HEADLESS_SOURCE 指向客户端源码;缺省跳过,显式开启却无隔离数据库则失败。
func TestHeadlessClientHTTPIntegration(t *testing.T) {
source, dsn := os.Getenv("FOUNDRY_HEADLESS_SOURCE"), os.Getenv("PLATFORM_TEST_DATABASE_URL")
if source == "" {
@@ -66,6 +68,7 @@ func TestHeadlessClientHTTPIntegration(t *testing.T) {
server := httptest.NewServer(mux)
defer server.Close()
// 子进程最多两分钟,环境传递临时项目/账户/会话;所有输出先替换 token 再报告。
commandContext, cancel := context.WithTimeout(ctx, 2*time.Minute)
defer cancel()
command := exec.CommandContext(commandContext, "node", filepath.Join(source, "tests/headless/foundry.integration.mjs"))
@@ -76,6 +79,7 @@ func TestHeadlessClientHTTPIntegration(t *testing.T) {
if err != nil {
t.Fatalf("headless HTTP client failed: %v\n%s", err, report)
}
// 仅退出零不够,报告必须声明 status ok 且 runtimeAI 实际执行过。
if !strings.Contains(report, `"status":"ok"`) || !strings.Contains(report, `"runtimeAI":true`) {
t.Fatalf("headless HTTP client did not return success: %s", report)
}
@@ -1,3 +1,4 @@
// Headless 测试专用 worker 适配:固定生成输出,但准入、认领、取消、事件和 canonical 落库仍走生产实现。
package platform
import (
@@ -20,8 +21,10 @@ import (
// Only the generation transport is deterministic. Admission, claims, events,
// canonical writes and action receipts use the real service and isolated DB.
// headlessWorkerRoutes 搭建 Unix 假 worker 与私有控制路由,返回给端到端客户端;不是生产服务注册入口。
func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string, project, account string) http.Handler {
t.Helper()
// gate 同步确认生成已进入并控制释放,sync.Once 防止并发控制重复 close 通道。
type gate struct {
entered, release chan struct{}
started, released sync.Once
@@ -80,6 +83,7 @@ func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string,
reply(w, 200, response{"result": "headless fixture output"})
}
})}
// 清理先释放正在阻塞的生成再关闭 server,避免用例失败后泄漏等待 goroutine。
go worker.Serve(listener)
t.Cleanup(func() {
mu.Lock()
@@ -89,6 +93,7 @@ func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string,
mu.Unlock()
worker.Close()
})
// 不启动周期队列,测试通过 execute 控制认领时刻,以稳定覆盖运行中目标移动/取消等竞态。
s := &service{db: db, origin: "https://api.example.com", canvasAI: codex.NewCanvasClient(socket)}
mux := http.NewServeMux()
prefix := "/projects/{project}/workspaces/{workspace}/materials/{material}/canvas/ai"
@@ -104,6 +109,7 @@ func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string,
reject(w, 403, "forbidden")
return nil
}
// arm/wait/release 管理传输门闩,execute 驱动一次真实队列认领,stats 暴露调用计数。
switch r.PathValue("action") {
case "arm":
mu.Lock()
@@ -143,6 +149,7 @@ func headlessWorkerRoutes(t *testing.T, db *sql.DB, callbacks map[string]string,
reply(w, 200, response{"executions": executions.Load()})
return nil
}))
// 其他平台请求走常规 Register;只有 AI 路径分流到可受测试精确控制的 service。
regular := http.NewServeMux()
Register(regular, db, callbacks, "https://api.example.com", nil)
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+5
View File
@@ -1,3 +1,4 @@
// 图规模预检与幂等键归一化,供多种画布 HTTP 命令共享。
package platform
import (
@@ -6,9 +7,13 @@ import (
"strings"
)
// canvasIdempotencyKey 统一 UUID 大小写,格式合法性由具体入口继续验证。
func canvasIdempotencyKey(r *http.Request) string {
return strings.ToLower(r.Header.Get("Idempotency-Key"))
}
// canvasExceededGraphLimits 只判断节点/边/knot 数量超限;坏 JSON 返回 false 交给完整校验报告 400。
// 与 normalizeCanvas 分离,使合法可解码但规模过大的请求能明确返回 413。
func canvasExceededGraphLimits(raw json.RawMessage) bool {
var doc struct {
Nodes []json.RawMessage `json:"nodes"`
+46
View File
@@ -1,3 +1,4 @@
// Canonical 画布的内存模型与纯事务 reducer:元素稳定身份独立于 owner,跨画布编辑一次校验最终全图。
package platform
import (
@@ -9,20 +10,26 @@ import (
"strings"
)
// 文档格式与写入协议独立版本化,前者描述模型视图,后者描述请求/回执契约。
const canvasModelFormat = 1
const canvasModelProtocol = 2
var errCanvasModel = errors.New("invalid_canvas_model")
var errModelConflict = errors.New("canvas_model_field_conflict")
// modelParent 用父画布和入口元素描述唯一所有权;不依赖旧 frameId 或投影端口。
type modelParent struct {
CanvasID string `json:"canvasId"`
EntryElementID string `json:"entryElementId"`
}
// modelCanvas 的根 Parent 为 nil,其他画布必须有唯一且有效的入口节点。
type modelCanvas struct {
ID string `json:"id"`
Parent *modelParent `json:"parent"`
}
// canvasModel 同时保留活跃对象、删除 incarnation 和死记录;Versions 也保留已移除画布的版本。
type canvasModel struct {
Root string
Canvases map[string]modelCanvas
@@ -32,6 +39,8 @@ type canvasModel struct {
DeadRecords map[string]map[string]any
Versions map[string]int64
}
// modelView 为客户端提供完整或参与者局部模型;Removed 明确列出已归档但仍有版本的画布。
type modelView struct {
Format int `json:"documentFormatVersion"`
ProjectID string `json:"projectId"`
@@ -42,10 +51,14 @@ type modelView struct {
Complete bool `json:"complete"`
Removed []string `json:"removedCanvasIds"`
}
// modelTarget 以 ID+incarnation 定位一代元素,避免删除后恢复的同 ID 被旧操作命中。
type modelTarget struct {
ID string `json:"id"`
Incarnation int64 `json:"incarnation"`
}
// modelChange 使用 before/after 做比较交换;data 字段的 Present 指针区分缺字段和显式 null。
type modelChange struct {
Kind string `json:"kind"`
ID string `json:"id,omitempty"`
@@ -56,10 +69,14 @@ type modelChange struct {
BeforePresent *bool `json:"beforePresent,omitempty"`
AfterPresent *bool `json:"afterPresent,omitempty"`
}
// modelOperation 是需跨请求去重的逻辑操作,一次包含若干有序变更。
type modelOperation struct {
ID string `json:"id"`
Changes []modelChange `json:"changes"`
}
// modelBatch 将多逻辑操作与所有参与画布版本打包;RequestID 必须等于 HTTP 幂等键。
type modelBatch struct {
ProtocolVersion int `json:"protocol_version"`
RequestID string `json:"request_id"`
@@ -67,10 +84,15 @@ type modelBatch struct {
Operations []modelOperation `json:"operations"`
}
// emptyModel 初始化所有索引,尚无活跃画布,需迁移或构造后通过 validateCanvasModel。
func emptyModel(root string) canvasModel {
return canvasModel{Root: root, Canvases: map[string]modelCanvas{}, Elements: map[string]map[string]any{}, Tombstones: map[string]int64{}, TombstoneOwners: map[string]string{}, DeadRecords: map[string]map[string]any{}, Versions: map[string]int64{}}
}
// modelString 只读取已解码 JSON 字符串,类型错误返回空值交由上层验证。
func modelString(value any) string { text, _ := value.(string); return text }
// modelInt 只接受 JavaScript 安全正整数,防止版本/incarnation 跨端精度丢失。
func modelInt(value any) int64 {
number, ok := value.(float64)
if !ok || number < 1 || number > 9007199254740991 || math.Trunc(number) != number {
@@ -78,6 +100,8 @@ func modelInt(value any) int64 {
}
return int64(number)
}
// modelJSONSafe 递归限制深度并拒绝非有限浮点或非 JSON 类型,允许未知组件保留合法数据。
func modelJSONSafe(value any, depth int) bool {
if depth > 64 {
return false
@@ -104,6 +128,8 @@ func modelJSONSafe(value any, depth int) bool {
}
return false
}
// modelEqual 统一到 JSON 值域后比较,使 Go 整数/结构体与解码出的 float64/对象能按语义相等。
func modelEqual(left, right any) bool {
// Round-trip numeric Go structs and JSON records to the same JSON value domain.
a, ea := json.Marshal(left)
@@ -114,6 +140,8 @@ func modelEqual(left, right any) bool {
var av, bv any
return json.Unmarshal(a, &av) == nil && json.Unmarshal(b, &bv) == nil && reflect.DeepEqual(av, bv)
}
// view 按稳定 ID 排序输出,participants 为 nil 表示完整模型,否则只返回给定画布及其墓碑。
func (model canvasModel) view(participants map[string]int64) modelView {
view := modelView{Format: canvasModelFormat, ProjectID: model.Root, Canvases: []modelCanvas{}, Elements: []map[string]any{}, Tombstones: map[string]int64{}, Versions: map[string]int64{}, Complete: participants == nil, Removed: []string{}}
for _, id := range sortedKeys(model.Canvases) {
@@ -134,6 +162,7 @@ func (model canvasModel) view(participants map[string]int64) modelView {
}
view.Elements = append(view.Elements, element)
}
// 删除代数也必须处于安全整数范围;活跃元素的 incarnation 稍后要求严格高于其墓碑。
for id, incarnation := range model.Tombstones {
owner := model.TombstoneOwners[id]
if live := model.Elements[id]; live != nil {
@@ -159,6 +188,8 @@ func (model canvasModel) view(participants map[string]int64) modelView {
}
return view
}
// sortedKeys 为模型、投影和回执提供确定顺序,不依赖 Go map 遍历顺序。
func sortedKeys[T any](values map[string]T) []string {
keys := make([]string, 0, len(values))
for key := range values {
@@ -167,12 +198,16 @@ func sortedKeys[T any](values map[string]T) []string {
sort.Strings(keys)
return keys
}
// cloneModel 深拷贝 JSON 兼容模型,让 reducer 失败时输入对象及嵌套 data 不被污染。
func cloneModel(model canvasModel) canvasModel {
raw, _ := json.Marshal(model)
var copy canvasModel
_ = json.Unmarshal(raw, &copy)
return copy
}
// modelAncestors 从当前画布向根遍历,拒绝缺父、循环和超过八层边界的路径。
func modelAncestors(model canvasModel, id string) ([]string, error) {
path, seen := []string{}, map[string]bool{}
for id != "" {
@@ -189,6 +224,8 @@ func modelAncestors(model canvasModel, id string) ([]string, error) {
}
return path, nil
}
// modelCommonCanvas 从右端最近祖先向上寻找交集,确定连接唯一的最低共同祖先所有者。
func modelCommonCanvas(model canvasModel, left, right string) (string, error) {
a, err := modelAncestors(model, left)
if err != nil {
@@ -209,6 +246,9 @@ func modelCommonCanvas(model canvasModel, left, right string) (string, error) {
}
return "", errCanvasModel
}
// validateCanvasModel 对最终状态检查唯一根、入口所有权、元素代数、JSON 预算及连接最低共同祖先。
// 未知组件的合法 data/envelope 字段保留;仅已知 v1 组件追加相应业务数据约束。
func validateCanvasModel(model canvasModel) error {
if !uuidSlugPattern.MatchString(model.Root) || len(model.Canvases) == 0 || len(model.Canvases) > 256 || len(model.Elements) > 128000 {
return errCanvasModel
@@ -310,6 +350,7 @@ func validateCanvasModel(model canvasModel) error {
}
// Pure transaction reducer. Unknown component data/envelope fields are retained.
// applyModelOperations 在副本依次执行变更,允许批次中间态暂不完整,最后统一验证所有权和引用。
func applyModelOperations(initial canvasModel, operations []modelOperation) (canvasModel, map[string]bool, error) {
model, touched, seen := cloneModel(initial), map[string]bool{}, map[string]bool{}
if len(operations) == 0 || len(operations) > 2500 {
@@ -332,6 +373,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
}
switch change.Kind {
case "field":
// 字段编辑必须命中同代元素;data.<key> 是单层键,其他字段只允许明确白名单。
element := model.Elements[change.Target.ID]
if element == nil || modelInt(element["incarnation"]) != change.Target.Incarnation {
return model, nil, errModelConflict
@@ -344,6 +386,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
}
data := element["data"].(map[string]any)
prior, present := data[key]
// beforePresent 缺省表示字段存在,因此缺字段与现有 null 不会被误当作同一前态。
if present != (change.BeforePresent == nil || *change.BeforePresent) || !modelEqual(prior, before) {
return model, nil, errModelConflict
}
@@ -365,6 +408,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
}
}
case "element":
// 整记录增删替换先比较前态;删除留下死记录,恢复要求比已删除代数更新的 incarnation。
if !canvasID.MatchString(change.ID) || !modelEqual(model.Elements[change.ID], before) {
return model, nil, errModelConflict
}
@@ -393,6 +437,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
touched[modelString(record["ownerCanvasId"])] = true
}
case "canvas":
// 画布关系变动同时触及旧父和新父,确保入口所有权变化被版本向量覆盖。
prior, exists := model.Canvases[change.ID]
var priorValue any
if exists {
@@ -443,6 +488,7 @@ func applyModelOperations(initial canvasModel, operations []modelOperation) (can
}
}
}
// 每个参与者无论本批被触及多少次都只递增一次;数据库权限与预期版本仍由 HTTP 层检查。
for id := range touched {
model.Versions[id] = initial.Versions[id] + 1
}
@@ -1,3 +1,4 @@
// Canonical 原子性数据库回归:需 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移测试库,未配置则跳过。
package platform
import (
@@ -16,6 +17,7 @@ import (
"time"
)
// canonicalAtomicFixture 持有随机项目、真实路由与源快照,所有请求共用有效账户和独立工作区。
type canonicalAtomicFixture struct {
db *sql.DB
mux *http.ServeMux
@@ -23,6 +25,7 @@ type canonicalAtomicFixture struct {
legacy json.RawMessage
}
// newCanonicalAtomicFixture 建账户/会话/admin/旧图,并按外键关系注册数据清理;不自动执行迁移脚本。
func newCanonicalAtomicFixture(t *testing.T) *canonicalAtomicFixture {
t.Helper()
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
@@ -68,10 +71,12 @@ func newCanonicalAtomicFixture(t *testing.T) *canonicalAtomicFixture {
return f
}
// path 返回本 fixture 根的 canonical 入口,避免测试错用旧快照路径。
func (f *canonicalAtomicFixture) path() string {
return "/projects/" + f.project + "/workspaces/" + f.workspace + "/materials/" + f.root + "/canvas/model"
}
// request 携带会话、预期账户及 v2 协商,并沿用传入 context 以测试数据库写入中途取消。
func (f *canonicalAtomicFixture) request(ctx context.Context, method, path, key string, raw []byte) *httptest.ResponseRecorder {
r := httptest.NewRequest(method, path, bytes.NewReader(raw)).WithContext(ctx)
r.Header.Set("Authorization", "Bearer "+f.token)
@@ -85,6 +90,7 @@ func (f *canonicalAtomicFixture) request(ctx context.Context, method, path, key
return w
}
// canonicalAtomicResponse 先断言实际 HTTP 状态,再解码响应,避免把错误 JSON 当作正常模型使用。
func canonicalAtomicResponse(t *testing.T, w *httptest.ResponseRecorder, status int) response {
t.Helper()
if w.Code != status {
@@ -97,6 +103,7 @@ func canonicalAtomicResponse(t *testing.T, w *httptest.ResponseRecorder, status
return body
}
// read 直接从权威模型表装配完整模型,检查 HTTP 应答外的持久化事实。
func (f *canonicalAtomicFixture) read(t *testing.T) canvasModel {
t.Helper()
tx, err := f.db.BeginTx(context.Background(), nil)
@@ -111,6 +118,7 @@ func (f *canonicalAtomicFixture) read(t *testing.T) canvasModel {
return model
}
// concurrent 同时放行多请求并按原索引收集,二十秒上下文限制等待,不以返回顺序猜赢家。
func (f *canonicalAtomicFixture) concurrent(t *testing.T, path string, keys []string, bodies [][]byte) []*httptest.ResponseRecorder {
t.Helper()
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
@@ -139,6 +147,8 @@ func (f *canonicalAtomicFixture) concurrent(t *testing.T, path string, keys []st
return out
}
// TestCanonicalConcurrentMigrationAndOwnershipWrites 验证同键迁移/编辑只执行一次,不同条件所有权写只有一个赢家。
// 成功和冲突都必须有可查询冻结回执,未涉及元素和树不得被部分改写。
func TestCanonicalConcurrentMigrationAndOwnershipWrites(t *testing.T) {
f := newCanonicalAtomicFixture(t)
ctx := context.Background()
@@ -176,6 +186,7 @@ func TestCanonicalConcurrentMigrationAndOwnershipWrites(t *testing.T) {
if before.Versions[child] != 2 || before.Versions[f.root] != 2 || modelString(before.Elements[ids["a"]]["data"].(map[string]any)["title"]) != "renamed" {
t.Fatal("concurrent edit executed more than once")
}
// 两请求共享同一版本向量,各移动不同节点但都移动其连接,验证条件写竞争而非简单串行重放。
var batches []modelBatch
var keys []string
var bodies [][]byte
@@ -223,6 +234,8 @@ func TestCanonicalConcurrentMigrationAndOwnershipWrites(t *testing.T) {
}
}
// TestCanonicalMigrationLateCancellationRollsBack 用独占表锁卡住后期身份映射 INSERT,观察确实到达后才取消请求。
// 所有模型/关系/新素材和旧版本应回滚,随后同原请求能安全重试且只分配一次最终身份映射。
func TestCanonicalMigrationLateCancellationRollsBack(t *testing.T) {
f := newCanonicalAtomicFixture(t)
ctx, stop := context.WithTimeout(context.Background(), 20*time.Second)
@@ -247,6 +260,7 @@ func TestCanonicalMigrationLateCancellationRollsBack(t *testing.T) {
go func() { done <- f.request(requestContext, "POST", f.path()+"/migrate", key, modelJSON(input)) }()
// Observe the actual late INSERT blocked behind this transaction. A timer
// alone cannot prove migration reached canonical/material/subgraph writes.
// 查询 pg_stat_activity/pg_blocking_pids 证明是目标后期写被阻塞,不用单纯 sleep 推断执行进度。
ticker := time.NewTicker(10 * time.Millisecond)
defer ticker.Stop()
observed := false
@@ -299,6 +313,8 @@ func TestCanonicalMigrationLateCancellationRollsBack(t *testing.T) {
}
}
// TestCanonicalMigrationPermissionVersionAndRunGuards 检查 viewer、陈旧版本及 queued/running AI 阻止身份屏障。
// 原拒绝键在版本或任务状态改变后仍冻结,新的请求键才能在条件满足后执行迁移。
func TestCanonicalMigrationPermissionVersionAndRunGuards(t *testing.T) {
f := newCanonicalAtomicFixture(t)
ctx := context.Background()
+3
View File
@@ -1,3 +1,4 @@
// Canonical 树的旧入口屏障,防止旧快照或子图命令覆盖已迁入的稳定身份模型。
package platform
import (
@@ -7,6 +8,8 @@ import (
// Old frozen receipts remain readable. Old whole-snapshot/ownership writers may
// not edit a migrated tree, even when their old client has not seen the barrier.
// guardLegacyCanonicalRequest 在 protected 分派前执行;历史回执 GET 可读,但旧快照读取和旧写命令被引导到模型接口。
// 返回 true 表示已经响应 409,调用方必须停止后续业务处理。
func (s *service) guardLegacyCanonicalRequest(w http.ResponseWriter, r *http.Request, project, account string) (bool, error) {
if r.PathValue("material") == "" {
return false, nil
+23
View File
@@ -1,3 +1,4 @@
// Canonical 读/迁移/写入口:冻结请求回执与逻辑操作去重,业务数据和回执同事务提交。
package platform
import (
@@ -13,6 +14,7 @@ import (
const modelMigrateAction = "model.migrate.v1"
const modelEditAction = "model.operations.v2"
// newModelID 用随机字节生成 UUIDv4,随机源失败返回空值,由调用方拒绝后续处理。
func newModelID() string {
var value [16]byte
if _, err := rand.Read(value[:]); err != nil {
@@ -22,6 +24,8 @@ func newModelID() string {
text := hex.EncodeToString(value[:])
return text[:8] + "-" + text[8:12] + "-" + text[12:16] + "-" + text[16:20] + "-" + text[20:]
}
// legacyModelRoot 沿活跃父链寻找旧树根,拒绝循环、归档和过深树。
func legacyModelRoot(r *http.Request, tx *sql.Tx, project, workspace, board string) (string, error) {
seen := map[string]bool{}
for len(seen) <= 8 {
@@ -43,6 +47,8 @@ func legacyModelRoot(r *http.Request, tx *sql.Tx, project, workspace, board stri
}
return "", errCanvasModel
}
// collectLegacyModel 收集根下最多 256 个 board 快照及关系,限额多取一项用于检测超限。
func collectLegacyModel(r *http.Request, tx *sql.Tx, project, workspace, root string) (map[string]canvasSnapshot, []subgraphRelation, error) {
rows, err := tx.QueryContext(r.Context(), `WITH RECURSIVE tree(id,path) AS (SELECT $3::uuid,ARRAY[$3::uuid] UNION ALL SELECT s.child_board_id,t.path||s.child_board_id FROM tree t JOIN canvas_subgraphs s ON s.project=$1 AND s.workspace_id=$2 AND s.parent_board_id=t.id WHERE s.archived_at IS NULL AND NOT s.child_board_id=ANY(t.path) AND cardinality(t.path)<=8) SELECT m.id::text,m.canvas_version,COALESCE(m.canvas_document,'{"schema_version":2,"nodes":[],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}'::jsonb) FROM tree t JOIN materials m ON m.project=$1 AND m.workspace_id=$2 AND m.id=t.id WHERE m.kind='board' ORDER BY m.id LIMIT 257`, project, workspace, root)
if err != nil {
@@ -82,6 +88,8 @@ func collectLegacyModel(r *http.Request, tx *sql.Tx, project, workspace, root st
}
return snapshots, relations, rows.Err()
}
// modelRequestRetry 按项目/工作区/账户/request ID 查冻结回执,并核对根、动作和载荷摘要防止跨用途复用。
func modelRequestRetry(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account, root, action, key, hash string) (bool, error) {
var previousRoot, previousAction, previousHash string
var status int
@@ -100,6 +108,8 @@ func modelRequestRetry(w http.ResponseWriter, r *http.Request, tx *sql.Tx, proje
reply(w, status, body)
return true, nil
}
// commitModelReceipt 注入协议和请求 ID,保存应用或终局拒绝回执后提交;提交成功才对外响应。
func commitModelReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, workspace, account, root, action, key, hash string, status int, body response) error {
body["request_id"], body["protocol_version"] = key, canvasModelProtocol
raw, err := json.Marshal(body)
@@ -116,6 +126,8 @@ func commitModelReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, proj
reply(w, status, body)
return nil
}
// decodeModelRequest 限制五 MiB、未知字段与尾随 JSON;失败立即写出 400。
func decodeModelRequest(w http.ResponseWriter, r *http.Request, input any) bool {
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, canvasLimit))
decoder.DisallowUnknownFields()
@@ -126,6 +138,7 @@ func decodeModelRequest(w http.ResponseWriter, r *http.Request, input any) bool
return true
}
// getCanvasModel 未迁移时返回根和源版本表;已迁移时读模型表,在发送 JSON/NDJSON 前释放锁。
func (s *service) getCanvasModel(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -181,6 +194,7 @@ func (s *service) getCanvasModel(w http.ResponseWriter, r *http.Request, project
return nil
}
// migrateCanonicalCanvas 是显式身份屏障:完整确认旧树版本、等待在途 AI 结束,再保存模型及身份映射。
func (s *service) migrateCanonicalCanvas(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -232,6 +246,7 @@ func (s *service) migrateCanonicalCanvas(w http.ResponseWriter, r *http.Request,
if err != nil || done {
return err
}
// 已鉴权且可冻结的业务拒绝也入回执表,同请求不能在外部条件改变后变成新的执行。
rejectMigration := func(status int, code string) error {
return commitModelReceipt(w, r, tx, project, workspace, account, root, modelMigrateAction, key, payloadDigest(input), status, response{"status": "not-applied", "terminal": true, "error": code})
}
@@ -289,6 +304,7 @@ func (s *service) migrateCanonicalCanvas(w http.ResponseWriter, r *http.Request,
return commitModelReceipt(w, r, tx, project, workspace, account, root, modelMigrateAction, key, payloadDigest(input), 200, response{"status": "applied", "model": migration.Model.view(nil), "identity_map": migration.Identities, "source_versions": input.Expected})
}
// submitCanvasModelOperations 校验预期版本与跨请求逻辑操作 ID,运行纯 reducer 后检查完整参与者和资产权限。
func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -339,6 +355,7 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
if err != nil || done {
return err
}
// terminal not-applied 冻结本次确定拒绝;连接故障等未定结果返回依赖错误,由客户端同键查询/重试。
rejectBatch := func(status int, code string) error {
return commitModelReceipt(w, r, tx, project, workspace, account, root, modelEditAction, key, payloadDigest(input), status, response{"status": "not-applied", "terminal": true, "error": code})
}
@@ -351,6 +368,7 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
return rejectBatch(412, "version_conflict")
}
}
// operation_id 独立于 request_id,防止同一逻辑编辑被换请求键再次应用。
for _, operation := range input.Operations {
if !uuidSlugPattern.MatchString(operation.ID) {
return rejectBatch(400, "invalid_model_operation")
@@ -371,6 +389,7 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
}
return rejectBatch(409, code)
}
// reducer 识别的读写参与者都必须在 Expected 中;额外明确参与者也推进一次版本。
for id := range touched {
if _, exists := input.Expected[id]; !exists {
return rejectBatch(428, "version_required")
@@ -394,6 +413,7 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
after.Versions[id] = before.Versions[id] + 1
}
}
// 新身份不能占用同项目其他树的元素 ID;新增或更换资产引用须按当前授权重新核对。
for id, element := range after.Elements {
if before.Elements[id] == nil {
var foreign bool
@@ -445,6 +465,8 @@ func (s *service) submitCanvasModelOperations(w http.ResponseWriter, r *http.Req
}
return commitModelReceipt(w, r, tx, project, workspace, account, root, modelEditAction, key, payloadDigest(input), 200, response{"status": "applied", "operation_ids": ids, "model": after.view(input.Expected)})
}
// getCanvasModelOperation 当前授权后只返回本人同根冻结回执;缺记录为 unknown,不能声称确定没有执行。
func (s *service) getCanvasModelOperation(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -490,6 +512,7 @@ func (s *service) getCanvasModelOperation(w http.ResponseWriter, r *http.Request
return nil
}
// modelExists 为其他平台流程提供是否已进入 canonical 树的轻量查询。
func modelExists(ctx context.Context, tx *sql.Tx, project, workspace, board string) (bool, error) {
root, err := canonicalRoot(ctx, tx, project, workspace, board)
return root != "", err
@@ -1,3 +1,4 @@
// Canonical 生命周期综合回归:使用真实 HTTP 与隔离 PostgreSQL,覆盖迁移屏障和增量写入持久化。
package platform
import (
@@ -15,6 +16,8 @@ import (
"testing"
)
// TestCanonicalModelMigrationAndIncrementalLifecycle 从旧 frame 分区迁移开始,逐步验证稳定身份、局部版本、墓碑和逻辑去重。
// 依赖 PLATFORM_TEST_DATABASE_URL;后续各段沿用前段版本,失败应在最早断言处定位。
func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -58,6 +61,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
mux := http.NewServeMux()
Register(mux, db, map[string]string{project: "https://app.example.com/auth/callback"}, "https://api.example.com", nil)
base := "/projects/" + project + "/workspaces/" + workspace + "/materials/" + root + "/canvas"
// call 经完整认证路由发请求;read 则从模型表独立重建,避免只相信回执中的内存结果。
call := func(method, path string, input any, key string, status int) response {
t.Helper()
raw, _ := json.Marshal(input)
@@ -93,6 +97,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
}
return model
}
// GET 只返回迁移需求,不隐式分配身份;显式迁移成功后旧 HTTP/数据库快照写入都应被屏障拦住。
if call("GET", base+"/model", nil, "", 409)["error"] != "canonical_migration_required" {
t.Fatal("legacy read silently migrated")
}
@@ -136,6 +141,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
if _, err = db.ExecContext(ctx, `UPDATE materials SET canvas_document=$4,canvas_version=canvas_version+1 WHERE project=$1 AND workspace_id=$2 AND id=$3`, project, workspace, root, legacy); err == nil {
t.Fatal("database identity barrier allowed an old writer")
}
// 每个 edit 分配不同请求与逻辑操作 ID,预期版本由用例显式给出,避免辅助函数掩盖版本错误。
edit := func(n int, versions map[string]int64, changes ...modelChange) response {
t.Helper()
key := modelTestID(n)
@@ -164,6 +170,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("missing receipt claimed zero writes")
}
// Move is a row owner update, retaining ElementId and incarnation.
// 元素移动只改 owner 与几何,不能删除再新建或改变 incarnation。
geometry := model.Elements[nodeID]["geometry"]
edit(1002, map[string]int64{root: 2, child: 2}, modelChange{Kind: "field", Target: modelTarget{ID: nodeID, Incarnation: 1}, Field: "ownerCanvasId", Before: modelJSON(child), After: modelJSON(root)}, modelChange{Kind: "field", Target: modelTarget{ID: nodeID, Incarnation: 1}, Field: "geometry", Before: modelJSON(geometry), After: modelJSON(map[string]any{"x": 150, "y": 260, "width": 240, "height": 72, "rotation": 0})})
model = read()
@@ -171,6 +178,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("move recreated the element")
}
// Future component/envelope bytes survive editing another object and legacy projections.
// 不认识的组件/数据版本和 envelope 作为不透明 JSON 保留,不因生成兼容快照而丢失。
opaqueID := modelTestID(3000)
opaque := modelTestNode(opaqueID, root)
opaque["componentId"], opaque["dataVersion"], opaque["data"], opaque["futureEnvelope"] = "future.plugin", float64(9), map[string]any{"raw": []any{map[string]any{"keep": true}}}, map[string]any{"extension": "retained"}
@@ -184,6 +192,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
if model.Tombstones[nodeID] != 1 {
t.Fatal("delete did not persist its lifecycle tombstone")
}
// 恢复同 ID 需升级 incarnation,旧代回调得到确定拒绝且不得改动任何版本或旁观元素。
restored := modelTestNode(nodeID, root)
restored["componentId"] = "plain-text"
restored["incarnation"] = float64(2)
@@ -215,6 +224,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("initial read has no explicit coverage")
}
// Negotiate the same authenticated canonical read as a streamed transfer.
// 相同授权入口协商 NDJSON,头部版本与真实模型一致,末尾必须存在 complete。
streamRequest := httptest.NewRequest("GET", base+"/model", nil)
streamRequest.Header.Set("Authorization", "Bearer "+token)
streamRequest.Header.Set("Accept", modelStreamType)
@@ -225,6 +235,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("authenticated stream lost canonical snapshot coverage")
}
// An object created and removed inside one transaction still has a lifecycle fact.
// 同批创建又删除仍要留下墓碑和死记录,不能当作未发生而允许旧生命周期被再次接受。
ghostID := modelTestID(4000)
ghost := modelTestNode(ghostID, root)
edit(1008, map[string]int64{root: 6}, modelChange{Kind: "element", ID: ghostID, Before: modelJSON(nil), After: modelJSON(ghost)}, modelChange{Kind: "element", ID: ghostID, Before: modelJSON(ghost), After: modelJSON(nil)})
@@ -247,6 +258,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("expected-account barrier was ignored")
}
// A new partition's entry, owning canvas and versions publish atomically.
// 新画布以期望版本零参与,入口节点和树关系同批创建;归档/恢复保留版本围栏。
newCanvas, newFrame := modelTestID(5000), modelTestID(5001)
frame := modelTestNode(newFrame, root)
frame["componentId"] = "frame"
@@ -269,6 +281,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
}
// A cross-scale entry move writes ownership, child binding and presentation units together.
// 跨缩放移动同时更改 owner、geometry、presentation 单位元数据和孩子 Parent,内部成员记录应不变。
innerCanvas, innerFrame, memberID := modelTestID(5100), modelTestID(5101), modelTestID(5102)
container := modelTestNode(innerFrame, root)
container["componentId"] = "frame"
@@ -312,6 +325,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("scaled move inverse did not restore absent unit metadata and the original child binding")
}
// Several logical edits share one atomic request while retaining every deduplication identity.
// 多逻辑编辑共用一个事务和版本增量,但每个原操作 ID 都必须登记并禁止换请求键重放。
batchKey, firstLogical, secondLogical := modelTestID(1016), modelTestID(22001), modelTestID(22002)
batchVersion := model.Versions[innerCanvas]
batch := modelBatch{ProtocolVersion: 2, RequestID: batchKey, Expected: map[string]int64{innerCanvas: batchVersion}, Operations: []modelOperation{
@@ -336,6 +350,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
t.Fatal("a covered logical ID was executable under a new request key")
}
// A later failed condition cannot publish the earlier edit or consume its logical identity.
// 后一个 before 条件失败必须回滚先成功的内存前缀,也不能消费该前缀的逻辑操作 ID。
failedKey := modelTestID(1018)
batch.RequestID = failedKey
batch.Operations = []modelOperation{
@@ -355,6 +370,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
}
// A compacted wire projection retains prefix IDs with conditional no-ops, including in a child scope.
// 压缩后的 wire 批次用条件无操作保留前缀身份;只触及孩子版本且保留创建/删除生命周期事实。
projectedKey, guardLogical, effectLogical := modelTestID(1019), modelTestID(22005), modelTestID(22006)
projectedGhost := modelTestID(5200)
finalGhost := modelTestNode(projectedGhost, innerCanvas)
@@ -381,6 +397,7 @@ func TestCanonicalModelMigrationAndIncrementalLifecycle(t *testing.T) {
}
// A locally canceled incarnation was never sent; undo may first publish incarnation 2.
// 本地取消且从未发送的第一代没有服务端墓碑;首次发布第二代仍合法,旧代回调不可冒领。
locallyElidedID := modelTestID(5201)
locallyRestored := modelTestNode(locallyElidedID, innerCanvas)
locallyRestored["incarnation"] = float64(2)
@@ -1,3 +1,4 @@
// 将旧快照树显式迁入 canonical 模型,保存完整旧→新稳定身份映射,原输入文档保持不变。
package platform
import (
@@ -6,21 +7,27 @@ import (
"strings"
)
// modelIdentity 包含来源画布和结构类型,避免不同画布或 node/edge 同名时映射碰撞。
type modelIdentity struct {
SourceCanvasID string `json:"sourceCanvasId"`
Structure string `json:"structure"`
SourceID string `json:"sourceId"`
ElementID string `json:"elementId"`
}
// modelMigration 返回模型、身份映射和普通旧 frame 新生成的画布 ID,由外层事务一次保存。
type modelMigration struct {
Model canvasModel
Identities []modelIdentity
NewCanvases []string
}
// modelSpace 描述累积到根的平移/缩放,用于迁移曲线路径,不应用 viewport。
type modelSpace struct{ X, Y, Scale float64 }
// No source document is changed. IDs are allocated once inside the eventual
// migration transaction and the complete mapping is stored with its receipt.
// migrateCanvasModel 通过注入 allocate 分配一次性稳定 ID;重复或非法分配结果直接拒绝。
func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relations []subgraphRelation, allocate func() string) (modelMigration, error) {
result := modelMigration{Model: emptyModel(root), Identities: []modelIdentity{}, NewCanvases: []string{}}
documents, nodes := map[string]map[string]any{}, map[string]map[string]any{}
@@ -73,6 +80,7 @@ func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relati
}
}
}
// 已有独立子图保留画布 ID,入口节点换为新元素 ID;关系必须与快照 subgraph 一致。
for _, relation := range relations {
if relation.Archived {
continue
@@ -91,6 +99,7 @@ func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relati
result.Model.Canvases[relation.Child] = modelCanvas{ID: relation.Child, Parent: &modelParent{CanvasID: relation.Parent, EntryElementID: identities[identityKey(relation.Parent, "node", relation.Frame)]}}
}
// Ordinary legacy frameId groups also become actual canvases, even if empty.
// 没有独立子图的旧框也变成真实画布(包括空框),随后把显式 frameId 成员迁入。
for _, key := range sortedKeys(nodes) {
node := nodes[key]
data := node["data"].(map[string]any)
@@ -149,6 +158,7 @@ func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relati
if err != nil {
return result, err
}
// 解开最多八层旧 port 链,得到 canonical 真实元素端点;方向错误或循环均拒绝。
resolve := func(board, node, handle, direction string) (map[string]any, error) {
seen := map[string]bool{}
for depth := 0; depth <= 8; depth++ {
@@ -217,6 +227,8 @@ func migrateCanvasModel(root string, snapshots map[string]canvasSnapshot, relati
}
return result, nil
}
// modelContentScale 读取正展示缩放,缺省一;仅在迁移几何和路径空间计算时使用。
func modelContentScale(data map[string]any) float64 {
presentation, _ := data["presentation"].(map[string]any)
if scale, ok := presentation["contentScale"].(float64); ok && scale > 0 {
@@ -224,6 +236,8 @@ func modelContentScale(data map[string]any) float64 {
}
return 1
}
// legacyModelGeometry 为旧节点缺省尺寸补种类默认值,将 position/rotation 汇总到 canonical geometry。
func legacyModelGeometry(node map[string]any, kind string) map[string]any {
width, height := float64(260), float64(200)
switch kind {
@@ -247,6 +261,8 @@ func legacyModelGeometry(node map[string]any, kind string) map[string]any {
rotation, _ := data["rotation"].(float64)
return map[string]any{"x": position["x"], "y": position["y"], "width": width, "height": height, "rotation": rotation}
}
// modelSpaces 迭代从已知父空间求孩子累计空间,九轮仍未覆盖或无进展表示树无效。
func modelSpaces(model canvasModel) (map[string]modelSpace, error) {
result := map[string]modelSpace{model.Root: {Scale: 1}}
remaining := len(model.Canvases) - 1
+11
View File
@@ -1,3 +1,4 @@
// Canonical 模型持久化及旧快照投影;数据库模型表是权威来源,canvas_document 是内部兼容视图。
package platform
import (
@@ -8,6 +9,7 @@ import (
"sort"
)
// canonicalRoot 查询所属模型根,尚未迁移返回空字符串而非缺行错误。
func canonicalRoot(ctx context.Context, tx *sql.Tx, project, workspace, board string) (string, error) {
var root string
err := tx.QueryRowContext(ctx, `SELECT root_id::text FROM canvas_model_canvases WHERE project=$1 AND workspace_id=$2 AND canvas_id=$3`, project, workspace, board).Scan(&root)
@@ -16,6 +18,8 @@ func canonicalRoot(ctx context.Context, tx *sql.Tx, project, workspace, board st
}
return root, err
}
// loadCanvasModel 读取根下所有画布/元素,保留归档版本与删除记录,重建后执行完整模型校验。
func loadCanvasModel(ctx context.Context, tx *sql.Tx, project, workspace, root string) (canvasModel, error) {
model := emptyModel(root)
rows, err := tx.QueryContext(ctx, `SELECT canvas_id::text,parent_canvas_id::text,entry_element_id,version,archived FROM canvas_model_canvases WHERE project=$1 AND workspace_id=$2 AND root_id=$3 ORDER BY canvas_id`, project, workspace, root)
@@ -81,6 +85,8 @@ func loadCanvasModel(ctx context.Context, tx *sql.Tx, project, workspace, root s
// Only changed element rows are written. canvas_document is a compatibility
// projection for internal AI readers, never the source of a canonical GET/replay.
// saveCanvasModel 在调用方事务中写参与画布与真正变化的元素,更新所有权关系并同步兼容快照。
// 先按 canonical 稳定身份使 AI 目标失效,再开启事务级 canonical_writer 以通过数据库旧写入屏障。
func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspace, account string, before, after canvasModel, participants map[string]bool) error {
ctx := r.Context()
if err := invalidateCanonicalAIIdentities(r, tx, project, workspace, before, after); err != nil {
@@ -120,6 +126,7 @@ func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspac
return err
}
}
// 只更新变化记录;同项目元素 ID 已属于其他 workspace/root 时,受限 upsert 不覆盖并报冲突。
for _, id := range sortedKeys(after.Elements) {
element := after.Elements[id]
if modelEqual(before.Elements[id], element) && before.Tombstones[id] == after.Tombstones[id] {
@@ -139,6 +146,7 @@ func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspac
return errModelConflict
}
}
// 删除也持久保留最后记录及代数,后续恢复/去重不能把墓碑当成从未存在。
for _, id := range sortedKeys(after.Tombstones) {
if after.Elements[id] != nil || before.Elements[id] == nil && before.Tombstones[id] == after.Tombstones[id] {
continue
@@ -169,6 +177,7 @@ func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspac
}
}
}
// 先归档旧关系,再按祖先深度由外向内安装最终树,避免父入口变动时出现重复活跃关系。
canvases := sortedKeys(after.Canvases)
sort.SliceStable(canvases, func(i, j int) bool {
a, _ := modelAncestors(after, canvases[i])
@@ -202,6 +211,7 @@ func (s *service) saveCanvasModel(r *http.Request, tx *sql.Tx, project, workspac
return nil
}
// projectCanvasModel 为旧 AI reader 生成 v2 快照,只投影已知 v1 组件,未知组件仍完整保存在 canonical 表。
func projectCanvasModel(model canvasModel) (map[string]json.RawMessage, error) {
documents := map[string]map[string]any{}
for id := range model.Canvases {
@@ -251,6 +261,7 @@ func projectCanvasModel(model canvasModel) (map[string]json.RawMessage, error) {
owner := modelString(element["ownerCanvasId"])
documents[owner]["nodes"] = append(documents[owner]["nodes"].([]any), node)
}
// Canonical 连接直接指真实元素;投影时才沿祖先树生成旧式 frame/port 链,不能反向作为权威身份。
for _, id := range elements {
element := model.Elements[id]
if element["structure"] != "connection" || element["componentId"] != "connection" || modelInt(element["dataVersion"]) != 1 {
+5
View File
@@ -1,3 +1,4 @@
// Canonical 模型 NDJSON 传输:从已一致捕获的内存模型编码,不边读库边向慢客户端发送。
package platform
import (
@@ -11,6 +12,7 @@ const modelStreamType = "application/vnd.foundry.canvas-model+ndjson;version=1"
// The caller captures a coherent model while holding the workspace lock, then
// releases its transaction before writing. A slow reader must not hold a writer.
// This streams transfer/encoding; it does not stream database row acquisition.
// writeCanvasModelStream 发送 header、elements 批次和 complete,统一 token/sequence 供客户端检测截断或混流。
func writeCanvasModelStream(ctx context.Context, w http.ResponseWriter, model canvasModel) {
token := newModelID()
if token == "" {
@@ -19,6 +21,7 @@ func writeCanvasModelStream(ctx context.Context, w http.ResponseWriter, model ca
}
view := model.view(nil)
// A count covers direct members only; an empty canvas is explicit too.
// 头部显式声明每画布直接元素数、总数与身份 owner,空画布也必须覆盖。
counts := map[string]int{}
owners := map[string]string{}
for _, canvas := range view.Canvases {
@@ -45,6 +48,7 @@ func writeCanvasModelStream(ctx context.Context, w http.ResponseWriter, model ca
const maxBytes = 64 * 1024 * 1024
sequence, total := 0, 0
started := false
// 每行/总字节/记录数均有预算;开始前可写结构化错误,开始后只能停流让缺 complete 表示失败。
write := func(value response) bool {
if ctx.Err() != nil {
return false
@@ -78,6 +82,7 @@ func writeCanvasModelStream(ctx context.Context, w http.ResponseWriter, model ca
}
batch := []map[string]any{}
batchBytes := 0
// 批次最多 64 元素或约 512 KiB,单个大元素仍受统一 maxLine 限制。
flush := func() bool {
if len(batch) == 0 {
return true
@@ -1,3 +1,4 @@
// 模型/协议纯回归:用内存对象与 recorder 验证身份、原子变更或流传输契约,不访问真实数据库。
package platform
import (
@@ -9,6 +10,7 @@ import (
"testing"
)
// streamRecords 把 recorder 内每行 JSON 转为断言对象;用例中的小记录不需要增大 Scanner 缺省预算。
func streamRecords(t *testing.T, writer *httptest.ResponseRecorder) []response {
t.Helper()
var records []response
@@ -25,6 +27,8 @@ func streamRecords(t *testing.T, writer *httptest.ResponseRecorder) []response {
}
return records
}
// TestCanonicalModelStreamFramesAndSnapshot 用超过两个批次的元素验证 header/批次/complete 分帧,token、序号、墓碑和全元素 owner 清单必须一致且无重复漏项。
func TestCanonicalModelStreamFramesAndSnapshot(t *testing.T) {
model := modelTestDocument()
for i := 0; i < 129; i++ {
@@ -80,15 +84,19 @@ func TestCanonicalModelStreamFramesAndSnapshot(t *testing.T) {
}
}
// cancelStreamWriter 在首个 flush 后取消请求,用于验证已开始流的中途停止语义。
type cancelStreamWriter struct {
*httptest.ResponseRecorder
cancel context.CancelFunc
}
// Flush 先模拟实际输出,再取消,使下一次编码检测到上下文结束。
func (writer cancelStreamWriter) Flush() {
writer.ResponseRecorder.Flush()
writer.cancel()
}
// TestCanonicalModelStreamCancellationNeverClaimsCompletion 第一次 Flush 即取消上下文,验证仅发 header,不能追加 complete 或假成功尾记录。
func TestCanonicalModelStreamCancellationNeverClaimsCompletion(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
@@ -100,6 +108,7 @@ func TestCanonicalModelStreamCancellationNeverClaimsCompletion(t *testing.T) {
}
}
// TestCanonicalModelStreamDeclaresDirectScopeCountsIncludingEmptyCanvases 验证每个 scope 只计直接成员且显式保留零元素画布,未知 owner 必须在首次 Flush 前拒绝。
func TestCanonicalModelStreamDeclaresDirectScopeCountsIncludingEmptyCanvases(t *testing.T) {
model := modelTestDocument()
empty, nested := modelTestID(41), modelTestID(42)
@@ -124,6 +133,7 @@ func TestCanonicalModelStreamDeclaresDirectScopeCountsIncludingEmptyCanvases(t *
}
}
// TestCanonicalModelStreamRejectsAmbiguousIdentityManifest 构造空或重复内部元素 ID,验证不发布有歧义的身份清单,返回 500 且未开始流。
func TestCanonicalModelStreamRejectsAmbiguousIdentityManifest(t *testing.T) {
for _, id := range []string{"", "a"} {
model := modelTestDocument()
+22 -1
View File
@@ -1,3 +1,4 @@
// 模型/协议纯回归:用内存对象与 recorder 验证身份、原子变更或流传输契约,不访问真实数据库。
package platform
import (
@@ -17,15 +18,24 @@ const modelLegacyFrame = `{"id":"f","type":"frame","position":{"x":100,"y":200},
//go:embed testdata/foundry-model-operation-v2.json
var canonicalFrontendFixture []byte
// modelJSON 将测试值统一编码为 before/after 原始 JSON。
func modelJSON(value any) json.RawMessage { raw, _ := json.Marshal(value); return raw }
func modelTestID(n int) string { return fmt.Sprintf("90000000-0000-4000-8000-%012d", n) }
// modelTestID 生成确定 UUID,便于跨回归复用可预期的请求/操作/资源身份。
func modelTestID(n int) string { return fmt.Sprintf("90000000-0000-4000-8000-%012d", n) }
// modelTestAllocator 返回有独立计数器的分配器,让迁移身份分配可重复断言。
func modelTestAllocator() func() string {
next := 0
return func() string { next++; return modelTestID(next) }
}
// modelTestNode 构造最小有效 v1 text 节点,其嵌套 data/geometry 每次独立创建。
func modelTestNode(id, owner string) map[string]any {
return map[string]any{"id": id, "incarnation": float64(1), "ownerCanvasId": owner, "componentId": "text", "dataVersion": float64(1), "structure": "node", "data": map[string]any{"title": id, "text": "preserved"}, "geometry": map[string]any{"x": float64(0), "y": float64(0), "width": float64(260), "height": float64(200), "rotation": float64(0)}}
}
// modelTestDocument 提供版本一根画布和一个 a 节点的最小完整模型。
func modelTestDocument() canvasModel {
model := emptyModel(modelRootID)
model.Canvases[modelRootID] = modelCanvas{ID: modelRootID}
@@ -34,6 +44,7 @@ func modelTestDocument() canvasModel {
return model
}
// TestCanonicalFramesRetainRotationAcrossOwnerChanges 检查 canonical frame 跨 owner 后保留旋转、兼容投影和无关 AI patch 不抹角度,同时旧快照写契约仍拒绝旋转 frame。
func TestCanonicalFramesRetainRotationAcrossOwnerChanges(t *testing.T) {
model := modelTestDocument()
frame := modelTestNode("f", modelRootID)
@@ -97,6 +108,7 @@ func TestCanonicalFramesRetainRotationAcrossOwnerChanges(t *testing.T) {
}
}
// TestCanonicalMigrationResolvesCanvasLocalIdentitiesAndPorts 用父子同名节点证明迁移分配不同全局身份,并将端口边解析为真实子节点、推进版本屏障且保留输入快照。
func TestCanonicalMigrationResolvesCanvasLocalIdentitiesAndPorts(t *testing.T) {
root := `{"schema_version":2,"nodes":[{"id":"a","type":"plainText","position":{"x":0,"y":0},"width":240,"height":72,"data":{"kind":"plain-text","title":"parent","text":""}},{"id":"f","type":"frame","position":{"x":100,"y":200},"width":640,"height":400,"data":{"kind":"frame","title":"F","text":"","subgraph":{"boardId":"` + modelChildID + `"},"ports":[{"id":"p","nodeId":"a","handle":"right","direction":"output"}]}}],"edges":[{"id":"e","source":"f","sourceHandle":"port:p","target":"a","targetHandle":"left"}],"viewport":{"x":0,"y":0,"zoom":1}}`
child := `{"schema_version":2,"nodes":[{"id":"a","type":"plainText","position":{"x":10,"y":20},"width":240,"height":72,"data":{"kind":"plain-text","title":"child","text":""}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
@@ -133,6 +145,8 @@ func TestCanonicalMigrationResolvesCanvasLocalIdentitiesAndPorts(t *testing.T) {
}
}
}
// TestCanonicalMigrationTurnsImplicitFramesIntoOwningCanvases 验证旧 frameId 分区成为新画布,成员几何改为 owner 局部坐标且 data 中不再存第二份 frameId 所有权。
func TestCanonicalMigrationTurnsImplicitFramesIntoOwningCanvases(t *testing.T) {
root := `{"schema_version":1,"nodes":[` + modelLegacyFrame + `,{"id":"a","type":"plainText","position":{"x":150,"y":260},"width":240,"height":72,"data":{"kind":"plain-text","title":"a","text":"","frameId":"f"}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
result, err := migrateCanvasModel(modelRootID, map[string]canvasSnapshot{modelRootID: {BoardID: modelRootID, Version: 1, Document: json.RawMessage(root)}}, nil, modelTestAllocator())
@@ -156,6 +170,8 @@ func TestCanonicalMigrationTurnsImplicitFramesIntoOwningCanvases(t *testing.T) {
t.Fatal("second ownership fact leaked into canonical data")
}
}
// TestCanonicalOperationsPreserveOpaquePayloadAndStableMoveIdentity 移动已知元素 owner 时保留 ID,触及新旧画布,并原样保留未知组件数据及 envelope,输入模型不被修改。
func TestCanonicalOperationsPreserveOpaquePayloadAndStableMoveIdentity(t *testing.T) {
model := modelTestDocument()
frame := modelTestNode("f", modelRootID)
@@ -180,6 +196,8 @@ func TestCanonicalOperationsPreserveOpaquePayloadAndStableMoveIdentity(t *testin
t.Fatal("opaque payload or old snapshot was mutated")
}
}
// TestCanonicalDeleteRestoreRejectsOldIncarnation 删除产生墓碑,恢复升级 incarnation;旧代异步字段编辑不能命中新一代同 ID 元素。
func TestCanonicalDeleteRestoreRejectsOldIncarnation(t *testing.T) {
model := modelTestDocument()
deleted, _, err := applyModelOperations(model, []modelOperation{{ID: modelTestID(1), Changes: []modelChange{{Kind: "element", ID: "a", Before: modelJSON(model.Elements["a"]), After: modelJSON(nil)}}}})
@@ -200,6 +218,8 @@ func TestCanonicalDeleteRestoreRejectsOldIncarnation(t *testing.T) {
t.Fatal("old callback claimed the restored incarnation")
}
}
// TestCanonicalValidationRejectsPartialChangesAndWrongEdgeOwner 第二个变更失败时输入不变;另构造跨父子的连接却归孩子所有,要求最终模型校验拒绝。
func TestCanonicalValidationRejectsPartialChangesAndWrongEdgeOwner(t *testing.T) {
model := modelTestDocument()
before := modelJSON(model)
@@ -222,6 +242,7 @@ func TestCanonicalValidationRejectsPartialChangesAndWrongEdgeOwner(t *testing.T)
}
}
// TestCanonicalFrontendProtocolFixture 读取嵌入的前端协议样本,验证请求 envelope 与 reducer 兼容,且仅改变预期标题和一次版本。
func TestCanonicalFrontendProtocolFixture(t *testing.T) {
var input modelBatch
decoder := json.NewDecoder(bytes.NewReader(canonicalFrontendFixture))
+6
View File
@@ -1,3 +1,4 @@
// 旧快照操作协议 v1 的纯批处理器,canonical 模型协议 v2 使用另一套 before/after reducer。
package platform
import (
@@ -8,6 +9,7 @@ import (
const canvasOperationsProtocol = 1
// canvasOperation 表示节点/边创建、patch 或删除,元素 ID 与完整 Record 内 ID 必须一致。
type canvasOperation struct {
ID string `json:"id"`
Type string `json:"type"`
@@ -16,6 +18,8 @@ type canvasOperation struct {
Record json.RawMessage `json:"record,omitempty"`
Patch map[string]json.RawMessage `json:"patch,omitempty"`
}
// canvasOperationBatch 用请求键及参与画布版本表包裹有序操作,HTTP 编排负责授权和事务。
type canvasOperationBatch struct {
ProtocolVersion int `json:"protocol_version"`
RequestID string `json:"request_id"`
@@ -27,6 +31,7 @@ var errInvalidCanvasOperation = errors.New("invalid_canvas_operation")
// applyCanvasOperations stages a complete batch. Input snapshots are never mutated.
// HTTP/auth/version/idempotency are checked by the transaction coordinator.
// applyCanvasOperations 复制所有输入,执行完全部操作才统一 normalize 并各增一次版本,失败不返回部分结果。
func applyCanvasOperations(initial map[string]canvasSnapshot, operations []canvasOperation) (map[string]canvasSnapshot, error) {
if len(operations) == 0 || len(operations) > 2500 {
return nil, errInvalidCanvasOperation
@@ -96,6 +101,7 @@ func applyCanvasOperations(initial map[string]canvasSnapshot, operations []canva
if !allowed {
return nil, errInvalidCanvasOperation
}
// data 是逐键 merge(null 删除),几何等字段整体替换,避免位置 patch 覆盖其他已保存内容。
if field == "data" {
// Merge individual data fields; a geometry-only patch never rolls back titles/assets.
var before, patch map[string]json.RawMessage
@@ -1,3 +1,4 @@
// 旧无界面操作批次 HTTP 协调器,原子验证多快照并冻结成功/终局拒绝回执。
package platform
import (
@@ -11,6 +12,7 @@ import (
const canvasOperationsAction = "headless.operations.v1"
// submitCanvasOperations 严格验证协议和参与者,稳定取锁后先重放回执,再比较版本并执行纯批处理。
func (s *service) submitCanvasOperations(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -100,6 +102,7 @@ func (s *service) submitCanvasOperations(w http.ResponseWriter, r *http.Request,
snapshots := make([]canvasSnapshot, 0, len(participants))
versions := map[string]int64{}
// Validate all participant documents before writing any of them.
// 写快照前逐一验证所有权、AI 模型和资产;任一拒绝结束整个批次。
for _, id := range participants {
snapshot := staged[id]
valid, e := validateCanvasRelations(r, tx, project, workspace, id, initial[id].Document, snapshot.Document)
@@ -137,6 +140,7 @@ func (s *service) submitCanvasOperations(w http.ResponseWriter, r *http.Request,
// A terminal rejection also reserves the frozen key/body. Losing that response must
// not turn a definite zero-write result into a future execution of the same request.
// commitCanvasOperationReceipt 将应用或 terminal 拒绝写入七天回执,与本事务已做的变更一起提交。
func commitCanvasOperationReceipt(w http.ResponseWriter, r *http.Request, tx *sql.Tx, project, account, board string, input canvasOperationBatch, status int, body response, before []canvasSnapshot, versions map[string]int64) error {
var transactionID string
if err := tx.QueryRowContext(r.Context(), `SELECT gen_random_uuid()::text`).Scan(&transactionID); err != nil {
@@ -171,6 +175,7 @@ func commitCanvasOperationReceipt(w http.ResponseWriter, r *http.Request, tx *sq
return nil
}
// getCanvasOperation 查询本人请求的冻结结果,返回前重查回执内全部快照当前可读性,缺记录为 unknown。
func (s *service) getCanvasOperation(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
@@ -1,3 +1,4 @@
// 旧 headless 操作批次数据库回归:需要 PLATFORM_TEST_DATABASE_URL 指向隔离且已迁移测试库。
package platform
import (
@@ -17,6 +18,7 @@ import (
"testing"
)
// TestCanvasOperationsTransactions 检查应用/拒绝回执可恢复、同键同体重试、权限隔离及多画布批次整体回滚。
func TestCanvasOperationsTransactions(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -72,6 +74,7 @@ func TestCanvasOperationsTransactions(t *testing.T) {
Register(mux, db, map[string]string{project: "https://app.example.com/auth/callback"}, "https://api.example.com", nil)
path := "/projects/" + project + "/workspaces/" + workspace + "/materials/" + boards[0] + "/canvas/operations"
key := func(n int) string { return fmt.Sprintf("a0000000-0000-4000-8000-%012d", n) }
// do 执行真实路由,call 断言状态并解码,version 从数据库读取真实 canvas_version。
do := func(method, path, token string, input canvasOperationBatch) *httptest.ResponseRecorder {
encoded, _ := json.Marshal(input)
request := httptest.NewRequest(method, path, bytes.NewReader(encoded))
@@ -124,6 +127,7 @@ func TestCanvasOperationsTransactions(t *testing.T) {
t.Fatal("missing receipt must not claim terminal zero writes")
}
// Terminal zero-write responses must remain queryable and reserve their frozen body.
// 终局拒绝冻结原键和请求体,不能修正版本后沿用同一键让先前零效果变为实际执行。
stale := batch(3, 1)
rejected := call("POST", path, tokens[0], stale, 412)
proof := call("GET", path+"/"+key(3), tokens[0], canvasOperationBatch{}, 200)
@@ -135,6 +139,7 @@ func TestCanvasOperationsTransactions(t *testing.T) {
t.Fatal("rejected request performed a write")
}
// Concurrent exact retries serialize to one transaction and one version increment.
// 四条同键并发请求共享原回执,数据库版本只能前进一次。
concurrent := batch(4, 2)
var wait sync.WaitGroup
results := make(chan *httptest.ResponseRecorder, 4)
@@ -153,6 +158,7 @@ func TestCanvasOperationsTransactions(t *testing.T) {
t.Fatal("concurrent request executed more than once")
}
// A valid first participant and an invalid second participant produce no partial write.
// 首画布 patch 合法但次画布删除不存在节点,检查两者版本都不变且拒绝回执可查。
atomic := batch(5, 3)
atomic.ExpectedVersions[boards[1]] = 1
atomic.Operations = append(atomic.Operations, canvasOperation{ID: key(500), Type: "node.delete", CanvasID: boards[1], ElementID: "missing"})
@@ -1,3 +1,4 @@
// 模型/协议纯回归:用内存对象与 recorder 验证身份、原子变更或流传输契约,不访问真实数据库。
package platform
import (
@@ -7,6 +8,7 @@ import (
const operationsFixture = `{"schema_version":2,"nodes":[{"id":"a","type":"plainText","position":{"x":0,"y":0},"width":240,"height":72,"data":{"kind":"plain-text","title":"original","text":"hello"}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
// TestCanvasOperationBatchStagesAndMerges 连续执行 data 标题 patch 和位置 patch,验证无关文本保留、整批只加一次版本且输入 JSON 不变。
func TestCanvasOperationBatchStagesAndMerges(t *testing.T) {
initial := map[string]canvasSnapshot{"board": {BoardID: "board", Version: 7, Document: json.RawMessage(operationsFixture)}}
operations := []canvasOperation{
@@ -39,6 +41,8 @@ func TestCanvasOperationBatchStagesAndMerges(t *testing.T) {
t.Fatal("input snapshot mutated")
}
}
// TestCanvasOperationBatchRejectsWithoutPartialOutput 拒绝改 ID、缺目标及指向缺失节点的边,要求错误时不返回任何部分批次结果。
func TestCanvasOperationBatchRejectsWithoutPartialOutput(t *testing.T) {
initial := map[string]canvasSnapshot{"board": {BoardID: "board", Version: 1, Document: json.RawMessage(operationsFixture)}}
for _, operation := range []canvasOperation{
@@ -51,6 +55,8 @@ func TestCanvasOperationBatchRejectsWithoutPartialOutput(t *testing.T) {
}
}
}
// TestCanvasOperationBatchValidatesFinalGraphInsteadOfIntermediateState 先创建指向 b 的边再创建 b,验证只对整批最终图做引用校验。
func TestCanvasOperationBatchValidatesFinalGraphInsteadOfIntermediateState(t *testing.T) {
initial := map[string]canvasSnapshot{"board": {BoardID: "board", Version: 1, Document: json.RawMessage(operationsFixture)}}
operations := []canvasOperation{
+8
View File
@@ -1,3 +1,4 @@
// frame 子图扩展与普通快照的所有权守卫,防止绕开多画布事务改写关系。
package platform
import (
@@ -8,6 +9,8 @@ import (
"strings"
)
// validCanvasFrameExtensions 仅允许 v2 frame 携带子图、端口和折叠展示配置,检查形状与本地 ID 唯一性。
// 端口 nodeId 的跨文档存在性留给持锁关系命令验证。
func validCanvasFrameExtensions(d map[string]any, v2 bool) bool {
for _, key := range []string{"subgraph", "ports", "presentation"} {
value, exists := d[key]
@@ -74,6 +77,7 @@ func validCanvasFrameExtensions(d map[string]any, v2 bool) bool {
return true
}
// canvasNodeData 从已规范化文档提取 id→data;依赖节点形状已验证,不适合直接读取未校验请求。
func canvasNodeData(raw json.RawMessage) map[string]map[string]any {
var doc map[string]any
_ = json.Unmarshal(raw, &doc)
@@ -88,6 +92,7 @@ func canvasNodeData(raw json.RawMessage) map[string]map[string]any {
// Ordinary saves cannot create, replace, detach or retarget ownership/ports.
// Cross-board commands validate these changes while holding the workspace lock.
// validateCanvasRelations 在工作区锁下将新快照与数据库活跃子图关系比较,普通保存不得删除/换绑 frame 或端口。
func validateCanvasRelations(r *http.Request, tx *sql.Tx, project, workspace, board string, before, after json.RawMessage) (bool, error) {
old, next := canvasNodeData(before), canvasNodeData(after)
rows, err := tx.QueryContext(r.Context(), `SELECT frame_id,child_board_id::text FROM canvas_subgraphs WHERE project=$1 AND workspace_id=$2 AND parent_board_id=$3 AND archived_at IS NULL`, project, workspace, board)
@@ -115,6 +120,7 @@ func validateCanvasRelations(r *http.Request, tx *sql.Tx, project, workspace, bo
return false, nil
}
}
// 新增伪子图、无关系的非空端口,或把本地图节点挂进已拥有独立子画布的 frame 都拒绝。
for id, d := range next {
if sub, exists := d["subgraph"]; exists {
m, _ := sub.(map[string]any)
@@ -130,6 +136,7 @@ func validateCanvasRelations(r *http.Request, tx *sql.Tx, project, workspace, bo
}
}
// A child node referenced by its parent's ports must not disappear or change kind.
// 若当前画布是孩子,还要保持父端口引用的节点存在且种类不变;无父关系则无需此检查。
var parentRaw json.RawMessage
err = tx.QueryRowContext(r.Context(), `SELECT m.canvas_document FROM canvas_subgraphs s JOIN materials m ON m.project=s.project AND m.workspace_id=s.workspace_id AND m.id=s.parent_board_id WHERE s.project=$1 AND s.workspace_id=$2 AND s.child_board_id=$3 AND s.archived_at IS NULL`, project, workspace, board).Scan(&parentRaw)
if err == sql.ErrNoRows {
@@ -155,6 +162,7 @@ func validateCanvasRelations(r *http.Request, tx *sql.Tx, project, workspace, bo
return true, nil
}
// validCanvasPortHandle 接受四个基础方向,或指向另一个已命名端口的 port:<id>。
func validCanvasPortHandle(value any) bool {
if canvasChoice(value, "top", "right", "bottom", "left") {
return true
+8
View File
@@ -1,3 +1,4 @@
// 画布与资产纯函数回归;测试说明对应实际断言,不依赖浏览器或真实模型。
package platform
import (
@@ -6,8 +7,10 @@ import (
"testing"
)
// canvasFixture 同时供多组回归使用:含中文文本、脚本、不可连线图标及临时 selected。
const canvasFixture = `{"schema_version":1,"nodes":[{"id":"a","type":"material","position":{"x":100,"y":200},"width":320,"height":220,"selected":true,"data":{"kind":"text","title":"灵感笔记","text":"正文","rotation":30,"fontSize":24,"textStyle":{"color":"#37352f","background":"transparent","bold":true,"italic":false,"underline":false,"align":"left","fontFamily":"sans","lineHeight":1.5}}},{"id":"b","type":"material","position":{"x":0,"y":0},"data":{"kind":"script","title":"Script","text":""}},{"id":"icon","type":"icon","position":{"x":500,"y":200},"width":80,"height":80,"data":{"kind":"icon","title":"火箭","text":"","icon":"Rocket","rotation":0}}],"edges":[{"id":"e","source":"a","target":"b","sourceHandle":"top","targetHandle":"bottom"}],"viewport":{"x":0,"y":0,"zoom":1}}`
// TestCanvasValidation 从合法快照逐项破坏类型、范围、引用和版本,检查临时 selected 不落库以及必需文档结构。
func TestCanvasValidation(t *testing.T) {
out, ok := normalizeCanvas(json.RawMessage(canvasFixture))
if !ok || strings.Contains(string(out), "selected") {
@@ -27,6 +30,8 @@ func TestCanvasValidation(t *testing.T) {
}
}
}
// TestSlugValidation 检查小写连字符别名可用,拒绝空值、空格大写、路径穿越和超长别名。
func TestSlugValidation(t *testing.T) {
for _, v := range []string{"my-board", "workspace-2026"} {
if !validSlug(&v) {
@@ -41,8 +46,10 @@ func TestSlugValidation(t *testing.T) {
}
// Frame nodes follow the frontend contract: membership is data, not containment.
// frameFixture 把重叠的 outside 留在框外,以区分几何包含与显式 frameId 成员关系。
const frameFixture = `{"schema_version":1,"nodes":[{"id":"text","type":"material","position":{"x":100,"y":100},"data":{"kind":"text","title":"成员","text":"正文","frameId":"frame"}},{"id":"plain","type":"plainText","position":{"x":0,"y":0},"data":{"kind":"plain-text","title":"纯文本","text":"文字","frameId":"frame"}},{"id":"icon","type":"icon","position":{"x":10,"y":10},"data":{"kind":"icon","title":"图标","text":"","icon":"Star","frameId":"frame"}},{"id":"frame","type":"frame","position":{"x":0,"y":0},"width":600,"height":400,"zIndex":-1,"style":{"width":600,"height":400,"pointerEvents":"none"},"data":{"kind":"frame","title":"框选区","text":"","rotation":0,"labelMode":"fixed"}},{"id":"outside","type":"material","position":{"x":100,"y":100},"data":{"kind":"script","title":"重叠但未加入","text":""}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
// TestCanvasFrames 检查三种标签模式、显式成员关系、临时渲染字段剔除;框不可旋转/嵌套为成员,v1 边不可连到框。
func TestCanvasFrames(t *testing.T) {
for _, mode := range []string{"hidden", "fixed", "scaled"} {
t.Run(mode, func(t *testing.T) {
@@ -89,6 +96,7 @@ func TestCanvasFrames(t *testing.T) {
}
}
// TestCanvasPlainImages 验证 v1 plainImage 的类型与源地址契约,以及显式 frameId;v1 下纯图片不能作为连线端点。
func TestCanvasPlainImages(t *testing.T) {
fixture := `{"schema_version":1,"nodes":[{"id":"photo","type":"plainImage","position":{"x":20,"y":30},"width":320,"height":240,"data":{"kind":"plain-image","title":"Photo","text":"","src":"https://example.com/photo.png","rotation":30,"frameId":"frame"}},{"id":"frame","type":"frame","position":{"x":0,"y":0},"width":640,"height":400,"data":{"kind":"frame","title":"Frame","text":"","labelMode":"fixed"}}],"edges":[],"viewport":{"x":0,"y":0,"zoom":1}}`
if _, ok := normalizeCanvas(json.RawMessage(fixture)); !ok {
+8
View File
@@ -1,3 +1,4 @@
// 旧多画布事务撤销:校验回执有效性与当前后态,恢复文档/关系并创建独立幂等撤销回执。
package platform
import (
@@ -7,6 +8,7 @@ import (
"strings"
)
// undoCanvasTransaction 只支持列出的子图/连接动作,过期或已撤销回执不可再次执行。
func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -91,6 +93,7 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
if err = json.Unmarshal(relationsRaw, &changes); err != nil {
return err
}
// 归档孩子无法按普通素材路径授权,需通过其当前父画布验证编辑权限;关系必须仍等于原 After。
archivedParticipants := map[string]bool{}
for _, change := range changes {
actual, err := readSubgraphRelation(r, tx, project, workspace, change.After.Child)
@@ -122,6 +125,7 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
if err = json.Unmarshal(afterResponse, &recorded); err != nil {
return err
}
// 从原响应的不同形态收集操作后文档,用内容相等而非原版本号判断是否仍可安全栈式撤销。
afterStates := map[string]json.RawMessage{}
if recorded.Parent.BoardID != "" {
afterStates[recorded.Parent.BoardID] = recorded.Parent.Document
@@ -153,12 +157,14 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
reject(w, 428, "version_required")
return nil
}
// 客户端确认当前版本,服务端还确认当前内容等于原后态,防止覆盖后续独立编辑。
if expected != snapshot.Version || !sameCanvasDocument(snapshot.Document, afterStates[id]) {
reject(w, 412, "version_conflict")
return nil
}
current[id] = snapshot
}
// 全部参与者校验完再恢复关系与快照;版本以当前值加一推进,绝不倒退到历史版本。
for _, change := range changes {
if err = writeSubgraphRelation(r, tx, project, workspace, change.Before); err != nil {
return err
@@ -176,6 +182,7 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
updated = append(updated, snapshot)
appliedVersions[snapshot.BoardID] = snapshot.Version
}
// 原操作前不存在的孩子不删除,归档并使旧版本失效,保留完整数据供恢复。
archived := []string{}
for id, snapshot := range current {
if beforeIDs[id] {
@@ -223,6 +230,7 @@ func (s *service) undoCanvasTransaction(w http.ResponseWriter, r *http.Request,
return nil
}
// sameCanvasDocument 解码后重编码比较摘要,忽略 JSON 对象键顺序,无法解码时明确不相等。
func sameCanvasDocument(a, b json.RawMessage) bool {
var first, second any
if json.Unmarshal(a, &first) != nil || json.Unmarshal(b, &second) != nil {
+8
View File
@@ -1,3 +1,4 @@
// schema v2 的协商、点与边扩展校验;这些纯检查被快照、连接和事务命令复用。
package platform
import (
@@ -9,6 +10,7 @@ import (
"strings"
)
// canvasSchema 只读取版本字段,无法解码时返回零;不能替代 normalizeCanvas 的完整验证。
func canvasSchema(raw json.RawMessage) int {
var d struct {
Version int `json:"schema_version"`
@@ -17,6 +19,7 @@ func canvasSchema(raw json.RawMessage) int {
return d.Version
}
// acceptsCanvasV2 逐项解析 Accept 媒体类型,要求明确 version=2,且存在 q 时必须在 (0,1]。
func acceptsCanvasV2(r *http.Request) bool {
for _, value := range strings.Split(r.Header.Get("Accept"), ",") {
typ, params, err := mime.ParseMediaType(strings.TrimSpace(value))
@@ -33,11 +36,13 @@ func acceptsCanvasV2(r *http.Request) bool {
return false
}
// canvasPoint 要求完整 x/y 与有限百万坐标范围,供贝塞尔控制点和结点偏移使用。
func canvasPoint(v any) bool {
p, ok := v.(map[string]any)
return ok && canvasFields(p, "x", "y") && canvasNumber(p["x"], -1e6, 1e6) && canvasNumber(p["y"], -1e6, 1e6)
}
// validCanvasEdgeData 分别检查外观、动画、执行开关和贝塞尔链;省略分组合法,出现时拒绝未知键。
func validCanvasEdgeData(v any) bool {
d, ok := v.(map[string]any)
if !ok || !canvasFields(d, "appearance", "animation", "path", "execution") {
@@ -117,6 +122,7 @@ func validCanvasEdgeData(v any) bool {
}
}
case "execution":
// 执行事件是否启用与展示动画独立,协议只允许布尔 enabled。
if !canvasFields(m, "enabled") {
return false
}
@@ -126,6 +132,7 @@ func validCanvasEdgeData(v any) bool {
}
}
case "path":
// 路径仅支持 bezier-chain,最多 64 个唯一 ID 的 knot,每个 knot 有位置与进/出切线。
if !canvasFields(m, "type", "startControl", "endControl", "knots") || m["type"] != "bezier-chain" {
return false
}
@@ -157,6 +164,7 @@ func validCanvasEdgeData(v any) bool {
if !canvasChoice(knot["mode"], "corner", "smooth", "symmetric") {
return false
}
// smooth 要求非零切线反向共线;symmetric 进一步要求长度相等,使用相对误差容忍浮点噪声。
if knot["mode"] != "corner" {
a, b := knot["in"].(map[string]any), knot["out"].(map[string]any)
ax, ay, bx, by := a["x"].(float64), a["y"].(float64), b["x"].(float64), b["y"].(float64)
+5
View File
@@ -1,3 +1,4 @@
// 画布与资产纯函数回归;测试说明对应实际断言,不依赖浏览器或真实模型。
package platform
import (
@@ -10,6 +11,7 @@ import (
"testing"
)
// TestCanvasV2EdgeRoundTrip 保存带外观、动画、曲线和执行配置的 v2 边,并逐项破坏范围/枚举/切线关系,验证不丢字段且拒绝非法配置。
func TestCanvasV2EdgeRoundTrip(t *testing.T) {
raw := strings.Replace(canvasFixture, `"schema_version":1`, `"schema_version":2`, 1)
data := `{"appearance":{"color":"#AA968B","width":2,"opacity":1,"line":"dashed","head":{"type":"triangle","size":12,"filled":true},"tail":{"type":"circle","size":8,"filled":false}},"animation":{"mode":"executing","effect":"flow","direction":"reverse","durationMs":1600,"color":"#FFFFFF"},"path":{"type":"bezier-chain","startControl":{"x":90,"y":0},"endControl":{"x":-90,"y":0},"knots":[{"id":"k1","position":{"x":450,"y":280},"in":{"x":-60,"y":0},"out":{"x":60,"y":0},"mode":"symmetric"}]},"execution":{"enabled":true}}`
@@ -39,6 +41,7 @@ func TestCanvasV2EdgeRoundTrip(t *testing.T) {
}
}
// TestCanvasSchemaAccept 验证媒体类型列表中的显式 version=2 协商,拒绝 q=0、NaN 和相似但不同的版本号。
func TestCanvasSchemaAccept(t *testing.T) {
for _, tc := range []struct {
accept string
@@ -59,6 +62,7 @@ func TestCanvasSchemaAccept(t *testing.T) {
}
}
// TestCanvasV2CurveLimits 检查 64 个 knot 的边界、重复 knot ID 及非有限/越界点;直接构造 float64 覆盖 JSON 不表示的 NaN。
func TestCanvasV2CurveLimits(t *testing.T) {
knot := func(id string) map[string]any {
return map[string]any{"id": id, "position": map[string]any{"x": 0.0, "y": 0.0}, "in": map[string]any{"x": -1.0, "y": 0.0}, "out": map[string]any{"x": 1.0, "y": 0.0}, "mode": "smooth"}
@@ -86,6 +90,7 @@ func TestCanvasV2CurveLimits(t *testing.T) {
}
}
// TestCanvasV2AppearanceAndAnimationEnums 遍历受支持标记/线型与动画模式/效果/方向的组合,保证合法枚举组合可被接受。
func TestCanvasV2AppearanceAndAnimationEnums(t *testing.T) {
for _, marker := range []string{"none", "open-arrow", "triangle", "circle", "diamond", "square"} {
for _, line := range []string{"solid", "dashed", "dotted"} {
+19
View File
@@ -1,3 +1,4 @@
// 素材内容 schema v1 的纯校验与规范化,不负责网络抓图或数据库存储。
package platform
import (
@@ -8,32 +9,43 @@ import (
"regexp"
)
// Paragraph 与 Section 的 ID 在同一文章内共享唯一命名空间,用于稳定引用内容块。
type Paragraph struct {
ID string `json:"id"`
Text string `json:"text"`
Description string `json:"description,omitempty"`
}
// Section 聚合标题、描述和有序段落;数量及总段落预算由 validArticle 检查。
type Section struct {
ID string `json:"id"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
Paragraphs []Paragraph `json:"paragraphs"`
}
// Article 是有序章节容器,可为空文章,但必须有非 nil 的 Article 对象。
type Article struct {
Sections []Section `json:"sections"`
}
// Image 仅保存 HTTPS 引用及展示信息,尺寸零值表示未提供,不在这里读取远程资源。
type Image struct {
URL string `json:"url"`
Alt string `json:"alt,omitempty"`
Width int `json:"width,omitempty"`
Height int `json:"height,omitempty"`
}
// CardPart 是带 Kind 的互斥联合,一次只能提供对应的 text/article/image 内容。
type CardPart struct {
Kind string `json:"kind"`
Text *string `json:"text,omitempty"`
Article *Article `json:"article,omitempty"`
Image *Image `json:"image,omitempty"`
}
// Content 按素材种类使用互斥字段;board 只存 schema 标记,画布节点通过专用协议管理。
type Content struct {
SchemaVersion int `json:"schema_version"`
Text *string `json:"text,omitempty"`
@@ -44,6 +56,7 @@ type Content struct {
var blockID = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)
// validArticle 限制章节、段落和文本字节数,并用一个 seen 集合拒绝章节/段落间任何重复 ID。
func validArticle(article *Article) bool {
if article == nil || len(article.Sections) > 200 {
return false
@@ -68,6 +81,8 @@ func validArticle(article *Article) bool {
}
return true
}
// validImage 校验 URL、替代文本及尺寸范围;拒绝用户名密码和 fragment,不执行资源可达性检查。
func validImage(image *Image) bool {
if image == nil || len(image.URL) > 2048 || len(image.Alt) > 2000 || image.Width < 0 || image.Width > 100000 || image.Height < 0 || image.Height > 100000 {
return false
@@ -75,6 +90,8 @@ func validImage(image *Image) bool {
u, err := url.Parse(image.URL)
return err == nil && u.Scheme == "https" && u.Hostname() != "" && u.User == nil && u.Fragment == ""
}
// validPart 按判别字段检查唯一有效分支,额外的异类内容即使本身合法也会被拒绝。
func validPart(part CardPart) bool {
switch part.Kind {
case "text":
@@ -87,6 +104,8 @@ func validPart(part CardPart) bool {
return false
}
}
// normalizeContent 严格解码单个对象,将缺省版本补为一,并重编码为统一存储形式。
func normalizeContent(kind string, raw json.RawMessage) (json.RawMessage, bool) {
if raw = bytes.TrimSpace(raw); len(raw) == 0 || raw[0] != '{' {
return nil, false
+2
View File
@@ -1,3 +1,4 @@
// 内容 schema 的纯函数回归,不访问数据库或远程图片。
package platform
import (
@@ -5,6 +6,7 @@ import (
"testing"
)
// TestContentValidation 按素材种类检查合法草稿、重复块 ID、未知字段/版本、图片 URL 和互斥内容,并检查规范化输出仍为合法 JSON。
func TestContentValidation(t *testing.T) {
cases := []struct {
name, kind, body string
+4
View File
@@ -1,7 +1,9 @@
// 素材显式授权由有效 admin 管理;授权写入与撤销都先取得相同的工作区/素材权限锁。
package platform
import "net/http"
// materialGrants 返回最多一千条显式授权,或按账户 upsert editor/viewer;不允许授予素材 admin。
func (s *service) materialGrants(w http.ResponseWriter, r *http.Request, project, account string) error {
workspace, material := r.PathValue("workspace"), r.PathValue("material")
if r.Method != http.MethodGet && r.Method != http.MethodPost {
@@ -65,6 +67,8 @@ ON CONFLICT(project,workspace_id,material_id,account_id) DO UPDATE SET role=EXCL
reply(w, 204, nil)
return nil
}
// deleteMaterialGrant 幂等撤销目标账户的素材授权;不存在也返回 204,工作区成员权限不受此操作影响。
func (s *service) deleteMaterialGrant(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
+14
View File
@@ -1,3 +1,4 @@
// Package platform 提供项目隔离的工作区、素材、画布和协作 API;HTTP 认证与业务事务分层处理。
package platform
import (
@@ -17,6 +18,7 @@ import (
"github.com/jackc/pgx/v5/pgconn"
)
// service 共享连接池与启动配置;canvasAI 可缺省,队列仅在配置了客户端时启动。
type service struct {
canvasAI *codex.CanvasClient
db *sql.DB
@@ -25,8 +27,10 @@ type service struct {
onboardingConfigs map[string]OnboardingConfig
}
// response 用于小型 JSON 对象;大型画布文档通常保留 RawMessage 避免重编码字段。
type response map[string]any
// reply 写出 JSON 与 no-store;value 为 nil 时只写状态,供 204 响应使用。
func reply(w http.ResponseWriter, status int, value any) {
w.Header().Set("Content-Type", "application/json")
w.Header().Set("Cache-Control", "no-store")
@@ -36,10 +40,12 @@ func reply(w http.ResponseWriter, status int, value any) {
}
}
// reject 用稳定错误码表示可预期业务拒绝;调用者随后返回 nil,避免 protected 重复响应。
func reject(w http.ResponseWriter, status int, code string) {
reply(w, status, response{"error": code})
}
// decode 对普通业务 JSON 限制 1 MiB,拒绝未知字段以及第二个 JSON 值;失败已经写出 400。
func decode(w http.ResponseWriter, r *http.Request, value any) bool {
decoder := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20))
decoder.DisallowUnknownFields()
@@ -54,8 +60,10 @@ func decode(w http.ResponseWriter, r *http.Request, value any) bool {
return true
}
// endpoint 接收已认证的 project/account;具体资源可见性仍由业务处理器在事务内校验。
type endpoint func(http.ResponseWriter, *http.Request, string, string) error
// protected 是统一路由包装:项目白名单/CORS、会话续期、资源别名解析、canonical 写入守卫和错误映射。
func (s *service) protected(callbacks map[string]string, handle endpoint) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
project := r.PathValue("project")
@@ -74,6 +82,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
w.Header().Set("Access-Control-Allow-Origin", origin)
w.Header().Set("Access-Control-Expose-Headers", "ETag, X-Canvas-Schema-Version, "+auth.SessionExpiryHeader)
}
// 预检只验证项目和 Origin,不要求 bearer;真正业务请求仍必须通过会话认证。
if r.Method == http.MethodOptions {
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type, If-Match, Idempotency-Key, X-Expected-Account, X-Resource-Id")
@@ -88,11 +97,13 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
account := session.AccountID
if err == nil {
auth.WriteSessionHeaders(w, session)
// 客户端可携带预期账户,阻止浏览器切换身份后把旧页面的写入落到新账户。
if expected := r.Header.Get("X-Expected-Account"); expected != "" && expected != account {
reject(w, 409, "identity_changed")
return
}
}
// 将 slug 或 UUID 统一为 UUID 后再分派,后续 SQL 无需兼容两种引用;这一步不替代资源授权。
if err == nil && r.PathValue("workspace") != "" {
var id string
err = s.db.QueryRowContext(r.Context(), "SELECT id::text FROM workspaces WHERE project=$1 AND (id::text=$2 OR slug=$2)", project, r.PathValue("workspace")).Scan(&id)
@@ -117,6 +128,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
if err == nil {
err = handle(w, r, project, account)
}
// 只公开可识别的约束/领域错误;其余依赖错误记录类型并统一返回 503。
if err != nil {
var pg *pgconn.PgError
switch {
@@ -140,6 +152,7 @@ func (s *service) protected(callbacks map[string]string, handle endpoint) http.H
}
}
// Register 由 main 装配平台路径;私有 AI 客户端存在时启动进程级队列,公开短链接单独处理。
func Register(mux *http.ServeMux, db *sql.DB, callbacks map[string]string, origin string, configs map[string]OnboardingConfig, clients ...*codex.CanvasClient) {
s := &service{db: db, origin: origin, callbacks: callbacks, onboardingConfigs: configs}
if len(clients) > 0 {
@@ -198,6 +211,7 @@ func Register(mux *http.ServeMux, db *sql.DB, callbacks map[string]string, origi
var usernamePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]{2,39}$`)
// profile 只操作当前项目的本人账户;PATCH 规范化用户名后与 GET 共用完整资料响应。
func (s *service) profile(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method == http.MethodPatch {
var input struct {
+29
View File
@@ -1,3 +1,5 @@
// 平台综合数据库回归:需要 PLATFORM_TEST_DATABASE_URL 指向已迁移的隔离测试库,缺省会跳过。
// 使用随机项目和真实 HTTP handler 覆盖权限、版本、子图事务与资源生命周期,不连接真实 OAuth 或邮件服务。
package platform
import (
@@ -27,6 +29,8 @@ import (
_ "github.com/jackc/pgx/v5/stdlib"
)
// TestOnboardingAndSharing 是跨模块流程测试,后续画布/资产/邮箱检查复用最初创建的三个账户。
// tokens[0] 为所有者,tokens[1] 经邀请成为 viewer,tokens[2] 只按阶段授予局部素材权限。
func TestOnboardingAndSharing(t *testing.T) {
dsn := os.Getenv("PLATFORM_TEST_DATABASE_URL")
if dsn == "" {
@@ -60,6 +64,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
tokens = append(tokens, token)
}
// 按引用关系先删除资产绑定、事务和子图,再删除工作区/账户,避免回归数据残留。
defer func() {
_, _ = db.ExecContext(ctx, "DELETE FROM canvas_asset_bindings WHERE project=$1", project)
_, _ = db.ExecContext(ctx, "DELETE FROM canvas_assets WHERE project=$1", project)
@@ -79,6 +84,7 @@ func TestOnboardingAndSharing(t *testing.T) {
Register(mux, db, callbacks, "https://api.example.com", map[string]OnboardingConfig{
project: {RequireWorkspace: true, Questions: []Question{{Key: "purpose", Required: true}}},
})
// call 在内存 recorder 上走真实路由;可选参数依次代表 If-Match、Accept 和幂等键。
call := func(method, path, token string, body any, status int, versions ...string) response {
t.Helper()
encoded, err := json.Marshal(body)
@@ -111,6 +117,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
return out
}
// 首段验证引导重试不重复建工作区,以及分享次数、重复兑换、owner 不可降级和撤销效果。
base := "/projects/" + project
call("GET", base+"/workspaces", "", nil, 401)
call("POST", base+"/onboarding", tokens[0], response{"answers": response{}}, 400)
@@ -145,6 +152,7 @@ func TestOnboardingAndSharing(t *testing.T) {
contentShare := call("POST", workspacePath+"/shares", tokens[0], response{"role": "editor", "material_id": material}, 201)
call("POST", base+"/shares/redeem", tokens[2], response{"token": contentShare["token"]}, 200)
call("GET", workspacePath, tokens[2], nil, 404)
// 素材局部授权不授予工作区可见性;随后验证 viewer/editor 区别与 If-Match 防止旧版本覆盖。
articleContent := response{"schema_version": 1, "article": response{"sections": []any{response{
"id": "chapter-1", "title": "Chapter", "description": "Chapter summary", "paragraphs": []any{response{"id": "p1", "text": "Paragraph", "description": "Paragraph summary"}},
}}}}
@@ -173,6 +181,7 @@ func TestOnboardingAndSharing(t *testing.T) {
board := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Board", "content": response{}}, 201)
boardPath := workspacePath + "/materials/" + board["id"].(string)
// 画布快照版本与素材元数据版本相互独立,保存/改名各自只推进对应版本。
canvasPath := boardPath + "/canvas"
empty := call("GET", canvasPath, tokens[0], nil, 200)
if empty["version"] != float64(1) {
@@ -221,6 +230,7 @@ func TestOnboardingAndSharing(t *testing.T) {
// Restore the material version expected by the pre-existing layout checks below.
// Exercise two independent HTTP transactions against the same expected version.
// 同一旧版本的两个并发保存必须一成一败,不能都成功或出现部分持久化。
encodedSnapshot, _ := json.Marshal(snapshot)
statuses := make(chan int, 2)
start := make(chan struct{})
@@ -253,6 +263,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
// Frames round-trip through PostgreSQL with all label modes and explicit memberships.
// 三种框标签模式逐次落库并回读;失效成员引用必须拒绝且不推进版本。
for index, mode := range []string{"hidden", "fixed", "scaled"} {
version := strconv.Itoa(4 + index)
raw := strings.Replace(frameFixture, `"labelMode":"fixed"`, `"labelMode":"`+mode+`"`, 1)
@@ -304,6 +315,7 @@ func TestOnboardingAndSharing(t *testing.T) {
// Subgraph creation is atomic and idempotent, and cannot be undone by
// a stale or legacy whole-document save.
// 子图创建将文档、子素材、关系和事务回执原子保存;同键重放只返回原结果,不再递增版本。
subBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Subgraphs", "content": response{}}, 201)
subPath := workspacePath + "/materials/" + subBoard["id"].(string) + "/canvas"
accept := "application/vnd.foundry.canvas+json;version=2"
@@ -367,6 +379,7 @@ func TestOnboardingAndSharing(t *testing.T) {
call("POST", dissolveUndoPath, tokens[0], response{"expected_versions": map[string]int64{subBoard["id"].(string): 3, childID: 2}}, 200, "", accept, "88888888-8888-4888-8888-888888888888")
call("GET", childPath, tokens[0], nil, 200, "", accept)
// 旧框迁移先 dry-run 生成计划,陈旧计划不得留下孤儿素材;执行与撤销都验证幂等回执。
migrationBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Legacy migration", "content": response{}}, 201)
migrationPath := workspacePath + "/materials/" + migrationBoard["id"].(string) + "/canvas"
call("PATCH", migrationPath, tokens[0], response{"document": json.RawMessage(legacyMigrationFixture)}, 200, `"1"`)
@@ -423,6 +436,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
parentID := migrationBoard["id"].(string)
memberPath := migrationPath + "/subgraphs/f/members"
// 多画布移动携带完整预期版本及来源局部坐标,要求节点所有权、几何位置和撤销一起生效。
moveCommand := response{"source_board_id": membersSource, "target_board_id": membersTarget, "node_ids": []string{"a"}, "positions": map[string]memberDropPosition{"a": {X: 40, Y: 50}}, "expected_versions": map[string]int64{parentID: 5, membersSource: 1, membersTarget: 1}}
call("POST", memberPath, tokens[0], response{"source_board_id": membersSource, "target_board_id": membersTarget, "node_ids": []string{"a"}, "positions": response{"wrong": response{"x": 1, "y": 2}}, "expected_versions": map[string]int64{parentID: 5, membersSource: 1, membersTarget: 1}}, 400, "", accept, "eeeeeeee-1111-4111-8111-111111111111")
movedMembers := call("POST", memberPath, tokens[0], moveCommand, 200, "", accept, "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb")
@@ -448,6 +462,7 @@ func TestOnboardingAndSharing(t *testing.T) {
parentMove := call("POST", memberPath, tokens[0], response{"source_board_id": parentID, "target_board_id": membersSource, "node_ids": []string{"outside"}, "expected_versions": map[string]int64{parentID: 7, membersSource: 3}}, 200, "", accept, "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee")
call("POST", migrationPath+"/transactions/"+parentMove["transaction_id"].(string)+"/undo", tokens[0], response{"expected_versions": map[string]int64{parentID: 8, membersSource: 4}}, 200, "", accept, "ffffffff-ffff-4fff-8fff-ffffffffffff")
innerCreated := call("POST", sourceCanvasPath+"/subgraphs", tokens[0], response{"frame": response{"id": "inner-frame", "title": "Inner", "position": response{"x": 20, "y": 40}, "width": 400, "height": 300, "labelMode": "fixed"}}, 201, `"5"`, accept, "10000000-0000-4000-8000-000000000001")
// 移动包含子图的框必须重挂原子图关系,而非复制孩子;撤销要恢复原父级。
innerID := innerCreated["child_board"].(map[string]any)["id"].(string)
nestedMove := call("POST", memberPath, tokens[0], response{"source_board_id": membersSource, "target_board_id": membersTarget, "node_ids": []string{"inner-frame"}, "expected_versions": map[string]int64{parentID: 9, membersSource: 6, membersTarget: 3, innerID: 1}}, 200, "", accept, "10000000-0000-4000-8000-000000000002")
var nestedParent string
@@ -461,6 +476,7 @@ func TestOnboardingAndSharing(t *testing.T) {
// Moving an externally exposed node inside a nested frame must repair the
// ancestor boundary atomically and preserve its port/edge identities.
// 嵌套移动和解散需同时修复祖先端口,保留逻辑端点身份;漏报祖先版本应返回 428。
innerMemberPath := sourceCanvasPath + "/subgraphs/inner-frame/members"
nestedMemberCommand := response{"source_board_id": membersSource, "target_board_id": innerID, "node_ids": []string{"b"}, "expected_versions": map[string]int64{parentID: 11, membersSource: 8, innerID: 3}}
nestedMemberMove := call("POST", innerMemberPath, tokens[0], nestedMemberCommand, 200, "", accept, "30000000-0000-4000-8000-000000000001")
@@ -495,6 +511,7 @@ func TestOnboardingAndSharing(t *testing.T) {
if err := png.Encode(&assetPNG, image.NewRGBA(image.Rect(0, 0, 3, 2))); err != nil {
t.Fatal(err)
}
// 上传使用故意错误的文件扩展名验证真实 MIME 嗅探,并可指定客户端预分配资源 ID。
upload := func(encoded []byte, key string, status int, resourceIDs ...string) response {
t.Helper()
var body bytes.Buffer
@@ -538,6 +555,7 @@ func TestOnboardingAndSharing(t *testing.T) {
if !modelEqual(managed, repeated) {
t.Fatal("resource retry changed receipt")
}
// 模拟响应丢失后查询回执:已应用可恢复原资产,未知请求不能被误报为已确定零写入。
lookup := call("GET", workspacePath+"/assets/operations/"+resourceKey, tokens[0], nil, 200)
if lookup["status"] != "applied" || !modelEqual(lookup["asset"], managed["asset"]) {
t.Fatal("lost upload acknowledgment cannot be recovered")
@@ -613,6 +631,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
// Neither a snapshot nor an asset response may keep the workspace locked
// while a slow downstream consumer is accepting its body.
// 在真正写出响应体时另开事务 NOWAIT 抢工作区锁,防止慢消费者拖长数据库锁生命周期。
for _, path := range []string{canvasPath, workspacePath + "/assets/" + uploaded["id"].(string), metadataPath} {
var probeErr error
writer := &readLockProbe{ResponseRecorder: httptest.NewRecorder(), probe: func() {
@@ -634,6 +653,7 @@ func TestOnboardingAndSharing(t *testing.T) {
}
// A slow multipart body must not hold the workspace lock either.
func() {
// 管道先交付 multipart 头再暂停正文,探测接收慢上传期间是否错误持有工作区锁。
reader, pipe := io.Pipe()
defer reader.Close()
defer pipe.Close()
@@ -688,6 +708,7 @@ func TestOnboardingAndSharing(t *testing.T) {
download(tokens[0], 200)
download(tokens[1], 404)
download(tokens[2], 404)
// 资产由上传者可读,写入可访问画布并绑定后才允许该画布协作者读取。
assetBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Assets", "content": response{}}, 201)
assetDoc := response{"schema_version": 2, "nodes": []any{response{"id": "asset-node", "type": "plainImage", "position": response{"x": 0, "y": 0}, "data": response{"kind": "plain-image", "title": "Image", "text": "", "src": uploaded["url"], "assetId": uploaded["id"]}}}, "edges": []any{}, "viewport": response{"x": 0, "y": 0, "zoom": 1}}
call("PATCH", workspacePath+"/materials/"+assetBoard["id"].(string)+"/canvas", tokens[0], response{"document": assetDoc}, 200, `"1"`, accept)
@@ -709,6 +730,7 @@ func TestOnboardingAndSharing(t *testing.T) {
// A warm metadata/original cache is not a future permission grant. An external
// collaborator can read through a source board grant, but a new canonical
// target write must recheck asset readability after that grant is revoked.
// 先暖元数据/原图缓存再撤销来源权限,确保新目标写入实时检查授权而非信任缓存命中。
sourceGrantPath := workspacePath + "/materials/" + assetBoard["id"].(string) + "/grants"
call("POST", sourceGrantPath, tokens[0], response{"account_id": accounts[2], "role": "viewer"}, 204)
call("GET", metadataPath, tokens[2], nil, 200)
@@ -752,6 +774,7 @@ func TestOnboardingAndSharing(t *testing.T) {
if !modelEqual(denied, replayedDenial) {
t.Fatal("permission restoration changed a terminal receipt")
}
// 恢复权限后必须新建请求才可成功;目标获得独立绑定后,撤销来源不应破坏目标读权限。
acceptedID := modelTestID(9204)
call("POST", targetPath+"/canvas/model/operations", tokens[2], adoptionRequest(acceptedID, modelTestID(9205)), 200, "", accept, acceptedID)
call("DELETE", sourceGrantPath+"/"+accounts[2], tokens[0], nil, 204)
@@ -765,6 +788,7 @@ func TestOnboardingAndSharing(t *testing.T) {
download(tokens[1], 200)
upload([]byte("not an image"), "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", 400)
// 超出节点预算要求确定拒绝且版本不变;UUID 幂等键大小写应归一到同一次操作。
limitBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Limits", "content": response{}}, 201)
limitPath := workspacePath + "/materials/" + limitBoard["id"].(string) + "/canvas"
oversizedNodes := []any{}
@@ -787,6 +811,7 @@ func TestOnboardingAndSharing(t *testing.T) {
code int
body []byte
}
// 四条并发同键请求应收敛到同一 transaction 和一个子图,而不是各创建一次。
results := make(chan concurrentResult, 4)
startConcurrent := make(chan struct{})
encodedFrame, _ := json.Marshal(caseFrame)
@@ -821,6 +846,7 @@ func TestOnboardingAndSharing(t *testing.T) {
if err := db.QueryRowContext(ctx, `SELECT count(*) FROM canvas_subgraphs WHERE project=$1 AND parent_board_id=$2`, project, concurrentBoard["id"]).Scan(&concurrentChildren); err != nil || concurrentChildren != 1 {
t.Fatalf("concurrent retry duplicated children: %d %v", concurrentChildren, err)
}
// 让父文档接近字节预算,使创建子图在最终父文档校验失败,验证孩子和父版本共同回滚。
rollbackBoard := call("POST", workspacePath+"/materials", tokens[0], response{"kind": "board", "title": "Rollback", "content": response{}}, 201)
rollbackPath := workspacePath + "/materials/" + rollbackBoard["id"].(string) + "/canvas"
nearLimit := []any{}
@@ -851,6 +877,7 @@ func TestOnboardingAndSharing(t *testing.T) {
t.Fatal("failed create changed parent version")
}
// 最后用 outbox 内链接完成邮箱验证:未验证不能登录,验证码不可重放,注销后的会话不可访问资料。
email := "fixture@example.invalid"
password := "a-long-fixture-password"
call("POST", base+"/auth/register", "", response{"email": email, "password": password}, 202)
@@ -882,11 +909,13 @@ func TestOnboardingAndSharing(t *testing.T) {
// A real SQL NOWAIT probe at the response-write boundary catches locks that
// would otherwise remain invisible in a buffered httptest recorder.
// readLockProbe 在首个 Write 前执行外部锁探测;只运行一次以免多段响应反复探测。
type readLockProbe struct {
*httptest.ResponseRecorder
probe func()
}
// Write 先清空 probe 再调用,随后交给 recorder 保存实际响应体。
func (w *readLockProbe) Write(body []byte) (int, error) {
if w.probe != nil {
probe := w.probe
+7
View File
@@ -1,3 +1,4 @@
// 旧 board_layouts 路由:布局变更与父素材版本递增同事务执行,canonical 画布由入口守卫限制旧写入。
package platform
import (
@@ -7,6 +8,7 @@ import (
"net/http"
)
// placement 是素材在旧画布内的矩形位置,MaterialID 指向工作区内可访问且非 board 的素材。
type placement struct {
MaterialID string `json:"material_id"`
X float64 `json:"x"`
@@ -16,12 +18,15 @@ type placement struct {
ZIndex int `json:"z_index"`
}
// valid 限制有限坐标、正尺寸和层级范围;NaN 显式拒绝,无穷值也会被范围判断拒绝。
func (p placement) valid() bool {
return !math.IsNaN(p.X) && !math.IsNaN(p.Y) && !math.IsNaN(p.Width) && !math.IsNaN(p.Height) &&
p.X >= -1000000 && p.X <= 1000000 && p.Y >= -1000000 && p.Y <= 1000000 &&
p.Width >= 1 && p.Width <= 100000 && p.Height >= 1 && p.Height <= 100000 &&
p.ZIndex >= -1000000 && p.ZIndex <= 1000000
}
// layouts 对集合提供 GET/POST,对单条提供 PATCH/DELETE;所有写入都比较父画布 If-Match。
func (s *service) layouts(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet && r.Method != http.MethodPost && r.Method != http.MethodPatch && r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
@@ -84,6 +89,7 @@ ORDER BY l.z_index,l.id LIMIT 2000
if !ok {
return nil
}
// 工作区锁保护当前事务内版本检查与写入;不匹配立即返回 412,不进入布局变更。
if expected != version {
reject(w, 412, "version_conflict")
return nil
@@ -141,6 +147,7 @@ WHERE project=$1 AND workspace_id=$2 AND board_id=$3 AND id=$4
return sql.ErrNoRows
}
}
// 即使只移动或删除一条布局,也递增父素材版本,供其他客户端发现画布变更。
_, err = tx.ExecContext(r.Context(), "UPDATE materials SET version=version+1,modified_at=now() WHERE project=$1 AND workspace_id=$2 AND id=$3", project, workspace, board)
if err != nil {
return err
+13
View File
@@ -1,3 +1,4 @@
// 素材 CRUD、根画布授权继承与乐观版本控制;画布专用结构由其他文件处理。
package platform
import (
@@ -8,6 +9,8 @@ import (
"strconv"
)
// lockMaterial 先锁工作区,再向上遍历最多八层子图祖先获取根素材授权,返回目标类型与有效角色。
// 任一祖先关系归档则不可访问;子素材单独授权不能绕过父级。事务由调用方持有。
func lockMaterial(ctx context.Context, tx *sql.Tx, project, workspace, material, account string) (string, string, error) {
var locked, kind, role string
err := tx.QueryRowContext(ctx, "SELECT id::text FROM workspaces WHERE project=$1 AND id=$2 FOR UPDATE", project, workspace).Scan(&locked)
@@ -36,6 +39,7 @@ func lockMaterial(ctx context.Context, tx *sql.Tx, project, workspace, material,
return kind, role, err
}
// expectedVersion 解析带双引号的正整数 If-Match;缺少返回 428,格式错误返回 400。
func expectedVersion(w http.ResponseWriter, r *http.Request) (int64, bool) {
header := r.Header.Get("If-Match")
if header == "" {
@@ -53,10 +57,13 @@ func expectedVersion(w http.ResponseWriter, r *http.Request) (int64, bool) {
}
return version, true
}
// setVersion 将素材版本写成带引号 ETag,与 expectedVersion 的输入格式对应。
func setVersion(w http.ResponseWriter, version int64) {
w.Header().Set("ETag", strconv.Quote(strconv.FormatInt(version, 10)))
}
// materials 的 GET 转入筛选列表,POST 要求工作区编辑权限并按种类验证内容后创建版本一。
func (s *service) materials(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method == http.MethodGet {
return s.listMaterials(w, r, project, account)
@@ -110,6 +117,7 @@ VALUES($1,$2,$3,$4,$5,$6,$7,$8) RETURNING id::text,slug
return nil
}
// material 先校验根级权限;读取返回完整内容与 ETag,修改/删除同时要求角色和预期版本。
func (s *service) material(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet && r.Method != http.MethodPatch && r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
@@ -182,6 +190,7 @@ WHERE project=$1 AND workspace_id=$2 AND id=$3 AND version=$7
if err != nil {
return err
}
// 已通过可见性检查但版本条件未命中,视为并发冲突;事务回滚,不能覆盖其他客户端更新。
if n == 0 {
reject(w, 412, "version_conflict")
return nil
@@ -196,6 +205,7 @@ WHERE project=$1 AND workspace_id=$2 AND id=$3 AND version=$7
return nil
}
// openMaterial 记录当前账户最近打开时间,重复打开更新同一记录,不修改素材内容版本。
func (s *service) openMaterial(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -224,6 +234,7 @@ ON CONFLICT(project,workspace_id,material_id,account_id) DO UPDATE SET opened_at
return nil
}
// listMaterials 按授权与筛选返回元数据,默认隐藏子图;排序片段只从固定白名单选择。
func (s *service) listMaterials(w http.ResponseWriter, r *http.Request, project, account string) error {
sort := r.URL.Query().Get("sort")
orders := map[string]string{
@@ -267,6 +278,7 @@ func (s *service) listMaterials(w http.ResponseWriter, r *http.Request, project,
reject(w, 400, "invalid_filter")
return nil
}
// 子图默认通过父画布进入;显式请求后仍需根级权限且整条祖先链未归档。
includeSubgraphs := false
if value := r.URL.Query().Get("include_subgraphs"); value != "" {
if value != "true" && value != "false" {
@@ -314,6 +326,7 @@ ORDER BY `+order+` LIMIT $7 OFFSET $8`, project, r.PathValue("workspace"), accou
if err := rows.Err(); err != nil {
return err
}
// SQL 多取一条探测后页;响应截回 limit,并给出下一次应使用的 offset。
var next *int
if len(items) > limit {
items = items[:limit]
+5
View File
@@ -1,3 +1,4 @@
// 子图成员拖放可附带来源画布局部坐标;此处只更新来源文档,目标坐标转换由所有权事务完成。
package platform
import (
@@ -8,11 +9,13 @@ import (
// Positions are expressed in the source board's local coordinates. The existing
// ownership transaction converts them into destination coordinates exactly once.
// memberDropPosition 必须显式携带 x/y,避免遗漏字段被当作零而让节点意外跳位。
type memberDropPosition struct {
X float64 `json:"x"`
Y float64 `json:"y"`
}
// validMemberDropPositions 兼容缺省坐标的旧客户端;提供时必须与成员 ID 集合完全一致且坐标有限。
func validMemberDropPositions(ids []string, positions map[string]memberDropPosition) bool {
if positions == nil {
return true
@@ -31,6 +34,7 @@ func validMemberDropPositions(ids []string, positions map[string]memberDropPosit
return true
}
// positionMemberDrop 在 JSON 节点数组中替换所有指定位置,缺节点或非法文档返回所有权错误。
func positionMemberDrop(raw json.RawMessage, positions map[string]memberDropPosition) (json.RawMessage, error) {
var doc map[string]any
if err := json.Unmarshal(raw, &doc); err != nil {
@@ -58,6 +62,7 @@ func positionMemberDrop(raw json.RawMessage, positions map[string]memberDropPosi
return json.Marshal(doc)
}
// UnmarshalJSON 只接受两个非 null 数值字段;范围与有限性由 validMemberDropPositions 继续检查。
func (p *memberDropPosition) UnmarshalJSON(raw []byte) error {
var fields map[string]json.RawMessage
if err := json.Unmarshal(raw, &fields); err != nil {
+3
View File
@@ -1,3 +1,4 @@
// 成员拖放纯文档回归,复用子图 fixture 验证来源坐标只转换一次。
package platform
import (
@@ -6,6 +7,8 @@ import (
"testing"
)
// TestMemberDropPositions 先更新来源局部位置,再执行跨子图移动,断言目标坐标为 (140,250)。
// 另覆盖缺失成员、不匹配 ID 集合、非有限/越界坐标及缺字段或 null 的严格解码。
func TestMemberDropPositions(t *testing.T) {
raw := memberFixture(t)
source := "11111111-1111-4111-8111-111111111111"
+9
View File
@@ -1,3 +1,4 @@
// 项目可配置的首次引导:账号资料、工作区、可选邀请和问卷在一个事务内完成。
package platform
import (
@@ -9,10 +10,13 @@ import (
"strings"
)
// Question 引用 surveyTypes 中的固定题目键,Required 决定缺省或空白答案是否允许。
type Question struct {
Key string `json:"key"`
Required bool `json:"required"`
}
// OnboardingConfig 按项目配置必需工作区及问题清单,缺省配置允许空引导。
type OnboardingConfig struct {
RequireWorkspace bool `json:"require_workspace"`
Questions []Question `json:"questions"`
@@ -23,6 +27,7 @@ var surveyTypes = map[string]string{
"previous_use": "boolean", "purpose": "string", "company_size": "string",
}
// ParseOnboarding 启动时严格解析配置,拒绝未配置项目、未知题目和重复键。
func ParseOnboarding(raw string, callbacks map[string]string) (map[string]OnboardingConfig, error) {
configs := map[string]OnboardingConfig{}
if strings.TrimSpace(raw) == "" {
@@ -51,6 +56,7 @@ func ParseOnboarding(raw string, callbacks map[string]string) (map[string]Onboar
return configs, nil
}
// validAnswers 先验证提交键与类型,再检查必答题;必答布尔 false 合法,null 与空白必答文本不合法。
func validAnswers(config OnboardingConfig, answers map[string]json.RawMessage) bool {
questions := map[string]Question{}
for _, question := range config.Questions {
@@ -89,6 +95,7 @@ func validAnswers(config OnboardingConfig, answers map[string]json.RawMessage) b
return true
}
// onboarding GET 返回配置和已完成状态;POST 锁账户后检查既有结果,防止并发创建重复工作区。
func (s *service) onboarding(w http.ResponseWriter, r *http.Request, project, account string) error {
config := s.onboardingConfigs[project]
if config.Questions == nil {
@@ -143,6 +150,7 @@ func (s *service) onboarding(w http.ResponseWriter, r *http.Request, project, ac
}
var prior json.RawMessage
err = tx.QueryRowContext(r.Context(), "SELECT result FROM onboarding_responses WHERE project=$1 AND account_id=$2", project, account).Scan(&prior)
// 已完成直接返回已存 result;邀请明文不落库,所以重复请求不会重新返回 invite_url。
if err == nil {
reply(w, 200, response{"completed": true, "result": prior, "already_completed": true})
return nil
@@ -178,6 +186,7 @@ VALUES($1,$2,$3,'viewer',$4,now()+interval '7 days') RETURNING id::text
invitation = s.origin + "/s/" + token
}
}
// 结果只保存工作区和邀请 ID;明文 URL 仅随首次成功提交返回。
answers, _ := json.Marshal(input.Answers)
resultJSON, _ := json.Marshal(result)
_, err = tx.ExecContext(r.Context(), "INSERT INTO onboarding_responses(project,account_id,answers,result) VALUES($1,$2,$3,$4)", project, account, answers, resultJSON)
+12
View File
@@ -1,3 +1,4 @@
// 邀请链接分离公开点击与登录后兑换:点击只记录来源,兑换才增加角色和使用次数。
package platform
import (
@@ -14,17 +15,21 @@ import (
var linkTokenPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{22}$`)
// newLinkToken 产生十六随机字节的公开邀请凭据及落库摘要;明文仅在创建响应中给出。
func newLinkToken() (string, string) {
var raw [16]byte
rand.Read(raw[:])
value := base64.RawURLEncoding.EncodeToString(raw[:])
return value, linkDigest(value)
}
// linkDigest 与 newLinkToken/shortLink/redeemShare 共用相同摘要格式,数据库不保存邀请明文。
func linkDigest(token string) string {
sum := sha256.Sum256([]byte(token))
return base64.RawURLEncoding.EncodeToString(sum[:])
}
// shareInput 可邀请加入整个工作区或单个素材;单素材不能授予 admin,缺省有效期七天。
type shareInput struct {
Role string `json:"role"`
MaterialID *string `json:"material_id"`
@@ -32,6 +37,7 @@ type shareInput struct {
MaxUses *int `json:"max_uses"`
}
// shares 仅供工作区 admin 列表或创建邀请;列表返回统计和链接 ID,不可还原原始 token。
func (s *service) shares(w http.ResponseWriter, r *http.Request, project, account string) error {
workspace := r.PathValue("workspace")
if r.Method != http.MethodPost && r.Method != http.MethodGet {
@@ -110,6 +116,7 @@ VALUES($1,$2,$3,$4,$5,$6,now()+$7*interval '1 second',$8) RETURNING id::text,exp
return nil
}
// revokeShare 设置首次撤销时间,重复撤销保留时间;只阻止未来兑换,不回收已授予角色。
func (s *service) revokeShare(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodDelete {
reject(w, 405, "method_not_allowed")
@@ -150,6 +157,7 @@ UPDATE share_links SET revoked_at=COALESCE(revoked_at,now()) WHERE project=$1 AN
// A public short link records only a referring origin and redirects to a fixed
// frontend. The fragment carries the invitation, never a login session.
// shortLink 是无需会话的公开入口,只记录 Referer 的 origin,邀请 token 放入固定前端回调 fragment。
func (s *service) shortLink(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Cache-Control", "no-store")
w.Header().Set("Referrer-Policy", "no-referrer")
@@ -202,6 +210,7 @@ SELECT project FROM click
http.Redirect(w, r, destination.String(), 302)
}
// redeemShare 按工作区再链接的顺序加锁,原子校验有效期、容量与既往兑换记录。
func (s *service) redeemShare(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodPost {
reject(w, 405, "method_not_allowed")
@@ -243,6 +252,7 @@ FROM share_links WHERE project=$1 AND workspace_id=$2 AND token_hash=$3 FOR UPDA
if err != nil {
return err
}
// 已兑换者可在容量耗尽后重复读取结果,但链接过期或撤销后仍不可兑换。
if !allowed || (!capacity && !redeemed) {
reject(w, 410, "share_unavailable")
return nil
@@ -257,6 +267,7 @@ INSERT INTO share_redemptions(project,workspace_id,link_id,account_id) VALUES($1
if err != nil {
return err
}
// 唯一兑换记录插入成功才提升角色并计数;重复请求不重复消耗额度,也不降低原有更高角色。
if n > 0 {
if material == nil {
_, err = tx.ExecContext(r.Context(), `
@@ -287,6 +298,7 @@ ON CONFLICT(project,workspace_id,material_id,account_id) DO UPDATE SET role=CASE
return nil
}
// shareClicks 仅 admin 可读,按递减点击 ID 做游标分页,多取一条判断 next_before。
func (s *service) shareClicks(w http.ResponseWriter, r *http.Request, project, account string) error {
if r.Method != http.MethodGet {
reject(w, 405, "method_not_allowed")
+2
View File
@@ -1,3 +1,4 @@
// 资源别名使用小写连字符格式,避免与受保护路由可直接接受的 UUID 引用发生歧义。
package platform
import "regexp"
@@ -7,6 +8,7 @@ var slugPattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
var uuidSlugPattern = regexp.MustCompile(`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`)
// Slugs remain stable across renames unless explicitly changed by an authorized edit.
// validSlug 的 nil 表示创建时由数据库生成或更新时保留原值;非 nil 必须非空、最多百字节且非 UUID。
func validSlug(slug *string) bool {
return slug == nil || (len(*slug) <= 100 && slugPattern.MatchString(*slug) && !uuidSlugPattern.MatchString(*slug))
}
@@ -1,3 +1,4 @@
// 节点迁移/解散时修复上一层祖先端口;外层 port ID 保持稳定,因此更高层链路无需全部重写。
package platform
import (
@@ -9,7 +10,10 @@ import (
"strings"
)
// ancestorPortChange 保存受影响外层端口 ID 及其原始真实节点、handle 与方向。
type ancestorPortChange struct{ PortID, NodeID, Handle, Direction string }
// ancestorPortRepair 描述需加入版本事务的祖先画布、对应 frame 和最小端口修改集。
type ancestorPortRepair struct {
Ancestor, Frame string
Changes []ancestorPortChange
@@ -17,6 +21,7 @@ type ancestorPortRepair struct {
// A parent keeps stable port IDs. Updating that one boundary also preserves all
// higher ancestor chains, which continue to reference the same frame/port pair.
// planAncestorPortRepair 只制定计划:读取父级所属关系与祖先快照,选出直接或经 source frame 暴露的移动节点。
func planAncestorPortRepair(r *http.Request, tx *sql.Tx, project, workspace, parent, source, account string, nodeIDs []string, before json.RawMessage) (*ancestorPortRepair, error) {
relation, err := readSubgraphRelation(r, tx, project, workspace, parent)
if err == sql.ErrNoRows {
@@ -56,6 +61,7 @@ func planAncestorPortRepair(r *http.Request, tx *sql.Tx, project, workspace, par
handle := port["handle"].(string)
direction := port["direction"].(string)
affected := source == parent && selected[node]
// 来源是孩子时再解开一层 port:<id>,确定祖先端口实际引用的移动成员。
if !affected && source != parent {
data := parentNodes[node]
sub, _ := data["subgraph"].(map[string]any)
@@ -82,6 +88,9 @@ func planAncestorPortRepair(r *http.Request, tx *sql.Tx, project, workspace, par
}
return result, nil
}
// applyAncestorPortRepair 对副本补齐目标 frame 内端口,再在祖先中保留原 PortID 只换指向。
// target==parent 表示节点已展开到父级,可直接指向真实节点,无需新的中间端口。
func applyAncestorPortRepair(repair *ancestorPortRepair, parent, target string, documents map[string]json.RawMessage) error {
if repair == nil {
return nil
@@ -157,6 +166,7 @@ func applyAncestorPortRepair(repair *ancestorPortRepair, parent, target string,
return errGraphOwnership
}
}
// 父和祖先都重新规范化后写回结果映射;数据库版本推进与提交仍由外层命令负责。
for board, doc := range map[string]map[string]any{parent: parentDoc, repair.Ancestor: ancestorDoc} {
encoded, _ := json.Marshal(doc)
normalized, ok := normalizeCanvas(encoded)

Some files were not shown because too many files have changed in this diff Show More