feat: establish Hestia server with preserved deployment resources
Verify Hestia server / verify (push) Failing after 0s

This commit is contained in:
2026-10-20 01:10:02 +08:00
commit 85ca0cd124
54 changed files with 3713 additions and 0 deletions
+10
View File
@@ -0,0 +1,10 @@
# Hestia 宿主包
| 目录 | 职责 |
| --- | --- |
| [server](server/README.md) | HTTP server,依赖固定 Aster core 和本地 host |
| [admin](admin/README.md) | 兼容 cli 二进制,只提供 bootstrap 与文件信息管理 |
| [host](host/README.md) | UTF-8 JSON 基础信息,不连接数据库 |
| [storage](storage/README.md) | 特殊类未来使用的显式 SQLite/PostgreSQL 适配 |
Aster 代码位于 vendor/aster,不复制引擎实现。返回 [项目入口](../README.md)。
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "admin"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
[[bin]]
name = "cli"
path = "src/main.rs"
[dependencies]
core.workspace = true
host.workspace = true
[lints]
workspace = true
+3
View File
@@ -0,0 +1,3 @@
# 兼容管理程序
Cargo 包名 admin,二进制 cli。仅提供 bootstrap、metadata put/get/import 和 help,保持既有部署脚本兼容。源码位于 [src](src/README.md),Cargo.toml 声明固定 Aster core 和本地 host 依赖。语言执行命令属于独立 Lyra。返回 [crates](../README.md)。
+3
View File
@@ -0,0 +1,3 @@
# 管理命令实现
main.rs 负责对象引导与释放、宿主 JSON 读写和缺失键导入;不提供 run/eval/parse,也不连接数据库。运行验证由 scripts/smoke.py 覆盖。返回 [admin](../README.md)。
+68
View File
@@ -0,0 +1,68 @@
use std::error::Error;
use std::process::ExitCode;
use endor_core::{Value, Vm};
use host::MetadataStore;
const USAGE: &str = "Usage: cli [bootstrap | metadata put <key> <value> | metadata get <key> | metadata import | help]";
fn main() -> ExitCode {
match run() {
Ok(()) => ExitCode::SUCCESS,
Err(error) => {
eprintln!("cli: {error}");
ExitCode::FAILURE
}
}
}
fn run() -> Result<(), Box<dyn Error>> {
let args: Vec<String> = std::env::args().skip(1).collect();
match args
.iter()
.map(String::as_str)
.collect::<Vec<_>>()
.as_slice()
{
[] | ["bootstrap"] => {
let mut vm = Vm::new()?;
let first = vm.new_object()?;
let second = vm.new_object()?;
vm.set_attr(
first,
"message",
Value::Text("Hello from EndorObject".into()),
)?;
println!("runtime=EndorObject type_system=disabled");
println!(
"objects_distinct={} heap_objects={}",
first != second,
vm.object_count()
);
vm.release(first)?;
vm.release(second)?;
println!("released heap_objects={}", vm.object_count());
println!("bootstrap uses no database");
}
["help"] | ["--help"] | ["-h"] => println!("{USAGE}"),
["metadata", "put", key, value] => {
MetadataStore::from_env()?.put(key, value)?;
println!("stored (file)");
}
["metadata", "get", key] => {
println!(
"{}",
MetadataStore::from_env()?
.get(key)?
.as_deref()
.unwrap_or("(missing)")
);
}
["metadata", "import"] => {
let count = MetadataStore::from_env()?.import_missing(std::io::stdin().lock())?;
println!("imported {count} missing entries (file)");
}
_ => return Err(USAGE.into()),
}
Ok(())
}
+16
View File
@@ -0,0 +1,16 @@
[package]
name = "host"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
[dependencies]
serde.workspace = true
serde_json.workspace = true
[dev-dependencies]
tempfile = "3"
[lints]
workspace = true
+11
View File
@@ -0,0 +1,11 @@
# host
宿主基础信息的文件层,与 Core 和数据库 Storage 分开。CLI/Server 使用它保存 host.version、deployment.release 和其他命名信息;不打开数据库,不保存 VM 堆。
| 内容 | 职责 |
| --- | --- |
| Cargo.toml | host 包、Serde/JSON 依赖及远端检查依赖 |
| [src](src/README.md) | MetadataStore、UTF-8 JSON 文件与迁移导入 |
| [tests](tests/README.md) | 持久读取、替换、并发、坏记录、路径边界和幂等导入 |
ASTER_STATE_DIR 指定信息目录;默认 data/host,容器使用 /data/host。协议、生命周期及旧数据库一次性迁移见 [宿主信息](../../docs/operations/host-information.md)。返回 [工作区](../README.md)。
+8
View File
@@ -0,0 +1,8 @@
# Host 源码导航
| 文件 | 职责 |
| --- | --- |
| [lib.rs](lib.rs) | 导出 MetadataStore,明确文件层不依赖 VM 或 SQL |
| [metadata.rs](metadata.rs) | 目录配置、键校验、逐键 JSON 读取/同步写入、原子发布、仅导入缺失项 |
文件数据以 UTF-8 JSON 保存,操作系统路径用 PathBuf;坏记录不自动覆盖。每个键独立发布,不提供多键事务。旧库导入不覆盖新文件,规则见 [宿主信息](../../../docs/operations/host-information.md)。返回 [host](../README.md)。
+4
View File
@@ -0,0 +1,4 @@
//! Host information stored in UTF-8 JSON files, independently of the VM and SQL.
mod metadata;
pub use metadata::MetadataStore;
+172
View File
@@ -0,0 +1,172 @@
use std::fs::{self, OpenOptions};
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use serde::{Deserialize, Serialize};
static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
const FORMAT_VERSION: u32 = 1;
#[derive(Deserialize)]
struct LegacyRecord {
key: String,
value: String,
}
#[derive(Serialize, Deserialize)]
struct Record {
format_version: u32,
key: String,
value: String,
}
/// One independently replaceable JSON file per ASCII metadata key. Clones
/// share a directory, not a cached map; reads always observe the file system.
#[derive(Debug, Clone)]
pub struct MetadataStore {
directory: PathBuf,
}
impl MetadataStore {
/// Does not create the directory until the first write.
pub fn new(directory: impl Into<PathBuf>) -> io::Result<Self> {
let directory = directory.into();
if directory.as_os_str().is_empty() {
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
"metadata directory is empty",
));
}
Ok(Self { directory })
}
/// Preserve OS paths without requiring the environment value to be UTF-8.
pub fn from_env() -> io::Result<Self> {
Self::new(
std::env::var_os("ASTER_STATE_DIR")
.map(PathBuf::from)
.unwrap_or_else(|| PathBuf::from("data/host")),
)
}
pub fn directory(&self) -> &Path {
&self.directory
}
pub fn get(&self, key: &str) -> io::Result<Option<String>> {
let path = self.path(key)?;
let bytes = match fs::read(path) {
Ok(bytes) => bytes,
Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(None),
Err(error) => return Err(error),
};
let record: Record = serde_json::from_slice(&bytes)
.map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
if record.format_version != FORMAT_VERSION || record.key != key {
return Err(io::Error::new(
io::ErrorKind::InvalidData,
"metadata key or format version mismatch",
));
}
Ok(Some(record.value))
}
/// Writes a new sibling file, syncs it, then publishes it with rename.
/// Different keys do not share a read/modify/write map. For the same key,
/// the last successful rename wins. This is not a multi-key transaction.
pub fn put(&self, key: &str, value: &str) -> io::Result<()> {
self.store(key, value, true).map(|_| ())
}
/// One-time migration input: a JSON array of key/value string records.
/// Validate all keys first, and never overwrite an existing file record.
pub fn import_missing(&self, reader: impl Read) -> io::Result<usize> {
let records: Vec<LegacyRecord> = serde_json::from_reader(reader)
.map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
for record in &records {
self.path(&record.key)?;
}
let mut imported = 0;
for record in records {
if self.store(&record.key, &record.value, false)? {
imported += 1;
} else if self.get(&record.key)?.is_none() {
return Err(io::Error::new(
io::ErrorKind::NotFound,
"existing metadata disappeared during import",
));
}
}
Ok(imported)
}
fn store(&self, key: &str, value: &str, replace: bool) -> io::Result<bool> {
let destination = self.path(key)?;
let mut contents = serde_json::to_vec_pretty(&Record {
format_version: FORMAT_VERSION,
key: key.into(),
value: value.into(),
})
.map_err(io::Error::other)?;
contents.push(b'\n');
fs::create_dir_all(&self.directory)?;
for _ in 0..32 {
let sequence = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
let temporary = self
.directory
.join(format!(".{key}.{}.{sequence}.tmp", std::process::id()));
let mut options = OpenOptions::new();
options.write(true).create_new(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt;
options.mode(0o600);
}
let mut file = match options.open(&temporary) {
Ok(file) => file,
Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue,
Err(error) => return Err(error),
};
let result = (|| {
file.write_all(&contents)?;
file.sync_all()?;
drop(file);
if replace {
fs::rename(&temporary, &destination)?;
Ok(true)
} else {
// Atomic create-if-absent: a concurrent writer's record
// cannot be replaced by the legacy import.
match fs::hard_link(&temporary, &destination) {
Ok(()) => Ok(true),
Err(error) if error.kind() == io::ErrorKind::AlreadyExists => Ok(false),
Err(error) => Err(error),
}
}
})();
let _ = fs::remove_file(&temporary);
return result;
}
Err(io::Error::new(
io::ErrorKind::AlreadyExists,
"cannot reserve a metadata temporary file",
))
}
fn path(&self, key: &str) -> io::Result<PathBuf> {
if key.is_empty()
|| key.len() > 128
|| !key.as_bytes()[0].is_ascii_alphanumeric()
|| !key
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
{
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
"metadata keys must start with an ASCII letter/digit and contain at most 128 ASCII letters, digits, dots, underscores or hyphens",
));
}
Ok(self.directory.join(format!("{key}.json")))
}
}
+5
View File
@@ -0,0 +1,5 @@
# Host 文件信息检查
[metadata.rs](metadata.rs) 检查缺失读取不建目录、日文/中文/emoji 值和日文路径、重开与同键替换、非法键不越界、坏 JSON/版本/键不匹配不改原文件、并发替换可见完整记录,以及旧记录幂等导入和保留更新值。
检查使用临时目录,仅在指定远端环境运行。本地不执行文件行为测试;当前是否通过应以对应提交的 CI 为准。命令见 [验证](../../../vendor/aster/docs/operations/validation.md),返回 [host](../README.md)。
+131
View File
@@ -0,0 +1,131 @@
use host::MetadataStore;
#[test]
fn missing_reads_do_not_create_state() {
let temporary = tempfile::tempdir().unwrap();
let directory = temporary.path().join("state");
let store = MetadataStore::new(&directory).unwrap();
assert_eq!(store.get("missing").unwrap(), None);
assert!(!directory.exists());
}
#[test]
fn utf8_values_survive_reopening_and_same_key_replacement() {
let temporary = tempfile::tempdir().unwrap();
let directory = temporary.path().join("日本語");
let store = MetadataStore::new(&directory).unwrap();
store.put("host.version", "0.1.0").unwrap();
store.put("project.note", "日本語・中文・😀").unwrap();
let reopened = MetadataStore::new(&directory).unwrap();
assert_eq!(
reopened.get("project.note").unwrap().as_deref(),
Some("日本語・中文・😀")
);
reopened.put("host.version", "0.2.0").unwrap();
assert_eq!(store.get("host.version").unwrap().as_deref(), Some("0.2.0"));
assert_eq!(
store.get("project.note").unwrap().as_deref(),
Some("日本語・中文・😀")
);
let record: serde_json::Value =
serde_json::from_slice(&std::fs::read(directory.join("project.note.json")).unwrap())
.unwrap();
assert_eq!(record["format_version"], 1);
assert_eq!(record["key"], "project.note");
}
#[test]
fn keys_cannot_escape_the_state_directory() {
let temporary = tempfile::tempdir().unwrap();
let directory = temporary.path().join("state");
let store = MetadataStore::new(&directory).unwrap();
for key in [
"",
"../outside",
"/outside",
"nested/key",
"nested\\key",
".hidden",
"日本語",
] {
assert!(store.put(key, "invalid").is_err(), "{key}");
assert!(store.get(key).is_err(), "{key}");
}
assert!(store.put(&"x".repeat(129), "invalid").is_err());
assert!(!directory.exists());
}
#[test]
fn corrupt_or_mismatched_records_fail_without_being_rewritten() {
let temporary = tempfile::tempdir().unwrap();
let store = MetadataStore::new(temporary.path()).unwrap();
let path = temporary.path().join("host.version.json");
for bytes in [
b"not-json".as_slice(),
b"\xff".as_slice(),
br#"{"format_version":2,"key":"host.version","value":"old"}"#.as_slice(),
br#"{"format_version":1,"key":"wrong","value":"old"}"#.as_slice(),
] {
std::fs::write(&path, bytes).unwrap();
assert!(store.get("host.version").is_err());
assert_eq!(std::fs::read(&path).unwrap(), bytes);
}
}
#[test]
fn concurrent_replacements_expose_complete_records_and_preserve_other_keys() {
let temporary = tempfile::tempdir().unwrap();
let store = MetadataStore::new(temporary.path()).unwrap();
store.put("independent", "keep").unwrap();
let a = "a".repeat(8192);
let b = "b".repeat(8192);
store.put("shared", &a).unwrap();
std::thread::scope(|scope| {
for value in [&a, &b] {
let store = &store;
scope.spawn(move || {
for _ in 0..8 {
store.put("shared", value).unwrap();
}
});
}
for _ in 0..64 {
let value = store.get("shared").unwrap().unwrap();
assert!(value == a || value == b);
}
});
assert_eq!(store.get("independent").unwrap().as_deref(), Some("keep"));
assert!(std::fs::read_dir(temporary.path()).unwrap().all(|entry| {
!entry
.unwrap()
.file_name()
.to_string_lossy()
.ends_with(".tmp")
}));
}
#[test]
fn legacy_import_is_repeatable_and_preserves_newer_file_values() {
let temporary = tempfile::tempdir().unwrap();
let store = MetadataStore::new(temporary.path()).unwrap();
store.put("host.version", "new").unwrap();
let input =
br#"[{"key":"host.version","value":"old"},{"key":"project.note","value":"legacy"}]"#;
assert_eq!(store.import_missing(input.as_slice()).unwrap(), 1);
assert_eq!(store.import_missing(input.as_slice()).unwrap(), 0);
assert_eq!(store.get("host.version").unwrap().as_deref(), Some("new"));
assert_eq!(
store.get("project.note").unwrap().as_deref(),
Some("legacy")
);
}
#[test]
fn invalid_import_keys_are_rejected_before_any_record_is_written() {
let temporary = tempfile::tempdir().unwrap();
let directory = temporary.path().join("state");
let store = MetadataStore::new(&directory).unwrap();
let input = br#"[{"key":"valid","value":"keep"},{"key":"../outside","value":"invalid"}]"#;
assert!(store.import_missing(input.as_slice()).is_err());
assert!(!directory.exists());
}
+16
View File
@@ -0,0 +1,16 @@
[package]
name = "server"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
[dependencies]
core.workspace = true
host.workspace = true
axum.workspace = true
serde.workspace = true
tokio.workspace = true
[lints]
workspace = true
+10
View File
@@ -0,0 +1,10 @@
# server
最小常驻 HTTP 宿主,提供存活检查和只读 VM 信息。通过 Arc 共享 Vm,启动不读取数据库配置、不连接或写入数据库;通过 host 包把 host.version 写入文件。特殊类的数据库能力尚未接入 HTTP 宿主。
| 内容 | 职责 |
| --- | --- |
| Cargo.toml | core/host、Axum、Tokio、Serde 依赖;无 storage 依赖 |
| [src](src/README.md) | AppState、启动、路由、信号与退出 |
HTTP 返回内容见 [运行指南](../../vendor/aster/docs/operations/README.md),监听变量见 [配置](../../docs/operations/configuration.md),预置 PostgreSQL 资源见 [部署](../../docs/operations/deployment.md)。没有语言执行接口或可变 VM 请求上下文。返回 [工作区](../README.md)。
+13
View File
@@ -0,0 +1,13 @@
# Server 入口
[main.rs](main.rs) 包含所有宿主启动代码:
| 部分 | 职责 |
| --- | --- |
| AppState | 共享只读 Arc<Vm> |
| main/run | 创建空 VM、绑定地址、设置退出信号、写文件 host.version、组装路由;不创建数据库连接 |
| health | 返回 200 和 status=ok,仅检查 HTTP 宿主可响应 |
| bootstrap | 返回对象模型、type_system=false 和堆对象数量,不分配对象 |
| shutdown_signal | Ctrl-C;Unix 上同时接受 SIGTERM,触发 Axum 优雅退出 |
/health 不表示 PostgreSQL、特殊类查询或执行脚本正常;数据库检查应属于实际消费连接的对象。宿主独立于数据库的行为由远端 smoke.py 验证,见 [验证](../../../vendor/aster/docs/operations/validation.md)。改变端点同步 [运行指南](../../../vendor/aster/docs/operations/README.md) 和 [scripts](../../../scripts/README.md)。返回 [server](../README.md)。
+77
View File
@@ -0,0 +1,77 @@
use std::error::Error;
use std::future::Future;
use std::process::ExitCode;
use std::sync::Arc;
use axum::{Json, Router, extract::State, routing::get};
use endor_core::Vm;
use host::MetadataStore;
use serde::Serialize;
#[derive(Clone)]
struct AppState {
vm: Arc<Vm>,
}
#[derive(Serialize)]
struct Health {
status: &'static str,
}
#[derive(Serialize)]
struct BootstrapInfo {
object_model: &'static str,
type_system: bool,
heap_objects: usize,
}
#[tokio::main]
async fn main() -> ExitCode {
match run().await {
Ok(()) => ExitCode::SUCCESS,
Err(error) => {
eprintln!("server: {error}");
ExitCode::FAILURE
}
}
}
async fn run() -> Result<(), Box<dyn Error>> {
let vm = Arc::new(Vm::new()?);
let address = std::env::var("ASTER_LISTEN").unwrap_or_else(|_| "127.0.0.1:8080".into());
let listener = tokio::net::TcpListener::bind(&address).await?;
let shutdown = shutdown_signal()?;
MetadataStore::from_env()?.put("host.version", env!("CARGO_PKG_VERSION"))?;
let app = Router::new()
.route("/health", get(health))
.route("/bootstrap", get(bootstrap))
.with_state(AppState { vm });
println!("Endor host listening on {}", listener.local_addr()?);
axum::serve(listener, app)
.with_graceful_shutdown(shutdown)
.await?;
Ok(())
}
async fn health() -> Json<Health> {
Json(Health { status: "ok" })
}
async fn bootstrap(State(state): State<AppState>) -> Json<BootstrapInfo> {
Json(BootstrapInfo {
object_model: "EndorObject",
type_system: false,
heap_objects: state.vm.object_count(),
})
}
fn shutdown_signal() -> std::io::Result<impl Future<Output = ()>> {
#[cfg(unix)]
let mut terminate = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())?;
Ok(async move {
#[cfg(unix)]
tokio::select! { _ = tokio::signal::ctrl_c() => {}, _ = terminate.recv() => {} }
#[cfg(not(unix))]
let _ = tokio::signal::ctrl_c().await;
})
}
+16
View File
@@ -0,0 +1,16 @@
[package]
name = "storage"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
[dependencies]
sqlx.workspace = true
tokio.workspace = true
[dev-dependencies]
tempfile = "3"
[lints]
workspace = true
+11
View File
@@ -0,0 +1,11 @@
# storage
按需数据库连接适配层,供将来需要数据库的特殊类或宿主适配器使用。依赖 SQLx/Tokio,不依赖 VM 内核;普通对象、CLI 和 Server 不连接这层。
| 内容 | 入口 |
| --- | --- |
| Cargo.toml | SQLx、Tokio 与远端检查依赖 |
| [src](src/README.md) | 显式 DatabaseConfig、连接池与关闭 |
| [tests](tests/README.md) | 连接不建表、调用方 SQL、隔离/持久化、真实 PostgreSQL |
没有默认数据库、自动环境变量读取、基础信息表或通用元数据 put/get。特殊类的名称、布局与查询接口尚未定义;当前只保留连接能力。设计边界见 [数据库对象](../../docs/runtime/database-objects.md),参数见 [配置](../../docs/operations/configuration.md)。返回 [工作区](../README.md)。
+7
View File
@@ -0,0 +1,7 @@
# 数据库连接源码导航
[lib.rs](lib.rs) 是唯一实现文件:DatabaseConfig 显式选择 SQLite 文件/内存或 PostgreSQL;DatabaseConnection 提供 connect、sqlite_pool/postgres_pool、backend_name、ping 和 close;DatabaseError 对公开错误脱敏。
connect 只建立连接池,不执行应用 DDL,不保存基础信息。没有 schema.sql、初始化表、put/get 或 from_env。业务表和查询由未来的数据库特殊类决定;本层不替它定义数据模型。
克隆共享连接池,close 会关闭所有克隆;具体生命周期及限制见 [数据库对象](../../../docs/runtime/database-objects.md)。配置变动同步 [配置](../../../docs/operations/configuration.md) 和 [tests](../tests/README.md)。返回 [storage](../README.md)。
+181
View File
@@ -0,0 +1,181 @@
//! Explicit database connections for database-backed objects.
//! Connecting never creates application tables or stores VM/host metadata.
use std::fmt;
use std::path::PathBuf;
use std::str::FromStr;
use std::time::Duration;
use sqlx::postgres::{PgConnectOptions, PgPoolOptions};
use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode, SqlitePoolOptions};
use sqlx::{PgPool, SqlitePool};
/// An explicit PostgreSQL configuration never falls back to SQLite.
#[derive(Clone)]
pub enum DatabaseConfig {
SqliteFile(PathBuf),
SqliteMemory,
Postgres(String),
}
impl fmt::Debug for DatabaseConfig {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::SqliteFile(path) => f.debug_tuple("SqliteFile").field(path).finish(),
Self::SqliteMemory => f.write_str("SqliteMemory"),
Self::Postgres(_) => f.write_str("Postgres([REDACTED])"),
}
}
}
#[derive(Debug)]
pub enum DatabaseError {
Config(&'static str),
Directory(std::io::Error),
Database(sqlx::Error),
}
impl fmt::Display for DatabaseError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Config(message) => f.write_str(message),
Self::Directory(_) => f.write_str("cannot create SQLite parent directory"),
// CLI/HTTP logs must never print a connection URL or credentials.
Self::Database(_) => {
f.write_str("database operation failed; no fallback was attempted")
}
}
}
}
impl std::error::Error for DatabaseError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
match self {
Self::Config(_) => None,
Self::Directory(error) => Some(error),
Self::Database(error) => Some(error),
}
}
}
impl From<sqlx::Error> for DatabaseError {
fn from(error: sqlx::Error) -> Self {
Self::Database(error)
}
}
#[derive(Clone)]
enum Backend {
Sqlite(SqlitePool),
Postgres(PgPool),
}
/// Created only on explicit request by an object or host adapter. Clones share
/// a pool; close() closes it for all users. There is no automatic schema or data.
/// In-memory SQLite uses one connection to preserve its database lifetime.
#[derive(Clone)]
pub struct DatabaseConnection {
backend: Backend,
}
impl DatabaseConnection {
/// Connects eagerly to the explicit backend without executing application DDL.
pub async fn connect(config: &DatabaseConfig) -> Result<Self, DatabaseError> {
let backend = match config {
DatabaseConfig::Postgres(url) => {
if !(url.starts_with("postgres://") || url.starts_with("postgresql://")) {
return Err(DatabaseError::Config(
"expected a PostgreSQL connection URL",
));
}
let options = PgConnectOptions::from_str(url)
.map_err(|_| DatabaseError::Config("invalid PostgreSQL connection URL"))?;
Backend::Postgres(
PgPoolOptions::new()
.max_connections(5)
.acquire_timeout(Duration::from_secs(5))
.connect_with(options)
.await?,
)
}
DatabaseConfig::SqliteFile(path) => {
if path.as_os_str().is_empty() || path == std::path::Path::new(":memory:") {
return Err(DatabaseError::Config(
"expected a nonempty file path; use SqliteMemory for :memory:",
));
}
if let Some(parent) = path.parent().filter(|p| !p.as_os_str().is_empty()) {
tokio::fs::create_dir_all(parent)
.await
.map_err(DatabaseError::Directory)?;
}
let options = SqliteConnectOptions::new()
.filename(path)
.create_if_missing(true)
.journal_mode(SqliteJournalMode::Wal)
.busy_timeout(Duration::from_secs(5));
Backend::Sqlite(
SqlitePoolOptions::new()
.max_connections(5)
.acquire_timeout(Duration::from_secs(5))
.connect_with(options)
.await?,
)
}
DatabaseConfig::SqliteMemory => {
let options = SqliteConnectOptions::new().in_memory(true);
Backend::Sqlite(
SqlitePoolOptions::new()
.max_connections(1)
.min_connections(1)
.idle_timeout(None)
.max_lifetime(None)
.connect_with(options)
.await?,
)
}
};
Ok(Self { backend })
}
/// Backend-specific access for the database-backed object implementation.
pub fn sqlite_pool(&self) -> Option<&SqlitePool> {
match &self.backend {
Backend::Sqlite(pool) => Some(pool),
Backend::Postgres(_) => None,
}
}
pub fn postgres_pool(&self) -> Option<&PgPool> {
match &self.backend {
Backend::Postgres(pool) => Some(pool),
Backend::Sqlite(_) => None,
}
}
pub fn backend_name(&self) -> &'static str {
match &self.backend {
Backend::Sqlite(_) => "sqlite",
Backend::Postgres(_) => "postgresql",
}
}
pub async fn ping(&self) -> Result<(), DatabaseError> {
match &self.backend {
Backend::Sqlite(pool) => {
sqlx::query("SELECT 1").execute(pool).await?;
}
Backend::Postgres(pool) => {
sqlx::query("SELECT 1").execute(pool).await?;
}
}
Ok(())
}
/// Explicitly closes the shared pool, including all DatabaseConnection clones.
pub async fn close(&self) {
match &self.backend {
Backend::Sqlite(pool) => pool.close().await,
Backend::Postgres(pool) => pool.close().await,
}
}
}
+8
View File
@@ -0,0 +1,8 @@
# 数据库连接检查
| 文件 | 覆盖与前提 |
| --- | --- |
| [storage.rs](storage.rs) | 显式错误配置、凭据脱敏、SQLite 连接后无应用表、克隆共享与独立内存隔离、调用方自建数据跨文件重连、目录错误、PostgreSQL 失败不降级 |
| [postgres.rs](postgres.rs) | 真实连接后 public 无表;测试在事务中创建临时 class_rows、参数绑定和读取,提交自动删除临时表,再连接;默认 ignore,需全新专用 ASTER_TEST_POSTGRES_URL |
所有业务表都由测试自己创建,连接层不得自动初始化基础信息表。临时 SQLite 文件和 PostgreSQL 测试库由远端 CI 隔离,不使用生产数据。检查命令见 [验证](../../../vendor/aster/docs/operations/validation.md),原生连接能力边界见 [数据库对象](../../../docs/runtime/database-objects.md)。本地不运行测试或下载依赖。返回 [storage](../README.md)。
+53
View File
@@ -0,0 +1,53 @@
use storage::{DatabaseConfig, DatabaseConnection};
/// Run against a fresh disposable database, never a production or shared schema.
#[tokio::test]
#[ignore = "requires ASTER_TEST_POSTGRES_URL pointing to a fresh disposable PostgreSQL database"]
async fn postgres_connects_without_schema_and_executes_caller_owned_sql() {
let url = std::env::var("ASTER_TEST_POSTGRES_URL")
.expect("set ASTER_TEST_POSTGRES_URL to a fresh disposable PostgreSQL database");
let config = DatabaseConfig::Postgres(url);
let database = DatabaseConnection::connect(&config).await.unwrap();
assert_eq!(database.backend_name(), "postgresql");
assert!(database.sqlite_pool().is_none());
database.ping().await.unwrap();
let pool = database.postgres_pool().unwrap();
let tables: i64 = sqlx::query_scalar(
"SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public'",
)
.fetch_one(pool)
.await
.unwrap();
assert_eq!(tables, 0, "connecting must not create application tables");
let mut transaction = pool.begin().await.unwrap();
sqlx::query(
"CREATE TEMP TABLE class_rows (id INTEGER PRIMARY KEY, value TEXT NOT NULL) ON COMMIT DROP",
)
.execute(&mut *transaction)
.await
.unwrap();
sqlx::query("INSERT INTO class_rows (id, value) VALUES ($1, $2)")
.bind(1_i64)
.bind("你好 ' ; $1")
.execute(&mut *transaction)
.await
.unwrap();
let value: String = sqlx::query_scalar("SELECT value FROM class_rows WHERE id = $1")
.bind(1_i64)
.fetch_one(&mut *transaction)
.await
.unwrap();
assert_eq!(value, "你好 ' ; $1");
transaction.commit().await.unwrap();
database.close().await;
let reopened = DatabaseConnection::connect(&config).await.unwrap();
reopened.ping().await.unwrap();
let tables: i64 = sqlx::query_scalar(
"SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public'",
)
.fetch_one(reopened.postgres_pool().unwrap())
.await
.unwrap();
assert_eq!(tables, 0);
reopened.close().await;
}
+130
View File
@@ -0,0 +1,130 @@
use storage::{DatabaseConfig, DatabaseConnection};
#[test]
fn postgres_configuration_debug_redacts_credentials() {
let config = DatabaseConfig::Postgres("postgres://user:secret@localhost/db".into());
assert!(!format!("{config:?}").contains("secret"));
}
#[tokio::test]
async fn explicit_invalid_backends_fail_without_fallback() {
for config in [
DatabaseConfig::Postgres(String::new()),
DatabaseConfig::Postgres("mysql://localhost/db".into()),
DatabaseConfig::SqliteFile("".into()),
DatabaseConfig::SqliteFile(":memory:".into()),
] {
assert!(DatabaseConnection::connect(&config).await.is_err());
}
}
#[tokio::test]
async fn memory_connections_start_without_tables_and_clones_share_the_pool() {
let database = DatabaseConnection::connect(&DatabaseConfig::SqliteMemory)
.await
.unwrap();
let other = DatabaseConnection::connect(&DatabaseConfig::SqliteMemory)
.await
.unwrap();
assert!(database.postgres_pool().is_none());
let pool = database.sqlite_pool().unwrap();
let tables: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM sqlite_master WHERE type = 'table'")
.fetch_one(pool)
.await
.unwrap();
assert_eq!(tables, 0, "connecting must not create application tables");
// This schema belongs to the test's simulated database-backed object.
sqlx::query("CREATE TABLE class_rows (id INTEGER PRIMARY KEY, value TEXT NOT NULL)")
.execute(pool)
.await
.unwrap();
sqlx::query("INSERT INTO class_rows (id, value) VALUES (?, ?)")
.bind(1_i64)
.bind("你好 ' ? $1 ;")
.execute(pool)
.await
.unwrap();
let cloned = database.clone();
let value: String = sqlx::query_scalar("SELECT value FROM class_rows WHERE id = ?")
.bind(1_i64)
.fetch_one(cloned.sqlite_pool().unwrap())
.await
.unwrap();
assert_eq!(value, "你好 ' ? $1 ;");
let other_tables: i64 =
sqlx::query_scalar("SELECT COUNT(*) FROM sqlite_master WHERE type = 'table'")
.fetch_one(other.sqlite_pool().unwrap())
.await
.unwrap();
assert_eq!(other_tables, 0);
database.close().await;
assert!(cloned.ping().await.is_err());
other.close().await;
}
#[tokio::test]
async fn explicit_sqlite_file_preserves_only_caller_created_data_across_reconnects() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("nested/data/class.db");
let config = DatabaseConfig::SqliteFile(path.clone());
let database = DatabaseConnection::connect(&config).await.unwrap();
let pool = database.sqlite_pool().unwrap();
let tables: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM sqlite_master WHERE type = 'table'")
.fetch_one(pool)
.await
.unwrap();
assert_eq!(tables, 0);
sqlx::query("CREATE TABLE class_rows (id INTEGER PRIMARY KEY, value TEXT NOT NULL)")
.execute(pool)
.await
.unwrap();
sqlx::query("INSERT INTO class_rows (id, value) VALUES (?, ?)")
.bind(1_i64)
.bind("caller-owned data")
.execute(pool)
.await
.unwrap();
database.close().await;
assert!(path.is_file());
let reopened = DatabaseConnection::connect(&config).await.unwrap();
let value: String = sqlx::query_scalar("SELECT value FROM class_rows WHERE id = ?")
.bind(1_i64)
.fetch_one(reopened.sqlite_pool().unwrap())
.await
.unwrap();
assert_eq!(value, "caller-owned data");
let tables: Vec<String> =
sqlx::query_scalar("SELECT name FROM sqlite_master WHERE type = 'table'")
.fetch_all(reopened.sqlite_pool().unwrap())
.await
.unwrap();
assert_eq!(tables, vec!["class_rows"]);
reopened.close().await;
}
#[tokio::test]
async fn invalid_sqlite_directory_reports_error() {
let dir = tempfile::tempdir().unwrap();
let file = dir.path().join("file");
std::fs::write(&file, "occupied").unwrap();
assert!(
DatabaseConnection::connect(&DatabaseConfig::SqliteFile(file.join("class.db")))
.await
.is_err()
);
}
#[tokio::test]
async fn postgres_connection_failure_is_an_error() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let url = format!(
"postgres://aster:secret@{}/aster?sslmode=disable",
listener.local_addr().unwrap()
);
let error = match DatabaseConnection::connect(&DatabaseConfig::Postgres(url)).await {
Ok(_) => panic!("unreachable PostgreSQL must fail"),
Err(error) => error,
};
assert!(!error.to_string().contains("secret"));
assert!(error.to_string().contains("no fallback"));
}