World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 整库导出为 RDF(0020)。
//!
//! **边查边发**:一页事实序列化完就把攒下的字节送出去,不在内存里拼出整份文件。
//! 一个十万条事实的库正是最需要导出的那种库,也正是「先拼成一个 String」会
//! 把服务打死的那种库。
//!
//! **同一份快照**:体检、词汇表与每一页查询跑在同一条只读 REPEATABLE READ
//! 事务里。若每页各自拿一条连接,词汇表发完之后才提交的规则会在派生页里
//! 留下一条指向它的 `wasGeneratedBy`——图里就出现没有本体的引用。
//!
//! 中途出错只能截断——HTTP 头早就发出去了。所以错误进日志,而客户端拿到的是
//! 一份短了一截的文件;这比先攒后发要好,那种做法在同样的库上根本发不出来。
use axum::body::Body;
use axum::extract::{Path, Query, State};
use axum::http::{header, HeaderMap, HeaderValue, StatusCode};
use axum::response::{IntoResponse, Response};
use serde::Deserialize;
use utopia_core::models::Role;
use utopia_core::AppError;
use uuid::Uuid;
use super::graph_routes::require_kb;
use crate::auth::AuthUser;
use crate::error::ApiResult;
use crate::rdf::{self, Format, Names, SharedBuf, Sink};
use crate::state::AppState;
#[derive(Deserialize)]
pub struct ExportQuery {
/// `turtle`(缺省)或 `jsonld`
#[serde(default)]
pub format: Option<String>,
/// 造 IRI 用的对外地址。不给就用 URN——稳定,且不假装自己知道部署在哪
#[serde(default)]
pub base: Option<String>,
}
pub async fn export(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path(kb_id): Path<Uuid>,
Query(q): Query<ExportQuery>,
) -> ApiResult<Response> {
let kb = require_kb(&state, &user, kb_id, Role::Viewer).await?;
let format = Format::parse(q.format.as_deref()).ok_or_else(|| {
AppError::Validation("Unknown `format` (expected turtle or jsonld)".into())
})?;
let names = Names::new(kb_id, q.base.as_deref()).map_err(AppError::Validation)?;
// 导出是一次「整个库离开这台机器」的动作,台账要记下(0014 的同一条理由)。
// 必须在快照事务之前写完并放掉连接:下面那条事务一占就是整个流的时长,
// 占着它再回头要连接,会把最小池(两条)上的并发导出互相饿死
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
user.id,
"kb.exported",
"knowledge_base",
Some(kb_id),
serde_json::json!({ "format": format.extension() }),
)
.await;
// 整份导出占一条连接上的只读 REPEATABLE READ 事务:下面的预检与流里
// 每一页查询读同一个快照,事务活到流结束
let mut tx = state.pool.begin().await?;
sqlx::query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY")
.execute(&mut *tx)
.await?;
// 出处链越库一律拒导(0070 挡新行,这里挡存量坏行):宁可不发一个字节,
// 也不能把别库的对象安上本库的 IRI——那份文件看着完整、实则悬空。
// 在流开始之前拦下:客户端拿到的是确定性的错误,不是一截断掉的文件
utopia_store::export::provenance_integrity(&mut tx, kb_id).await?;
// 认知状态同一条纪律(0062):越库引用、词表以外的存储值、以及 open
// 违规上解不开的判据,都在发第一个字节之前拦下
utopia_store::export::contest_integrity(&mut tx, kb_id).await?;
let stream = async_stream::try_stream! {
let buf = SharedBuf::default();
let mut sink = Sink::new(format, buf.clone());
let classes = utopia_store::export::classes(&mut tx, kb_id).await.map_err(io)?;
let relations = utopia_store::export::relations(&mut tx, kb_id).await.map_err(io)?;
let vocab = rdf::vocabulary(&names, &classes, &relations);
for c in &classes {
rdf::emit_class(&mut sink, &vocab, c)?;
}
for r in &relations {
rdf::emit_relation(&mut sink, &vocab, r)?;
}
yield axum::body::Bytes::from(buf.take());
let mut after = None;
loop {
let page = utopia_store::export::documents_page(&mut tx, kb_id, after).await.map_err(io)?;
let Some(last) = page.last() else { break };
after = Some(last.id);
for d in &page {
rdf::emit_document(&mut sink, &names, d)?;
}
yield axum::body::Bytes::from(buf.take());
}
let mut after = None;
loop {
let page = utopia_store::export::entities_page(&mut tx, kb_id, after).await.map_err(io)?;
let Some(last) = page.last() else { break };
after = Some(last.id);
for e in &page {
rdf::emit_entity(&mut sink, &names, &vocab, e)?;
}
yield axum::body::Bytes::from(buf.take());
}
// 现行三元组按「导出这一刻」判定,整份文件用同一个 now:
// 边发边取当前时间的话,同一份文件的前后两半会按两个不同的现在写
let now = chrono::Utc::now();
let mut after = None;
loop {
let page = utopia_store::export::facts_page(&mut tx, kb_id, after).await.map_err(io)?;
let Some(last) = page.last() else { break };
after = Some(last.id);
for f in &page {
rdf::emit_fact(&mut sink, &names, &vocab, f, now)?;
}
yield axum::body::Bytes::from(buf.take());
}
let mut after = None;
loop {
let page = utopia_store::export::derived_page(&mut tx, kb_id, after).await.map_err(io)?;
let Some(last) = page.last() else { break };
after = Some(last.id);
for d in &page {
rdf::emit_derived(&mut sink, &names, &vocab, d)?;
}
yield axum::body::Bytes::from(buf.take());
}
// 认知状态(0062):争议与违规都指着事实的 IRI,放在事实与派生之后
let mut after = None;
loop {
let page = utopia_store::export::fact_conflicts_page(&mut tx, kb_id, after).await.map_err(io)?;
let Some(last) = page.last() else { break };
after = Some(last.id);
for c in &page {
rdf::emit_fact_conflict(&mut sink, &names, c)?;
}
yield axum::body::Bytes::from(buf.take());
}
let mut after = None;
loop {
let page = utopia_store::export::axiom_violations_page(&mut tx, kb_id, after).await.map_err(io)?;
let Some(last) = page.last() else { break };
after = Some(last.id);
for v in &page {
rdf::emit_axiom_violation(&mut sink, &names, &vocab, v)?;
}
yield axum::body::Bytes::from(buf.take());
}
sink.finish()?;
yield axum::body::Bytes::from(buf.take());
};
let filename = format!("{}.{}", slug(&kb.name), format.extension());
let mut headers = HeaderMap::new();
headers.insert(
header::CONTENT_TYPE,
HeaderValue::from_static(format.content_type()),
);
if let Ok(v) = HeaderValue::from_str(&format!("attachment; filename=\"{filename}\"")) {
headers.insert(header::CONTENT_DISPOSITION, v);
}
Ok((
StatusCode::OK,
headers,
Body::from_stream(Box::pin(stream)
as std::pin::Pin<
Box<
dyn futures_util::Stream<Item = Result<axum::body::Bytes, std::io::Error>>
+ Send,
>,
>),
)
.into_response())
}
/// 库里出的错在流中间只能变成 io 错误——响应头已经发出去了,改不了状态码。
fn io(e: AppError) -> std::io::Error {
tracing::error!(error = %e, "导出中断");
std::io::Error::other(e.to_string())
}
/// 文件名用的短名。ASCII 之外的字符不进 Content-Disposition 的 filename,
/// 中文库名会在那里变成一串问号
fn slug(name: &str) -> String {
let mut out: String = name
.chars()
.map(|c| {
if c.is_ascii_alphanumeric() {
c.to_ascii_lowercase()
} else {
'-'
}
})
.collect();
while out.contains("--") {
out = out.replace("--", "-");
}
let trimmed = out.trim_matches('-').to_string();
if trimmed.is_empty() {
"export".into()
} else {
trimmed
}
}