use std::collections::HashMap;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::time::Duration;
use redis::Value;
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
use serde_json::Value as JsonValue;
use tokio_util::sync::CancellationToken;
use crate::client::{Conn, RedisClient};
use crate::config::{MAX_REDIS_NAME_BYTES, MAX_REDIS_RUNTIME_DURATION_MS, MAX_STREAM_BATCH_SIZE};
use crate::error::{NasaRedisError, Result};
pub const STREAM_EVENT: &str = "msg";
#[derive(Debug, Clone)]
pub struct StreamField {
pub event: String,
pub raw: Vec<u8>,
}
#[derive(Debug, Clone)]
pub struct StreamEntry {
pub stream: String,
pub id: String,
pub fields: Vec<StreamField>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StreamEnvelope<T> {
pub topic: String,
pub data: T,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub passthrough: Option<serde_json::Map<String, JsonValue>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub event: Option<String>,
}
#[derive(Debug, Clone)]
pub struct StreamPublishItem {
pub event: String,
pub data: JsonValue,
}
impl StreamPublishItem {
pub fn new<T: Serialize>(event: impl Into<String>, message: &T) -> Result<Self> {
let data = serialize_stream_value(message)?;
Ok(Self {
event: event.into(),
data,
})
}
}
fn serialize_stream_value<T: Serialize>(message: &T) -> Result<JsonValue> {
let encoded = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
serde_json::to_value(message)
}))
.map_err(|_| NasaRedisError::Config("Stream 消息序列化展开".into()))?;
encoded.map_err(|error| {
NasaRedisError::Config(format!(
"Stream 消息序列化失败: {:?} at {}:{}",
error.classify(),
error.line(),
error.column()
))
})
}
#[derive(Debug, Clone, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StreamStart {
Now,
After(String),
Beginning,
}
#[derive(Debug, Clone, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StreamGroupStart {
New,
History,
}
#[derive(Debug, Clone, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StreamMode {
Broadcast {
start: StreamStart,
},
Group {
group: String,
consumer: String,
start: StreamGroupStart,
},
}
#[derive(Debug, Clone, Copy, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StreamAckPolicy {
Auto,
OnSuccess,
}
#[derive(Debug, Clone, serde::Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct StreamSubscribeCfg {
pub mode: StreamMode,
pub batch_size: usize,
pub block_ms: u64,
pub idle_sleep_ms: u64,
pub handler_timeout_ms: u64,
pub ack_policy: StreamAckPolicy,
}
impl Default for StreamSubscribeCfg {
fn default() -> Self {
Self {
mode: StreamMode::Broadcast {
start: StreamStart::Now,
},
batch_size: 100,
block_ms: 500,
idle_sleep_ms: 200,
handler_timeout_ms: 30_000,
ack_policy: StreamAckPolicy::Auto,
}
}
}
#[derive(Debug, Clone)]
pub struct StreamEvent {
pub stream: String,
pub id: String,
pub event: String,
pub raw: Vec<u8>,
}
#[derive(Debug, Clone)]
pub struct StreamTypedEvent<T> {
pub stream: String,
pub id: String,
pub event: String,
pub data: T,
pub passthrough: Option<serde_json::Map<String, JsonValue>>,
}
type BoxFut = Pin<Box<dyn Future<Output = std::result::Result<(), String>> + Send>>;
type Handler = Arc<dyn Fn(StreamEvent) -> BoxFut + Send + Sync>;
impl RedisClient {
pub async fn publish<T: Serialize>(
&self,
stream: &str,
event: &str,
message: &T,
) -> Result<String> {
let body = stream_publish_body(stream, event, message)?;
self.x_add_bytes(stream, "*", &[(event, body.as_slice())])
.await
}
pub async fn publish_default<T: Serialize>(&self, stream: &str, message: &T) -> Result<String> {
self.publish(stream, STREAM_EVENT, message).await
}
pub async fn publish_many(&self, stream: &str, events: &[StreamPublishItem]) -> Result<String> {
if stream.is_empty() {
return Err(NasaRedisError::Config(
"publish_many: stream 不能为空".into(),
));
}
if events.is_empty() {
return Err(NasaRedisError::Config(
"publish_many: events 不能为空".into(),
));
}
let mut bufs: Vec<(String, Vec<u8>)> = Vec::with_capacity(events.len());
for item in events {
if item.event.is_empty() {
return Err(NasaRedisError::Config(
"publish_many: event 不能为空".into(),
));
}
if item.data.is_null() {
return Err(NasaRedisError::Config(
"publish_many: message 序列化为 JSON null".into(),
));
}
let bytes = encode_envelope(stream, &item.data)?;
bufs.push((item.event.clone(), bytes));
}
let fields: Vec<(&str, &[u8])> = bufs
.iter()
.map(|(e, b)| (e.as_str(), b.as_slice()))
.collect();
self.x_add_bytes(stream, "*", &fields).await
}
pub async fn x_read(
&self,
stream: &str,
cursor: &str,
count: usize,
block_ms: Option<u64>,
) -> Result<Vec<StreamEntry>> {
if stream.is_empty() {
return Err(NasaRedisError::Config("x_read: stream 不能为空".into()));
}
if count == 0 {
return Err(NasaRedisError::Config("x_read: count 必须 > 0".into()));
}
if count > MAX_STREAM_BATCH_SIZE {
return Err(NasaRedisError::Config(format!(
"x_read: count 过大(上限 {MAX_STREAM_BATCH_SIZE})"
)));
}
if block_ms == Some(0) {
return Err(NasaRedisError::Config(
"x_read: block_ms=Some(0)(无限阻塞)不允许——用 None 非阻塞或 Some(>0)".into(),
));
}
let cmd = build_xread_cmd(stream, cursor, count, block_ms);
let v: Value = match block_ms {
None => self.execute_raw(&cmd).await?,
Some(_) => {
let mut conn = self.dedicated_conn("x_read blocking").await?;
cmd.query_async(&mut conn).await?
}
};
parse_xread_reply(v, stream, count, cursor, false)
}
pub async fn x_read_group(
&self,
stream: &str,
group: &str,
consumer: &str,
cursor: &str,
count: usize,
block_ms: Option<u64>,
) -> Result<Vec<StreamEntry>> {
if stream.is_empty() || group.is_empty() || consumer.is_empty() {
return Err(NasaRedisError::Config(
"x_read_group: stream / group / consumer 不能为空".into(),
));
}
if count == 0 {
return Err(NasaRedisError::Config(
"x_read_group: count 必须 > 0".into(),
));
}
if count > MAX_STREAM_BATCH_SIZE {
return Err(NasaRedisError::Config(format!(
"x_read_group: count 过大(上限 {MAX_STREAM_BATCH_SIZE})"
)));
}
if block_ms == Some(0) {
return Err(NasaRedisError::Config(
"x_read_group: block_ms=Some(0)(无限阻塞)不允许——用 None 非阻塞或 Some(>0)".into(),
));
}
let cmd = build_xreadgroup_cmd(stream, group, consumer, cursor, count, block_ms);
let v: Value = match block_ms {
None => self.execute_raw(&cmd).await?,
Some(_) => {
let mut conn = self.dedicated_conn("x_read_group blocking").await?;
cmd.query_async(&mut conn).await?
}
};
parse_xread_reply(v, stream, count, cursor, cursor != ">")
}
pub fn subscribe(self: &Arc<Self>, stream: impl Into<String>) -> StreamSubscriber {
StreamSubscriber {
client: Arc::clone(self),
stream: stream.into(),
cfg: StreamSubscribeCfg::default(),
handlers: HashMap::new(),
}
}
}
pub struct StreamSubscriber {
client: Arc<RedisClient>,
stream: String,
cfg: StreamSubscribeCfg,
handlers: HashMap<String, Handler>,
}
impl StreamSubscriber {
pub fn with_cfg(mut self, cfg: StreamSubscribeCfg) -> Self {
self.cfg = cfg;
self
}
pub fn broadcast_from(mut self, start: StreamStart) -> Self {
self.cfg.mode = StreamMode::Broadcast {
start,
};
self
}
pub fn group(mut self, group: impl Into<String>, consumer: impl Into<String>) -> Self {
self.cfg.mode = StreamMode::Group {
group: group.into(),
consumer: consumer.into(),
start: StreamGroupStart::New,
};
self
}
pub fn group_from(mut self, start: StreamGroupStart) -> Self {
if let StreamMode::Group {
group,
consumer,
..
} = self.cfg.mode
{
self.cfg.mode = StreamMode::Group {
group,
consumer,
start,
};
}
self
}
pub fn ack_policy(mut self, policy: StreamAckPolicy) -> Self {
self.cfg.ack_policy = policy;
self
}
pub fn on<F, Fut>(mut self, event: impl Into<String>, handler: F) -> Self
where
F: Fn(StreamEvent) -> Fut + Send + Sync + 'static,
Fut: Future<Output = std::result::Result<(), String>> + Send + 'static,
{
let h: Handler = Arc::new(move |ev| Box::pin(handler(ev)));
self.handlers.insert(event.into(), h);
self
}
pub fn on_typed<T, F, Fut>(mut self, event: impl Into<String>, handler: F) -> Self
where
T: DeserializeOwned + Send + 'static,
F: Fn(StreamTypedEvent<T>) -> Fut + Send + Sync + 'static,
Fut: Future<Output = std::result::Result<(), String>> + Send + 'static,
{
let stream = self.stream.clone();
let handler = Arc::new(handler);
let h: Handler = Arc::new(move |ev: StreamEvent| {
let handler = Arc::clone(&handler);
let stream = stream.clone();
Box::pin(async move {
let (data_val, passthrough) = unwrap_envelope(&ev.raw, &stream)
.map_err(|e| format!("envelope 解包失败: {e}"))?;
let data: T = serde_json::from_value(data_val).map_err(|e| {
format!(
"data 反序列化失败: category={:?}, line={}, column={}",
e.classify(),
e.line(),
e.column()
)
})?;
let tev = StreamTypedEvent {
stream: ev.stream,
id: ev.id,
event: ev.event,
data,
passthrough,
};
handler(tev).await
})
});
self.handlers.insert(event.into(), h);
self
}
pub fn handler_count(&self) -> usize {
self.handlers.len()
}
pub async fn start(self) -> Result<StreamSubscription> {
let subscription = self.start_suspended().await?;
subscription.activate();
Ok(subscription)
}
pub async fn start_suspended(self) -> Result<StreamSubscription> {
self.start_suspended_with_activation(CancellationToken::new())
.await
}
pub async fn start_suspended_with_activation(
self,
ready: CancellationToken,
) -> Result<StreamSubscription> {
if self.stream.trim().is_empty()
|| self.stream != self.stream.trim()
|| self.stream.len() > MAX_REDIS_NAME_BYTES
{
return Err(NasaRedisError::Config(
format!(
"stream subscribe: stream key 必须无首尾空白、非空且不超过 {MAX_REDIS_NAME_BYTES} 字节"
),
));
}
if self.cfg.batch_size == 0 {
return Err(NasaRedisError::Config(
"stream subscribe: batch_size 必须 > 0".into(),
));
}
if self.cfg.batch_size > MAX_STREAM_BATCH_SIZE {
return Err(NasaRedisError::Config(format!(
"stream subscribe: batch_size 过大(上限 {MAX_STREAM_BATCH_SIZE})"
)));
}
if self.cfg.idle_sleep_ms == 0
|| self.cfg.idle_sleep_ms > MAX_REDIS_RUNTIME_DURATION_MS
|| self.cfg.block_ms > MAX_REDIS_RUNTIME_DURATION_MS
|| self.cfg.handler_timeout_ms > MAX_REDIS_RUNTIME_DURATION_MS
{
return Err(NasaRedisError::Config(format!(
"stream subscribe: block/idle/handler 时长超出允许范围(idle 必须 >0,最大 {MAX_REDIS_RUNTIME_DURATION_MS}ms)"
)));
}
if matches!(
&self.cfg.mode,
StreamMode::Broadcast {
start: StreamStart::After(id)
} if !valid_stream_entry_id(id)
) {
return Err(NasaRedisError::Config(
"stream subscribe: After 必须使用 `<milliseconds>-<sequence>` 形式的具体 entry ID"
.into(),
));
}
if let StreamMode::Group {
group,
consumer,
..
} = &self.cfg.mode
{
if group.trim().is_empty()
|| consumer.trim().is_empty()
|| group != group.trim()
|| consumer != consumer.trim()
|| group.len() > MAX_REDIS_NAME_BYTES
|| consumer.len() > MAX_REDIS_NAME_BYTES
{
return Err(NasaRedisError::Config(
format!(
"stream subscribe: group / consumer 必须无首尾空白、非空且不超过 {MAX_REDIS_NAME_BYTES} 字节"
),
));
}
}
let runtime = tokio::runtime::Handle::try_current()
.map_err(|_| NasaRedisError::Config("Stream 启动需要有效的 Tokio 执行上下文".into()))?;
runtime
.spawn(async {})
.await
.map_err(|_| NasaRedisError::Config("Stream 启动执行器未接纳准备任务".into()))?;
let cancel = CancellationToken::new();
let child = cancel.child_token();
let conn = self.client.dedicated_conn("stream subscribe").await?;
let read_kind = match &self.cfg.mode {
StreamMode::Broadcast {
start,
} => {
let cursor = resolve_broadcast_cursor(&self.client, &self.stream, start).await?;
ReadKind::Broadcast {
cursor,
}
}
StreamMode::Group {
group,
consumer,
start,
} => {
ensure_group(&self.client, &self.stream, group, start).await?;
ReadKind::Group {
group: group.clone(),
consumer: consumer.clone(),
}
}
};
let gate = ready.clone();
let activity = Arc::new(crate::activity::Activity::default());
let active = activity.task(crate::activity::TaskKind::Consumer);
let progress = activity.clone();
let handle = runtime.spawn(async move {
let _active = active;
tokio::select! {
biased;
_ = child.cancelled() => return,
_ = gate.cancelled() => {},
}
run_loop(self, conn, read_kind, child, progress).await;
});
let abort = handle.abort_handle();
let (done, outcome) = tokio::sync::watch::channel(StreamTaskState::Running);
let done = activity.completion(done);
let owner_cancel = cancel.clone();
let owner_stop = cancel.clone().drop_guard();
runtime.spawn(async move {
let _stop = owner_stop;
let result = handle.await;
let state = if result.is_ok() && owner_cancel.is_cancelled() {
StreamTaskState::Stopped
} else {
StreamTaskState::Failed
};
owner_cancel.cancel();
done.send_replace(state);
});
let running = StreamSubscription {
cancel,
ready,
abort,
outcome,
activity,
};
if running.with_running(|| ()).is_none() {
running.begin_shutdown();
return Err(NasaRedisError::Config(
"Stream 启动时未取得完整任务责任,已请求关闭".into(),
));
}
Ok(running)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StreamTaskState {
Running,
Stopped,
Failed,
}
pub struct StreamSubscription {
activity: Arc<crate::activity::Activity>,
cancel: CancellationToken,
ready: CancellationToken,
abort: tokio::task::AbortHandle,
outcome: tokio::sync::watch::Receiver<StreamTaskState>,
}
impl StreamSubscription {
pub fn with_running<T>(&self, publish: impl FnOnce() -> T) -> Option<T> {
self.activity
.with_tasks(1, 0, 0, || {
if self.cancel.is_cancelled() || self.state() != StreamTaskState::Running {
None
} else {
Some(publish())
}
})
.flatten()
}
pub fn observation(&self) -> crate::RedisTaskObservation {
self.activity.snapshot()
}
pub fn activate(&self) -> bool {
if self.cancel.is_cancelled() {
return false;
}
self.ready.cancel();
true
}
pub fn begin_shutdown(&self) {
self.activity.close();
self.cancel.cancel();
}
pub fn abort(&self) {
self.begin_shutdown();
self.abort.abort();
}
pub fn state(&self) -> StreamTaskState {
let disconnected = self.outcome.has_changed().is_err();
let state = *self.outcome.borrow();
if disconnected && state == StreamTaskState::Running {
StreamTaskState::Failed
} else {
state
}
}
pub async fn wait_closed(&self) -> StreamTaskState {
let mut outcome = self.outcome.clone();
loop {
let state = *outcome.borrow_and_update();
if state != StreamTaskState::Running {
return state;
}
if outcome.changed().await.is_err() {
return StreamTaskState::Failed;
}
}
}
pub async fn shutdown(self) {
self.begin_shutdown();
if self.wait_closed().await == StreamTaskState::Failed {
tracing::warn!("Stream 消费任务异常退出");
}
}
}
impl Drop for StreamSubscription {
fn drop(&mut self) {
self.begin_shutdown();
}
}
enum ReadKind {
Broadcast {
cursor: String,
},
Group {
group: String,
consumer: String,
},
}
async fn run_loop(
subscriber: StreamSubscriber,
mut conn: Conn,
mut read_kind: ReadKind,
cancel: CancellationToken,
activity: Arc<crate::activity::Activity>,
) {
let StreamSubscriber {
client,
stream,
cfg,
handlers,
} = subscriber;
let resp_timeout = client.config().command.response_timeout_ms;
let block_ms = effective_block(cfg.block_ms, resp_timeout);
let idle = Duration::from_millis(cfg.idle_sleep_ms.max(1));
loop {
if cancel.is_cancelled() {
break;
}
let cmd = match &read_kind {
ReadKind::Broadcast {
cursor,
} => build_xread_cmd(
&stream,
cursor,
cfg.batch_size,
(block_ms > 0).then_some(block_ms),
),
ReadKind::Group {
group,
consumer,
} => build_xreadgroup_cmd(
&stream,
group,
consumer,
">",
cfg.batch_size,
(block_ms > 0).then_some(block_ms),
),
};
let v: Value = tokio::select! {
biased;
_ = cancel.cancelled() => break,
r = cmd.query_async::<Value>(&mut conn) => match r {
Ok(v) => v,
Err(e) => {
tracing::warn!(stream = %stream, err = %e, "stream 订阅读失败,退避后重建连接");
if sleep_or_cancel(&cancel, idle).await {
break;
}
let reconnect = client.dedicated_conn("stream subscribe reconnect");
tokio::select! {
biased;
_ = cancel.cancelled() => break,
result = reconnect => {
if let Ok(c) = result {
conn = c;
}
}
}
continue;
}
}
};
let cursor = match &read_kind {
ReadKind::Broadcast {
cursor,
} => cursor.as_str(),
ReadKind::Group {
..
} => ">",
};
let entries = match parse_xread_reply(v, &stream, cfg.batch_size, cursor, false) {
Ok(e) => e,
Err(e) => {
tracing::warn!(stream = %stream, err = %e, "stream 响应解析失败,退避重试");
if sleep_or_cancel(&cancel, idle).await {
break;
}
continue;
}
};
activity.finish(0, false);
activity.accept(entries.len(), 0);
if entries.is_empty() {
if block_ms == 0 && sleep_or_cancel(&cancel, idle).await {
break;
}
continue;
}
for entry in entries {
let mut all_ok = true;
for field in &entry.fields {
let Some(handler) = handlers.get(&field.event) else {
continue; };
let ev = StreamEvent {
stream: entry.stream.clone(),
id: entry.id.clone(),
event: field.event.clone(),
raw: field.raw.clone(),
};
tokio::select! {
biased;
_ = cancel.cancelled() => {
tracing::debug!(stream = %stream, id = %entry.id, "stream handler 因订阅停机被取消,消息不 ACK");
return;
}
ok = dispatch_one(handler, ev, cfg.handler_timeout_ms) => {
if !ok {
all_ok = false;
}
}
}
}
match &mut read_kind {
ReadKind::Broadcast {
cursor,
} => {
*cursor = entry.id.clone();
}
ReadKind::Group {
group,
..
} => {
let should_ack = match cfg.ack_policy {
StreamAckPolicy::Auto => true,
StreamAckPolicy::OnSuccess => all_ok,
};
if should_ack {
let ack_ids = [entry.id.as_str()];
let ack = client.x_ack(&stream, group, &ack_ids);
tokio::select! {
biased;
_ = cancel.cancelled() => {
tracing::debug!(stream = %stream, id = %entry.id, "stream XACK 因订阅停机被取消,确认结果按不确定态处理");
return;
}
result = ack => {
if let Err(e) = result {
tracing::warn!(stream = %stream, id = %entry.id, err = %e, "XACK 失败");
}
}
}
}
}
}
activity.finish(1, false);
}
}
tracing::debug!(stream = %stream, "stream 订阅任务退出");
}
async fn sleep_or_cancel(cancel: &CancellationToken, duration: Duration) -> bool {
tokio::select! {
biased;
_ = cancel.cancelled() => true,
_ = tokio::time::sleep(duration) => false,
}
}
fn valid_stream_entry_id(value: &str) -> bool {
let Some((milliseconds, sequence)) = value.split_once('-') else {
return false;
};
!milliseconds.is_empty()
&& !sequence.is_empty()
&& milliseconds.bytes().all(|byte| byte.is_ascii_digit())
&& sequence.bytes().all(|byte| byte.is_ascii_digit())
&& milliseconds.parse::<u64>().is_ok()
&& sequence.parse::<u64>().is_ok()
}
fn stream_id_parts(value: &str) -> Option<(u64, u64)> {
if !valid_stream_entry_id(value) {
return None;
}
let (milliseconds, sequence) = value.split_once('-')?;
Some((milliseconds.parse().ok()?, sequence.parse().ok()?))
}
pub(crate) fn check_stream_id_reply(reply: &Value, requested: &str) -> Result<()> {
let invalid = || NasaRedisError::Parsing("XADD 回复不是与请求一致的有效条目身份".into());
let text = match reply {
Value::BulkString(bytes) => std::str::from_utf8(bytes).map_err(|_| invalid())?,
Value::SimpleString(text) => text.as_str(),
_ => return Err(invalid()),
};
let parts = stream_id_parts(text)
.filter(|parts| *parts != (0, 0))
.ok_or_else(invalid)?;
let matches = if requested == "*" {
true
} else if let Some(expected) = stream_id_parts(requested) {
expected == parts
} else {
let milliseconds = requested.strip_suffix("-*").unwrap_or(requested);
!milliseconds.is_empty()
&& milliseconds.bytes().all(|byte| byte.is_ascii_digit())
&& milliseconds.parse::<u64>().ok() == Some(parts.0)
&& (requested.ends_with("-*") || parts.1 == 0)
};
if !matches {
return Err(invalid());
}
Ok(())
}
pub(crate) fn check_stream_ack_reply(reply: &Value, requested: usize) -> Result<()> {
if matches!(reply, Value::Int(count) if usize::try_from(*count).is_ok_and(|count| count <= requested))
{
Ok(())
} else {
Err(NasaRedisError::Parsing(
"XACK 回复不是有效的确认计数".into(),
))
}
}
async fn dispatch_one(handler: &Handler, ev: StreamEvent, timeout_ms: u64) -> bool {
let guarded = futures::FutureExt::catch_unwind(std::panic::AssertUnwindSafe(
async move {
handler(ev).await
},
));
let res = if timeout_ms > 0 {
match tokio::time::timeout(Duration::from_millis(timeout_ms), guarded).await {
Ok(r) => r,
Err(_) => {
tracing::warn!("stream handler 超时({timeout_ms}ms),按失败处理");
return false;
}
}
} else {
guarded.await
};
match res {
Ok(Ok(())) => true,
Ok(Err(e)) => {
tracing::warn!(err = %e, "stream handler 返回 Err");
false
}
Err(_) => {
tracing::error!("stream handler panic");
false
}
}
}
fn effective_block(block_ms: u64, resp_timeout_ms: u64) -> u64 {
if resp_timeout_ms > 0 && block_ms >= resp_timeout_ms {
(resp_timeout_ms / 2).max(1)
} else {
block_ms
}
}
fn encode_envelope(stream: &str, data: &JsonValue) -> Result<Vec<u8>> {
let env = StreamEnvelope {
topic: stream.to_string(),
data,
passthrough: None,
event: None,
};
serde_json::to_vec(&env)
.map_err(|e| NasaRedisError::Config(format!("envelope 序列化失败: {e}")))
}
pub(crate) fn stream_publish_body<T: Serialize>(
stream: &str,
event: &str,
message: &T,
) -> Result<Vec<u8>> {
if stream.is_empty() || event.is_empty() {
return Err(NasaRedisError::Config(
"publish: stream / event 不能为空".into(),
));
}
let data = serialize_stream_value(message)?;
if data.is_null() {
return Err(NasaRedisError::Config(
"publish: message 序列化为 JSON null".into(),
));
}
encode_envelope(stream, &data)
}
fn unwrap_envelope(
raw: &[u8],
stream: &str,
) -> Result<(JsonValue, Option<serde_json::Map<String, JsonValue>>)> {
let v: JsonValue = serde_json::from_slice(raw)
.map_err(|e| NasaRedisError::Config(format!("JSON 解析失败: {e}")))?;
if let Some(obj) = v.as_object() {
if obj.get("topic").and_then(|t| t.as_str()) == Some(stream) {
let data = obj.get("data").cloned().unwrap_or(JsonValue::Null);
let passthrough = obj.get("passthrough").and_then(|p| p.as_object().cloned());
return Ok((data, passthrough));
}
}
Ok((v, None))
}
fn build_xread_cmd(stream: &str, cursor: &str, count: usize, block_ms: Option<u64>) -> redis::Cmd {
let mut cmd = redis::cmd("XREAD");
cmd.arg("COUNT").arg(count);
if let Some(b) = block_ms {
cmd.arg("BLOCK").arg(b);
}
cmd.arg("STREAMS").arg(stream).arg(cursor);
cmd
}
fn build_xreadgroup_cmd(
stream: &str,
group: &str,
consumer: &str,
cursor: &str,
count: usize,
block_ms: Option<u64>,
) -> redis::Cmd {
let mut cmd = redis::cmd("XREADGROUP");
cmd.arg("GROUP").arg(group).arg(consumer);
cmd.arg("COUNT").arg(count);
if let Some(b) = block_ms {
cmd.arg("BLOCK").arg(b);
}
cmd.arg("STREAMS").arg(stream).arg(cursor);
cmd
}
async fn resolve_broadcast_cursor(
client: &RedisClient,
stream: &str,
start: &StreamStart,
) -> Result<String> {
match start {
StreamStart::After(id) => Ok(id.clone()),
StreamStart::Beginning => Ok("0-0".to_string()),
StreamStart::Now => {
let mut cmd = redis::cmd("XREVRANGE");
cmd.arg(stream).arg("+").arg("-").arg("COUNT").arg(1);
let v: Value = client.execute_raw(&cmd).await?;
Ok(first_entry_id(&v)?.unwrap_or_else(|| "0-0".into()))
}
}
}
async fn ensure_group(
client: &RedisClient,
stream: &str,
group: &str,
start: &StreamGroupStart,
) -> Result<()> {
let mkid = match start {
StreamGroupStart::New => "$",
StreamGroupStart::History => "0",
};
let mut cmd = redis::cmd("XGROUP");
cmd.arg("CREATE")
.arg(stream)
.arg(group)
.arg(mkid)
.arg("MKSTREAM");
match client.execute_raw::<Value>(&cmd).await {
Ok(Value::Okay) => Ok(()),
Ok(Value::SimpleString(reply)) if reply == "OK" => Ok(()),
Ok(Value::BulkString(reply)) if reply == b"OK" => Ok(()),
Err(NasaRedisError::Redis(error)) if error.code() == Some("BUSYGROUP") => Ok(()),
Ok(_) => Err(NasaRedisError::Parsing(
"Stream 建组回复不是预期的 OK".into(),
)),
Err(e) => Err(e),
}
}
fn parse_xread_reply(
v: Value,
expected_stream: &str,
count: usize,
cursor: &str,
history: bool,
) -> Result<Vec<StreamEntry>> {
let stream_pairs: Vec<(Value, Value)> = match v {
Value::Nil => return Ok(Vec::new()),
Value::Map(m) => m,
Value::Array(arr) => {
if arr.len() > 1 {
return Err(NasaRedisError::Parsing("单来源读取返回多个 Stream".into()));
}
let mut pairs = Vec::with_capacity(arr.len());
for item in arr {
match item {
Value::Array(mut kv) if kv.len() == 2 => {
let entries = kv.pop().unwrap();
let stream = kv.pop().unwrap();
pairs.push((stream, entries));
}
other => return Err(shape_err("stream item 应为 [stream, entries]", &other)),
}
}
pairs
}
other => return Err(shape_err("顶层应为 Array/Map/Nil", &other)),
};
if stream_pairs.len() > 1 {
return Err(NasaRedisError::Parsing("单来源读取返回多个 Stream".into()));
}
let mut out = Vec::new();
for (stream_v, entries_v) in stream_pairs {
let stream = xread_string(&stream_v)?;
if stream != expected_stream {
return Err(NasaRedisError::Parsing(
"Stream 回复来源与请求不一致".into(),
));
}
let entries = match entries_v {
Value::Array(e) => e,
other => return Err(shape_err("entries 应为 Array", &other)),
};
if entries.len() > count {
return Err(NasaRedisError::Parsing("Stream 回复超过请求条数".into()));
}
let mut previous = stream_id_parts(cursor)
.or_else(|| {
if !cursor.is_empty() && cursor.bytes().all(|byte| byte.is_ascii_digit()) {
cursor
.parse::<u64>()
.ok()
.map(|milliseconds| (milliseconds, 0))
} else {
None
}
})
.unwrap_or((0, 0));
for entry in entries {
let mut idfields = match entry {
Value::Array(a) if a.len() == 2 => a,
other => return Err(shape_err("entry 应为 [id, fields]", &other)),
};
let fields_v = idfields.pop().unwrap();
let id_v = idfields.pop().unwrap();
let id = xread_string(&id_v)?;
let parts = stream_id_parts(&id)
.filter(|parts| *parts > previous)
.ok_or_else(|| NasaRedisError::Parsing("Stream 身份非法或不满足读取顺序".into()))?;
let fields = if history && matches!(fields_v, Value::Nil) {
Vec::new()
} else {
parse_fields(fields_v)?
};
previous = parts;
out.push(StreamEntry {
stream: stream.clone(),
id,
fields,
});
}
}
Ok(out)
}
fn parse_fields(v: Value) -> Result<Vec<StreamField>> {
let mut fields = Vec::new();
match v {
Value::Array(fv) => {
if fv.is_empty() || fv.len() % 2 != 0 {
return Err(NasaRedisError::Parsing(
"Stream 字段必须为非空且成对的数组".into(),
));
}
let mut it = fv.into_iter();
while let (Some(f), Some(val)) = (it.next(), it.next()) {
fields.push(StreamField {
event: xread_string(&f)?,
raw: xread_bytes(&val)?,
});
}
}
other => return Err(shape_err("entry fields 应为 Array", &other)),
}
Ok(fields)
}
fn shape_err(what: &str, got: &Value) -> NasaRedisError {
let kind = match got {
Value::Nil => "Nil",
Value::Array(_) => "Array",
Value::Map(_) => "Map",
Value::Set(_) => "Set",
Value::BulkString(_) => "BulkString",
Value::SimpleString(_) => "SimpleString",
Value::Int(_) => "Int",
_ => "其它类型",
};
NasaRedisError::Config(format!("Stream 回复结构异常:{what}(实得 {kind})"))
}
fn first_entry_id(v: &Value) -> Result<Option<String>> {
let arr = match v {
Value::Array(a) if a.len() <= 1 => a,
other => return Err(shape_err("XREVRANGE 应为最多一条的 Array", other)),
};
let Some(first) = arr.first() else {
return Ok(None);
};
let idfields = match first {
Value::Array(a) if a.len() == 2 => a,
other => return Err(shape_err("XREVRANGE entry 应为 [id, fields]", other)),
};
let id = xread_string(&idfields[0])?;
if stream_id_parts(&id).is_none_or(|parts| parts == (0, 0)) {
return Err(NasaRedisError::Parsing("XREVRANGE 条目身份非法".into()));
}
let fields = match &idfields[1] {
Value::Array(fields) if !fields.is_empty() && fields.len() % 2 == 0 => fields,
other => return Err(shape_err("XREVRANGE fields 应为非空成对 Array", other)),
};
if !fields
.iter()
.all(|field| matches!(field, Value::BulkString(_) | Value::SimpleString(_)))
{
return Err(NasaRedisError::Parsing("XREVRANGE 字段不是字符串".into()));
}
Ok(Some(id))
}
fn xread_string(v: &Value) -> Result<String> {
match v {
Value::BulkString(b) => String::from_utf8(b.clone())
.map_err(|_| NasaRedisError::Parsing("Stream 文本不是合法 UTF-8".into())),
Value::SimpleString(s) => Ok(s.clone()),
other => Err(shape_err("应为字符串(bulk/simple)", other)),
}
}
fn xread_bytes(v: &Value) -> Result<Vec<u8>> {
match v {
Value::BulkString(b) => Ok(b.clone()),
Value::SimpleString(s) => Ok(s.clone().into_bytes()),
other => Err(shape_err("field value 应为字符串/字节", other)),
}
}