diff --git a/src/runtime/io_tasks.rs b/src/runtime/io_tasks.rs index 60d646c..512daad 100644 --- a/src/runtime/io_tasks.rs +++ b/src/runtime/io_tasks.rs @@ -215,6 +215,7 @@ fn read_text(path: &str) -> Completion { return Err("text source must be a regular file".into()); } if metadata.len() > MAX_TEXT as u64 { + // 提交线程已校验路径字符串,这里依据实际文件长度提前拒绝,避免明显超限请求进入读取阶段。 return Err("text source exceeds 1 MiB".into()); } // 路径检查与打开之间可能变化,所以打开后再次检查句柄实际指向的对象类型。 @@ -233,6 +234,7 @@ fn read_text(path: &str) -> Completion { .read_to_end(&mut bytes) .map_err(|error| error.to_string())?; if bytes.len() > MAX_TEXT { + // metadata 后文件仍可能增长,因此按实际读到的字节数再核验;多读的那个探测字节不会作为正文交付。 return Err("text source exceeds 1 MiB".into()); } String::from_utf8(bytes).map_err(|_| "text source must be UTF-8".into()) @@ -250,6 +252,7 @@ pub fn valid_url(url: &str) -> bool { return false; }; if !scheme.eq_ignore_ascii_case("http") && !scheme.eq_ignore_ascii_case("https") { + // scheme 不区分大小写,但必须是明确 HTTP(S);拒绝 file 等其他 curl 可处理协议,不依赖调用方只传网页地址。 return false; } // 仅检查协议与 authority 基本约束;@ 禁止 userinfo 凭据,空白禁止模糊主机部分。 @@ -266,6 +269,7 @@ impl Drop for Reaper<'_> { // 从控制槽取出子进程后释放锁,再 kill/wait;只有实际留下的进程才需要回收。 let child = self.0.process.lock().ok().and_then(|mut slot| slot.take()); if let Some(mut child) = child { + // 两项清理都尽力尝试,kill 的错误不跳过 wait;进程可能已经退出,回收仍由这个后台 worker 完成。 let _ = child.kill(); let _ = child.wait(); } @@ -348,6 +352,7 @@ fn fetch_text(url: &str, control: &Control) -> Completion { .read_to_end(&mut bytes) .map_err(|_| "HTTP response read failed".to_owned())?; if bytes.len() > MAX_TEXT + 4 { + // 四字节属于 curl 追加的换行/状态码尾部,超过正文预算加尾部即拒绝;Reaper 随返回回收仍可能运行的 curl。 return Err("HTTP text exceeds 1 MiB".into()); } // 读完输出后用 try_wait 检查退出;等待间隔先释放 process 锁,让其他线程仍可取消进程。 @@ -397,6 +402,7 @@ fn fetch_text(url: &str, control: &Control) -> Completion { }); } if !code.is_some_and(|code| (200..300).contains(&code)) { + // 即使 curl 成功退出,也须有完整且为 2xx 的状态尾;没有状态不能把截断/异常输出当作成功正文。 return Err("HTTP response status unavailable".into()); } // 确认 2xx 与成功退出后才剥去协议附加状态尾部,再严格解码 UTF-8 正文。 diff --git a/src/runtime/tasks.rs b/src/runtime/tasks.rs index 05e5363..267fe08 100644 --- a/src/runtime/tasks.rs +++ b/src/runtime/tasks.rs @@ -6,6 +6,11 @@ //! 源 API 经 After 创建 Task;UiBridge/endor_host 的轮询调用 Scheduler::poll,才在所属 VM 交付结果或推进协程。 //! 页面/窗口关闭调用 cancel_owner,运行时退出调用 quiesce;只取消身份和执行边,不允许旧 I/O 结果复活它们。 //! 这里同时含通用调度和 Tessera 展示资格检查,未来迁移 Nexus 时需将 scope/eligible 的 UI 规则留在宿主适配中。 +//! +//! 一次交付需要三项同时成立:Task 仍处于可推进状态、owner 仍有宿主资格、owner/key 字典仍指向这个精确 Task。 +//! eligible 只检查宿主资格,current 只检查同键身份,不能互相替代;Task.status/active 的查询也使用同一划分。 +//! poll 先把邮箱纯数据转入 Task,再按工作预算轮转;advance_coroutine 保存 await/软挂起状态,finish 才清理执行边。 +//! Completed/Failed 的 token 可由源变量继续持有和查询;finish 撤销仍匹配的 owner/key 边,prune 在轮末移除终态弱索引。 use std::{ sync::{ Arc, Mutex, @@ -64,7 +69,7 @@ impl State { #[derive(Debug, Clone)] /// 托管异步对象,保存 owner/key、结果与真正拥有的回调/协程/等待引用。 struct Task { - // owner 通过 scope 字典强持有 Task,Task 反向弱引用 owner,避免任务把已关闭页面永久保活。 + // owner 通过 scope 字典强持有 Task,Task 的 owner 字段反向使用弱边;callback/协程仍可能形成由 GC 处理的真实引用环。 owner: WeakObjectRef, // owner 内唯一键,作用域字典决定它是否仍是当前任务;不是跨运行时的全局 ID。 key: String, @@ -132,12 +137,15 @@ impl ObjectPayload for Task { visit(callback); } if let Some(coroutine) = self.coroutine { + // spawn 的保存帧是真实拥有边,包含已执行到的位置和局部值;不能靠弱索引让挂起帧碰巧存活。 visit(coroutine); } if let Some(waiting) = self.waiting { + // await 的目标在等待期间必须可达,取消或 finish 会清此边;它与 coroutine 自身的身份不同。 visit(waiting); } if let Some(Value::Object(result)) = self.result { + // 成功协程可返回任意对象,Task.result 要在外层创建根释放后继续拥有它;标量结果无托管边可追踪。 visit(result); } } @@ -671,6 +679,7 @@ impl NativeCallable for Method { }) } Query::Error => Value::Text( + // 只有 Failed 返回保存诊断;取消/运行中返回空错误文本,空文本本身不能作为任务已经成功的判断依据。 if task.state == State::Failed { task.error.as_deref().unwrap_or_default() } else { @@ -686,6 +695,7 @@ impl NativeCallable for Method { )); } if pending { + // pending 同时覆盖 Running;即使 active 已因 owner/key 失效而为 false,也清执行边,但最终返回值仍报告未取消有效任务。 task.state = State::Cancelled; task.callback = None; // 取消立即放弃 I/O 租约与执行边,下面也清掉 text/result;不保留可交付的成功结果。 @@ -763,6 +773,7 @@ impl Scheduler { }) })(); if let Some(owner) = owner { + // 邮箱阶段仅临时升级 owner 以检查资格,无论 active 检查成功或失败都先释放这个临时根再传播结果。 vm.release(owner)?; } if !active? { @@ -904,6 +915,7 @@ impl Scheduler { } })(); if let Some(owner) = owner { + // 调度回调或协程推进可能失败;先释放本项的 owner 临时根,外层再释放 Task 根,最后才传播错误。 vm.release(owner)?; } result @@ -988,6 +1000,7 @@ impl Scheduler { } vm.release(task)?; if pending? { + // 查询成功且仍为 Pending/Running 才留下弱索引;终态 token 可以继续存在,但不再占下一轮调度槽。 live.push(weak); } } @@ -1078,6 +1091,7 @@ fn advance_coroutine(vm: &mut Vm, reference: ObjectRef) -> Result<()> { vm.payload::(reference, "Task")?.state, State::Pending | State::Running ); + // Waiting 保存依赖,Pending 等下一软量子,Complete 保存任意返回值;三条成功路径都先尊重本片执行期间发生的取消。 match result { Ok(endor_core::CoroutineProgress::Waiting { awaitable, .. }) => { if !active { @@ -1227,6 +1241,7 @@ pub fn install( ], endor_core::AnnotationType::Nominal(definition), if external { + // I/O 签名声明 External;与下面纯计时/协作的 Mutating 不同,二者都不能在只读渲染中提交。 endor_core::CallEffect::External } else { endor_core::CallEffect::Mutating