feat(unstable_createRoot): support unsafe_penetrate #4683
Conversation
Walkthrough本次变更在运行时相关的接口和逻辑中引入了一个新的可选布尔标志 Changes
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
packages/runtime/src/createRoot.tsOops! Something went wrong! :( ESLint: 9.22.0 Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@next-core/eslint-config-next' imported from /eslint.config.mjs packages/runtime/src/internal/compute/computeRealValue.spec.tsOops! Something went wrong! :( ESLint: 9.22.0 Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@next-core/eslint-config-next' imported from /eslint.config.mjs packages/runtime/src/internal/compute/computeRealValue.tsOops! Something went wrong! :( ESLint: 9.22.0 Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@next-core/eslint-config-next' imported from /eslint.config.mjs
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (7)
🚧 Files skipped from review as they are similar to previous changes (7)
⏰ Context from checks skipped due to timeout of 90000ms (2)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Pull Request Overview
This PR introduces an unsafe_penetrate flag to allow accessing global variables from an isolated root. Changes include:
- Adding an unsafe_penetrate property to RuntimeContext and CreateRootOptions.
- Updating evaluation and computeRealValue functions to optionally use a penetrable runtime context.
- Enhancing test coverage and API documentation to support the new unsafe_penetrate behavior.
Reviewed Changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| packages/runtime/src/internal/interfaces.ts | Added optional unsafe_penetrate flag to RuntimeContext. |
| packages/runtime/src/internal/compute/evaluate.ts | Modified context extraction to support unsafe penetration. |
| packages/runtime/src/internal/compute/evaluate.spec.ts | Added tests for unsafe penetration feature. |
| packages/runtime/src/internal/compute/computeRealValue.ts | Updated compute functions to possibly use a penetrable context. |
| packages/runtime/src/internal/compute/computeRealValue.spec.ts | Added test cases for behavior with and without unsafe penetration. |
| packages/runtime/src/createRoot.ts | Extended CreateRootOptions and unstable_createRoot with unsafe_penetrate support. |
| etc/runtime.api.md | Updated API documentation to include unsafe_penetrate. |
Comments suppressed due to low confidence (1)
packages/runtime/src/internal/interfaces.ts:39
- [nitpick] The property name 'unsafe_penetrate' uses snake_case while other similar properties in this codebase use camelCase. Consider changing it to 'unsafePenetrate' for consistency.
unsafe_penetrate?: boolean;
weareoutman
force-pushed
the
steve/v3-unsafe-penetrate
branch
from
0820bc6 to
785217d
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (2)
packages/runtime/src/internal/interfaces.ts (1)
1-40: 💡 Verification agent🧩 Analysis chain
注意需要更新 API 文档
管道失败提示 API 签名已更改，请确保运行本地构建并更新 'etc/runtime.api.md' 文件以反映新添加的接口成员。
🏁 Script executed:
#!/bin/bash # 检查 API 提取器是否已更新 temp 文件夹中的 API 文档 if [ -f "temp/runtime.api.md" ]; then echo "临时 API 文档存在，需要复制到 etc/runtime.api.md" # 显示差异 diff -u etc/runtime.api.md temp/runtime.api.md || true else echo "临时 API 文档不存在，可能需要运行 API 提取器构建" fiLength of output: 101
更新 runtime API 文档
检测到
packages/runtime/src/internal/interfaces.ts中新增了接口成员，但未生成最新的 API 文档。请按以下步骤操作：
- 在项目根目录运行 API 提取器（如
npm run docs:api或对应的构建命令），生成temp/runtime.api.md。- 将生成的
temp/runtime.api.md与现有的etc/runtime.api.md合并或替换，以同步接口签名变更。- 提交更新后的
etc/runtime.api.md，确保管道通过。🧰 Tools
🪛 GitHub Actions: CI
[error] 1-1: API Extractor docs:build script failed with exit code 1. Warning: API signature changed; please copy 'temp/runtime.api.md' to 'etc/runtime.api.md' or perform a local build to update.
etc/runtime.api.md (1)
581-625:⚠️ Potential issue注意 API 接口更改需要更新构建
管道失败显示 API 接口已更改，需要将 'temp/runtime.api.md' 复制到 'etc/runtime.api.md' 或执行本地构建来更新。建议在提交前确保 API 文档已正确更新。
🧹 Nitpick comments (1)
packages/runtime/src/internal/compute/computeRealValue.ts (1)
20-226: 考虑添加穿透行为的文档注释当前代码实现了
unsafe_penetrate功能，但缺少相关的文档注释来解释这个功能的用途、使用场景和潜在风险。建议在penetrableCtxNames常量和使用unsafe_penetrate的函数部分添加详细的注释，说明此功能的设计意图和使用注意事项。+/** + * 可穿透的上下文属性名称列表。 + * 当启用 unsafe_penetrate 时，这些属性将从全局上下文中获取， + * 而不是使用当前隔离的运行时上下文中的值。 + * + * 注意: 这是一个不稳定的功能，应谨慎使用，因为它可能破坏上下文隔离。 + */ const penetrableCtxNames = [ "app", "location", "query", "match", "flags", "sys", ] as const;同样，在函数实现中的穿透逻辑部分也应添加注释，解释为什么需要这种行为以及它解决了什么问题。
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
etc/runtime.api.md(3 hunks)packages/runtime/src/createRoot.ts(3 hunks)packages/runtime/src/internal/compute/computeRealValue.spec.ts(4 hunks)packages/runtime/src/internal/compute/computeRealValue.ts(4 hunks)packages/runtime/src/internal/compute/evaluate.spec.ts(3 hunks)packages/runtime/src/internal/compute/evaluate.ts(1 hunks)packages/runtime/src/internal/interfaces.ts(1 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (1)
packages/runtime/src/internal/compute/evaluate.spec.ts (2)
packages/runtime/src/internal/Renderer.spec.ts (1)
_internalApiGetRuntimeContext(70-72)packages/runtime/src/internal/compute/evaluate.ts (1)
evaluate(105-112)
🪛 GitHub Actions: CI
packages/runtime/src/internal/interfaces.ts
[error] 1-1: API Extractor docs:build script failed with exit code 1. Warning: API signature changed; please copy 'temp/runtime.api.md' to 'etc/runtime.api.md' or perform a local build to update.
packages/runtime/src/internal/compute/evaluate.spec.ts
[error] 1-1: API Extractor docs:build script failed with exit code 1. Warning: API signature changed; please copy 'temp/runtime.api.md' to 'etc/runtime.api.md' or perform a local build to update.
packages/runtime/src/createRoot.ts
[error] 1-1: API Extractor docs:build script failed with exit code 1. Warning: API signature changed; please copy 'temp/runtime.api.md' to 'etc/runtime.api.md' or perform a local build to update.
packages/runtime/src/internal/compute/evaluate.ts
[error] 1-1: API Extractor docs:build script failed with exit code 1. Warning: API signature changed; please copy 'temp/runtime.api.md' to 'etc/runtime.api.md' or perform a local build to update.
packages/runtime/src/internal/compute/computeRealValue.ts
[error] 1-1: API Extractor docs:build script failed with exit code 1. Warning: API signature changed; please copy 'temp/runtime.api.md' to 'etc/runtime.api.md' or perform a local build to update.
packages/runtime/src/internal/compute/computeRealValue.spec.ts
[error] 1-1: API Extractor docs:build script failed with exit code 1. Warning: API signature changed; please copy 'temp/runtime.api.md' to 'etc/runtime.api.md' or perform a local build to update.
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (19)
packages/runtime/src/internal/interfaces.ts (1)
38-39: 添加了 unsafe_penetrate 选项该变更添加了一个新的可选布尔属性
unsafe_penetrate到RuntimeContext接口中，这与 PR 的目标一致。packages/runtime/src/internal/compute/evaluate.spec.ts (3)
257-259: 添加了 beforeEach 钩子以重置模拟良好的测试实践，确保每个测试都有一个干净的模拟状态。
412-424: 修改了 mockReturnValueOnce 为 mockReturnValue这个改变使模拟值在整个测试期间持续有效，而不仅仅是第一次调用时。这是测试逻辑上的改进。
426-444: 增加了 unsafe_penetrate 功能的测试这个测试很好地验证了新的
unsafe_penetrate标志的行为：
- 当标志设置为 true 时，会从全局上下文中获取
app和flags属性- 测试确认全局属性 (
app.id为 "global") 被正确地使用- 测试确认全局标志 (
flags.unsafe为 true) 被正确地使用- 测试确认当全局上下文中不存在的属性 (
flags.test) 返回 undefined这些测试覆盖了新功能的关键行为，确保其按预期工作。
packages/runtime/src/createRoot.ts (4)
47-53: 添加了 unsafe_penetrate 选项文档文档清晰地解释了该选项的目的和风险：允许从隔离的根访问全局变量，并警告用户这是不安全的。这是一个很好的文档实践，特别是对于可能有风险的功能。
70-75: 更新了 unstable_createRoot 函数签名函数签名已更新以接受新的
unsafe_penetrate选项，使用解构赋值模式保持了代码风格的一致性。
126-126: 传递 unsafe_penetrate 标志到运行时上下文正确地将
unsafe_penetrate标志添加到运行时上下文初始化中，这样标志就可以在渲染过程中被访问。
31-54:✅ Verification successful
注意 CreateRootOptions 接口已更改
接口更改需要更新 API 文档。请确保在提交前运行本地构建并更新
etc/runtime.api.md文件。
🏁 Script executed:
#!/bin/bash # 查找所有引用了 CreateRootOptions 的文件，以检查是否有需要更新的地方 echo "查找引用了 CreateRootOptions 的文件:" rg --type ts "CreateRootOptions" --files-with-matchesLength of output: 155
🏁 Script executed:
#!/bin/bash # 检查 API 文档中是否包含并已更新 CreateRootOptions 接口定义 echo "扫描 etc/runtime.api.md 中的 CreateRootOptions 定义：" rg -n "CreateRootOptions" etc/runtime.api.md || echo "未找到 CreateRootOptions，需添加文档条目"Length of output: 356
文档已同步 CreateRootOptions 接口
已确认
etc/runtime.api.md中包含最新的CreateRootOptions接口定义，无需额外更新。packages/runtime/src/internal/compute/computeRealValue.spec.ts (3)
4-8: 添加了对 _internalApiGetRuntimeContext 的模拟正确地设置了对
_internalApiGetRuntimeContext函数的模拟，这对于测试新功能是必要的。
167-169: 添加了 beforeEach 钩子以重置模拟良好的测试实践，确保每个测试都有一个干净的模拟状态。
314-331: 添加了两个测试用例验证 unsafe_penetrate 功能这些测试很好地验证了
computeRealValue函数在使用和不使用unsafe_penetrate标志时的行为：
- 第一个测试验证当不使用
unsafe_penetrate时，函数使用本地上下文的query(返回 "foo")- 第二个测试验证当使用
unsafe_penetrate时，函数使用全局上下文的query(返回 "bar")这些测试确保了新功能的核心行为按预期工作。
etc/runtime.api.md (3)
122-122: 扩展接口添加了 unsafe_penetrate 选项
CreateRootOptions接口中新增了可选的unsafe_penetrate布尔属性，该属性允许开发者控制在执行时是否应该"穿透"访问全局上下文。
462-463: 运行时上下文接口添加 unsafe_penetrate 支持
RuntimeContext接口新增了可选的unsafe_penetrate布尔属性，用于在运行时上下文中传递穿透访问标志。此更改与CreateRootOptions的更新保持一致。
588-588: unstable_createRoot 函数参数支持 unsafe_penetrate
unstable_createRoot函数签名已更新，现在可以接收并解构unsafe_penetrate参数。此更改确保了从 API 到实现的一致性。packages/runtime/src/internal/compute/evaluate.ts (1)
306-313: 实现运行时上下文的穿透访问机制此代码片段实现了
unsafe_penetrate的核心功能：从当前运行时上下文中提取unsafe_penetrate标志，并据此决定是使用全局上下文（通过_internalApiGetRuntimeContext()）还是本地上下文。这种方式允许在隔离的根中访问全局上下文的特定属性。代码的实现简洁明了，使用解构赋值来提取并重组所需属性，保持了代码的可读性。
packages/runtime/src/internal/compute/computeRealValue.ts (4)
1-1: 添加 pick 方法导入添加了
pick方法的导入，用于后续对运行时上下文对象进行属性选择操作。此变更是必要的，以支持unsafe_penetrate功能的实现。🧰 Tools
🪛 GitHub Actions: CI
[error] 1-1: API Extractor docs:build script failed with exit code 1. Warning: API signature changed; please copy 'temp/runtime.api.md' to 'etc/runtime.api.md' or perform a local build to update.
18-27: 定义可穿透的上下文属性列表引入
_internalApiGetRuntimeContext导入和定义penetrableCtxNames常量数组，明确指定了哪些上下文属性可以被"穿透"访问。这种显式列举的方式增加了代码的可维护性和安全性，防止了不必要的属性泄露。使用
as const断言确保了类型安全，这是一个良好的实践。
56-75: 在 asyncComputeRealValue 中实现穿透上下文逻辑这段代码实现了
asyncComputeRealValue函数中的穿透逻辑。当lazy为 true 时，直接返回原始值；否则，检查unsafe_penetrate标志并据此创建穿透上下文。穿透上下文通过巧妙组合
pick和omit函数，将全局上下文中的特定属性与本地上下文的其他属性合并，确保了正确的属性优先级和访问控制。值得注意的是，代码结构清晰，条件分支处理得当，保持了函数的可读性。
144-163: 在 computeRealValue 中实现穿透上下文逻辑此段代码在同步版本的
computeRealValue函数中实现了与asyncComputeRealValue相同的穿透逻辑。代码保持了一致性，确保了两个函数在行为上的统一。实现方式与异步版本相同，通过
pick和omit函数组合创建穿透上下文，并根据上下文中是否存在data属性选择适当的转换函数。这种一致性有助于代码维护和理解。
weareoutman
force-pushed
the
steve/v3-unsafe-penetrate
branch
from
785217d to
729a787
Compare
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## v3 #4683 +/- ##
==========================================
- Coverage 95.27% 95.26% -0.01%
==========================================
Files 209 209
Lines 9028 9037 +9
Branches 1734 1737 +3
==========================================
+ Hits 8601 8609 +8
Misses 319 319
- Partials 108 109 +1
🚀 New features to boost your workflow:
|
next-core
|
||||||||||||||||||||||||||||
| Project |
next-core
|
| Branch Review |
steve/v3-unsafe-penetrate
|
| Run status |
|
| Run duration | 00m 22s |
| Commit |
|
| Committer | Shenwei Wang |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
Failures
|
0
|
Flaky
|
0
|
Pending
|
0
|
Skipped
|
0
|
Passing
|
16
|
| View all changes introduced in this branch ↗︎ | |
依赖检查
组件之间的依赖声明，是微服务组件架构下的重要信息，请确保其正确性。
请勾选以下两组选项其中之一：
或者：
提交信息检查
Git 提交信息将决定包的版本发布及自动生成的 CHANGELOG，请检查工作内容与提交信息是否相符，并在以下每组选项中都依次确认。
破坏性变更：
feat作为提交类型。BREAKING CHANGE: 你的变更说明。新特性：
feat作为提交类型。问题修复：
fix作为提交类型。杂项工作：
即所有对下游使用者无任何影响、且没有必要显示在 CHANGELOG 中的改动，例如修改注释、测试用例、开发文档等：
chore,docs,test等作为提交类型。Summary by CodeRabbit
unsafe_penetrate，允许在特定场景下访问全局上下文变量（存在安全风险）。unsafe_penetrate行为的单元测试，确保其生效及上下文优先级正确。unsafe_penetrate的用途和风险提示。