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

103 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 03 · Endor 执行、并发请求与发布
## 完整程序提交的时序
```mermaid
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](uml/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 的活对象修改不能混为一谈。
## 代际与失败边界
```mermaid
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。
```mermaid
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](uml/tasks.puml)。
## 预算与实际边界
源码上限 1 MiB;AST 访问上限 10000、深度 64;VM 栈帧上限 128;指令预算、UI 对象和页面预算各有上限。完整脚本各输入共享分摊总指令额度;Console 还检查累计来源与活对象限制。队列上限是 8,不是无限吞吐。
这些预算帮助限制失控工作,**不构成执行任意不可信代码的安全沙箱**。当前程序仍运行在桌面进程内,文件和网络能力没有完成产品级权限治理。