use bytes::{Buf, BufMut, Bytes, BytesMut};
use super::{
COMPRESSION_THRESHOLD, FLAG_COMPRESSED, FLAG_HAS_RECOVERY, FLAG_REPLAYED, MAGIC,
MAX_CLUSTER_PEERS, MAX_FRAME_SIZE, MAX_KNOWN_PEERS, PROTOCOL_VERSION, PROTOCOL_VERSION_MIN,
};
#[repr(u8)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum MsgType {
Msg = 0x01,
Ping = 0x02,
Pong = 0x03,
Hello = 0x04,
Shutdown = 0x05,
Sub = 0x06,
Unsub = 0x07,
Resync = 0x08,
PeerAnnounce = 0x09,
PeerList = 0x0A,
PresenceUpdate = 0x0B,
PresenceFull = 0x0C,
Drain = 0x0D,
Resume = 0x0E,
}
impl MsgType {
fn from_u8(v: u8) -> Option<Self> {
match v {
0x01 => Some(Self::Msg),
0x02 => Some(Self::Ping),
0x03 => Some(Self::Pong),
0x04 => Some(Self::Hello),
0x05 => Some(Self::Shutdown),
0x06 => Some(Self::Sub),
0x07 => Some(Self::Unsub),
0x08 => Some(Self::Resync),
0x09 => Some(Self::PeerAnnounce),
0x0A => Some(Self::PeerList),
0x0B => Some(Self::PresenceUpdate),
0x0C => Some(Self::PresenceFull),
0x0D => Some(Self::Drain),
0x0E => Some(Self::Resume),
_ => None,
}
}
}
pub(crate) fn encode_msg(buf: &mut BytesMut, topic: &str, payload: &str) -> bool {
let topic_bytes = topic.as_bytes();
if topic_bytes.len() > u16::MAX as usize {
tracing::warn!(
"[WSE-Cluster] Topic too long ({} bytes, max {}), dropping message",
topic_bytes.len(),
u16::MAX
);
return false;
}
let payload_bytes = payload.as_bytes();
let total_frame = 8 + topic_bytes.len() + payload_bytes.len();
if total_frame > MAX_FRAME_SIZE {
tracing::warn!(
"[WSE-Cluster] Frame too large ({total_frame} bytes, max {MAX_FRAME_SIZE}), dropping message",
);
return false;
}
buf.reserve(total_frame);
buf.put_u8(MsgType::Msg as u8);
buf.put_u8(0); buf.put_u16_le(topic_bytes.len() as u16);
buf.put_u32_le(payload_bytes.len() as u32);
buf.put_slice(topic_bytes);
buf.put_slice(payload_bytes);
true
}
pub(crate) fn encode_msg_compressed(buf: &mut BytesMut, topic: &str, payload: &str) -> bool {
let topic_bytes = topic.as_bytes();
if topic_bytes.len() > u16::MAX as usize {
tracing::warn!(
"[WSE-Cluster] Topic too long ({} bytes, max {}), dropping message",
topic_bytes.len(),
u16::MAX
);
return false;
}
let payload_bytes = payload.as_bytes();
if payload_bytes.len() >= COMPRESSION_THRESHOLD
&& let Ok(compressed) = zstd::bulk::compress(payload_bytes, 1)
&& compressed.len() < payload_bytes.len()
{
buf.reserve(8 + topic_bytes.len() + compressed.len());
buf.put_u8(MsgType::Msg as u8);
buf.put_u8(FLAG_COMPRESSED);
buf.put_u16_le(topic_bytes.len() as u16);
buf.put_u32_le(compressed.len() as u32);
buf.put_slice(topic_bytes);
buf.put_slice(&compressed);
return true;
}
encode_msg(buf, topic, payload)
}
pub(crate) fn encode_msg_with_recovery(
buf: &mut BytesMut,
topic: &str,
payload: &str,
origin_epoch: u32,
origin_offset: u64,
compress: bool,
) -> bool {
let topic_bytes = topic.as_bytes();
if topic_bytes.len() > u16::MAX as usize {
return false;
}
let payload_bytes = payload.as_bytes();
if compress
&& payload_bytes.len() >= COMPRESSION_THRESHOLD
&& let Ok(compressed) = zstd::bulk::compress(payload_bytes, 1)
&& compressed.len() < payload_bytes.len()
{
let total = 8 + topic_bytes.len() + compressed.len() + 12; if total > MAX_FRAME_SIZE {
return false;
}
buf.reserve(total);
buf.put_u8(MsgType::Msg as u8);
buf.put_u8(FLAG_COMPRESSED | FLAG_HAS_RECOVERY);
buf.put_u16_le(topic_bytes.len() as u16);
buf.put_u32_le(compressed.len() as u32);
buf.put_slice(topic_bytes);
buf.put_slice(&compressed);
buf.put_u32_le(origin_epoch);
buf.put_u64_le(origin_offset);
return true;
}
let total = 8 + topic_bytes.len() + payload_bytes.len() + 12;
if total > MAX_FRAME_SIZE {
return false;
}
buf.reserve(total);
buf.put_u8(MsgType::Msg as u8);
buf.put_u8(FLAG_HAS_RECOVERY);
buf.put_u16_le(topic_bytes.len() as u16);
buf.put_u32_le(payload_bytes.len() as u32);
buf.put_slice(topic_bytes);
buf.put_slice(payload_bytes);
buf.put_u32_le(origin_epoch);
buf.put_u64_le(origin_offset);
true
}
pub(crate) fn encode_ping(buf: &mut BytesMut) {
buf.reserve(8);
buf.put_u8(MsgType::Ping as u8);
buf.put_u8(0);
buf.put_u16_le(0);
buf.put_u32_le(0);
}
pub(crate) fn encode_pong(buf: &mut BytesMut) {
buf.reserve(8);
buf.put_u8(MsgType::Pong as u8);
buf.put_u8(0);
buf.put_u16_le(0);
buf.put_u32_le(0);
}
pub(crate) fn encode_hello(buf: &mut BytesMut, instance_id: &str, capabilities: u32) {
let id_bytes = instance_id.as_bytes();
let payload_len = 4 + 2 + 2 + id_bytes.len() + 4;
buf.reserve(8 + payload_len);
buf.put_u8(MsgType::Hello as u8);
buf.put_u8(0); buf.put_u16_le(0); buf.put_u32_le(payload_len as u32);
buf.put_slice(MAGIC);
buf.put_u16_le(PROTOCOL_VERSION);
buf.put_u16_le(id_bytes.len() as u16);
buf.put_slice(id_bytes);
buf.put_u32_le(capabilities);
}
pub(crate) fn encode_shutdown(buf: &mut BytesMut) {
buf.reserve(8);
buf.put_u8(MsgType::Shutdown as u8);
buf.put_u8(0);
buf.put_u16_le(0);
buf.put_u32_le(0);
}
pub(crate) fn encode_drain(buf: &mut BytesMut) {
buf.reserve(8);
buf.put_u8(MsgType::Drain as u8);
buf.put_u8(0);
buf.put_u16_le(0);
buf.put_u32_le(0);
}
pub(crate) fn encode_sub(buf: &mut BytesMut, topic: &str) -> bool {
let topic_bytes = topic.as_bytes();
if topic_bytes.len() > u16::MAX as usize {
return false;
}
buf.reserve(8 + topic_bytes.len());
buf.put_u8(MsgType::Sub as u8);
buf.put_u8(0); buf.put_u16_le(topic_bytes.len() as u16);
buf.put_u32_le(0); buf.put_slice(topic_bytes);
true
}
pub(crate) fn encode_unsub(buf: &mut BytesMut, topic: &str) -> bool {
let topic_bytes = topic.as_bytes();
if topic_bytes.len() > u16::MAX as usize {
return false;
}
buf.reserve(8 + topic_bytes.len());
buf.put_u8(MsgType::Unsub as u8);
buf.put_u8(0); buf.put_u16_le(topic_bytes.len() as u16);
buf.put_u32_le(0); buf.put_slice(topic_bytes);
true
}
const RESYNC_CONTINUATION: u8 = 0x01;
const RESYNC_MORE: u8 = 0x02;
pub(crate) fn encode_replayed(
buf: &mut BytesMut,
topic: &str,
payload: &str,
origin_epoch: u32,
origin_offset: u64,
) -> bool {
let start = buf.len();
if !encode_msg_with_recovery(buf, topic, payload, origin_epoch, origin_offset, true) {
return false;
}
if buf.len() - start > MAX_FRAME_SIZE {
buf.truncate(start);
return false;
}
buf[start + 1] |= FLAG_REPLAYED;
true
}
pub(crate) const RESUME_LAST: u8 = 0x01;
pub(crate) type ResumePoint = (String, u32, u64);
pub(crate) fn encode_resume(points: &[ResumePoint]) -> Vec<BytesMut> {
fn header(buf: &mut BytesMut) {
buf.put_u8(MsgType::Resume as u8);
buf.put_u8(0);
buf.put_u16_le(0);
buf.put_u32_le(0);
}
let mut frames = Vec::new();
let mut buf = BytesMut::new();
header(&mut buf);
for (topic, epoch, offset) in points {
let topic = topic.as_bytes();
let Ok(len) = u16::try_from(topic.len()) else {
continue;
};
let entry = 2 + topic.len() + 12;
if buf.len() + entry > MAX_FRAME_SIZE && buf.len() > 8 {
frames.push(std::mem::take(&mut buf));
header(&mut buf);
}
buf.put_u16_le(len);
buf.put_slice(topic);
buf.put_u32_le(*epoch);
buf.put_u64_le(*offset);
}
frames.push(buf);
if let Some(last) = frames.last_mut() {
last[1] = RESUME_LAST;
}
for frame in &mut frames {
let len = (frame.len() - 8) as u32;
frame[4..8].copy_from_slice(&len.to_le_bytes());
}
frames
}
pub(crate) fn encode_resync(topics: &[String]) -> Vec<BytesMut> {
let payload = topics.join("\n");
let payload_bytes = payload.as_bytes();
fn encode_single(chunk: &[u8], flags: u8) -> BytesMut {
let mut buf = BytesMut::with_capacity(8 + chunk.len());
buf.put_u8(MsgType::Resync as u8);
buf.put_u8(flags);
buf.put_u16_le(0);
buf.put_u32_le(chunk.len() as u32);
buf.put_slice(chunk);
buf
}
if payload_bytes.len() <= MAX_FRAME_SIZE - 8 {
return vec![encode_single(payload_bytes, 0x00)];
}
let mut frames = Vec::new();
let mut start = 0;
while start < payload_bytes.len() {
let remaining = payload_bytes.len() - start;
let chunk_limit = MAX_FRAME_SIZE - 8;
let chunk_end = if remaining <= chunk_limit {
payload_bytes.len()
} else {
let window_end = start + chunk_limit;
match payload_bytes[start..window_end]
.iter()
.rposition(|&b| b == b'\n')
{
Some(pos) => start + pos,
None => window_end,
}
};
let mut flags = if frames.is_empty() {
0x00
} else {
RESYNC_CONTINUATION
};
if chunk_end < payload_bytes.len() {
flags |= RESYNC_MORE;
}
frames.push(encode_single(&payload_bytes[start..chunk_end], flags));
start = if chunk_end < payload_bytes.len() && payload_bytes[chunk_end] == b'\n' {
chunk_end + 1
} else {
chunk_end
};
}
frames
}
pub(crate) fn encode_peer_announce(buf: &mut BytesMut, addr: &str) {
let addr_bytes = addr.as_bytes();
if addr_bytes.len() > u16::MAX as usize {
tracing::warn!(
"[WSE-Cluster] Peer address too long ({} bytes), dropping announce",
addr_bytes.len()
);
return;
}
buf.reserve(8 + addr_bytes.len());
buf.put_u8(MsgType::PeerAnnounce as u8);
buf.put_u8(0); buf.put_u16_le(addr_bytes.len() as u16);
buf.put_u32_le(0); buf.put_slice(addr_bytes);
}
pub(crate) fn encode_peer_list(buf: &mut BytesMut, addrs: &[String]) {
let mut size = 2;
let safe_addrs: Vec<&String> = addrs
.iter()
.filter(|a| a.len() <= u16::MAX as usize)
.take(MAX_KNOWN_PEERS)
.take_while(|a| {
size += 2 + a.len();
size <= MAX_FRAME_SIZE - 8
})
.collect();
let mut payload = BytesMut::new();
payload.put_u16_le(safe_addrs.len() as u16);
for addr in &safe_addrs {
payload.put_u16_le(addr.len() as u16);
payload.extend_from_slice(addr.as_bytes());
}
buf.reserve(8 + payload.len());
buf.put_u8(MsgType::PeerList as u8);
buf.put_u8(0); buf.put_u16_le(0); buf.put_u32_le(payload.len() as u32);
buf.extend_from_slice(&payload);
}
pub(crate) fn encode_presence_update(
buf: &mut BytesMut,
topic: &str,
user_id: &str,
action: u8,
data: &str,
updated_at: u64,
) -> bool {
let topic_bytes = topic.as_bytes();
let user_id_bytes = user_id.as_bytes();
let data_bytes = data.as_bytes();
if topic_bytes.len() > u16::MAX as usize || user_id_bytes.len() > u16::MAX as usize {
return false;
}
let payload_len = 1 + 8 + 2 + user_id_bytes.len() + data_bytes.len();
let total_frame = 8 + topic_bytes.len() + payload_len;
if total_frame > MAX_FRAME_SIZE {
tracing::warn!(
"[WSE-Cluster] PresenceUpdate frame too large ({total_frame} bytes, max {MAX_FRAME_SIZE}), dropping",
);
return false;
}
buf.reserve(total_frame);
buf.put_u8(MsgType::PresenceUpdate as u8);
buf.put_u8(0); buf.put_u16_le(topic_bytes.len() as u16);
buf.put_u32_le(payload_len as u32);
buf.put_slice(topic_bytes);
buf.put_u8(action);
buf.put_u64_le(updated_at);
buf.put_u16_le(user_id_bytes.len() as u16);
buf.put_slice(user_id_bytes);
buf.put_slice(data_bytes);
true
}
pub(crate) const PRESENCE_ROUND: u8 = 0x04;
pub(crate) const PRESENCE_ROUND_FIRST: u8 = 0x01;
pub(crate) const PRESENCE_ROUND_LAST: u8 = 0x02;
#[cfg(test)]
pub(crate) fn encode_presence_full(buf: &mut BytesMut, entries_json: &str) -> bool {
encode_presence_frame(buf, entries_json, 0)
}
pub(crate) fn encode_presence_round(buf: &mut BytesMut, entries_json: &str, edges: u8) -> bool {
encode_presence_frame(buf, entries_json, PRESENCE_ROUND | edges)
}
fn encode_presence_frame(buf: &mut BytesMut, entries_json: &str, flags: u8) -> bool {
let payload_bytes = entries_json.as_bytes();
let total_frame = 8 + payload_bytes.len();
if total_frame > MAX_FRAME_SIZE {
tracing::warn!(
"[WSE-Cluster] PresenceFull frame too large ({total_frame} bytes, max {MAX_FRAME_SIZE}), dropping",
);
return false;
}
let topic_len: u16 = 0; buf.reserve(total_frame);
buf.put_u8(MsgType::PresenceFull as u8);
buf.put_u8(flags);
buf.put_u16_le(topic_len);
buf.put_u32_le(payload_bytes.len() as u32);
buf.put_slice(payload_bytes);
true
}
pub(super) fn write_framed(buf: &mut BytesMut, inner: &[u8]) {
buf.reserve(4 + inner.len());
buf.put_u32(inner.len() as u32); buf.put_slice(inner);
}
#[derive(Debug, PartialEq)]
pub(crate) enum ClusterFrame {
Msg {
topic: String,
payload: Bytes,
recovery: Option<(u32, u64)>,
},
Ping,
Pong,
Hello {
instance_id: String,
protocol_version: u16,
capabilities: u32,
},
Shutdown,
Sub {
topic: String,
},
Unsub {
topic: String,
},
Resync {
topics: Vec<String>,
is_continuation: bool,
more: bool,
},
PeerAnnounce {
addr: String,
},
PeerList {
addrs: Vec<String>,
},
PresenceUpdate {
topic: String,
user_id: String,
action: u8,
data: String,
updated_at: u64,
},
PresenceFull {
entries: String,
flags: u8,
},
Drain,
Resume {
points: Vec<ResumePoint>,
last: bool,
},
Replayed {
topic: String,
payload: Bytes,
position: (u32, u64),
},
Unknown {
msg_type: u8,
},
}
pub(crate) fn decode_frame(mut data: BytesMut) -> Option<ClusterFrame> {
if data.remaining() < 8 {
return None;
}
let raw_type = data.get_u8();
let flags = data.get_u8();
let topic_len = data.get_u16_le() as usize;
let payload_len = data.get_u32_le() as usize;
match MsgType::from_u8(raw_type) {
Some(MsgType::Msg) => {
if data.remaining() < topic_len + payload_len {
return None;
}
let topic = String::from_utf8(data.split_to(topic_len).to_vec()).ok()?;
let payload = if flags & FLAG_COMPRESSED != 0 {
let compressed = data.split_to(payload_len);
let mut decompressed = match zstd::bulk::decompress(&compressed, MAX_FRAME_SIZE) {
Ok(d) => d,
Err(e) => {
tracing::warn!(
"[WSE-Cluster] Decompression failed ({payload_len} bytes compressed): {e}"
);
return None;
}
};
decompressed.shrink_to_fit();
Bytes::from(decompressed)
} else {
data.split_to(payload_len).freeze() };
let recovery = if flags & FLAG_HAS_RECOVERY != 0 {
if data.remaining() < 12 {
return None; }
let epoch = data.get_u32_le();
let offset = data.get_u64_le();
Some((epoch, offset))
} else {
None
};
if flags & FLAG_REPLAYED != 0
&& let Some(position) = recovery
{
return Some(ClusterFrame::Replayed {
topic,
payload,
position,
});
}
Some(ClusterFrame::Msg {
topic,
payload,
recovery,
})
}
Some(MsgType::Resume) => {
if data.remaining() < payload_len {
return None;
}
let mut payload = data.split_to(payload_len);
let mut points = Vec::new();
while payload.has_remaining() {
if payload.remaining() < 2 {
return None;
}
let topic_len = payload.get_u16_le() as usize;
if payload.remaining() < topic_len + 12 {
return None;
}
let topic = String::from_utf8(payload.split_to(topic_len).to_vec()).ok()?;
let epoch = payload.get_u32_le();
let offset = payload.get_u64_le();
points.push((topic, epoch, offset));
}
Some(ClusterFrame::Resume {
points,
last: flags & RESUME_LAST != 0,
})
}
Some(MsgType::Ping) => Some(ClusterFrame::Ping),
Some(MsgType::Pong) => Some(ClusterFrame::Pong),
Some(MsgType::Hello) => {
if payload_len < 12 || data.remaining() < payload_len {
return None;
}
let magic = data.split_to(4);
if magic.as_ref() != MAGIC {
return None;
}
let version = data.get_u16_le();
let id_len = data.get_u16_le() as usize;
if id_len > 256 {
tracing::warn!(
"[WSE-Cluster] Instance ID too long: {} bytes, max 256",
id_len
);
return None;
}
if data.remaining() < id_len + 4 {
return None;
}
let instance_id = String::from_utf8(data.split_to(id_len).to_vec()).ok()?;
let capabilities = data.get_u32_le();
Some(ClusterFrame::Hello {
instance_id,
protocol_version: version,
capabilities,
})
}
Some(MsgType::Shutdown) => Some(ClusterFrame::Shutdown),
Some(MsgType::Drain) => Some(ClusterFrame::Drain),
Some(MsgType::Sub) => {
if data.remaining() < topic_len {
return None;
}
let topic = String::from_utf8(data.split_to(topic_len).to_vec()).ok()?;
Some(ClusterFrame::Sub { topic })
}
Some(MsgType::Unsub) => {
if data.remaining() < topic_len {
return None;
}
let topic = String::from_utf8(data.split_to(topic_len).to_vec()).ok()?;
Some(ClusterFrame::Unsub { topic })
}
Some(MsgType::Resync) => {
if data.remaining() < payload_len {
return None;
}
let topics = if payload_len == 0 {
Vec::new()
} else {
let raw_bytes = data.split_to(payload_len);
let slice: &[u8] = &raw_bytes;
slice
.split(|&b| b == b'\n')
.filter(|chunk| !chunk.is_empty())
.filter_map(|chunk| String::from_utf8(chunk.to_vec()).ok())
.collect()
};
Some(ClusterFrame::Resync {
topics,
is_continuation: flags & RESYNC_CONTINUATION != 0,
more: flags & RESYNC_MORE != 0,
})
}
Some(MsgType::PeerAnnounce) => {
if data.remaining() < topic_len {
return None;
}
let addr = String::from_utf8(data.split_to(topic_len).to_vec()).ok()?;
Some(ClusterFrame::PeerAnnounce { addr })
}
Some(MsgType::PeerList) => {
if data.remaining() < payload_len {
return None;
}
if payload_len < 2 {
return Some(ClusterFrame::PeerList { addrs: Vec::new() });
}
let payload = data.split_to(payload_len);
let count =
(u16::from_le_bytes([payload[0], payload[1]]) as usize).min(MAX_CLUSTER_PEERS);
let mut addrs = Vec::with_capacity(count);
let mut pos = 2usize;
for _ in 0..count {
if pos + 2 > payload.len() {
break;
}
let alen = u16::from_le_bytes([payload[pos], payload[pos + 1]]) as usize;
pos += 2;
if pos + alen > payload.len() {
break;
}
if let Ok(a) = std::str::from_utf8(&payload[pos..pos + alen]) {
addrs.push(a.to_string());
}
pos += alen;
}
Some(ClusterFrame::PeerList { addrs })
}
Some(MsgType::PresenceUpdate) => {
if data.remaining() < topic_len + payload_len {
return None;
}
let topic = String::from_utf8(data.split_to(topic_len).to_vec()).ok()?;
if data.remaining() < 1 + 8 + 2 {
return None;
}
let action = data.get_u8();
let updated_at = data.get_u64_le();
let user_id_len = data.get_u16_le() as usize;
if data.remaining() < user_id_len {
return None;
}
let user_id = String::from_utf8(data.split_to(user_id_len).to_vec()).ok()?;
let remaining_data = payload_len.saturating_sub(1 + 8 + 2 + user_id_len);
let presence_data = if remaining_data > 0 && data.remaining() >= remaining_data {
String::from_utf8(data.split_to(remaining_data).to_vec()).ok()?
} else {
String::new()
};
Some(ClusterFrame::PresenceUpdate {
topic,
user_id,
action,
data: presence_data,
updated_at,
})
}
Some(MsgType::PresenceFull) => {
if data.remaining() < payload_len {
return None;
}
let entries = String::from_utf8(data.split_to(payload_len).to_vec()).ok()?;
Some(ClusterFrame::PresenceFull { entries, flags })
}
None => {
Some(ClusterFrame::Unknown { msg_type: raw_type })
}
}
}
pub(crate) fn negotiate_version(local_ver: u16, remote_ver: u16) -> Option<u16> {
let negotiated = local_ver.min(remote_ver);
if negotiated >= PROTOCOL_VERSION_MIN {
Some(negotiated)
} else {
None
}
}
pub(crate) fn negotiate_capabilities(local: u32, remote: u32) -> u32 {
local & remote
}