Files
endorphin-tessera-gui/docs/architecture/03-runtime.md
T
2026-10-25 21:25:43 +08:00

4.9 KiB
Raw Blame History

03 · Endor 执行、并发请求与发布

完整程序提交的时序

sequenceDiagram
    actor Client as 本机客户端
    participant API as api.rs
    participant Queue as 有界队列
    participant Worker as api/worker.rs
    participant Aster as Reader/Parser/Compiler/VM
    participant Bridge as UiBridge
    participant State as NamespaceState
    participant GUI as TesseraApp
    Client->>API: PUT /v1/namespaces/app.main/code
    API->>API: 校验命名空间/大小/入队资格
    API->>Queue: BuildRequest + submission
    Queue->>Worker: 串行接收
    Worker->>Aster: 在新候选中解析、编译和执行
    Aster->>Bridge: 构建对象、Page 和回调
    loop 可恢复的刷新切片
        Worker->>Bridge: 绑定、快照、布局、绘制、挂载同步
        Bridge-->>Worker: Pending / 完成的原生文档
    end
    Worker->>State: 核对提交代际
    alt 仍有效且构建成功
        Worker->>State: 提交 RenderDocument / 窗口命令
        Worker->>Worker: 候选成为活跃 ReplSession
        Worker-->>GUI: DocumentUpdated
        Worker-->>Client: 成功响应与修订信息
    else 已过期或错误
        Worker->>Worker: 丢弃候选,保留已有有效程序
        Worker-->>Client: 409 / 422 / 500 等错误
    end

图简化了 HTTP Response 的持有:原始请求在入队后由 worker 完成响应,不是 GUI 执行 HTTP 请求。可编辑来源:publication.puml。

不同入口的语义

入口 VM / 发布行为
GET /agent 按当前 namespace 生成使用指南,不执行 Endor
GET .../code 读取最后成功发布的源码文本
PUT .../code 新候选执行;成功后接替活跃运行时,失败保留原程序
POST .../repl 在活跃 Console/程序 VM 内执行,不靠重放历史恢复对象
DELETE .../repl 清理 Console 上下文,重新建立可用会话
DELETE .../code 清空并使旧工作失去发布资格
POST .../events 校验窗口、运行时代际与布局身份,再在拥有对象的 VM 中分发
POST .../evaluate 独立表达式求值;不是替换当前页面的入口

在线契约以 GET http://127.0.0.1:4737/agent 为准,静态正文实现位于 runtime/api/guide.rs。

Console 的编译错误发生在执行前;运行期错误则可能保留此前已经完成的赋值,所以它不是数据库事务回滚。故障运行时有单独的停用/清理规则;完整 PUT 的隔离候选和 REPL 的活对象修改不能混为一谈。

代际与失败边界

stateDiagram-v2
    [*] --> Candidate: 接受完整 PUT
    Candidate --> Refreshing: 编译执行成功
    Candidate --> Rejected: 编译/执行错误
    Refreshing --> Refreshing: 让出并继续刷新
    Refreshing --> Active: 文档有效且 submission 匹配
    Refreshing --> Superseded: 更新的写入或删除
    Active --> Active: Console / 输入 / 任务完成
    Active --> Faulted: 活跃回调或刷新故障
    Active --> Retired: 成功替换 / reset / delete / shutdown
    Faulted --> Retired: 清理或替换
    Rejected --> [*]
    Superseded --> [*]
    Retired --> [*]

这是候选和活跃运行时的概念状态图,并非源码中一个同名 enum。刷新具体由 RefreshWork、PendingLayout、paint Work 与 worker 的 PendingRequest 协作,不能在挂起时换一个 VM 恢复。

异步任务

ui.after、ui.readText、ui.fetchText 和协作任务由托管 Task 表示。回调及 scope 是 VM 强边,调度索引保留弱身份。I/O 池只接收路径/URL等原生数据、取消控制及完成消息,不拿着 ObjectRef 在其他线程调用 VM。

stateDiagram-v2
    [*] --> Pending
    Pending --> Running: 到期 / 可以执行
    Pending --> Completed: provider 完成且无需回调
    Pending --> Failed: provider 返回错误
    Pending --> Cancelled: owner 失效 / key 替换 / 主动取消
    Running --> Completed: 成功交付
    Running --> Failed: 传输或执行错误
    Running --> Cancelled: 取消及生命周期清理
    Completed --> [*]
    Failed --> [*]
    Cancelled --> [*]

源码的 Task 状态为 pending、running、completed、cancelled、failed;具体 provider 可能在 Pending 期间已开展后台 I/O,图中的 Running 不表示后台 I/O 一定此时才启动。见 tasks.puml。

预算与实际边界

源码上限 1 MiB;AST 访问上限 10000、深度 64;VM 栈帧上限 128;指令预算、UI 对象和页面预算各有上限。完整脚本各输入共享分摊总指令额度;Console 还检查累计来源与活对象限制。队列上限是 8,不是无限吞吐。

这些预算帮助限制失控工作,不构成执行任意不可信代码的安全沙箱。当前程序仍运行在桌面进程内,文件和网络能力没有完成产品级权限治理。