use std::time::Duration;
pub(crate) const MAGIC: &[u8; 4] = b"ZKB1";
pub(crate) const MAX_FIELD_BYTES: u32 = 64 * 1024 * 1024;
pub(crate) const MAX_TASKS: u32 = 10_000;
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct BatchTask {
pub id: u32,
pub requirements: Vec<u8>,
pub payload: Vec<u8>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ResultStatus {
Ok,
Failed,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct BatchResult {
pub id: u32,
pub status: ResultStatus,
pub body: Vec<u8>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum CodecError {
BadMagic,
Truncated,
TrailingBytes(usize),
DuplicateId(u32),
TooLarge {
field: &'static str,
len: u32,
},
BadStatus(u8),
}
pub(crate) fn encode_request(tasks: &[BatchTask]) -> Vec<u8> {
let mut out = Vec::with_capacity(
8 + tasks
.iter()
.map(|t| 12 + t.requirements.len() + t.payload.len())
.sum::<usize>(),
);
out.extend_from_slice(MAGIC);
out.extend_from_slice(&(tasks.len() as u32).to_le_bytes());
for t in tasks {
out.extend_from_slice(&t.id.to_le_bytes());
out.extend_from_slice(&(t.requirements.len() as u32).to_le_bytes());
out.extend_from_slice(&t.requirements);
out.extend_from_slice(&(t.payload.len() as u32).to_le_bytes());
out.extend_from_slice(&t.payload);
}
out
}
struct Cursor<'a> {
bytes: &'a [u8],
at: usize,
}
pub(crate) fn decode_request(bytes: &[u8]) -> Result<Vec<BatchTask>, CodecError> {
if bytes.len() < MAGIC.len() || &bytes[..MAGIC.len()] != MAGIC {
return Err(CodecError::BadMagic);
}
let mut c = Cursor {
bytes,
at: MAGIC.len(),
};
let count = c.u32()?;
if count > MAX_TASKS {
return Err(CodecError::TooLarge {
field: "count",
len: count,
});
}
let mut tasks = Vec::with_capacity(count as usize);
let mut seen = std::collections::HashSet::with_capacity(count as usize);
for _ in 0..count {
let id = c.u32()?;
if !seen.insert(id) {
return Err(CodecError::DuplicateId(id));
}
let requirements = c.blob("requirements")?;
let payload = c.blob("payload")?;
tasks.push(BatchTask {
id,
requirements,
payload,
});
}
match bytes.len() - c.at {
0 => Ok(tasks),
extra => Err(CodecError::TrailingBytes(extra)),
}
}
pub(crate) fn encode_result(result: &BatchResult) -> Vec<u8> {
let mut out = Vec::with_capacity(9 + result.body.len());
out.extend_from_slice(&result.id.to_le_bytes());
out.push(match result.status {
ResultStatus::Ok => 0,
ResultStatus::Failed => 1,
});
out.extend_from_slice(&(result.body.len() as u32).to_le_bytes());
out.extend_from_slice(&result.body);
out
}
pub(crate) fn decode_results(bytes: &[u8]) -> Result<(Vec<BatchResult>, usize), CodecError> {
const HEADER: usize = 4 + 1 + 4;
let mut out = Vec::new();
let mut at = 0usize;
while bytes.len() - at >= HEADER {
let id = u32::from_le_bytes(bytes[at..at + 4].try_into().expect("4 bytes"));
let status = match bytes[at + 4] {
0 => ResultStatus::Ok,
1 => ResultStatus::Failed,
other => return Err(CodecError::BadStatus(other)),
};
let len = u32::from_le_bytes(bytes[at + 5..at + 9].try_into().expect("4 bytes"));
if len > MAX_FIELD_BYTES {
return Err(CodecError::TooLarge {
field: "result",
len,
});
}
let end = at + HEADER + len as usize;
if end > bytes.len() {
break; }
out.push(BatchResult {
id,
status,
body: bytes[at + HEADER..end].to_vec(),
});
at = end;
}
Ok((out, at))
}
pub(crate) fn batch_hint(
rtt: Duration,
service_p50: Duration,
worker_slots: usize,
cap: usize,
) -> usize {
let cap = cap.max(1);
if worker_slots == 0 || rtt.is_zero() {
return 1;
}
if service_p50.is_zero() {
return cap;
}
let want = worker_slots as f64 * rtt.as_secs_f64() / service_p50.as_secs_f64();
(want.ceil() as usize).clamp(1, cap)
}
impl Cursor<'_> {
fn take(&mut self, n: usize) -> Result<&[u8], CodecError> {
let end = self.at.checked_add(n).ok_or(CodecError::Truncated)?;
let slice = self.bytes.get(self.at..end).ok_or(CodecError::Truncated)?;
self.at = end;
Ok(slice)
}
fn u32(&mut self) -> Result<u32, CodecError> {
Ok(u32::from_le_bytes(
self.take(4)?.try_into().expect("take(4) yields 4 bytes"),
))
}
fn blob(&mut self, field: &'static str) -> Result<Vec<u8>, CodecError> {
let len = self.u32()?;
if len > MAX_FIELD_BYTES {
return Err(CodecError::TooLarge { field, len });
}
Ok(self.take(len as usize)?.to_vec())
}
}
#[cfg(test)]
mod tests {
use super::*;
fn task(id: u32, payload: &[u8]) -> BatchTask {
BatchTask {
id,
requirements: Vec::new(),
payload: payload.to_vec(),
}
}
#[test]
fn a_batch_survives_the_round_trip() {
let tasks = vec![
task(1, b"\x80\x05K\x05."),
BatchTask {
id: 2,
requirements: br#"{"cpus":4.0}"#.to_vec(),
payload: b"payload two".to_vec(),
},
task(3, b""),
];
let wire = encode_request(&tasks);
assert_eq!(decode_request(&wire).unwrap(), tasks);
}
#[test]
fn an_empty_batch_is_legal_and_round_trips() {
let wire = encode_request(&[]);
assert_eq!(decode_request(&wire).unwrap(), Vec::new());
}
#[test]
fn tasks_inheriting_the_batch_requirements_cost_no_bytes_for_them() {
let inherited = encode_request(&[task(1, b"x"), task(2, b"y")]);
let overridden = encode_request(&[
BatchTask {
id: 1,
requirements: br#"{"cpus":4.0}"#.to_vec(),
payload: b"x".to_vec(),
},
task(2, b"y"),
]);
assert_eq!(
overridden.len() - inherited.len(),
r#"{"cpus":4.0}"#.len(),
"an inherited requirement costs its length field and nothing else"
);
}
#[test]
fn something_that_is_not_a_batch_is_refused_before_anything_is_allocated() {
assert_eq!(
decode_request(b"<html>nope</html>"),
Err(CodecError::BadMagic)
);
assert_eq!(decode_request(b""), Err(CodecError::BadMagic));
}
#[test]
fn every_truncation_of_a_batch_is_refused() {
let wire = encode_request(&[task(1, b"hello"), task(2, b"world")]);
for cut in 0..wire.len() {
let err = decode_request(&wire[..cut]).unwrap_err();
assert!(
matches!(err, CodecError::BadMagic | CodecError::Truncated),
"prefix of {cut} bytes gave {err:?}"
);
}
assert!(decode_request(&wire).is_ok(), "the whole thing still reads");
}
#[test]
fn a_repeated_id_is_refused() {
let wire = encode_request(&[task(7, b"a"), task(7, b"b")]);
assert_eq!(decode_request(&wire), Err(CodecError::DuplicateId(7)));
}
#[test]
fn an_absurd_length_is_refused_rather_than_allocated() {
let mut wire = Vec::new();
wire.extend_from_slice(MAGIC);
wire.extend_from_slice(&1u32.to_le_bytes()); wire.extend_from_slice(&1u32.to_le_bytes()); wire.extend_from_slice(&0u32.to_le_bytes()); wire.extend_from_slice(&u32::MAX.to_le_bytes()); assert_eq!(
decode_request(&wire),
Err(CodecError::TooLarge {
field: "payload",
len: u32::MAX
})
);
}
#[test]
fn an_absurd_task_count_is_refused_before_the_loop() {
let mut wire = Vec::new();
wire.extend_from_slice(MAGIC);
wire.extend_from_slice(&u32::MAX.to_le_bytes());
assert_eq!(
decode_request(&wire),
Err(CodecError::TooLarge {
field: "count",
len: u32::MAX
})
);
}
#[test]
fn a_count_larger_than_the_body_is_a_truncation() {
let mut wire = encode_request(&[task(1, b"a")]);
wire[4..8].copy_from_slice(&3u32.to_le_bytes());
assert_eq!(decode_request(&wire), Err(CodecError::Truncated));
}
#[test]
fn a_body_longer_than_the_declared_count_is_refused() {
let mut wire = encode_request(&[task(1, b"a")]);
wire.extend_from_slice(b"leftover");
assert_eq!(decode_request(&wire), Err(CodecError::TrailingBytes(8)));
}
#[test]
fn a_result_survives_the_round_trip() {
let r = BatchResult {
id: 9,
status: ResultStatus::Ok,
body: b"\x80\x05K\x05.".to_vec(),
};
let (got, used) = decode_results(&encode_result(&r)).unwrap();
assert_eq!(got, vec![r.clone()]);
assert_eq!(used, encode_result(&r).len());
}
#[test]
fn a_partial_trailing_frame_is_kept_for_later_not_treated_as_an_error() {
let a = BatchResult {
id: 1,
status: ResultStatus::Ok,
body: b"first".to_vec(),
};
let b = BatchResult {
id: 2,
status: ResultStatus::Failed,
body: b"worker raised".to_vec(),
};
let mut buf = encode_result(&a);
buf.extend_from_slice(&encode_result(&b));
let whole = buf.len();
buf.extend_from_slice(
&encode_result(&BatchResult {
id: 3,
status: ResultStatus::Ok,
body: b"incomplete".to_vec(),
})[..4],
);
let (got, used) = decode_results(&buf).unwrap();
assert_eq!(got, vec![a, b]);
assert_eq!(used, whole, "only the complete frames are consumed");
}
#[test]
fn nothing_yet_is_not_an_error() {
assert_eq!(decode_results(b"").unwrap(), (Vec::new(), 0));
}
#[test]
fn an_unknown_status_byte_is_refused() {
let mut wire = encode_result(&BatchResult {
id: 1,
status: ResultStatus::Ok,
body: b"x".to_vec(),
});
wire[4] = 99;
assert_eq!(decode_results(&wire), Err(CodecError::BadStatus(99)));
}
#[test]
fn a_result_claiming_an_absurd_body_is_refused() {
let mut wire = Vec::new();
wire.extend_from_slice(&1u32.to_le_bytes()); wire.push(0); wire.extend_from_slice(&u32::MAX.to_le_bytes()); assert_eq!(
decode_results(&wire),
Err(CodecError::TooLarge {
field: "result",
len: u32::MAX
})
);
}
const CAP: usize = 512;
#[test]
fn the_hint_keeps_the_fleet_fed_across_one_round_trip() {
assert_eq!(
batch_hint(
Duration::from_millis(800),
Duration::from_millis(10),
8,
CAP
),
CAP
);
assert_eq!(
batch_hint(
Duration::from_millis(800),
Duration::from_millis(100),
4,
CAP
),
32
);
}
#[test]
fn a_local_broker_is_told_not_to_batch() {
assert_eq!(
batch_hint(Duration::ZERO, Duration::from_millis(1), 32, CAP),
1
);
}
#[test]
fn work_slower_than_the_round_trip_needs_no_batching() {
assert_eq!(
batch_hint(Duration::from_millis(800), Duration::from_secs(30), 1, CAP),
1
);
}
#[test]
fn degenerate_inputs_still_give_a_usable_size() {
assert_eq!(
batch_hint(Duration::from_millis(800), Duration::ZERO, 8, CAP),
CAP,
"unmeasured service time means we do not know it is slow"
);
assert_eq!(
batch_hint(
Duration::from_millis(800),
Duration::from_millis(10),
0,
CAP
),
1,
"no free slots: ask for one task, not none"
);
assert_eq!(
batch_hint(Duration::from_millis(800), Duration::from_millis(10), 8, 0),
1,
"a zero cap must not mean a zero batch"
);
}
}