refactor: separate language engine from CLI and server hosts
Verify Aster engine / verify (push) Failing after 0s
Verify Aster engine / verify (push) Failing after 0s
This commit is contained in:
@@ -1,63 +1,15 @@
|
||||
# 运行宿主
|
||||
# 使用引擎
|
||||
|
||||
CLI 提供 VM 引导、源码解析/执行及文件基础信息,Server 提供状态与文件基础信息,二者不连接数据库。Storage 为未来数据库特殊类保留显式连接能力,见 [数据库对象](../runtime/database-objects.md)。以下构建和运行命令仅供用户指定的远端环境,本地不执行。
|
||||
Aster 工作区只产出 Rust 库,不包含 CLI 或 HTTP 可执行文件。宿主在自己的进程中创建 Vm,按需使用 Reader、Frontend 和 Compiler;宿主构建会自动编译所需引擎库。
|
||||
|
||||
## CLI
|
||||
|
||||
下列 Cargo 构建针对 Rust 实现与宿主;Endor 的设计是由平台自动准备字节码并解释执行,无需使用者自行构建程序。当前已有最小 run/eval 源码执行入口,见 [执行与版本模型](../architecture/execution-and-versions.md)。
|
||||
|
||||
工作区要求 Rust 1.91 或兼容更高版本,镜像固定 rust:1.91.1-bookworm,依赖由 Cargo.lock 锁定。
|
||||
|
||||
```sh
|
||||
cargo build --workspace --locked
|
||||
cargo run -p cli -- bootstrap
|
||||
cargo run -p cli -- help
|
||||
cargo run -p cli -- parse crates/frontend/examples/basic.endor
|
||||
cargo run -p cli -- parse - < crates/frontend/examples/basic.endor
|
||||
cargo run -p cli -- parse --json crates/frontend/examples/basic.endor
|
||||
cargo run -p cli -- run crates/compiler/examples/hello.endor
|
||||
cargo run -p cli -- run --entry main crates/compiler/examples/calls.endor
|
||||
cargo run -p cli -- eval - < crates/compiler/examples/literal.endor
|
||||
```
|
||||
|
||||
bootstrap 创建两个 Record,输出 runtime=EndorObject、type_system=disabled、objects_distinct=true 和 heap_objects=2,显式释放后输出 released heap_objects=0。默认无参数执行同一示例。
|
||||
|
||||
parse 通过 EndorReader 严格读取 UTF-8 源码文件;`parse -` 从 stdin 读到 EOF,输入来源为 `<stdin>`,没有 REPL 提示符或会话求值。默认解析 module 模式,成功时输出 Rust Debug 格式的 AstRoot;--mode 支持 expression/interactive,--json 输出带 schema 的 JSON,见 [AST 模型](../runtime/ast.md);失败时输出来源、行、列并返回非零退出码;阅读错误在进入 lexer 前返回。输入适配与 URI provider 见 [阅读器](../runtime/reader.md)。该命令只解析语法,不执行源码;语法与当前边界见 [源码前端](../runtime/frontend.md)。
|
||||
|
||||
run 编译模块、初始化函数并调用无参数入口(默认 main),--entry 可指定名称;eval 执行一个完整表达式。二者支持文件或 - 读取 stdin 到 EOF,输出返回值,失败不输出成功结果。支持范围、命名空间释放及 traceback 精度见 [编译链路](../runtime/compiler.md),真实 Endor 输入见 [可执行示例](../../crates/compiler/examples/README.md);frontend/basic.endor 含算术,仍仅作为解析样例。
|
||||
|
||||
CLI 不读取数据库环境,不创建基础信息数据库表。metadata put/get 通过 host 包写 UTF-8 JSON 文件,metadata import 仅导入缺失记录;示例、配置和协议见 [宿主信息](host-information.md)。输入与退出码见 [cli/src](../../crates/cli/src/README.md)。
|
||||
|
||||
## HTTP
|
||||
|
||||
```sh
|
||||
cargo run -p server
|
||||
curl --fail http://127.0.0.1:8080/health
|
||||
curl --fail http://127.0.0.1:8080/bootstrap
|
||||
```
|
||||
|
||||
Server 创建空 VM 并绑定监听地址,默认 127.0.0.1:8080;通过 host 包写入文件 host.version,不读取数据库 URL、不建表。
|
||||
|
||||
| 端点 | 行为 |
|
||||
| 入口 | 位置与职责 |
|
||||
| --- | --- |
|
||||
| GET /health | 返回 200 和 status=ok;仅表明 HTTP 宿主存活,不包含数据库后端字段 |
|
||||
| GET /bootstrap | 返回 object_model=EndorObject、type_system=false、heap_objects=0;只读、不分配对象 |
|
||||
| [Lyra CLI](https://gitea.entroia.com/Zayden-Jung/endorphin-lyra-cli) | lyra run/eval/parse/bootstrap;命令行文件与 stdin 行为及实际输出报告 |
|
||||
| [Hestia Server](https://gitea.entroia.com/Zayden-Jung/endorphin-hestia-server) | HTTP、管理命令、文件信息、数据库适配、Docker 运维 |
|
||||
| Tessera GUI | 原生窗口、布局、绘制和输入;本地可编译运行,但测试交给 CI |
|
||||
|
||||
没有语言执行、对象写入或认证 API。Unix 上 Ctrl-C/SIGTERM 触发 Axum 优雅退出,最后的 Arc 释放时销毁 Vm;没有数据库池需要在此处关闭,也没有执行中脚本的取消协议。
|
||||
宿主固定子模块提交,再在 Cargo 中引用 crates/core(库名 endor_core)、crates/frontend、crates/compiler。源码编译与返回值根引用契约见 [Compiler](../runtime/compiler.md)、[生命周期](../runtime/lifecycle.md)。宿主不能把另一个 VM 的句柄传入当前 VM。
|
||||
|
||||
## 数据库能力的使用位置
|
||||
引擎没有环境变量、locale 初始化、数据库连接或后台服务。宿主负责源码来源、globals、限额、调度和释放。Aster 本地不构建或测试;验证命令只在 ces-control 执行,见 [验证](validation.md)。旧部署运行资源继续由 Hestia 管理,移除本仓库 CD 不会删除资源。
|
||||
|
||||
当前应用不把数据库作为启动依赖;即使进程带有失效 DATABASE_URL 或 SQLITE_PATH,也不会因此读取它们。特殊类将来需要连接时,宿主适配实现显式传入 DatabaseConfig,详见 [配置](configuration.md)。
|
||||
|
||||
Storage 支持 SQLite 文件/内存和 PostgreSQL,不自带应用 schema 或 key/value 数据模型。旧数据库数据保留原位,发布时只读导入到文件信息;新的普通宿主不会继续写入数据库;数据持久化也不自动保存 VM 堆、句柄或帧。
|
||||
|
||||
## 定位问题
|
||||
|
||||
| 现象 | 定位 |
|
||||
| --- | --- |
|
||||
| Server 无法绑定地址 | ASTER_LISTEN 与端口占用,见 [配置](configuration.md) |
|
||||
| /health 正常但数据库不可用 | health 不检测数据库;当前没有使用数据库的语言类 |
|
||||
| 重启后 VM 对象消失 | 当前未实现 VM 快照,见 [生命周期](../runtime/lifecycle.md) |
|
||||
| 需要连接或查询数据库 | [storage](../../crates/storage/README.md) 和 [数据库对象](../runtime/database-objects.md);先定义实际特殊类接口 |
|
||||
|
||||
容器与预置 PostgreSQL 见 [部署](deployment.md),检查范围见 [验证](validation.md)。返回 [文档索引](../README.md)。
|
||||
本目录:[README.md](README.md) 描述嵌入入口,[configuration.md](configuration.md) 描述配置边界,[validation.md](validation.md) 描述检查。返回 [文档索引](../README.md)。
|
||||
|
||||
@@ -1,73 +1,9 @@
|
||||
# 配置、UTF-8 与进程边界
|
||||
# 引擎配置边界
|
||||
|
||||
## 当前选择
|
||||
Aster 的 objects、core、frontend、compiler 不读取进程环境或修改 locale。输入文本为 UTF-8,其他编码由宿主在创建 SourceUnit 前转换,见 [文本编码](../runtime/text-encoding.md)。
|
||||
|
||||
当前先明确少量稳定边界,不引入 PyPreConfig/PyConfig 式两阶段初始化,也不新增 VM 配置文件、环境变量前缀或配置框架。Vm::new 从空堆启动;监听与网络由宿主处理,数据库连接仅由真正消费它的对象显式请求。
|
||||
Vm::new 创建独立空堆。宿主显式提供 globals 和必要对象;CompileOptions.globals 只声明可见名称,不注入实际值。execute/call 的对象结果拥有根,使用后 release_value。
|
||||
|
||||
| 配置层 | 当前入口 | 责任 |
|
||||
| --- | --- | --- |
|
||||
| 内核 | Vm::new、显式创建对象/函数;call_with_limits/execute_with_limits | 可预测的运行时语义,不读取环境变量、修改 locale、注册信号或加载 .env |
|
||||
| 宿主 | Server 启动代码与 host::MetadataStore | 读取监听/文件信息目录;基础信息存 JSON 文件,不读取数据库配置 |
|
||||
| 数据库对象适配 | DatabaseConnection::connect(&DatabaseConfig) | 显式选择后端后连接,不预设应用表;特殊类尚未接入 |
|
||||
| 部署 | Compose 与 ces-control 脚本 | 端口映射、数据库密码、持久卷和镜像版本 |
|
||||
| 构建/CI | Cargo.toml、Cargo.lock、Dockerfile、工作流 | 工具链、依赖锁定与验证环境;不作为语言运行语义配置 |
|
||||
ExecutionLimits 默认 max_frames=1000、max_instructions=usize::MAX。嵌入方可通过 execute_with_limits/call_with_limits 显式设置有限值。没有内存配额、可靠取消或完整沙箱;原生回调耗时不由指令数限制覆盖。具体契约见 [字节码 VM](../runtime/bytecode.md)。
|
||||
|
||||
内核不直接依赖 HTTP、SQLx 或操作系统 locale 接口。这个隔离来自现有代码与分层,不是已经实现的独立安全沙箱。
|
||||
|
||||
## 为什么不照搬 CPython 的 locale 初始化
|
||||
|
||||
CPython 的 PyPreConfig 支持选择分配器、UTF-8 模式以及是否配置 LC_CTYPE,以处理它自己的启动和兼容性需求。Python 官方也提供忽略环境、保留 LC_CTYPE、不注册信号处理的隔离初始化。当前 Endor 通过 Rust 宿主接收已构造的值,没有需要复刻这套预初始化的依赖环。[CPython 初始化文档](https://docs.python.org/3.14/c-api/init_config.html)。
|
||||
|
||||
LC_CTYPE 处理字符分类、大小写和多字节字符相关约定;小数点和数字分组属于 LC_NUMERIC。只调整 LC_CTYPE 不能直接等同于修改数字小数点,这两类配置应区分。[locale 类别说明](https://docs.python.org/3.14/library/locale.html#locale.LC_CTYPE)。
|
||||
|
||||
云原生环境仍会遇到进程变量、终端、文件路径与外部工具的问题;较少跨语言互操作不代表可以省略输入边界。当前解决方式是让核心语义独立于进程区域设置,把必要的解码留在宿主入口。
|
||||
|
||||
## 当前文本和数字行为
|
||||
|
||||
- Value::Text 与 EndorStringObject 使用 Rust String,内容始终是有效 UTF-8。字符访问按 Unicode 标量值,不按字节或字形簇;不支持孤立代理码点。[Rust String](https://doc.rust-lang.org/std/string/struct.String.html#utf-8)。
|
||||
- Number 的整数与十进制构造器明确检查 ASCII 数字和语法;十进制点为句点,不根据 LANG/LC_NUMERIC 切换为逗号。当前数值比较、哈希和算术尚未实现。
|
||||
- 内核没有 setlocale 调用;不会为了启动 VM 修改 LANG、LC_ALL 或 LC_CTYPE。外部库、终端、字体或下游工具自身的行为不在这项保证之内。
|
||||
- CLI parse 通过 EndorReader 严格读取 UTF-8 文件/stdin,阅读器也接受字符串和宿主 URI provider;来源与解码失败契约见 [阅读器](../runtime/reader.md)。Frontend 提供基础标识符与语法解析,见 [源码前端](../runtime/frontend.md)。尚无通用字节串对象、语言文件系统 API 或非 UTF-8 源码自动转码入口。
|
||||
|
||||
日文与外部 Shift_JIS/CP932 的处理见 [文本编码](../runtime/text-encoding.md);内部 UTF-8 不因地区切换。
|
||||
|
||||
## 已有进程与部署变量
|
||||
|
||||
| 名称 | 使用位置与默认值 | 错误和优先级 |
|
||||
| --- | --- | --- |
|
||||
| ASTER_STATE_DIR | Host 文件信息目录;默认 data/host,容器 /data/host | 使用 var_os 保留操作系统路径;显式空值报错,不影响数据库选择 |
|
||||
| ASTER_LISTEN | Server;默认 127.0.0.1:8080 | 当前 var(...).unwrap_or_else:缺失或非 Unicode 都用默认值;有效 Unicode 的错误地址在绑定时失败 |
|
||||
| ASTER_PORT | Compose 宿主端口映射 | 独立方案默认 8080,ces-control 默认 18081;不是 Vm 配置 |
|
||||
| POSTGRES_PASSWORD | PostgreSQL Compose/生产环境文件 | Compose 必填;示例使用随机十六进制以避免 URL 转义歧义;不写入仓库 |
|
||||
| ASTER_IMAGE | ces-control Compose | 必填已构建的版本镜像,通常由 release.env 提供 |
|
||||
| ASTER_RELEASE_SHA | CI 与部署脚本 | 必须为 40 位小写十六进制提交 SHA;用于镜像和版本目录 |
|
||||
| ASTER_TEST_POSTGRES_URL | 指定环境显式运行 PostgreSQL 集成测试 | 专用测试库 URL;不是生产数据库配置 |
|
||||
|
||||
文件信息命令及 Server 通过 host 包读取 ASTER_STATE_DIR,Server 还读取 ASTER_LISTEN;不会把 DATABASE_URL/SQLITE_PATH 作为基础信息存储配置。程序不自动加载 .env,Cargo 运行时须显式导出监听变量。Compose 会按其规则读取 .env;显式 --env-file 的生产文件由部署脚本管理。模板见 [.env.example](../../.env.example),执行链见 [部署](deployment.md)。
|
||||
|
||||
## 显式数据库配置
|
||||
|
||||
DatabaseConfig 没有默认值和 from_env,仅允许显式构造:Postgres(url)、SqliteFile(path)、SqliteMemory。没有默认 data/aster.db,也没有应用启动时的全局连接。connect 不执行应用 DDL,不保存基础信息;基础信息另由 [host 文件层](host-information.md) 保存;未来的特殊类负责消费连接和定义数据,见 [数据库对象](../runtime/database-objects.md)。
|
||||
|
||||
SQLite 文件显式连接时创建父目录与文件、启用 WAL,最多 5 个连接、busy timeout 5 秒;内存库单连接、不因池轮换销毁。PostgreSQL 最多 5 个连接、获取超时 5 秒,错误不降级。数据库 URL 的 Debug 和公开错误脱敏;底层错误 source 保留,不应不加处理地公开输出。
|
||||
|
||||
## 已有执行限额
|
||||
|
||||
ExecutionLimits 是每次调用显式传入的普通 Rust 值,不是进程全局开关;字段定义见 [frame.rs](../../crates/core/src/frame.rs)。
|
||||
|
||||
| 字段 | 默认值 | 作用 |
|
||||
| --- | --- | --- |
|
||||
| max_frames | 1000 | 本次执行允许的活动语言帧数量 |
|
||||
| max_instructions | usize::MAX | 本次执行共享的逻辑指令预算;默认不设实用的有限预算 |
|
||||
|
||||
call_with_limits/execute_with_limits 使用自定义值;嵌套语言调用共用计数。预算不能抢占正在执行的 Native 回调,也没有超时、内存上限或异步取消能力;不能据此视为安全执行不可信代码的完整方案。
|
||||
|
||||
## 保留的入口缺口与以后再做的内容
|
||||
|
||||
CLI 当前使用 std::env::args,遇到非 Unicode 命令行参数可能 panic,并没有统一转换成友好的配置错误。[Rust args 文档](https://doc.rust-lang.org/std/env/fn.args.html#panics)。Server 的非 Unicode ASTER_LISTEN 也尚未严格报错;宿主输入错误接口尚未统一。
|
||||
|
||||
以后增加宿主输入时,应明确使用 OsString/PathBuf 保留系统路径,或显式拒绝不符合文本协议的输入;不要通过修改整个进程 locale 让隐式解码暂时成功。未来源码文本默认 UTF-8、协议数字固定格式是设计方向,只有加载器实现后才能写成已实现行为。
|
||||
|
||||
现在不新增通用 VmConfig。出现构造期策略时再集中为实例级不可变配置;进程参数由宿主解析后传入,不让 Vm::new 自动读取一组隐含开关。时区、模块路径、凭据注入、内存配额和网络能力也按实际实现分别设计,不预设已存在。
|
||||
|
||||
返回 [运行指南](README.md) 或 [文档索引](../README.md)。
|
||||
ASTER_LISTEN、ASTER_STATE_DIR、数据库 URL 和部署配置属于独立宿主,不属于引擎设置。旧兼容标识由 Hestia 管理。返回 [使用引擎](README.md)。
|
||||
|
||||
@@ -1,74 +0,0 @@
|
||||
# Docker 与 ces-control 部署
|
||||
|
||||
这里描述仓库当前工作流和脚本行为,不代表正在运行的服务器状态。生产保留预置 PostgreSQL 与既有数据。当前 VM 宿主不消费数据库,数据库连接仅为未来特殊类保留。配置字段见 [配置](configuration.md),CI 检查细节见 [验证](validation.md)。
|
||||
|
||||
## 镜像与独立运行
|
||||
|
||||
Dockerfile 的 source 阶段复制 Cargo 工作区及脚本;ci 阶段安装远端检查工具,build 阶段构建 server 和 cli,runtime 阶段使用 Debian slim、UID 10001、/data 工作目录及 HTTP 健康检查。
|
||||
|
||||
指定环境的独立宿主方案(沿用原 SQLite 卷,基础信息写入其中的 host 目录):
|
||||
|
||||
```sh
|
||||
cp .env.example .env
|
||||
docker compose up --build -d
|
||||
curl --fail http://127.0.0.1:8080/health
|
||||
docker compose exec aster cli bootstrap
|
||||
```
|
||||
|
||||
默认 docker-compose.yml 提供监听地址和 ASTER_STATE_DIR,保留 aster-sqlite 卷挂载;只写基础信息 JSON,不自动打开卷中的数据库。down 保留数据,down -v 会删除卷。
|
||||
|
||||
指定环境中同时预置 PostgreSQL 的独立方案:先在 .env 中将 POSTGRES_PASSWORD 改为随机十六进制字符串,例如 openssl rand -hex 24,再运行:
|
||||
|
||||
```sh
|
||||
docker compose -f docker-compose.postgres.yml up --build -d
|
||||
docker compose -f docker-compose.postgres.yml exec aster cli bootstrap
|
||||
```
|
||||
|
||||
仅使用该 Compose 文件,不与默认文件叠加。此方案使用 aster-postgres 命名卷、PostgreSQL 17,以及独立的 aster-host 文件信息卷;数据库不发布宿主端口。两个独立方案不要同时占用相同应用端口。未来特殊类跨不可信网络连接数据库时,需要明确配置 PostgreSQL TLS 验证。
|
||||
|
||||
## CI 到正式发布
|
||||
|
||||
[工作流](../../.gitea/workflows/README.md) 响应 main push 和 workflow_dispatch,在 ces-control 上串行运行:
|
||||
|
||||
1. 检出代码,调用 ci-ces-control.sh;在 Docker 中检查 workspace(含 SQLite 适配)、Endor 示例实际输出、独立 HTTP 冒烟及专用真实 PostgreSQL。清理检查容器前复制报告到宿主 ci-output,工作流无论验证成功或失败均展示并上传 endor-execution-output-<sha> artifact;字段与位置见 [验证报告](validation.md)。
|
||||
2. 检查成功后构建 endorphin-aster-vm:<sha> 生产镜像。
|
||||
3. main 上调用 deploy-ces-control.sh 更新 VM 宿主并保留预置 PostgreSQL。
|
||||
|
||||
临时检查容器与网络退出时清理,Cargo 下载与构建缓存保留在专属远端卷。生产镜像、已有发布目录与数据库数据保留;没有自动 image prune 或数据库卷清理。工作流不改动其他项目或共享 Runner 配置。
|
||||
|
||||
## 生产目录与数据
|
||||
|
||||
Cargo 包名为 core/objects/frontend/compiler/storage/host/cli/server,core 的 Rust 库名为 endor_core,可执行文件为 cli/server。Compose 应用服务名 aster、数据库名、卷和生产路径是已有部署资源标识,运行命令为该服务中的 cli。应用不接收 DATABASE_URL、不依赖数据库健康才能启动;Compose 的整体 --wait 仍检查所预置 PostgreSQL 的就绪状态。
|
||||
|
||||
| 路径 | 用途 |
|
||||
| --- | --- |
|
||||
| /opt/endorphin-aster-vm/releases/<sha>/ | 固定版本的 compose.yml 与 release.env |
|
||||
| /opt/endorphin-aster-vm/current | 最近通过部署检查的版本符号链接 |
|
||||
| /etc/endorphin-aster-vm/production.env | 首次生成的数据库密码和默认端口,权限 0600 |
|
||||
| /var/lib/endorphin-aster-vm/host | 文件基础信息,挂载到 /data/host,目录由部署准备并交给 UID 10001 |
|
||||
| /var/lib/endorphin-aster-vm/postgres | 独立的 PostgreSQL 持久数据目录 |
|
||||
| /var/lock/endorphin-aster-vm-deploy.lock | 避免并行切换生产版本的文件锁 |
|
||||
|
||||
生产 Compose 固定项目名 endorphin-aster-vm,默认应用入口仅绑定 127.0.0.1:18081;数据库不发布端口,两个服务使用 unless-stopped 自动重启和日志轮换。端口绑定回环地址不等于已实现应用认证。
|
||||
|
||||
部署脚本只接受已构建镜像。容器就绪、HTTP status=ok 和 CLI 对象引导/释放检查都成功后才切换 current;发布记录改写到 deployment.release.json;首次发布一次性只读导入旧基础信息,再保留完成标记,不删除数据库原记录。详情见 [宿主信息](host-information.md)。镜像 SHA、release.env 与 current 链接负责标识版本。失败时保留数据并尝试恢复上一个健康版本;首次部署没有旧版本可恢复。脚本内容导航见 [scripts](../../scripts/README.md)。
|
||||
|
||||
这里的镜像 SHA、host.version 与 deployment.release 标识 Rust 实现/宿主发布,不是 Endor 用户资源的源码修订。平台方向是统一升级解释器,保留用户源码修订及明确的依赖选择;当前没有资源存储、依赖锁、持久化字节码缓存或执行帧热切换机制。两类版本的边界见 [执行与版本模型](../architecture/execution-and-versions.md)。
|
||||
|
||||
## 查看、停止与恢复
|
||||
|
||||
以下命令在服务器上使用已有生产配置,不重新生成密码:
|
||||
|
||||
```sh
|
||||
docker compose -p endorphin-aster-vm --env-file /etc/endorphin-aster-vm/production.env --env-file /opt/endorphin-aster-vm/current/release.env -f /opt/endorphin-aster-vm/current/compose.yml ps
|
||||
curl --fail http://127.0.0.1:18081/health
|
||||
curl --fail http://127.0.0.1:18081/bootstrap
|
||||
```
|
||||
|
||||
同样的 Compose 参数接 stop 停服保留数据,接 up -d --wait 恢复。不要删除数据目录或使用删除卷的操作代替停服。
|
||||
|
||||
更改环境文件密码不会自动修改已有 PostgreSQL 数据库用户密码;需另行同步数据库凭据。数据库 major 升级、schema 变更需要迁移设计,恢复旧应用镜像不等于回退数据库。
|
||||
|
||||
Compose 配置依据 [Docker 环境变量说明](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/),触发方式依据 [Gitea Actions](https://docs.gitea.com/usage/actions/)。按用户约定不主动追踪运行状态;需要排障时针对具体提交核实,不能用旧成功记录推断新版本结果。
|
||||
|
||||
返回 [运行指南](README.md) 或 [文档索引](../README.md)。
|
||||
@@ -1,47 +0,0 @@
|
||||
# 宿主基础信息:文件保存
|
||||
|
||||
基础信息不使用数据库。host 包保存逐键 UTF-8 JSON,CLI 提供读写,Server 启动写 host.version,部署检查通过后写 deployment.release。Storage 的数据库连接仅给未来特殊类使用。
|
||||
|
||||
## 文件与配置
|
||||
|
||||
ASTER_STATE_DIR 使用操作系统路径,默认 data/host;显式空值报错。读取一个不存在的键返回 None,不创建目录;写入时创建目录。容器为 /data/host;生产挂载到 /var/lib/endorphin-aster-vm/host,独立 PostgreSQL Compose 使用 aster-host 卷。
|
||||
|
||||
例如 host.version 对应 host.version.json:
|
||||
|
||||
```json
|
||||
{
|
||||
"format_version": 1,
|
||||
"key": "host.version",
|
||||
"value": "0.1.0"
|
||||
}
|
||||
```
|
||||
|
||||
控制键以 ASCII 字母或数字开头,最长 128 字节,其余只能是字母、数字、点、下划线或连字符。它是信息命名协议,不是文本编码限制;值支持日文、中文、emoji 等 Unicode 文本。用户文本不应被当作文件路径或控制键。
|
||||
|
||||
文件必须是有效 UTF-8 JSON,版本和 key 必须匹配请求。损坏记录返回错误,不清空、不用默认值偷偷替换。文件不属于 VM 堆快照,也不存数据库凭据。
|
||||
|
||||
## 读写与生命周期
|
||||
|
||||
CLI 的 metadata put/get 通过 host::MetadataStore 访问文件,不连接 SQL:
|
||||
|
||||
```sh
|
||||
cli metadata put project.note '日本語・中文・😀'
|
||||
cli metadata get project.note
|
||||
cli metadata get host.version
|
||||
```
|
||||
|
||||
MetadataStore::clone 只共享目录路径,没有缓存;每次读取重新打开文件。写入先建立同目录唯一临时文件,写完并 sync_all,再通过 rename 发布;Unix 新文件权限 0600。不同键分别写文件,不会因整张 map 的读改写丢失其他键;同键并发是最后一次成功发布生效。
|
||||
|
||||
没有跨键事务、分布式锁或共享网络文件系统一致性保证;文件同步与原子发布也不等于数据库的完整断电持久性协议。异常进程终止可能留下隐藏临时文件,正常失败会清理自己的临时文件。
|
||||
|
||||
## 旧基础信息的一次性迁移
|
||||
|
||||
ces-control 发布时,在 host/.legacy-imported 标记缺失的情况下,只读检查 PostgreSQL 原 public.aster_metadata 表。存在时,使用 UTF-8 客户端导出 key/value JSON,再经 cli metadata import 的标准输入导入。该命令只创建缺失文件,不覆盖 Server 刚写入的版本或其他已有文件;临时导出文件以私有权限创建并清理,不打印数据内容。
|
||||
|
||||
只导入缺失项通过同目录临时文件的原子 hard_link 实现,因此运行目录应使用支持该操作的本地文件系统。导入可重复执行;只有导入成功或源表不存在才写完成标记。损坏记录、不支持的控制键或 I/O 错误会停止发布,保留原库数据,不能当作迁移成功。
|
||||
|
||||
本迁移针对已配置的 PostgreSQL 生产路径,不自动扫描或删除其他 SQLite 文件。原数据库表与数据不会被修改/删除。此处说明发布脚本行为,不代表远端已执行成功;按约定不主动跟踪 CI 或服务器。
|
||||
|
||||
部署记录仍以版本镜像、release.env 与 current 链接为发布来源;deployment.release.json 是文件信息记录,不是数据库迁移表。脚本见 [scripts](../../scripts/README.md)。
|
||||
|
||||
返回 [运行指南](README.md) 或 [文档索引](../README.md)。
|
||||
@@ -1,62 +1,13 @@
|
||||
# 验证范围与结果边界
|
||||
# 引擎验证
|
||||
|
||||
本页维护当前检查入口和覆盖范围,不累计已失效的测试数量、机器资源快照或旧对象模型的通过记录。历史行为查 Git 历史;某个版本是否通过,只能依据该提交对应的实际结果。
|
||||
本地不运行 Cargo 构建、测试、Clippy、冒烟、Docker 或依赖下载。允许静态阅读、格式化、ASDL 生成/同步检查及文档链接检查;运行验证交给 ces-control。不主动查询 CI/部署结果。
|
||||
|
||||
## 执行约定
|
||||
[ci.yml](../../.gitea/workflows/ci.yml) 在 main push、pull request 和手动触发时运行引擎 CI,标签为 ces-control。Dockerfile.ci 只提供远端 Rust 1.91.1 验证环境,不生成生产服务镜像或执行部署。
|
||||
|
||||
本地不运行 Cargo 构建、测试、Clippy、冒烟、Docker 或依赖下载;允许阅读、格式化、ASDL 源码生成/产物同步检查和静态文件/文档检查。指定运行验证环境为 ces-control。按用户要求不主动追踪 CI/部署结果,有问题由用户反馈后再查。
|
||||
远端的 scripts/check.sh 验证 ASDL 产物、生成器回归、Cargo 格式、独立 PEG 文件格式、cargo test --workspace --locked 和 Clippy;包括 objects/core 的对象与执行测试、frontend 的读取/AST/语法测试、compiler 的名称分析/源码执行测试及 rustdoc。Compiler 的五个源码样例继续位于 crates/compiler/examples。
|
||||
|
||||
## 检查入口
|
||||
五个样例的真实命令行输出报告改由 [Lyra CI](https://gitea.entroia.com/Zayden-Jung/endorphin-lyra-cli) 调用真实 lyra 可执行文件生成,保存源码、预期/实际 stdout、stderr 和退出码;失败也保留 artifact。Aster 的编译器测试与 Lyra 的可执行程序测试是不同层次,消费者的 cargo test 不会自动运行依赖库的全部自身测试。
|
||||
|
||||
以下命令只在指定的验证环境执行,不表示已经运行:
|
||||
HTTP、宿主 JSON、SQLite 与真实 PostgreSQL 测试归 [Hestia CI](https://gitea.entroia.com/Zayden-Jung/endorphin-hestia-server)。Aster 无 CD;现有服务和数据由 Hestia 的独立部署定义保留。CI 的 bot SSH 凭据要求见 [.gitea](../../.gitea/README.md)。源码和工作流定义不证明运行通过;未查询时结果记为未核实。
|
||||
|
||||
```sh
|
||||
sh scripts/check.sh
|
||||
cargo test -p storage --test postgres --locked -- --ignored
|
||||
python3 scripts/smoke.py
|
||||
```
|
||||
|
||||
check.sh 先运行 generate_ast.py --check 验证 ASDL 产物同步,以及仅远端执行的 test_generate_ast.py 生成器回归检查、test_endor_examples.py 报告失败路径检查,再执行 cargo fmt --all --check、独立词法/语法文件的 rustfmt --edition 2024 --check crates/frontend/src/lexer.peg crates/frontend/src/grammar.peg、cargo test --workspace --locked 和 cargo clippy --workspace --all-targets --locked -- -D warnings。workspace 测试也包含 rustdoc 示例;显式忽略的 PostgreSQL 测试需要单独执行。
|
||||
|
||||
ci-ces-control.sh 负责准备全新专用临时 PostgreSQL 和测试 URL;成功路径使用真实数据库,不用模拟 socket 代替。测试库与生产数据不共享挂载。没有 ASTER_TEST_POSTGRES_URL 时,显式执行 PostgreSQL 测试会失败,不标记为通过。
|
||||
|
||||
## Endor 示例实际输出
|
||||
|
||||
在对应 Gitea 仓库的 Actions → 本次提交的 run 页面,打开 Show Endor example execution output 步骤可看实际运行报告;下载 endor-execution-output-<sha> artifact 可保存两种格式:
|
||||
|
||||
- endor-examples.md:逐例展示源码、执行命令、预期值、实际 stdout/stderr、退出码和 PASS/FAIL/NOT_RUN。
|
||||
- endor-examples.json:保留精确输出(包括换行)、提交 SHA、UTC 时间、构建/定位命令结果和逐例状态,供工具读取。
|
||||
|
||||
[endor_examples.py](../../scripts/endor_examples.py) 构建真实 CLI,通过 Cargo metadata 定位二进制并执行 [cases.json](../../crates/compiler/examples/cases.json) 中的全部示例;不以预期值冒充实际值。stdout 必须精确匹配、stderr 为空且退出码为 0 才通过。单例超时 30 秒;构建失败不运行示例并标记 NOT_RUN;报告本身的异常标记 FAIL。一个案例失败仍收集后续案例。示例报告不代表 workspace、数据库、宿主和部署全部通过,整体结果仍看工作流。
|
||||
|
||||
ci-ces-control.sh 在检查容器退出后、清理前将两份文件复制到宿主 ci-output;验证步骤提前失败时已有 NOT_RUN 占位说明。报告运行不掩盖前面检查的失败;后续数据库或宿主检查失败也不丢报告。工作流用 always() 展示并上传,artifact 保留 30 天,不写进 Git 或生产数据目录。普通 Actions 日志仍保留完整测试/构建信息;报告上传失败会使工作流失败。
|
||||
|
||||
## 覆盖范围与文件位置
|
||||
|
||||
| 范围 | 当前检查内容 | 入口 |
|
||||
| --- | --- | --- |
|
||||
| 堆内部边界 | 非法索引、槽位代数、代数耗尽、计数溢出原子性 | [objects/src](../../crates/objects/src/README.md) 的 heap.rs 私有单元测试 |
|
||||
| 独立对象存储 | 不依赖 VM 的稳定地址、跨存储拒绝、更新失败原子性、循环回收、函数校验与共享代码所有权 | [objects/tests](../../crates/objects/tests/README.md) 的 store.rs |
|
||||
| 对象运行时 | 地址稳定、引用/借用、属性、长链、循环、原生操作、VM 销毁 | [core/tests](../../crates/core/tests/README.md) 的 runtime.rs |
|
||||
| 基本对象 | Number 表示、字符串、Dict/Cell 引用与更新、函数环境、异常数据 | 同目录 builtins.rs |
|
||||
| 字节码 | 编解码、非法指令/控制流、跳转、调用、闭包、字节码创建函数/默认值/环境捕获、函数创建及后续失败清理、结果存活与限额 | 同目录 execution.rs |
|
||||
| Endor 阅读器 | 字符串、分块 UTF-8 流、文件、读取失败、URI provider、修订标签与来源诊断 | [frontend/tests](../../crates/frontend/tests/README.md) 的 reader.rs |
|
||||
| AST 与接口生成 | 三类根、声明/语句层次、Visitor 及失败退出、Unicode 位置、JSON 往返、schema/范围错误和跨语言产物标识 | frontend/tests/ast.rs 与 scripts/test_generate_ast.py,见 [AST 模型](../runtime/ast.md) |
|
||||
| 源码前端 | 字符 PEG 词法边界、逐 Token 原文位置与首个错误诊断、Unicode 范围、数字原文、字符串与错误、优先级/结合性、函数/绑定、完整输入与错误位置、源码样例 | [frontend/tests](../../crates/frontend/tests/README.md) |
|
||||
| 源码编译与执行 | 真实 Endor 文件到 VM、名称/初始化检查、参数与函数值、精确常量、宿主成员回调、跨 VM 模板、错误清理、递归限额、交互命名空间及扩展操作数 | [compiler/tests](../../crates/compiler/tests/README.md) |
|
||||
| CLI 执行 | run/eval 文件与 stdin、入口、返回值、语义/编译/运行错误、traceback 和退出码 | [cli/tests](../../crates/cli/tests/README.md) |
|
||||
| CLI 解析 | AST 输出、未执行源码、文件/stdin 来源和行列错误、EOF 读取与非法 UTF-8 退出 | [cli/tests](../../crates/cli/tests/README.md) |
|
||||
| 公开示例 | 对象操作、手写指令执行与释放 | objects 与 core 的 src/lib.rs rustdoc,见 [objects/src](../../crates/objects/src/README.md)、[core/src](../../crates/core/src/README.md) |
|
||||
| 宿主文件信息 | UTF-8 值/路径、持久读取、同键替换、并发、坏记录、幂等迁移与保留新值 | [host/tests](../../crates/host/tests/README.md) |
|
||||
| 数据库连接 | 不自动建表、显式配置、隔离/共享、调用方数据重连、失败不降级、真实 PostgreSQL | [storage/tests](../../crates/storage/tests/README.md) |
|
||||
| 端到端宿主 | 文件 metadata 跨进程读写、日文值、Server 文件版本;忽略失效数据库变量且不创建 SQLite 文件、HTTP 与 SIGTERM | [scripts](../../scripts/README.md) 的 smoke.py |
|
||||
|
||||
测试源码说明验证意图,不能证明已通过;现有测试也不代表完整 Python 兼容、panic 恢复、云沙箱或 VM 快照已经实现。
|
||||
|
||||
## 文档修改的静态检查
|
||||
|
||||
修改后核对所有受版本管理目录存在 README、父目录有入口、相对链接指向现存文件;运行 git diff --check 检查差异空白。静态文本检索可以查出旧路径和过时 API;维护规则见 [开发与文档维护](../contributing/README.md)。这些检查不执行 VM 或数据库。
|
||||
|
||||
仅修改文档时也不据此宣称运行检查通过。推送触发现有 CI 时,仍由原流程检查和部署;报告应分别说明静态检查、运行测试与推送结果。
|
||||
|
||||
返回 [运行指南](README.md) 或 [文档索引](../README.md)。
|
||||
返回 [使用引擎](README.md)。
|
||||
|
||||
Reference in New Issue
Block a user