pub mod actuator;
pub mod array;
pub mod query;
use std::collections::HashMap;
use crate::error::{NasaRedisError, Result};
use crate::partition::compat_string_hash;
pub fn to_json_omit_null<T: serde::Serialize>(doc: &T) -> Result<String> {
let v = to_json_value_omit_null(doc)?;
serde_json::to_string(&v).map_err(|error| {
NasaRedisError::Codec(format!(
"JSON 文档编码失败: {:?} at {}:{}",
error.classify(),
error.line(),
error.column()
))
})
}
fn strip_nulls(v: &mut serde_json::Value) {
match v {
serde_json::Value::Object(map) => {
map.retain(|_, val| !val.is_null());
for val in map.values_mut() {
strip_nulls(val);
}
}
serde_json::Value::Array(arr) => {
for val in arr.iter_mut() {
strip_nulls(val);
}
}
_ => {}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DataType {
Hash,
Json,
JsonArray,
JsonArrayBucket,
}
impl DataType {
pub fn is_array(&self) -> bool {
matches!(self, DataType::JsonArray | DataType::JsonArrayBucket)
}
}
#[derive(Debug, Clone, PartialEq)]
pub enum FieldType {
Tag {
sortable: bool,
separator: Option<char>,
case_sensitive: bool,
with_suffix_trie: bool,
},
Text {
sortable: bool,
weight: f64,
no_stem: bool,
phonetic: Option<String>,
no_index: bool,
with_suffix_trie: bool,
},
Numeric {
sortable: bool,
no_index: bool,
},
Geo,
}
#[derive(Debug, Clone)]
pub struct FieldMeta {
pub name: String,
pub alias: String,
pub json_path: Option<String>,
pub ftype: FieldType,
}
impl FieldMeta {
pub fn alias_or_name(&self) -> &str {
if self.alias.is_empty() {
&self.name
} else {
&self.alias
}
}
}
#[derive(Debug, Clone, PartialEq)]
pub enum KeySeg {
Lit(String),
Field(String),
}
#[derive(Debug, Clone)]
pub struct DocMeta {
pub index: String,
pub prefix: String,
pub data_type: DataType,
pub fields: Vec<FieldMeta>,
pub id_name: String,
pub id_numeric: bool,
pub array_keys: Vec<String>,
pub bucket_count: u32,
}
impl DocMeta {
pub fn validate(&self) -> Result<()> {
if self.index.is_empty() || self.prefix.is_empty() {
return Err(NasaRedisError::Config(
"DocMeta: index/prefix 不能为空".into(),
));
}
if self.id_name.is_empty() {
return Err(NasaRedisError::Config("DocMeta: id_name 不能为空".into()));
}
let mut seen = std::collections::HashSet::new();
for f in &self.fields {
if f.name.is_empty() {
return Err(NasaRedisError::Config("DocMeta: 字段 name 为空".into()));
}
if !seen.insert(f.alias_or_name().to_string()) {
return Err(NasaRedisError::Config(format!(
"DocMeta: 别名重复 \"{}\"",
f.alias_or_name()
)));
}
}
let segs = self.segments()?;
match self.data_type {
DataType::JsonArray | DataType::JsonArrayBucket => {
if self.array_keys.is_empty() {
return Err(NasaRedisError::Config(
"DocMeta: ARRAY 模式必须声明至少一个 array_keys(@JsonArrayKey)".into(),
));
}
if segs.is_some() {
return Err(NasaRedisError::Config(
"DocMeta: ARRAY 模式 prefix 不支持 {field} 占位符".into(),
));
}
if self.data_type == DataType::JsonArrayBucket && self.bucket_count <= 1 {
return Err(NasaRedisError::Config(format!(
"DocMeta: JsonArrayBucket 要求 bucket_count > 1,得到 {}",
self.bucket_count
)));
}
if self.data_type == DataType::JsonArray && self.bucket_count != 0 {
return Err(NasaRedisError::Config(
"DocMeta: JsonArray(非 BUCKET)bucket_count 必须为 0".into(),
));
}
}
_ => {
if !self.array_keys.is_empty() || self.bucket_count != 0 {
return Err(NasaRedisError::Config(
"DocMeta: array_keys/bucket_count 仅 ARRAY 模式可用".into(),
));
}
}
}
Ok(())
}
pub fn field(&self, alias: &str) -> Option<&FieldMeta> {
self.fields.iter().find(|f| f.alias_or_name() == alias)
}
pub fn segments(&self) -> Result<Option<Vec<KeySeg>>> {
if !self.prefix.contains('{') {
if self.prefix.contains('}') {
return Err(NasaRedisError::Config(format!(
"DocMeta: prefix \"{}\" 含未配对的 '}}'",
self.prefix
)));
}
return Ok(None);
}
let mut segs = Vec::new();
let mut lit = String::new();
let mut rest = self.prefix.as_str();
while let Some(open) = rest.find('{') {
if rest[..open].contains('}') {
return Err(NasaRedisError::Config(format!(
"DocMeta: prefix \"{}\" 含未配对的 '}}'",
self.prefix
)));
}
lit.push_str(&rest[..open]);
let after = &rest[open + 1..];
let close = after.find('}').ok_or_else(|| {
NasaRedisError::Config(format!("DocMeta: prefix \"{}\" 占位符未闭合", self.prefix))
})?;
let name = &after[..close];
if name.is_empty() || name.contains('{') {
return Err(NasaRedisError::Config(format!(
"DocMeta: prefix \"{}\" 占位符名非法(空或嵌套)",
self.prefix
)));
}
if !lit.is_empty() {
segs.push(KeySeg::Lit(std::mem::take(&mut lit)));
}
segs.push(KeySeg::Field(name.to_string()));
rest = &after[close + 1..];
}
if rest.contains('}') {
return Err(NasaRedisError::Config(format!(
"DocMeta: prefix \"{}\" 含未配对的 '}}'",
self.prefix
)));
}
if !rest.is_empty() {
segs.push(KeySeg::Lit(rest.to_string()));
}
Ok(Some(segs))
}
pub fn has_placeholder(&self) -> bool {
self.prefix.contains('{')
}
pub fn placeholder_count(&self) -> usize {
self.prefix.matches('{').count()
}
pub fn literal_prefix(&self) -> &str {
match self.prefix.find('{') {
Some(i) => &self.prefix[..i],
None => &self.prefix,
}
}
pub fn key_of(&self, id: &str) -> Result<String> {
if self.has_placeholder() {
return Err(NasaRedisError::Config(format!(
"prefix \"{}\" 含占位符,必须用 key_of_parts(parts, id)",
self.prefix
)));
}
Ok(format!("{}{}", self.prefix, id))
}
pub fn key_of_parts(&self, parts: &[&str], id: &str) -> Result<String> {
let Some(segs) = self.segments()? else {
if !parts.is_empty() {
return Err(NasaRedisError::Config(format!(
"prefix \"{}\" 无占位符,parts 必须为空(得到 {} 个)",
self.prefix,
parts.len()
)));
}
return Ok(format!("{}{}", self.prefix, id));
};
let expected = self.placeholder_count();
if parts.len() != expected {
return Err(NasaRedisError::Config(format!(
"prefix \"{}\" 有 {expected} 个占位符,得到 {} 个 parts",
self.prefix,
parts.len()
)));
}
let mut out = String::with_capacity(self.prefix.len() + id.len() + 16);
let mut idx = 0usize;
for seg in &segs {
match seg {
KeySeg::Lit(s) => out.push_str(s),
KeySeg::Field(name) => {
let v = parts[idx];
idx += 1;
check_part(v, &format!("占位符 {{{name}}}"))?;
out.push_str(v);
}
}
}
check_part(id, "@RsId")?;
out.push_str(id);
Ok(out)
}
fn array_body(&self, parts: &[&str]) -> Result<String> {
if parts.len() != self.array_keys.len() {
return Err(NasaRedisError::Config(format!(
"array key 需要 {} 个 parts(@JsonArrayKey 字段数),得到 {}",
self.array_keys.len(),
parts.len()
)));
}
let mut body = String::with_capacity(32);
for (i, p) in parts.iter().enumerate() {
check_part(p, &format!("@JsonArrayKey \"{}\"", self.array_keys[i]))?;
if i > 0 {
body.push(':');
}
body.push_str(p);
}
Ok(body)
}
pub fn array_key_of(&self, parts: &[&str]) -> Result<String> {
if !self.data_type.is_array() {
return Err(NasaRedisError::Config(format!(
"array_key_of 仅 ARRAY 模式可用(当前 {:?})",
self.data_type
)));
}
Ok(format!("{}{}", self.prefix, self.array_body(parts)?))
}
pub fn bucket_index_of(&self, sub_id: &str) -> Result<u32> {
if self.data_type != DataType::JsonArrayBucket {
return Err(NasaRedisError::Config(
"bucket_index_of 仅 JsonArrayBucket 模式可用".into(),
));
}
let h = compat_string_hash(sub_id) as i64;
let n = self.bucket_count as i64;
Ok(((h % n + n) % n) as u32)
}
pub fn bucket_key(&self, parts: &[&str], sub_id: &str) -> Result<String> {
let idx = self.bucket_index_of(sub_id)?;
Ok(format!(
"{}{{{}}}:bucket:{}",
self.prefix,
self.array_body(parts)?,
idx
))
}
pub fn all_bucket_keys(&self, parts: &[&str]) -> Result<Vec<String>> {
if self.data_type != DataType::JsonArrayBucket {
return Err(NasaRedisError::Config(
"all_bucket_keys 仅 JsonArrayBucket 模式可用".into(),
));
}
let tag = format!("{}{{{}}}:bucket:", self.prefix, self.array_body(parts)?);
Ok((0..self.bucket_count)
.map(|i| format!("{tag}{i}"))
.collect())
}
pub fn parse_array_key(&self, key: &str) -> Result<Vec<String>> {
if !self.data_type.is_array() {
return Err(NasaRedisError::Config(format!(
"parse_array_key 仅 ARRAY 模式可用(当前 {:?})",
self.data_type
)));
}
let rest = key.strip_prefix(self.prefix.as_str()).ok_or_else(|| {
NasaRedisError::Config(format!(
"key \"{key}\" 不以 prefix \"{}\" 开头",
self.prefix
))
})?;
let body = if matches!(self.data_type, DataType::JsonArrayBucket) {
rest.strip_prefix('{')
.and_then(|s| s.split_once("}:bucket:"))
.map(|(b, _)| b)
.ok_or_else(|| {
NasaRedisError::Config(format!(
"bucket key \"{key}\" 形态不符 {{body}}:bucket:N"
))
})?
} else {
rest
};
let parts: Vec<String> = body.split(':').map(|s| s.to_string()).collect();
if parts.len() != self.array_keys.len() {
return Err(NasaRedisError::Config(format!(
"key \"{key}\" 解析出 {} 段,期望 {}(@JsonArrayKey 字段数)",
parts.len(),
self.array_keys.len()
)));
}
Ok(parts)
}
pub fn array_key_for(&self, parts: &[&str], sub_id: &str) -> Result<String> {
match self.data_type {
DataType::JsonArray => self.array_key_of(parts),
DataType::JsonArrayBucket => self.bucket_key(parts, sub_id),
other => Err(NasaRedisError::Config(format!(
"array_key_for 仅 ARRAY 模式可用(当前 {other:?})"
))),
}
}
pub fn schema_args(&self) -> Vec<String> {
let mut out = Vec::new();
for f in &self.fields {
match self.data_type {
DataType::Json => {
out.push(
f.json_path
.clone()
.unwrap_or_else(|| format!("$.{}", f.name)),
);
out.push("AS".into());
out.push(f.alias_or_name().to_string());
}
_ => out.push(f.name.clone()),
}
if matches!(self.data_type, DataType::Hash) && !f.alias.is_empty() && f.alias != f.name
{
out.push("AS".into());
out.push(f.alias.clone());
}
match &f.ftype {
FieldType::Tag {
sortable,
separator,
case_sensitive,
with_suffix_trie,
} => {
out.push("TAG".into());
if let Some(sep) = separator {
out.push("SEPARATOR".into());
out.push(sep.to_string());
}
if *case_sensitive {
out.push("CASESENSITIVE".into());
}
if *with_suffix_trie {
out.push("WITHSUFFIXTRIE".into());
}
if *sortable {
out.push("SORTABLE".into());
}
}
FieldType::Text {
sortable,
weight,
no_stem,
phonetic,
no_index,
with_suffix_trie,
} => {
out.push("TEXT".into());
if *no_stem {
out.push("NOSTEM".into());
}
if (*weight - 1.0).abs() > f64::EPSILON {
out.push("WEIGHT".into());
out.push(weight.to_string());
}
if let Some(matcher) = phonetic {
out.push("PHONETIC".into());
out.push(matcher.clone());
}
if *with_suffix_trie {
out.push("WITHSUFFIXTRIE".into());
}
if *sortable {
out.push("SORTABLE".into());
}
if *no_index {
out.push("NOINDEX".into());
}
}
FieldType::Numeric {
sortable,
no_index,
} => {
out.push("NUMERIC".into());
if *sortable {
out.push("SORTABLE".into());
}
if *no_index {
out.push("NOINDEX".into());
}
}
FieldType::Geo => out.push("GEO".into()),
}
}
out
}
}
pub fn check_part(s: &str, desc: &str) -> Result<()> {
if s.contains(':') || s.contains('{') || s.contains('}') {
return Err(NasaRedisError::Config(format!(
"{desc} 值 \"{s}\" 不得含 ':'/'{{'/'}}'(':' 是 key 分隔符;'{{}}' 破坏 hash tag)"
)));
}
Ok(())
}
pub trait RedisDocument: Sized + Send + Sync {
fn meta() -> &'static DocMeta;
fn id(&self) -> String;
fn to_fields(&self) -> Vec<(String, String)>;
fn from_fields(fields: &HashMap<String, String>) -> Result<Self>;
fn placeholder_parts(&self) -> Vec<String> {
Vec::new()
}
fn array_key_parts(&self) -> Vec<String> {
Vec::new()
}
}
fn to_json_value_omit_null<T: serde::Serialize>(doc: &T) -> Result<serde_json::Value> {
let encoded =
std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| serde_json::to_value(doc)))
.map_err(|_| NasaRedisError::Codec("JSON 文档序列化展开".into()))?;
let mut v = encoded.map_err(|error| {
NasaRedisError::Codec(format!(
"JSON 文档序列化失败: {:?} at {}:{}",
error.classify(),
error.line(),
error.column()
))
})?;
strip_nulls(&mut v);
Ok(v)
}