use std::collections::{BTreeMap, HashMap, VecDeque};
use std::future::Future;
use std::io::{IoSlice, Write};
use std::ops::Range;
use std::pin::Pin;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
use bytes::Bytes;
use shardline_xet_adapter::{ReconstructionFetchInfo, ReconstructionMultiRangeFetch};
use tokio::sync::mpsc::{UnboundedReceiver, UnboundedSender, unbounded_channel};
use tokio::sync::{Notify, OnceCell, OwnedSemaphorePermit, Semaphore, oneshot};
use tokio::task::{JoinHandle, JoinSet};
use tokio_util::{sync::CancellationToken, task::AbortOnDropHandle};
use xet_core_structures::ExpWeightedMovingAvg;
use xet_runtime as _;
use crate::{
auth::TokenService,
cache::ChunkCache,
error::{SdxError, TransferError},
hash::parse_xet_hash_hex,
reconstruction::{ReconstructionResponse, fetch_reconstruction_response},
retry::{RetryContext, RetryMarkers, RetryPolicy, RetryScope},
transfer::{ByteRange, TransferClient},
xorb::XorbReader,
};
pub const DEFAULT_DOWNLOAD_BUFFER_SIZE: u64 = 2_147_483_648;
pub const DEFAULT_DOWNLOAD_BUFFER_PERFILE_SIZE: u64 = 536_870_912;
pub const DEFAULT_DOWNLOAD_BUFFER_LIMIT: u64 = 8_589_934_592;
pub const DEFAULT_MIN_RECONSTRUCTION_FETCH_SIZE: u64 = 268_435_456;
pub const DEFAULT_MAX_RECONSTRUCTION_FETCH_SIZE: u64 = 8_589_934_592;
pub const DEFAULT_MIN_PREFETCH_BUFFER: u64 = 1_073_741_824;
pub const DEFAULT_TARGET_BLOCK_COMPLETION_TIME_SECS: f64 = 900.0;
pub const DEFAULT_COMPLETION_RATE_ESTIMATOR_HALF_LIFE: f64 = 4.0;
pub const DEFAULT_DOWNLOAD_CONCURRENCY: usize = 4;
const MAX_BUFFERED_TERMS: usize = 128;
const MAX_COALESCED_BLOCK_BYTES: u64 = 512 * 1024;
#[derive(Debug, Clone)]
pub struct StreamLimits {
pub min_reconstruction_fetch_size: u64,
pub max_reconstruction_fetch_size: u64,
pub min_prefetch_buffer: u64,
pub target_block_completion_time_secs: f64,
pub completion_rate_estimator_half_life: f64,
}
impl Default for StreamLimits {
fn default() -> Self {
Self {
min_reconstruction_fetch_size: DEFAULT_MIN_RECONSTRUCTION_FETCH_SIZE,
max_reconstruction_fetch_size: DEFAULT_MAX_RECONSTRUCTION_FETCH_SIZE,
min_prefetch_buffer: DEFAULT_MIN_PREFETCH_BUFFER,
target_block_completion_time_secs: DEFAULT_TARGET_BLOCK_COMPLETION_TIME_SECS,
completion_rate_estimator_half_life: DEFAULT_COMPLETION_RATE_ESTIMATOR_HALF_LIFE,
}
}
}
#[derive(Clone)]
pub(crate) struct StreamContext {
pub transfer: TransferClient,
pub api_base: String,
pub buffer_semaphore: Arc<BufferSemaphore>,
pub active_downloads: Arc<AtomicU64>,
pub download_permits: Arc<Semaphore>,
pub limits: StreamLimits,
pub chunk_cache: Option<Arc<ChunkCache>>,
pub xorb_fetch_count: Arc<AtomicU64>,
pub tokens: TokenService,
pub retry_policy: RetryPolicy,
#[cfg(not(target_family = "wasm"))]
pub blocking_runtime: Arc<tokio::runtime::Runtime>,
}
impl StreamContext {
pub(crate) fn retry_context(&self) -> RetryContext {
RetryContext {
policy: self.retry_policy.clone(),
tokens: Some(self.tokens.clone()),
scope: RetryScope::Read,
markers: RetryMarkers::ranged_xorb(),
}
}
}
#[cfg(not(target_family = "wasm"))]
pub(crate) fn global_blocking_runtime() -> Result<Arc<tokio::runtime::Runtime>, SdxError> {
static RUNTIME: OnceLock<Result<Arc<tokio::runtime::Runtime>, String>> = OnceLock::new();
let slot = RUNTIME.get_or_init(|| {
tokio::runtime::Builder::new_multi_thread()
.worker_threads(
std::thread::available_parallelism().map_or(1, |count| count.get().min(2)),
)
.enable_all()
.build()
.map(Arc::new)
.map_err(|error| error.to_string())
});
match slot {
Ok(runtime) => Ok(runtime.clone()),
Err(message) => Err(SdxError::StreamInternal(format!(
"blocking runtime failed to start: {message}"
))),
}
}
#[cfg(not(target_family = "wasm"))]
fn block_on_download<F, T>(runtime: &tokio::runtime::Runtime, future: F) -> Result<T, SdxError>
where
F: Future<Output = Result<T, SdxError>> + Send,
T: Send,
{
if tokio::runtime::Handle::try_current().is_err() {
return runtime.block_on(future);
}
std::thread::scope(|scope| {
std::thread::Builder::new()
.name("sdx-download-bridge".to_owned())
.spawn_scoped(scope, || runtime.block_on(future))
.map_err(SdxError::Io)?
.join()
.map_err(|_panic_payload| {
SdxError::StreamInternal("download bridge thread panicked".to_owned())
})?
})
}
pub struct BufferSemaphore {
semaphore: Arc<Semaphore>,
total_permits: AtomicU64,
enqueued_permit_decreases: AtomicU64,
min_physical_permits: u64,
max_physical_permits: u64,
basis: u64,
adjustment_lock: Mutex<()>,
}
pub struct BufferPermit {
permit: Option<OwnedSemaphorePermit>,
num_physical_permits: u32,
parent: Arc<BufferSemaphore>,
_term_slot: Option<OwnedSemaphorePermit>,
_backing_block: Option<Arc<XorbBlock>>,
}
impl BufferSemaphore {
#[must_use]
pub fn new(min_permits: u64, initial_permits: u64, max_permits: u64) -> Self {
let basis = Self::compute_basis(max_permits);
let min_physical = min_permits.div_ceil(basis);
let max_physical = max_permits.div_ceil(basis);
let initial_physical = initial_permits
.div_ceil(basis)
.clamp(min_physical, max_physical);
Self {
semaphore: Arc::new(Semaphore::new(
usize::try_from(initial_physical).unwrap_or(usize::MAX),
)),
total_permits: AtomicU64::new(initial_physical),
enqueued_permit_decreases: AtomicU64::new(0),
min_physical_permits: min_physical,
max_physical_permits: max_physical,
basis,
adjustment_lock: Mutex::new(()),
}
}
#[must_use]
pub fn total_permits(&self) -> u64 {
self.total_permits
.load(Ordering::Relaxed)
.saturating_mul(self.basis)
}
#[must_use]
pub fn available_permits(&self) -> u64 {
u64::try_from(self.semaphore.available_permits())
.unwrap_or(u64::MAX)
.saturating_mul(self.basis)
}
pub async fn acquire_many(self: &Arc<Self>, n: u64) -> Result<BufferPermit, SdxError> {
let physical = self.to_physical_acquire(n);
let permit = self
.semaphore
.clone()
.acquire_many_owned(physical)
.await
.map_err(|error| {
SdxError::StreamInternal(format!("buffer permit acquire failed: {error}"))
})?;
Ok(BufferPermit {
permit: Some(permit),
num_physical_permits: physical,
parent: self.clone(),
_term_slot: None,
_backing_block: None,
})
}
pub fn increment_permits_to_target(self: &Arc<Self>, target: u64) -> Option<BufferPermit> {
let _lock = self
.adjustment_lock
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let current = self.total_permits();
if target <= current {
return None;
}
self.increment_total_permits_impl(target.saturating_sub(current))
}
pub fn decrement_permits_to_target(&self, target: u64) -> Option<u64> {
let _lock = self
.adjustment_lock
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
let current = self.total_permits();
if target >= current {
return None;
}
let n = current.saturating_sub(target);
let physical_n = n.div_ceil(self.basis);
if physical_n == 0 {
return None;
}
let removed = attempt_sub(&self.total_permits, physical_n, self.min_physical_permits);
if removed == 0 {
return None;
}
let removed_u32 = u32::try_from(removed).unwrap_or(u32::MAX);
if let Ok(permit) = self.semaphore.clone().try_acquire_many_owned(removed_u32) {
permit.forget();
} else {
self.enqueued_permit_decreases
.fetch_add(removed, Ordering::Relaxed);
}
Some(removed.saturating_mul(self.basis))
}
fn increment_total_permits_impl(self: &Arc<Self>, n: u64) -> Option<BufferPermit> {
let physical_n = n.div_ceil(self.basis);
if physical_n == 0 {
return None;
}
let added = attempt_add(&self.total_permits, physical_n, self.max_physical_permits);
if added == 0 {
return None;
}
let cancelled = attempt_sub(&self.enqueued_permit_decreases, added, 0);
let to_hold = added.saturating_sub(cancelled);
Some(BufferPermit {
permit: None,
num_physical_permits: u32::try_from(to_hold).unwrap_or(u32::MAX),
parent: self.clone(),
_term_slot: None,
_backing_block: None,
})
}
fn to_physical_acquire(&self, n: u64) -> u32 {
let total = self.total_permits.load(Ordering::Relaxed).max(1);
u32::try_from(n.div_ceil(self.basis).clamp(1, total)).unwrap_or(u32::MAX)
}
const fn compute_basis(max_permits: u64) -> u64 {
let mut basis: u64 = 1;
while max_permits.div_ceil(basis) > u32::MAX as u64 {
basis = basis.saturating_mul(2);
}
basis
}
}
impl BufferPermit {
const fn for_term(
parent: Arc<BufferSemaphore>,
slot: OwnedSemaphorePermit,
block: Arc<XorbBlock>,
) -> Self {
Self {
permit: None,
num_physical_permits: 0,
parent,
_term_slot: Some(slot),
_backing_block: Some(block),
}
}
#[must_use]
pub fn num_permits(&self) -> u64 {
u64::from(self.num_physical_permits).saturating_mul(self.parent.basis)
}
pub fn split(&mut self, n: u64) -> Option<BufferPermit> {
let physical_n = n.div_ceil(self.parent.basis);
if physical_n > u64::from(self.num_physical_permits) {
return None;
}
let physical_n = u32::try_from(physical_n).unwrap_or(u32::MAX);
self.num_physical_permits = self.num_physical_permits.saturating_sub(physical_n);
if physical_n > 0 {
let permit = self
.permit
.as_mut()
.and_then(|permit| permit.split(usize::try_from(physical_n).unwrap_or(usize::MAX)));
Some(BufferPermit {
permit,
num_physical_permits: physical_n,
parent: self.parent.clone(),
_term_slot: None,
_backing_block: None,
})
} else {
None
}
}
}
impl Drop for BufferPermit {
fn drop(&mut self) {
let parent = &self.parent;
let num_permits = u64::from(self.num_physical_permits);
let resolved = attempt_sub(&parent.enqueued_permit_decreases, num_permits, 0);
if let Some(mut permit) = self.permit.take() {
if resolved > 0 {
if let Some(split) = permit.split(usize::try_from(resolved).unwrap_or(usize::MAX)) {
split.forget();
}
}
} else {
let to_return = num_permits.saturating_sub(resolved);
if to_return > 0 {
parent
.semaphore
.add_permits(usize::try_from(to_return).unwrap_or(usize::MAX));
}
}
}
}
fn attempt_add(counter: &AtomicU64, n: u64, max_value: u64) -> u64 {
counter
.try_update(Ordering::SeqCst, Ordering::SeqCst, |current| {
if current >= max_value {
None
} else {
Some(current.saturating_add(n).min(max_value))
}
})
.map_or(0, |previous| {
previous
.saturating_add(n)
.min(max_value)
.saturating_sub(previous)
})
}
fn attempt_sub(counter: &AtomicU64, n: u64, min_value: u64) -> u64 {
counter
.try_update(Ordering::SeqCst, Ordering::SeqCst, |current| {
if current <= min_value {
None
} else {
Some(current.saturating_sub(n).max(min_value))
}
})
.map_or(0, |previous| {
let after = previous.saturating_sub(n).max(min_value);
previous.saturating_sub(after)
})
}
struct ExitGuard<F: FnOnce()>(Option<F>);
impl<F: FnOnce()> ExitGuard<F> {
const fn new(f: F) -> Self {
Self(Some(f))
}
fn disarm(&mut self) {
drop(self.0.take());
}
}
impl<F: FnOnce()> Drop for ExitGuard<F> {
fn drop(&mut self) {
if let Some(f) = self.0.take() {
f();
}
}
}
pub(crate) enum RunError {
Cancelled,
Error(SdxError),
}
impl From<SdxError> for RunError {
fn from(error: SdxError) -> Self {
RunError::Error(error)
}
}
pub(crate) struct RunState {
cancellation_token: CancellationToken,
has_error: AtomicBool,
stored_error: Mutex<Option<SdxError>>,
total_bytes_scheduled: AtomicU64,
total_bytes_delivered: AtomicU64,
}
impl RunState {
pub(crate) fn new(cancellation_token: CancellationToken) -> Arc<Self> {
Arc::new(Self {
cancellation_token,
has_error: AtomicBool::new(false),
stored_error: Mutex::new(None),
total_bytes_scheduled: AtomicU64::new(0),
total_bytes_delivered: AtomicU64::new(0),
})
}
pub(crate) fn set_error(&self, error: SdxError) {
let mut guard = self
.stored_error
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
if guard.is_none() {
*guard = Some(error);
self.has_error.store(true, Ordering::Release);
}
drop(guard);
self.cancellation_token.cancel();
}
pub(crate) fn check_error(&self) -> Result<(), SdxError> {
let mut guard = self.stored_error.lock().unwrap_or_else(|p| p.into_inner());
if let Some(error) = guard.take() {
self.has_error.store(false, Ordering::Release);
return Err(error);
}
Ok(())
}
fn check_background_error(&self) -> Result<(), SdxError> {
if let Some(message) = self.error_message() {
return Err(SdxError::StreamInternal(message));
}
Ok(())
}
pub(crate) fn check_run_state(&self) -> Result<(), RunError> {
if let Err(error) = self.check_background_error() {
return Err(RunError::Error(error));
}
if self.cancellation_token.is_cancelled() {
return Err(RunError::Cancelled);
}
Ok(())
}
pub(crate) fn cancel(&self) {
self.cancellation_token.cancel();
}
pub(crate) async fn cancelled(&self) {
self.cancellation_token.cancelled().await;
}
pub(crate) fn record_new_term(&self, size: u64) {
self.total_bytes_scheduled
.fetch_add(size, Ordering::Relaxed);
}
pub(crate) fn report_bytes_written(&self, size: u64) {
self.total_bytes_delivered
.fetch_add(size, Ordering::Relaxed);
}
pub(crate) fn total_bytes_scheduled(&self) -> u64 {
self.total_bytes_scheduled.load(Ordering::Relaxed)
}
pub(crate) fn total_bytes_delivered(&self) -> u64 {
self.total_bytes_delivered.load(Ordering::Relaxed)
}
pub(crate) fn error_message(&self) -> Option<String> {
if !self.has_error.load(Ordering::Acquire) {
return None;
}
let guard = self
.stored_error
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
guard.as_ref().map(ToString::to_string)
}
pub(crate) fn is_cancelled(&self) -> bool {
self.cancellation_token.is_cancelled()
}
}
pub type DataFuture = Pin<Box<dyn Future<Output = Result<Bytes, SdxError>> + Send + 'static>>;
#[async_trait::async_trait]
pub trait DataWriter: Send {
async fn set_next_term_data_source(
&mut self,
byte_range: Range<u64>,
permit: Option<BufferPermit>,
data_future: DataFuture,
) -> Result<(), SdxError>;
async fn finish(self: Box<Self>) -> Result<u64, SdxError>;
}
pub(crate) enum SequentialRetrievalItem {
Data {
receiver: oneshot::Receiver<Bytes>,
permit: Option<BufferPermit>,
},
Finish,
}
type PendingWrite = (Bytes, Option<BufferPermit>);
const WRITEV_MAX_SLICE: usize = 24;
struct SyncWriterThread {
rx: UnboundedReceiver<SequentialRetrievalItem>,
bytes_written: Arc<AtomicU64>,
run_state: Arc<RunState>,
pending: Option<SequentialRetrievalItem>,
finished: bool,
}
impl SyncWriterThread {
fn next_write(&mut self, should_block: bool) -> Result<Option<PendingWrite>, SdxError> {
if self.pending.is_none() {
self.pending = if should_block {
self.rx.blocking_recv()
} else {
self.rx.try_recv().ok()
};
}
match self.pending.take() {
Some(SequentialRetrievalItem::Data {
mut receiver,
permit,
}) => {
if should_block {
let data = match receiver.blocking_recv() {
Ok(data) => data,
Err(_) => {
self.run_state.check_background_error()?;
return Err(SdxError::StreamInternal(
"data sender was dropped before sending data".to_owned(),
));
}
};
Ok(Some((data, permit)))
} else {
match receiver.try_recv() {
Ok(data) => Ok(Some((data, permit))),
Err(oneshot::error::TryRecvError::Empty) => {
self.pending = Some(SequentialRetrievalItem::Data { receiver, permit });
Ok(None)
}
Err(oneshot::error::TryRecvError::Closed) => {
self.run_state.check_background_error()?;
Err(SdxError::StreamInternal(
"data sender was dropped before sending data".to_owned(),
))
}
}
}
}
Some(SequentialRetrievalItem::Finish) => {
self.finished = true;
Ok(None)
}
None => Ok(None),
}
}
fn run(mut self, mut writer: impl Write) -> Result<(), SdxError> {
while let Some((data, permit)) = self.next_write(true)? {
let mut remaining = data.as_ref();
while !remaining.is_empty() {
self.run_state.check_background_error()?;
if self.run_state.is_cancelled() {
return Ok(());
}
let written = match writer.write(remaining) {
Ok(0) => return Err(SdxError::Io(std::io::ErrorKind::WriteZero.into())),
Ok(written) => written,
Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
Err(error) => return Err(SdxError::Io(error)),
};
remaining = remaining.get(written..).ok_or_else(|| {
SdxError::Io(std::io::Error::new(
std::io::ErrorKind::InvalidData,
"writer returned an invalid byte count",
))
})?;
self.bytes_written.fetch_add(
u64::try_from(written).unwrap_or(u64::MAX),
Ordering::Relaxed,
);
}
drop(permit);
if self.finished {
break;
}
}
self.run_state.check_background_error()?;
if !self.run_state.is_cancelled() {
writer.flush().map_err(SdxError::Io)?;
}
Ok(())
}
fn run_vectorized(mut self, mut writer: impl Write) -> Result<(), SdxError> {
let mut pending_writes: VecDeque<PendingWrite> = VecDeque::new();
while !self.finished || !pending_writes.is_empty() {
self.run_state.check_background_error()?;
if self.run_state.is_cancelled() {
return Ok(());
}
if pending_writes.is_empty() {
let Some(write) = self.next_write(true)? else {
break;
};
pending_writes.push_back(write);
}
while let Some(write) = self.next_write(false)? {
pending_writes.push_back(write);
}
let io_slices: Vec<IoSlice<'_>> = pending_writes
.iter()
.take(WRITEV_MAX_SLICE)
.map(|(data, _)| IoSlice::new(data))
.collect();
self.run_state.check_background_error()?;
if self.run_state.is_cancelled() {
return Ok(());
}
let written = match writer.write_vectored(&io_slices) {
Ok(0) if !io_slices.is_empty() => {
return Err(SdxError::StreamInternal(
"write_vectored returned 0 with non-empty buffers".to_owned(),
));
}
Ok(n) => n,
Err(ref error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
Err(error) => return Err(SdxError::Io(error)),
};
self.bytes_written.fetch_add(
u64::try_from(written).unwrap_or(u64::MAX),
Ordering::Relaxed,
);
let mut remaining = written;
while remaining > 0 && !pending_writes.is_empty() {
let front_len = pending_writes
.front()
.map(|(data, _)| data.len())
.unwrap_or(0);
if remaining >= front_len {
remaining = remaining.saturating_sub(front_len);
pending_writes.pop_front();
} else {
if let Some(front) = pending_writes.front_mut() {
front.0 = front.0.slice(remaining..);
}
remaining = 0;
}
}
}
self.run_state.check_background_error()?;
if !self.run_state.is_cancelled() {
writer.flush().map_err(SdxError::Io)?;
}
Ok(())
}
}
pub struct SequentialWriter {
sender: UnboundedSender<SequentialRetrievalItem>,
next_position: u64,
background_handle: Option<JoinHandle<()>>,
run_state: Arc<RunState>,
bytes_written: Arc<AtomicU64>,
active_tasks: JoinSet<Result<(), SdxError>>,
finished: bool,
}
impl Drop for SequentialWriter {
fn drop(&mut self) {
if !self.finished {
self.run_state.cancel();
}
}
}
#[async_trait::async_trait]
impl DataWriter for SequentialWriter {
async fn set_next_term_data_source(
&mut self,
byte_range: Range<u64>,
permit: Option<BufferPermit>,
data_future: DataFuture,
) -> Result<(), SdxError> {
self.run_state.check_background_error()?;
while let Some(result) = self.active_tasks.try_join_next() {
result.map_err(|error| SdxError::TaskJoin(error.to_string()))??;
}
if self.finished {
return Err(SdxError::StreamInternal(
"writer has already finished".to_owned(),
));
}
if byte_range.start != self.next_position {
return Err(SdxError::StreamInternal(format!(
"byte range not sequential: expected start at {}, got {}",
self.next_position, byte_range.start
)));
}
let expected_size = byte_range.end.saturating_sub(byte_range.start);
self.next_position = byte_range.end;
let (sender, receiver) = oneshot::channel();
if self
.sender
.send(SequentialRetrievalItem::Data { receiver, permit })
.is_err()
{
self.run_state.check_background_error()?;
return Err(SdxError::StreamInternal(
"background writer channel closed".to_owned(),
));
}
let run_state = self.run_state.clone();
let task = async move {
let result = async {
run_state.check_background_error()?;
let data = data_future.await?;
if u64::try_from(data.len()).unwrap_or(u64::MAX) != expected_size {
return Err(SdxError::StreamInternal(format!(
"data size mismatch: expected {expected_size} bytes, got {} bytes",
data.len()
)));
}
Ok(data)
}
.await;
let result = match result {
Ok(data) => sender.send(data).map_err(|_data| {
SdxError::StreamInternal("failed to send data: receiver dropped".to_owned())
}),
Err(error) => Err(error),
};
if let Err(error) = result {
run_state.set_error(error);
Err(SdxError::StreamInternal(
"term data task failed; see run state".to_owned(),
))
} else {
result
}
};
self.active_tasks.spawn(task);
Ok(())
}
async fn finish(mut self: Box<Self>) -> Result<u64, SdxError> {
self.run_state.check_background_error()?;
if self.finished {
return Err(SdxError::StreamInternal(
"writer has already finished".to_owned(),
));
}
if self.sender.send(SequentialRetrievalItem::Finish).is_err() {
self.run_state.check_background_error()?;
return Err(SdxError::StreamInternal(
"background writer channel closed".to_owned(),
));
}
let expected_bytes = self.next_position;
while let Some(result) = self.active_tasks.join_next().await {
result.map_err(|error| SdxError::TaskJoin(error.to_string()))??;
}
match self.background_handle.take() {
Some(handle) => {
handle.await.map_err(|error| {
SdxError::StreamInternal(format!("background writer task failed: {error}"))
})?;
self.run_state.check_background_error()?;
let actual_bytes = self.bytes_written.load(Ordering::Relaxed);
if actual_bytes != expected_bytes {
return Err(SdxError::StreamInternal(format!(
"bytes written mismatch: expected {expected_bytes} bytes, wrote {actual_bytes} bytes"
)));
}
self.finished = true;
Ok(actual_bytes)
}
None => {
self.finished = true;
Ok(expected_bytes)
}
}
}
}
impl SequentialWriter {
pub(crate) fn new_streaming(
run_state: Arc<RunState>,
) -> (
Box<dyn DataWriter>,
UnboundedReceiver<SequentialRetrievalItem>,
) {
let (sender, receiver) = unbounded_channel();
let writer = Box::new(Self {
sender,
next_position: 0,
background_handle: None,
run_state,
bytes_written: Arc::new(AtomicU64::new(0)),
active_tasks: JoinSet::new(),
finished: false,
});
(writer, receiver)
}
#[allow(clippy::new_ret_no_self)]
pub(crate) fn new<W: Write + Send + 'static>(
writer: W,
use_vectorized: bool,
run_state: Arc<RunState>,
) -> Box<dyn DataWriter> {
let (sender, receiver) = unbounded_channel();
let bytes_written = Arc::new(AtomicU64::new(0));
let run_state_thread = run_state.clone();
let run_state_clone = run_state.clone();
let bytes_written_clone = bytes_written.clone();
let handle = tokio::task::spawn_blocking(move || {
let writer_thread = SyncWriterThread {
rx: receiver,
bytes_written: bytes_written_clone,
run_state: run_state_thread,
pending: None,
finished: false,
};
let result = if use_vectorized {
writer_thread.run_vectorized(writer)
} else {
writer_thread.run(writer)
};
if let Err(error) = result {
run_state_clone.set_error(error);
}
});
Box::new(Self {
sender,
next_position: 0,
background_handle: Some(handle),
run_state,
bytes_written,
active_tasks: JoinSet::new(),
finished: false,
})
}
}
pub(crate) struct CompletedTerm {
pub byte_range: Range<u64>,
pub data: Bytes,
pub permit: Option<BufferPermit>,
}
pub(crate) struct UnorderedWriterProgress {
pub terms_in_progress: AtomicU64,
pub bytes_in_progress: AtomicU64,
}
impl UnorderedWriterProgress {
pub(crate) fn terms_in_progress(&self) -> u64 {
self.terms_in_progress.load(Ordering::Acquire)
}
pub(crate) fn bytes_in_progress(&self) -> u64 {
self.bytes_in_progress.load(Ordering::Relaxed)
}
}
pub struct UnorderedWriter {
result_tx: UnboundedSender<Result<CompletedTerm, SdxError>>,
run_state: Arc<RunState>,
progress: Arc<UnorderedWriterProgress>,
task_set: JoinSet<Result<u64, SdxError>>,
total_bytes_sent: u64,
finished: bool,
}
impl Drop for UnorderedWriter {
fn drop(&mut self) {
if !self.finished {
self.run_state.cancel();
}
}
}
#[async_trait::async_trait]
impl DataWriter for UnorderedWriter {
async fn set_next_term_data_source(
&mut self,
byte_range: Range<u64>,
permit: Option<BufferPermit>,
data_future: DataFuture,
) -> Result<(), SdxError> {
self.run_state.check_background_error()?;
while let Some(result) = self.task_set.try_join_next() {
self.total_bytes_sent = self
.total_bytes_sent
.saturating_add(result.map_err(|error| SdxError::TaskJoin(error.to_string()))??);
}
if self.finished {
return Err(SdxError::StreamInternal(
"writer has already finished".to_owned(),
));
}
let expected_size = byte_range.end.saturating_sub(byte_range.start);
self.progress
.terms_in_progress
.fetch_add(1, Ordering::Relaxed);
self.progress
.bytes_in_progress
.fetch_add(expected_size, Ordering::Relaxed);
let result_tx = self.result_tx.clone();
let run_state = self.run_state.clone();
let progress = self.progress.clone();
self.task_set.spawn(async move {
let result = async {
run_state.check_background_error()?;
let data = data_future.await?;
if u64::try_from(data.len()).unwrap_or(u64::MAX) != expected_size {
return Err(SdxError::StreamInternal(format!(
"data size mismatch: expected {expected_size} bytes, got {} bytes",
data.len()
)));
}
Ok(CompletedTerm {
byte_range,
data,
permit,
})
}
.await;
let completed_bytes = result
.as_ref()
.map(|term| u64::try_from(term.data.len()).unwrap_or(u64::MAX))
.unwrap_or(0);
match result {
Ok(term) => {
drop(result_tx.send(Ok(term)));
}
Err(error) => {
run_state.set_error(error);
}
}
progress
.bytes_in_progress
.fetch_sub(expected_size, Ordering::Relaxed);
progress.terms_in_progress.fetch_sub(1, Ordering::Release);
if completed_bytes > 0 {
Ok(completed_bytes)
} else {
run_state.check_background_error()?;
Ok(0)
}
});
Ok(())
}
async fn finish(mut self: Box<Self>) -> Result<u64, SdxError> {
self.run_state.check_background_error()?;
while let Some(result) = self.task_set.join_next().await {
self.total_bytes_sent = self
.total_bytes_sent
.saturating_add(result.map_err(|error| SdxError::TaskJoin(error.to_string()))??);
}
self.finished = true;
Ok(self.total_bytes_sent)
}
}
type UnorderedStreamingWriter = (
Box<dyn DataWriter>,
UnboundedReceiver<Result<CompletedTerm, SdxError>>,
Arc<UnorderedWriterProgress>,
);
impl UnorderedWriter {
pub(crate) fn new_streaming(run_state: Arc<RunState>) -> UnorderedStreamingWriter {
let (result_tx, result_rx) = unbounded_channel();
let progress = Arc::new(UnorderedWriterProgress {
terms_in_progress: AtomicU64::new(0),
bytes_in_progress: AtomicU64::new(0),
});
let writer = Box::new(Self {
result_tx,
run_state,
progress: progress.clone(),
task_set: JoinSet::new(),
total_bytes_sent: 0,
finished: false,
});
(writer, result_rx, progress)
}
}
#[derive(Clone)]
pub(crate) struct FileTerm {
pub byte_range: Range<u64>,
pub xorb_block_start_index: usize,
xorb_block_end_index: usize,
unpacked_length: u64,
pub offset_into_first_range: u64,
pub xorb_block: Arc<XorbBlock>,
}
pub(crate) struct XorbBlockData {
pub chunk_offsets: Vec<(usize, usize)>,
pub data: Bytes,
_buffer_permit: BufferPermit,
}
pub(crate) struct XorbBlock {
pub hash: String,
pub chunk_range: (u64, u64),
pub url: String,
pub bytes: ByteRange,
pub data: OnceCell<Arc<XorbBlockData>>,
decoded_budget: u64,
reservation: Mutex<Option<BufferPermit>>,
reservation_started: AtomicBool,
#[cfg(test)]
publication_gate: Option<Arc<PublicationGate>>,
}
#[cfg(test)]
struct PublicationGate {
ready: Mutex<Option<oneshot::Sender<()>>>,
release: Mutex<std::sync::mpsc::Receiver<()>>,
}
impl XorbBlock {
#[cfg(test)]
fn wait_for_publication(&self) -> Result<(), SdxError> {
if let Some(gate) = &self.publication_gate {
let sender = gate
.ready
.lock()
.map_err(|error| SdxError::StreamInternal(error.to_string()))?
.take();
if let Some(sender) = sender {
let _ = sender.send(());
gate.release
.lock()
.map_err(|error| SdxError::StreamInternal(error.to_string()))?
.recv_timeout(std::time::Duration::from_secs(5))
.map_err(|error| SdxError::StreamInternal(error.to_string()))?;
}
}
Ok(())
}
async fn reserve(
&self,
ctx: &StreamContext,
seed: &mut Option<BufferPermit>,
) -> Result<(), SdxError> {
if self.data.get().is_some() || self.reservation_started.load(Ordering::Acquire) {
return Ok(());
}
if self.decoded_budget > ctx.buffer_semaphore.total_permits() {
return Err(SdxError::StreamInternal(
"xorb decoded size exceeds download buffer capacity".to_owned(),
));
}
let permit = match seed
.as_mut()
.and_then(|reserved| reserved.split(self.decoded_budget))
{
Some(permit) => permit,
None => {
*seed = None;
ctx.buffer_semaphore
.acquire_many(self.decoded_budget)
.await?
}
};
*self.reservation.lock().unwrap_or_else(|p| p.into_inner()) = Some(permit);
self.reservation_started.store(true, Ordering::Release);
Ok(())
}
async fn retrieve_data(
self: Arc<Self>,
ctx: &StreamContext,
token: &str,
) -> Result<Arc<XorbBlockData>, SdxError> {
self.data
.get_or_try_init(|| async {
self.reserve(ctx, &mut None).await?;
let mut reservation_reset = ExitGuard::new(|| {
self.reservation_started.store(false, Ordering::Release);
});
let buffer_permit = self
.reservation
.lock()
.unwrap_or_else(|p| p.into_inner())
.take()
.ok_or_else(|| {
SdxError::StreamInternal("xorb buffer reservation missing".to_owned())
})?;
if let Some(cache) = &ctx.chunk_cache
&& let Some(cached) = cache
.get_bounded(&self.hash, self.chunk_range, self.decoded_budget)
.await?
{
if u64::try_from(cached.data.len()).unwrap_or(u64::MAX) > self.decoded_budget {
return Err(SdxError::StreamInternal(
"cached xorb exceeds buffer reservation".to_owned(),
));
}
let base = usize::try_from(self.chunk_range.0).unwrap_or(usize::MAX);
let chunk_offsets = cached
.chunk_offsets
.iter()
.enumerate()
.map(|(index, offset)| {
(
base.saturating_add(index),
usize::try_from(*offset).unwrap_or(usize::MAX),
)
})
.collect();
let block_data = Arc::new(XorbBlockData {
chunk_offsets,
data: cached.data,
_buffer_permit: buffer_permit,
});
reservation_reset.disarm();
drop(reservation_reset);
#[cfg(test)]
self.wait_for_publication()?;
return Ok(block_data);
}
let _download_permit =
ctx.download_permits
.clone()
.acquire_owned()
.await
.map_err(|error| {
SdxError::StreamInternal(format!(
"download permit acquire failed: {error}"
))
})?;
let retry = ctx.retry_context();
let url = self.url.clone();
let bytes = self.bytes;
let ranged = retry
.run(token.to_owned(), move |tok| {
let url = url.clone();
async move {
ctx.transfer
.fetch_xorb_range_bounded(&url, &tok, bytes)
.await
}
})
.await?;
ctx.xorb_fetch_count.fetch_add(1, Ordering::Relaxed);
if ranged.served_range != self.bytes {
return Err(SdxError::Transfer(TransferError::InvalidResponse(format!(
"xorb served range {:?} does not match requested range {:?}",
ranged.served_range, self.bytes
))));
}
let chunk_data = XorbReader::new(ranged.data).decode_chunk_data_bounded(
usize::try_from(self.decoded_budget).unwrap_or(usize::MAX),
)?;
let expected_chunks = self
.chunk_range
.1
.checked_sub(self.chunk_range.0)
.ok_or_else(|| {
SdxError::StreamInternal("inverted xorb chunk range".to_owned())
})?;
let actual_chunks = u64::try_from(chunk_data.chunk_offsets.len().saturating_sub(1))
.unwrap_or(u64::MAX);
if actual_chunks != expected_chunks {
return Err(SdxError::FetchChunkCountMismatch {
url: self.url.clone(),
expected: expected_chunks,
actual: actual_chunks,
});
}
if let Some(cache) = &ctx.chunk_cache {
let cache = cache.clone();
let hash = self.hash.clone();
let chunk_range = self.chunk_range;
let data = chunk_data.data.clone();
let chunk_offsets = chunk_data
.chunk_offsets
.iter()
.map(|offset| u32::try_from(*offset).unwrap_or(u32::MAX))
.collect::<Vec<u32>>();
drop(cache.put(&hash, chunk_range, &chunk_offsets, &data).await);
}
let start_chunk = self.chunk_range.0;
let base = usize::try_from(start_chunk).unwrap_or(usize::MAX);
let chunk_offsets = chunk_data
.chunk_offsets
.iter()
.enumerate()
.map(|(index, offset)| (base.saturating_add(index), *offset))
.collect();
let block_data = Arc::new(XorbBlockData {
chunk_offsets,
data: chunk_data.data,
_buffer_permit: buffer_permit,
});
reservation_reset.disarm();
drop(reservation_reset);
#[cfg(test)]
self.wait_for_publication()?;
Ok(block_data)
})
.await
.cloned()
}
}
impl FileTerm {
fn extract_bytes(&self, block_data: &XorbBlockData) -> Result<Bytes, SdxError> {
let (_, start_byte_offset) = block_data
.chunk_offsets
.get(self.xorb_block_start_index)
.copied()
.ok_or_else(|| {
SdxError::StreamInternal(format!(
"chunk offset {} missing from xorb block",
self.xorb_block_start_index
))
})?;
let (_, end_byte_offset) = block_data
.chunk_offsets
.get(self.xorb_block_end_index)
.copied()
.ok_or_else(|| {
SdxError::StreamInternal("term ending chunk offset missing".to_owned())
})?;
if u64::try_from(end_byte_offset.saturating_sub(start_byte_offset)).unwrap_or(u64::MAX)
!= self.unpacked_length
{
return Err(SdxError::StreamInternal(
"term unpacked length disagrees with decoded chunks".to_owned(),
));
}
let start = start_byte_offset
.checked_add(usize::try_from(self.offset_into_first_range).unwrap_or(usize::MAX))
.ok_or_else(|| SdxError::StreamInternal("term start offset overflow".to_owned()))?;
let expected_size =
usize::try_from(self.byte_range.end.saturating_sub(self.byte_range.start))
.unwrap_or(usize::MAX);
let end = start
.checked_add(expected_size)
.ok_or_else(|| SdxError::StreamInternal("term end offset overflow".to_owned()))?;
if end > block_data.data.len() {
return Err(SdxError::StreamInternal(format!(
"term byte range {start}..{end} exceeds xorb block data length {}",
block_data.data.len()
)));
}
Ok(block_data.data.slice(start..end))
}
async fn get_data_task(
&self,
ctx: &StreamContext,
token: &str,
) -> Result<DataFuture, SdxError> {
if let Some(block_data) = self.xorb_block.data.get() {
let bytes = self.extract_bytes(block_data)?;
return Ok(Box::pin(async move { Ok(bytes) }));
}
let file_term = self.clone();
let xorb_block = self.xorb_block.clone();
let token = token.to_owned();
let ctx = ctx.clone();
Ok(Box::pin(async move {
let block_data = xorb_block.retrieve_data(&ctx, &token).await?;
file_term.extract_bytes(&block_data)
}))
}
}
pub(crate) struct TermBlock {
pub file_terms: Vec<FileTerm>,
pub actual_end: u64,
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct XorbDescriptor {
url: String,
bytes: ByteRange,
chunks: (u64, u64),
}
enum XorbDescriptorSource {
V2(BTreeMap<String, Vec<ReconstructionMultiRangeFetch>>),
V1(BTreeMap<String, Vec<ReconstructionFetchInfo>>),
}
impl XorbDescriptorSource {
fn for_hash(&self, hash: &str) -> Vec<XorbDescriptor> {
match self {
XorbDescriptorSource::V2(xorbs) => xorbs
.get(hash)
.map(|entries| {
entries
.iter()
.flat_map(|entry| {
entry.ranges.iter().map(|range| XorbDescriptor {
url: entry.url.clone(),
bytes: ByteRange::new(range.bytes.start, range.bytes.end),
chunks: (range.chunks.start, range.chunks.end),
})
})
.collect()
})
.unwrap_or_default(),
XorbDescriptorSource::V1(fetch_info) => fetch_info
.get(hash)
.map(|entries| {
entries
.iter()
.map(|entry| XorbDescriptor {
url: entry.url.clone(),
bytes: ByteRange::new(entry.url_range.start, entry.url_range.end),
chunks: (entry.range.start, entry.range.end),
})
.collect()
})
.unwrap_or_default(),
}
}
}
async fn fetch_term_block(
ctx: &StreamContext,
token: &str,
file_id: &str,
query_range: Range<u64>,
) -> Result<Option<TermBlock>, SdxError> {
if query_range.start >= query_range.end {
return Ok(None);
}
let wire_range = ByteRange::new(query_range.start, query_range.end.saturating_sub(1));
let retry = ctx.retry_context();
let response = match fetch_reconstruction_response(
&ctx.transfer,
Some(&retry),
&ctx.api_base,
token,
file_id,
Some(wire_range),
)
.await
{
Ok(response) => response,
Err(SdxError::Transfer(TransferError::RangeNotSatisfiable(_))) => return Ok(None),
Err(error) => return Err(error),
};
normalize_block(
response,
query_range.start,
query_range.end,
ctx.buffer_semaphore.total_permits(),
)
}
fn normalize_block(
response: ReconstructionResponse,
query_start: u64,
query_end: u64,
buffer_capacity: u64,
) -> Result<Option<TermBlock>, SdxError> {
let (offset_into_first_range, terms, descriptors) = match response {
ReconstructionResponse::V2(resp) => (
resp.offset_into_first_range,
resp.terms,
XorbDescriptorSource::V2(resp.xorbs),
),
ReconstructionResponse::V1(resp) => (
resp.offset_into_first_range,
resp.terms,
XorbDescriptorSource::V1(resp.fetch_info),
),
};
if terms.is_empty() {
return Ok(None);
}
let mut descriptor_index: HashMap<String, Vec<XorbDescriptor>> = HashMap::new();
let mut groups: Vec<FetchGroup> = Vec::new();
let mut current_offset = query_start;
let merge_limit = buffer_capacity.min(MAX_COALESCED_BLOCK_BYTES);
for (term_index, term) in terms.iter().enumerate() {
parse_xet_hash_hex(&term.hash)?;
let sorted = descriptor_index
.entry(term.hash.clone())
.or_insert_with(|| {
let mut list = descriptors.for_hash(&term.hash);
list.sort_by_key(|descriptor| descriptor.chunks.0);
list
});
let position = sorted.partition_point(|descriptor| descriptor.chunks.0 <= term.range.start);
let descriptor = position
.checked_sub(1)
.and_then(|index| sorted.get(index))
.filter(|descriptor| descriptor.chunks.1 >= term.range.end)
.cloned()
.ok_or_else(|| SdxError::MissingFetchInfo {
term_index,
hash: term.hash.clone(),
})?;
let exact = descriptor.chunks == (term.range.start, term.range.end);
let budget = if exact {
term.unpacked_length
} else {
buffer_capacity.min(64 * 1024 * 1024)
};
if budget > buffer_capacity
|| descriptor.bytes.start > descriptor.bytes.end
|| descriptor.chunks.1.saturating_sub(descriptor.chunks.0) > 8192
|| term.range.start >= term.range.end
{
return Err(SdxError::StreamInternal(
"invalid or oversized reconstruction fetch block".to_owned(),
));
}
let offset = if term_index == 0 {
offset_into_first_range
} else {
0
};
if offset > term.unpacked_length {
return Err(SdxError::UnpackedLengthMismatch {
term_index,
expected: term.unpacked_length,
actual: offset,
});
}
let term_size = term.unpacked_length.saturating_sub(offset);
let term_range = current_offset..current_offset.saturating_add(term_size);
current_offset = term_range.end;
let parsed = GroupTerm {
byte_range: term_range,
first_chunk: term.range.start,
end_chunk: term.range.end,
unpacked_length: term.unpacked_length,
offset,
};
if let Some(group) = groups.last_mut() {
if group.hash == term.hash && group.last_descriptor == descriptor {
group.budget = group.budget.max(budget);
group.exact &= exact;
group.terms.push(parsed);
continue;
}
if group.hash == term.hash
&& group.descriptor.url == descriptor.url
&& group.descriptor.chunks.1 == descriptor.chunks.0
&& group.descriptor.bytes.end.checked_add(1) == Some(descriptor.bytes.start)
&& group.exact
&& exact
&& group.terms.len() < MAX_BUFFERED_TERMS
&& group
.budget
.checked_add(budget)
.is_some_and(|size| size <= merge_limit)
{
group.descriptor.chunks.1 = descriptor.chunks.1;
group.descriptor.bytes.end = descriptor.bytes.end;
group.budget = group.budget.saturating_add(budget);
group.last_descriptor = descriptor;
group.terms.push(parsed);
continue;
}
}
groups.push(FetchGroup {
hash: term.hash.clone(),
descriptor: descriptor.clone(),
last_descriptor: descriptor,
budget,
exact,
terms: vec![parsed],
});
}
let mut file_terms = Vec::with_capacity(terms.len());
for group in groups {
let budget = if group.exact {
group.budget
} else {
let mut covered = BTreeMap::new();
for term in &group.terms {
covered.insert(term.first_chunk, (term.end_chunk, term.unpacked_length));
}
let mut cursor = group.descriptor.chunks.0;
let mut length = 0u64;
for (start, (end, bytes)) in covered {
if start != cursor {
break;
}
cursor = end;
length = length.checked_add(bytes).ok_or_else(|| {
SdxError::StreamInternal("decoded block length overflow".to_owned())
})?;
}
if cursor == group.descriptor.chunks.1 {
length
} else {
group.budget
}
};
if budget > buffer_capacity {
return Err(SdxError::StreamInternal(
"decoded xorb exceeds download buffer capacity".to_owned(),
));
}
let block = Arc::new(XorbBlock {
hash: group.hash,
chunk_range: group.descriptor.chunks,
url: group.descriptor.url,
bytes: group.descriptor.bytes,
data: OnceCell::new(),
decoded_budget: budget.max(1),
reservation: Mutex::new(None),
reservation_started: AtomicBool::new(false),
#[cfg(test)]
publication_gate: None,
});
for term in group.terms {
file_terms.push(FileTerm {
byte_range: term.byte_range,
xorb_block_start_index: usize::try_from(
term.first_chunk.saturating_sub(block.chunk_range.0),
)
.unwrap_or(usize::MAX),
xorb_block_end_index: usize::try_from(
term.end_chunk.saturating_sub(block.chunk_range.0),
)
.unwrap_or(usize::MAX),
unpacked_length: term.unpacked_length,
offset_into_first_range: term.offset,
xorb_block: block.clone(),
});
}
}
if current_offset > query_end {
let shrink = current_offset.saturating_sub(query_end);
if let Some(last) = file_terms.last_mut() {
last.byte_range.end = last.byte_range.end.saturating_sub(shrink);
}
current_offset = query_end;
}
Ok(Some(TermBlock {
file_terms,
actual_end: current_offset,
}))
}
struct GroupTerm {
byte_range: Range<u64>,
first_chunk: u64,
end_chunk: u64,
unpacked_length: u64,
offset: u64,
}
struct FetchGroup {
hash: String,
descriptor: XorbDescriptor,
last_descriptor: XorbDescriptor,
budget: u64,
exact: bool,
terms: Vec<GroupTerm>,
}
struct ReconstructionTermManager {
ctx: StreamContext,
file_id: String,
token: String,
requested_byte_range: Range<u64>,
last_block_info: Option<(std::time::Instant, Range<u64>)>,
known_final_byte_position: Arc<AtomicU64>,
prefetched_byte_position: u64,
current_active_byte_position: u64,
prefetch_queue: VecDeque<AbortOnDropHandle<Result<Option<TermBlock>, SdxError>>>,
completion_rate_estimator: ExpWeightedMovingAvg,
}
impl ReconstructionTermManager {
async fn new(
ctx: StreamContext,
file_id: String,
token: String,
requested_byte_range: Range<u64>,
) -> Result<Self, SdxError> {
let mut manager = Self {
ctx,
file_id,
token,
requested_byte_range: requested_byte_range.clone(),
last_block_info: None,
known_final_byte_position: Arc::new(AtomicU64::new(requested_byte_range.end)),
prefetched_byte_position: requested_byte_range.start,
current_active_byte_position: requested_byte_range.start,
prefetch_queue: VecDeque::new(),
completion_rate_estimator: ExpWeightedMovingAvg::new_count_decay(
DEFAULT_COMPLETION_RATE_ESTIMATOR_HALF_LIFE,
),
};
let initial = manager.ctx.limits.min_reconstruction_fetch_size;
manager.prefetch_block(initial).await?;
manager.prefetch_block(initial.saturating_mul(2)).await?;
Ok(manager)
}
async fn next_file_terms(&mut self) -> Result<Option<TermBlock>, SdxError> {
if let Some((start_time, block_range)) = self.last_block_info.take() {
let completion_time = start_time.elapsed().as_secs_f64();
let block_size = block_range.end.saturating_sub(block_range.start) as f64;
if block_size != 0.0 {
#[allow(clippy::float_arithmetic)]
{
self.completion_rate_estimator
.update(block_size / completion_time.max(1e-6));
}
}
}
self.check_prefetch_buffer().await?;
let Some(join_handle) = self.prefetch_queue.pop_front() else {
return Ok(None);
};
let maybe_block = join_handle
.await
.map_err(|error| SdxError::TaskJoin(error.to_string()))??;
match maybe_block {
Some(block) => {
let block_start = block
.file_terms
.first()
.map(|t| t.byte_range.start)
.unwrap_or(0);
let block_end = block.actual_end;
self.last_block_info = Some((std::time::Instant::now(), block_start..block_end));
self.current_active_byte_position = block_end;
Ok(Some(block))
}
None => {
self.known_final_byte_position
.store(self.prefetched_byte_position, Ordering::Relaxed);
Ok(None)
}
}
}
fn is_done_fetching(&self) -> bool {
self.prefetched_byte_position >= self.known_final_byte_position.load(Ordering::Relaxed)
}
async fn check_prefetch_buffer(&mut self) -> Result<(), SdxError> {
if self.is_done_fetching() {
return Ok(());
}
#[allow(clippy::float_arithmetic)]
{
let completion_rate = self.completion_rate_estimator.value();
let target_time = self.ctx.limits.target_block_completion_time_secs;
let prefetch_buffer_target = target_time * completion_rate;
let min_buffer = self.ctx.limits.min_prefetch_buffer as f64;
let target_buffer = prefetch_buffer_target.max(min_buffer);
let current = self
.prefetched_byte_position
.saturating_sub(self.current_active_byte_position);
if !self.prefetch_queue.is_empty() && target_buffer <= current as f64 {
return Ok(());
}
let deficit = (target_buffer - current as f64).max(0.0);
let next_block_size = (deficit as u64).clamp(
self.ctx.limits.min_reconstruction_fetch_size,
self.ctx.limits.max_reconstruction_fetch_size,
);
self.prefetch_block(next_block_size).await
}
}
async fn prefetch_block(&mut self, block_size: u64) -> Result<(), SdxError> {
let block_size = block_size.clamp(
self.ctx.limits.min_reconstruction_fetch_size,
self.ctx.limits.max_reconstruction_fetch_size,
);
let mut prefetch_range =
self.prefetched_byte_position..self.prefetched_byte_position.saturating_add(block_size);
let last_byte_position = self
.known_final_byte_position
.load(Ordering::Relaxed)
.min(self.requested_byte_range.end);
if prefetch_range.end > last_byte_position {
prefetch_range.end = last_byte_position;
}
let min_fetch_size = self.ctx.limits.min_reconstruction_fetch_size;
if prefetch_range.end.saturating_add(min_fetch_size) > self.requested_byte_range.end {
prefetch_range.end = self.requested_byte_range.end;
}
if prefetch_range.start >= prefetch_range.end {
return Ok(());
}
self.prefetched_byte_position = prefetch_range.end;
let ctx = self.ctx.clone();
let token = self.token.clone();
let file_id = self.file_id.clone();
let known_final_byte_position = self.known_final_byte_position.clone();
let join_handle = tokio::task::spawn(async move {
match fetch_term_block(&ctx, &token, &file_id, prefetch_range.clone()).await {
Ok(Some(block)) => {
if block.actual_end < prefetch_range.end {
known_final_byte_position.store(block.actual_end, Ordering::Relaxed);
}
Ok(Some(block))
}
Ok(None) => {
known_final_byte_position.fetch_min(prefetch_range.start, Ordering::Relaxed);
Ok(None)
}
Err(error) => Err(error),
}
});
self.prefetch_queue
.push_back(AbortOnDropHandle::new(join_handle));
Ok(())
}
}
pub(crate) struct FileReconstructor {
ctx: StreamContext,
file_id: String,
token: String,
byte_range: Option<Range<u64>>,
chunk_cache: Option<Arc<ChunkCache>>,
cancellation_token: CancellationToken,
}
impl FileReconstructor {
pub(crate) fn new(ctx: StreamContext, file_id: String, token: String) -> Self {
let chunk_cache = ctx.chunk_cache.clone();
Self {
ctx,
file_id,
token,
byte_range: None,
chunk_cache,
cancellation_token: CancellationToken::new(),
}
}
pub(crate) const fn with_byte_range(mut self, byte_range: Range<u64>) -> Self {
self.byte_range = Some(byte_range);
self
}
pub(crate) fn with_cancellation_token(mut self, token: CancellationToken) -> Self {
self.cancellation_token = token;
self
}
pub(crate) async fn reconstruct_to_writer<W: Write + Send + 'static>(
self,
writer: W,
) -> Result<u64, SdxError> {
let run_state = RunState::new(self.cancellation_token.clone());
let data_writer = SequentialWriter::new(writer, true, run_state.clone());
self.run(data_writer, run_state).await
}
pub(crate) fn reconstruct_to_stream(self) -> DownloadStream {
let run_state = RunState::new(self.cancellation_token.clone());
let runtime = self.ctx.blocking_runtime.clone();
DownloadStream::new(self, run_state, runtime)
}
pub(crate) fn reconstruct_to_unordered_stream(self) -> UnorderedDownloadStream {
let run_state = RunState::new(self.cancellation_token.clone());
let runtime = self.ctx.blocking_runtime.clone();
UnorderedDownloadStream::new(self, run_state, runtime)
}
async fn run(
self,
data_writer: Box<dyn DataWriter>,
run_state: Arc<RunState>,
) -> Result<u64, SdxError> {
match self.run_impl(data_writer, &run_state).await {
Ok(value) => Ok(value),
Err(RunError::Cancelled) => {
if let Some(message) = run_state.error_message() {
return Err(SdxError::StreamInternal(message));
}
Ok(0)
}
Err(RunError::Error(error)) => {
run_state.set_error(error);
Err(run_state
.error_message()
.map(SdxError::StreamInternal)
.unwrap_or_else(|| SdxError::StreamInternal("download failed".to_owned())))
}
}
}
async fn run_impl(
self,
mut data_writer: Box<dyn DataWriter>,
run_state: &RunState,
) -> Result<u64, RunError> {
let Self {
ctx,
file_id,
token,
byte_range,
chunk_cache,
cancellation_token: _,
} = self;
let ctx = StreamContext {
chunk_cache: chunk_cache.or_else(|| ctx.chunk_cache.clone()),
..ctx
};
run_state.check_run_state()?;
let requested_range = byte_range.unwrap_or(0..u64::MAX);
let mut term_manager = ReconstructionTermManager::new(
ctx.clone(),
file_id,
token.clone(),
requested_range.clone(),
)
.await?;
let base = DEFAULT_DOWNLOAD_BUFFER_SIZE;
let perfile = DEFAULT_DOWNLOAD_BUFFER_PERFILE_SIZE;
let limit = DEFAULT_DOWNLOAD_BUFFER_LIMIT;
let active = ctx
.active_downloads
.fetch_add(1, Ordering::Relaxed)
.saturating_add(1);
let target = base
.saturating_add(active.saturating_mul(perfile))
.min(limit);
let mut seed_buffer_permit = ctx.buffer_semaphore.increment_permits_to_target(target);
let semaphore = ctx.buffer_semaphore.clone();
let active_downloads = ctx.active_downloads.clone();
let _download_count_guard = ExitGuard::new(move || {
let n = active_downloads
.fetch_sub(1, Ordering::Relaxed)
.saturating_sub(1);
let shrunk_target = base.saturating_add(n.saturating_mul(perfile)).min(limit);
semaphore.decrement_permits_to_target(shrunk_target);
});
let range_start_offset = requested_range.start;
let term_slots = Arc::new(Semaphore::new(MAX_BUFFERED_TERMS));
loop {
let maybe_block = tokio::select! {
biased;
() = run_state.cancelled() => {
run_state.check_run_state()?;
return Ok(0);
}
result = term_manager.next_file_terms() => result?,
};
let Some(block) = maybe_block else {
break;
};
run_state.check_run_state()?;
for file_term in block.file_terms {
run_state.check_run_state()?;
let term_size = file_term
.byte_range
.end
.saturating_sub(file_term.byte_range.start);
let slot = tokio::select! {
biased;
() = run_state.cancelled() => { run_state.check_run_state()?; return Ok(0); }
result = term_slots.clone().acquire_owned() => result.map_err(|error| SdxError::StreamInternal(error.to_string()))?,
};
tokio::select! {
biased;
() = run_state.cancelled() => { run_state.check_run_state()?; return Ok(0); }
result = file_term.xorb_block.reserve(&ctx, &mut seed_buffer_permit) => result?,
}
let buffer_permit = BufferPermit::for_term(
ctx.buffer_semaphore.clone(),
slot,
file_term.xorb_block.clone(),
);
let data_future = file_term.get_data_task(&ctx, &token).await?;
let relative_start = file_term
.byte_range
.start
.saturating_sub(range_start_offset);
let relative_end = file_term.byte_range.end.saturating_sub(range_start_offset);
data_writer
.set_next_term_data_source(
relative_start..relative_end,
Some(buffer_permit),
data_future,
)
.await?;
run_state.record_new_term(term_size);
}
}
let bytes_written = tokio::select! {
biased;
() = run_state.cancelled() => {
run_state.check_run_state()?;
return Ok(0);
}
result = data_writer.finish() => result?,
};
Ok(bytes_written)
}
}
struct PendingDownloadData {
receiver: oneshot::Receiver<Bytes>,
permit: Option<BufferPermit>,
}
pub struct DownloadStream {
pending_data: Option<PendingDownloadData>,
receiver: UnboundedReceiver<SequentialRetrievalItem>,
finished: bool,
run_state: Arc<RunState>,
start_signal: Option<Arc<Notify>>,
#[cfg(not(target_family = "wasm"))]
runtime: Arc<tokio::runtime::Runtime>,
}
impl DownloadStream {
pub(crate) fn new(
reconstructor: FileReconstructor,
run_state: Arc<RunState>,
#[cfg(not(target_family = "wasm"))] runtime: Arc<tokio::runtime::Runtime>,
) -> Self {
let (data_writer, receiver) = SequentialWriter::new_streaming(run_state.clone());
let start_signal = Arc::new(Notify::new());
let signal = start_signal.clone();
let rs = run_state.clone();
let task = async move {
signal.notified().await;
drop(reconstructor.run(data_writer, rs).await);
};
#[cfg(not(target_family = "wasm"))]
{
runtime.spawn(task);
}
#[cfg(target_family = "wasm")]
{
tokio::task::spawn(task);
}
Self {
receiver,
pending_data: None,
finished: false,
run_state,
start_signal: Some(start_signal),
#[cfg(not(target_family = "wasm"))]
runtime,
}
}
pub fn start(&mut self) {
if let Some(signal) = self.start_signal.take() {
signal.notify_one();
}
}
fn ensure_started(&mut self) {
if self.start_signal.is_some() {
self.start();
}
}
fn cancel_reconstruction(&self) {
self.run_state.cancel();
if let Some(signal) = self.start_signal.as_ref() {
signal.notify_one();
}
}
pub async fn next(&mut self) -> Result<Option<Bytes>, SdxError> {
if self.finished {
return Ok(None);
}
if self.run_state.is_cancelled() {
let terminal = self.run_state.check_error();
self.cancel();
terminal?;
return Ok(None);
}
self.ensure_started();
if self.pending_data.is_none() {
let item = if let Ok(item) = self.receiver.try_recv() {
Some(item)
} else {
tokio::select! {
biased;
recv = self.receiver.recv() => recv,
() = self.run_state.cancelled() => None,
}
};
if self.run_state.is_cancelled() {
let terminal = self.run_state.check_error();
drop(item);
self.cancel();
terminal?;
return Ok(None);
}
match item {
Some(SequentialRetrievalItem::Data { receiver, permit }) => {
self.pending_data = Some(PendingDownloadData { receiver, permit });
}
Some(SequentialRetrievalItem::Finish) | None => {
self.finished = true;
self.run_state.check_error()?;
return Ok(None);
}
}
}
let Some(pending) = self.pending_data.as_mut() else {
return Err(SdxError::StreamInternal(
"pending stream data is missing".to_owned(),
));
};
let result = tokio::select! {
biased;
data = &mut pending.receiver => Some(data),
() = self.run_state.cancelled() => None,
};
if self.run_state.is_cancelled() {
let terminal = self.run_state.check_error();
self.cancel();
terminal?;
return Ok(None);
}
if let Some(completed) = self.pending_data.take() {
drop(completed.permit);
}
match result {
Some(Ok(data)) => {
self.run_state
.report_bytes_written(u64::try_from(data.len()).unwrap_or(u64::MAX));
Ok(Some(data))
}
Some(Err(_)) => {
self.run_state.check_error()?;
if self.run_state.is_cancelled() {
self.finished = true;
return Ok(None);
}
Err(SdxError::StreamInternal(
"data sender was dropped before sending data".to_owned(),
))
}
None => {
self.finished = true;
self.run_state.check_error()?;
Ok(None)
}
}
}
#[cfg(not(target_family = "wasm"))]
pub fn blocking_next(&mut self) -> Result<Option<Bytes>, SdxError> {
let runtime = self.runtime.clone();
block_on_download(&runtime, self.next())
}
pub fn cancel(&mut self) {
self.cancel_reconstruction();
drop(self.start_signal.take());
self.receiver.close();
while let Ok(item) = self.receiver.try_recv() {
drop(item);
}
drop(self.pending_data.take());
self.finished = true;
}
pub(crate) fn run_state(&self) -> Arc<RunState> {
self.run_state.clone()
}
pub(crate) fn pending_start_signal(&self) -> Option<Arc<Notify>> {
self.start_signal.clone()
}
}
impl Drop for DownloadStream {
fn drop(&mut self) {
self.cancel_reconstruction();
self.receiver.close();
}
}
pub struct UnorderedDownloadStream {
progress: Arc<UnorderedWriterProgress>,
receiver: UnboundedReceiver<Result<CompletedTerm, SdxError>>,
finished: bool,
run_state: Arc<RunState>,
start_signal: Option<Arc<Notify>>,
#[cfg(not(target_family = "wasm"))]
runtime: Arc<tokio::runtime::Runtime>,
}
impl UnorderedDownloadStream {
pub(crate) fn new(
reconstructor: FileReconstructor,
run_state: Arc<RunState>,
#[cfg(not(target_family = "wasm"))] runtime: Arc<tokio::runtime::Runtime>,
) -> Self {
let (writer, receiver, progress) = UnorderedWriter::new_streaming(run_state.clone());
let start_signal = Arc::new(Notify::new());
let signal = start_signal.clone();
let rs = run_state.clone();
let task = async move {
signal.notified().await;
drop(reconstructor.run(writer, rs).await);
};
#[cfg(not(target_family = "wasm"))]
{
runtime.spawn(task);
}
#[cfg(target_family = "wasm")]
{
tokio::task::spawn(task);
}
Self {
progress,
receiver,
finished: false,
run_state,
start_signal: Some(start_signal),
#[cfg(not(target_family = "wasm"))]
runtime,
}
}
pub fn start(&mut self) {
if let Some(signal) = self.start_signal.take() {
signal.notify_one();
}
}
fn ensure_started(&mut self) {
if self.start_signal.is_some() {
self.start();
}
}
fn cancel_reconstruction(&self) {
self.run_state.cancel();
if let Some(signal) = self.start_signal.as_ref() {
signal.notify_one();
}
}
pub async fn next(&mut self) -> Result<Option<(u64, Bytes)>, SdxError> {
if self.finished {
return Ok(None);
}
if self.run_state.is_cancelled() {
let terminal = self.run_state.check_error();
self.cancel();
terminal?;
return Ok(None);
}
self.ensure_started();
if let Ok(result) = self.receiver.try_recv() {
return self.process_term(result);
}
let next_item = tokio::select! {
biased;
recv = self.receiver.recv() => recv,
() = self.run_state.cancelled() => None,
};
match next_item {
Some(result) => self.process_term(result),
None => {
if self.run_state.is_cancelled() {
let terminal = self.run_state.check_error();
self.cancel();
terminal?;
return Ok(None);
}
self.finished = true;
self.run_state.check_error()?;
Ok(None)
}
}
}
#[cfg(not(target_family = "wasm"))]
pub fn blocking_next(&mut self) -> Result<Option<(u64, Bytes)>, SdxError> {
let runtime = self.runtime.clone();
block_on_download(&runtime, self.next())
}
fn process_term(
&mut self,
result: Result<CompletedTerm, SdxError>,
) -> Result<Option<(u64, Bytes)>, SdxError> {
if self.run_state.is_cancelled() {
drop(result);
let terminal = self.run_state.check_error();
self.cancel();
terminal?;
return Ok(None);
}
let term = result?;
let offset = term.byte_range.start;
let data = term.data;
drop(term.permit);
self.run_state
.report_bytes_written(u64::try_from(data.len()).unwrap_or(u64::MAX));
Ok(Some((offset, data)))
}
pub fn cancel(&mut self) {
self.cancel_reconstruction();
drop(self.start_signal.take());
self.receiver.close();
while let Ok(item) = self.receiver.try_recv() {
drop(item);
}
self.finished = true;
}
#[must_use]
pub fn total_bytes_expected(&self) -> u64 {
self.run_state.total_bytes_scheduled()
}
#[must_use]
pub fn bytes_in_progress(&self) -> u64 {
self.progress.bytes_in_progress()
}
#[must_use]
pub fn bytes_completed(&self) -> u64 {
self.run_state.total_bytes_delivered()
}
#[must_use]
pub fn terms_in_progress(&self) -> u64 {
self.progress.terms_in_progress()
}
pub(crate) fn run_state(&self) -> Arc<RunState> {
self.run_state.clone()
}
pub(crate) fn pending_start_signal(&self) -> Option<Arc<Notify>> {
self.start_signal.clone()
}
}
impl Drop for UnorderedDownloadStream {
fn drop(&mut self) {
self.cancel_reconstruction();
self.receiver.close();
}
}
#[cfg(test)]
mod tests {
use std::sync::atomic::AtomicU64;
use std::time::Duration;
use serde_json::json;
use tokio::runtime::Runtime;
use wiremock::{
Mock, MockServer, ResponseTemplate,
matchers::{header, method, path},
};
use super::*;
use crate::{auth::Auth, reconstruction, transfer::TransferClient};
const FILE_ID: &str = "0000000000000000000000000000000000000000000000000000000000000000";
const XORB_HASH: &str = "1111111111111111111111111111111111111111111111111111111111111111";
const READ_TOKEN: &str = "read-token";
fn serialize_payload(chunks: &[&[u8]]) -> Vec<u8> {
use xet_core_structures::xorb_object::{CompressionScheme, serialize_chunk};
let mut payload = Vec::new();
for chunk in chunks {
serialize_chunk(chunk, &mut payload, CompressionScheme::None).unwrap();
}
payload
}
fn v2_response_body(
offset: u64,
terms: serde_json::Value,
xorbs: serde_json::Value,
) -> serde_json::Value {
let mut body = serde_json::Map::new();
body.insert(
"offset_into_first_range".to_owned(),
serde_json::Value::from(offset),
);
body.insert("terms".to_owned(), terms);
body.insert("xorbs".to_owned(), xorbs);
serde_json::Value::Object(body)
}
fn test_limits() -> StreamLimits {
StreamLimits {
min_reconstruction_fetch_size: 4096,
max_reconstruction_fetch_size: 4096,
min_prefetch_buffer: 8192,
..StreamLimits::default()
}
}
fn test_runtime() -> Arc<Runtime> {
static RUNTIME: std::sync::OnceLock<Arc<Runtime>> = std::sync::OnceLock::new();
RUNTIME
.get_or_init(|| Arc::new(Runtime::new().unwrap()))
.clone()
}
fn test_stream_context(server: &MockServer, buffer_cap: u64) -> StreamContext {
StreamContext {
transfer: TransferClient::new(reqwest::Client::new()),
api_base: server.uri(),
buffer_semaphore: Arc::new(BufferSemaphore::new(buffer_cap, buffer_cap, buffer_cap)),
active_downloads: Arc::new(AtomicU64::new(0)),
download_permits: Arc::new(Semaphore::new(DEFAULT_DOWNLOAD_CONCURRENCY)),
limits: test_limits(),
chunk_cache: None,
xorb_fetch_count: Arc::new(AtomicU64::new(0)),
tokens: test_tokens(server),
retry_policy: RetryPolicy::default(),
blocking_runtime: test_runtime(),
}
}
fn test_tokens(server: &MockServer) -> TokenService {
let auth = Auth::new(
&server.uri(),
crate::RepositoryId {
provider: "github".to_owned(),
owner: "team".to_owned(),
repo: "assets".to_owned(),
revision: "main".to_owned(),
},
)
.unwrap()
.with_token(READ_TOKEN.to_owned());
auth.build().unwrap()
}
async fn reconstruction_mock(
server: &MockServer,
start: u64,
end: u64,
offset: u64,
terms: serde_json::Value,
xorbs: serde_json::Value,
) {
Mock::given(method("GET"))
.and(path(format!("/v2/reconstructions/{FILE_ID}")))
.and(header("authorization", format!("Bearer {READ_TOKEN}")))
.and(header("range", format!("bytes={start}-{end}")))
.respond_with(
ResponseTemplate::new(200).set_body_json(v2_response_body(offset, terms, xorbs)),
)
.mount(server)
.await;
Mock::given(method("GET"))
.and(path(format!("/v2/reconstructions/{FILE_ID}")))
.and(header("authorization", format!("Bearer {READ_TOKEN}")))
.respond_with(ResponseTemplate::new(416).set_body_json(json!({"error": "past eof"})))
.mount(server)
.await;
}
async fn xorb_range_mock(server: &MockServer, start: u64, end: u64, body: Vec<u8>) {
Mock::given(method("GET"))
.and(path(format!("/transfer/xorb/default/{XORB_HASH}")))
.and(header("authorization", format!("Bearer {READ_TOKEN}")))
.and(header("range", format!("bytes={start}-{end}")))
.respond_with(
ResponseTemplate::new(206)
.insert_header(
"Content-Range",
format!("bytes {start}-{end}/{}", body.len()),
)
.set_body_raw(body, "application/octet-stream"),
)
.mount(server)
.await;
}
async fn xorb_payload_mock(server: &MockServer, payload: Vec<u8>) {
Mock::given(method("GET"))
.and(path(format!("/transfer/xorb/default/{XORB_HASH}")))
.respond_with(move |request: &wiremock::Request| {
let range = request.headers.get("range").unwrap().to_str().unwrap();
let (start, end) = range
.strip_prefix("bytes=")
.unwrap()
.split_once('-')
.unwrap();
let start: usize = start.parse().unwrap();
let end: usize = end.parse().unwrap();
ResponseTemplate::new(206)
.insert_header(
"Content-Range",
format!("bytes {start}-{end}/{}", payload.len()),
)
.set_body_bytes(payload[start..=end].to_vec())
})
.mount(server)
.await;
}
async fn adjacent_chunk_fixture(
server: &MockServer,
count: usize,
size: usize,
order: &[usize],
requested: Option<Range<u64>>,
) -> Vec<u8> {
let chunks: Vec<Vec<u8>> = (0..count)
.map(|i| vec![u8::try_from(i % 251).unwrap(); size])
.collect();
let serialized_size = serialize_payload(&[&chunks[0]]).len();
let payload = serialize_payload(&chunks.iter().map(Vec::as_slice).collect::<Vec<_>>());
let expected: Vec<u8> = order
.iter()
.flat_map(|i| chunks[*i].iter().copied())
.collect();
let terms: serde_json::Value = order
.iter()
.map(
|i| json!({"hash": XORB_HASH,"unpacked_length":size,"range":{"start":i,"end":i.saturating_add(1)}}),
)
.collect();
let ranges: serde_json::Value = (0..count).map(|i| json!({"chunks":{"start":i,"end":i.saturating_add(1)},"bytes":{"start":i.saturating_mul(serialized_size),"end":i.saturating_add(1).saturating_mul(serialized_size).saturating_sub(1)}})).collect();
let start = requested.as_ref().map_or(0, |range| range.start);
let end = requested
.as_ref()
.map_or(4095, |range| range.end.saturating_sub(1));
reconstruction_mock(server,start,end,start,terms,json!({XORB_HASH:[{"url":format!("{}/transfer/xorb/default/{XORB_HASH}",server.uri()),"ranges":ranges}]})).await;
xorb_payload_mock(server, payload).await;
requested.map_or_else(
|| expected.clone(),
|range| expected[range.start as usize..range.end as usize].to_vec(),
)
}
#[tokio::test]
async fn streaming_coalesces_actual_http_requests_with_partial_slices() {
let server = MockServer::start().await;
let range = 3..507;
let expected = adjacent_chunk_fixture(
&server,
64,
8,
&(0..64).collect::<Vec<_>>(),
Some(range.clone()),
)
.await;
let ctx = test_stream_context(&server, 256);
let (output, _) = tokio::time::timeout(
Duration::from_secs(3),
drain(make_stream(ctx.clone(), Some(range))),
)
.await
.unwrap();
assert_eq!(output, expected);
let requests = server.received_requests().await.unwrap();
let fetches = requests
.iter()
.filter(|request| request.url.path().starts_with("/transfer/xorb/"))
.count();
assert_eq!(
fetches, 2,
"64 tiny descriptors should become two bounded block fetches"
);
assert_eq!(ctx.xorb_fetch_count.load(Ordering::Relaxed), 2);
assert_eq!(ctx.buffer_semaphore.available_permits(), 256);
}
#[tokio::test]
async fn streaming_gapped_and_repeated_ranges_do_not_pin_old_blocks() {
let server = MockServer::start().await;
let expected = adjacent_chunk_fixture(&server, 6, 8, &[0, 1, 4, 5, 0, 1], None).await;
let ctx = test_stream_context(&server, 16);
let (output, _) = tokio::time::timeout(
Duration::from_secs(3),
drain(make_stream(ctx.clone(), None)),
)
.await
.unwrap();
assert_eq!(output, expected);
assert_eq!(ctx.xorb_fetch_count.load(Ordering::Relaxed), 3);
assert_eq!(ctx.buffer_semaphore.available_permits(), 16);
}
#[tokio::test]
async fn streaming_tiny_terms_bound_queued_work_until_consumer_advances() {
let server = MockServer::start().await;
let expected =
adjacent_chunk_fixture(&server, 512, 1, &(0..512).collect::<Vec<_>>(), None).await;
let ctx = test_stream_context(&server, 4096);
let mut stream = make_stream(ctx.clone(), None);
stream.start();
tokio::time::timeout(Duration::from_secs(3), async {
while stream
.run_state
.total_bytes_scheduled
.load(Ordering::Relaxed)
< MAX_BUFFERED_TERMS as u64
{
tokio::time::sleep(Duration::from_millis(1)).await;
}
})
.await
.unwrap();
tokio::time::sleep(Duration::from_millis(20)).await;
assert_eq!(
stream
.run_state
.total_bytes_scheduled
.load(Ordering::Relaxed),
MAX_BUFFERED_TERMS as u64
);
assert_eq!(
ctx.buffer_semaphore.total_permits() - ctx.buffer_semaphore.available_permits(),
128
);
let (output, _) = tokio::time::timeout(Duration::from_secs(3), drain(stream))
.await
.unwrap();
assert_eq!(output, expected);
assert_eq!(ctx.xorb_fetch_count.load(Ordering::Relaxed), 4);
while tokio::task::coop::has_budget_remaining() {
tokio::task::consume_budget().await;
}
assert!(!tokio::task::coop::has_budget_remaining());
tokio::task::unconstrained(async { drop(server) }).await;
}
#[tokio::test]
async fn cancelling_stream_releases_fetch_and_buffer_without_detached_tasks() {
let server = MockServer::start().await;
let payload = serialize_payload(&[b"payload"]);
reconstruction_mock(&server,0,4095,0,json!([{"hash":XORB_HASH,"unpacked_length":7,"range":{"start":0,"end":1}}]),
json!({XORB_HASH:[{"url":format!("{}/transfer/xorb/default/{XORB_HASH}",server.uri()),"ranges":[{"chunks":{"start":0,"end":1},"bytes":{"start":0,"end":payload.len()-1}}]}]})).await;
Mock::given(method("GET"))
.and(path(format!("/transfer/xorb/default/{XORB_HASH}")))
.respond_with(
ResponseTemplate::new(206)
.insert_header(
"Content-Range",
format!("bytes 0-{}/{}", payload.len() - 1, payload.len()),
)
.set_body_bytes(payload)
.set_delay(Duration::from_secs(2)),
)
.mount(&server)
.await;
let ctx = test_stream_context(&server, 128);
let mut stream = make_stream(ctx.clone(), None);
stream.start();
tokio::time::timeout(Duration::from_secs(1), async {
while ctx.download_permits.available_permits() == DEFAULT_DOWNLOAD_CONCURRENCY {
tokio::time::sleep(Duration::from_millis(1)).await;
}
})
.await
.unwrap();
drop(stream);
tokio::time::timeout(Duration::from_millis(250), async {
while ctx.download_permits.available_permits() != DEFAULT_DOWNLOAD_CONCURRENCY
|| ctx.buffer_semaphore.available_permits() != 128
{
tokio::time::sleep(Duration::from_millis(1)).await;
}
})
.await
.expect("cancelled stream left an untracked fetch holding permits");
assert_eq!(ctx.xorb_fetch_count.load(Ordering::Relaxed), 0);
}
fn make_stream(ctx: StreamContext, range: Option<Range<u64>>) -> DownloadStream {
let mut reconstructor =
FileReconstructor::new(ctx, FILE_ID.to_owned(), READ_TOKEN.to_owned());
if let Some(range) = range {
reconstructor = reconstructor.with_byte_range(range);
}
reconstructor.reconstruct_to_stream()
}
fn make_unordered_stream(
ctx: StreamContext,
range: Option<Range<u64>>,
) -> UnorderedDownloadStream {
let mut reconstructor =
FileReconstructor::new(ctx, FILE_ID.to_owned(), READ_TOKEN.to_owned());
if let Some(range) = range {
reconstructor = reconstructor.with_byte_range(range);
}
reconstructor.reconstruct_to_unordered_stream()
}
async fn drain(mut stream: DownloadStream) -> (Vec<u8>, Vec<u64>) {
let mut out = Vec::new();
let mut sizes = Vec::new();
while let Some(chunk) = stream.next().await.unwrap() {
sizes.push(u64::try_from(chunk.len()).unwrap());
out.extend_from_slice(&chunk);
}
(out, sizes)
}
#[test]
fn buffer_semaphore_acquire_release_bounds_in_flight() {
let sem = Arc::new(BufferSemaphore::new(100, 100, 100));
assert_eq!(sem.total_permits(), 100);
assert_eq!(sem.available_permits(), 100);
let rt = Runtime::new().unwrap();
rt.block_on(async {
let p1 = sem.acquire_many(60).await.unwrap();
assert_eq!(sem.available_permits(), 40);
let p2 = sem.acquire_many(40).await.unwrap();
assert_eq!(sem.available_permits(), 0);
drop(p1);
assert_eq!(sem.available_permits(), 60);
drop(p2);
assert_eq!(sem.available_permits(), 100);
});
}
#[test]
fn buffer_semaphore_scales_with_active_download_target() {
let base = 100u64;
let perfile = 50u64;
let limit = 250u64;
let sem = Arc::new(BufferSemaphore::new(base, base, limit));
assert_eq!(sem.total_permits(), base);
let seed = sem.increment_permits_to_target(base + perfile);
assert!(seed.is_some());
assert_eq!(sem.total_permits(), 150);
let mut seed = seed.unwrap();
let term = seed.split(40).unwrap();
assert_eq!(term.num_permits(), 40);
assert_eq!(sem.total_permits(), 150);
drop(term);
drop(seed);
assert_eq!(sem.available_permits(), 150);
let _seed2 = sem.increment_permits_to_target(base + perfile.saturating_mul(2));
assert_eq!(sem.total_permits(), 200);
assert!(sem.decrement_permits_to_target(base).is_some());
assert_eq!(sem.total_permits(), 100);
}
#[test]
fn buffer_semaphore_clamps_to_max_and_min() {
let sem = Arc::new(BufferSemaphore::new(50, 50, 100));
let _ = sem.increment_permits_to_target(10_000);
assert_eq!(sem.total_permits(), 100);
assert!(sem.increment_permits_to_target(100).is_none());
let _ = sem.decrement_permits_to_target(0);
assert_eq!(sem.total_permits(), 50);
}
#[test]
fn buffer_semaphore_large_capacity_uses_scaling_basis() {
let sem = Arc::new(BufferSemaphore::new(
DEFAULT_DOWNLOAD_BUFFER_SIZE,
DEFAULT_DOWNLOAD_BUFFER_SIZE,
DEFAULT_DOWNLOAD_BUFFER_LIMIT,
));
assert_eq!(sem.basis, 4);
let rt = Runtime::new().unwrap();
rt.block_on(async {
let p = sem
.acquire_many(DEFAULT_DOWNLOAD_BUFFER_SIZE)
.await
.unwrap();
assert!(p.num_permits() >= DEFAULT_DOWNLOAD_BUFFER_SIZE);
drop(p);
assert_eq!(sem.available_permits(), DEFAULT_DOWNLOAD_BUFFER_SIZE);
});
}
#[tokio::test]
async fn run_state_error_surfaces_via_check_error() {
let state = RunState::new(CancellationToken::new());
assert!(state.check_error().is_ok());
state.set_error(SdxError::StreamInternal("boom".to_owned()));
let error = state.check_error().unwrap_err();
assert!(matches!(error, SdxError::StreamInternal(_)));
state.cancelled().await;
}
#[test]
fn background_checks_preserve_first_typed_error_for_consumer() {
let state = RunState::new(CancellationToken::new());
state.set_error(SdxError::Transfer(TransferError::InvalidResponse(
"original".to_owned(),
)));
assert!(state.check_background_error().is_err());
assert!(state.check_run_state().is_err());
assert!(
matches!(state.check_error(), Err(SdxError::Transfer(TransferError::InvalidResponse(message))) if message == "original")
);
assert!(state.check_error().is_ok());
}
#[tokio::test]
async fn run_state_cancel_returns_cancelled() {
let state = RunState::new(CancellationToken::new());
state.cancel();
assert!(matches!(state.check_run_state(), Err(RunError::Cancelled)));
}
#[tokio::test]
async fn run_state_tracks_scheduled_and_delivered_bytes() {
let state = RunState::new(CancellationToken::new());
state.record_new_term(100);
state.record_new_term(50);
assert_eq!(state.total_bytes_scheduled(), 150);
state.report_bytes_written(75);
assert_eq!(state.total_bytes_delivered(), 75);
}
fn immediate_future(data: Bytes) -> DataFuture {
Box::pin(async move { Ok(data) })
}
fn delayed_future(data: Bytes, delay: Duration) -> DataFuture {
Box::pin(async move {
tokio::time::sleep(delay).await;
Ok(data)
})
}
#[tokio::test]
async fn sequential_writer_streaming_orders_chunks() {
let state = RunState::new(CancellationToken::new());
let (mut writer, mut receiver) = SequentialWriter::new_streaming(state);
writer
.set_next_term_data_source(
0..5,
None,
delayed_future(Bytes::from("Hello"), Duration::from_millis(50)),
)
.await
.unwrap();
writer
.set_next_term_data_source(
5..6,
None,
delayed_future(Bytes::from(" "), Duration::from_millis(10)),
)
.await
.unwrap();
writer
.set_next_term_data_source(6..11, None, immediate_future(Bytes::from("World")))
.await
.unwrap();
let total = writer.finish().await.unwrap();
assert_eq!(total, 11);
let mut out = Vec::new();
while let Some(item) = receiver.recv().await {
match item {
SequentialRetrievalItem::Data { receiver, permit } => {
let data = receiver.await.unwrap();
out.extend_from_slice(&data);
drop(permit);
}
SequentialRetrievalItem::Finish => break,
}
}
assert_eq!(&out, b"Hello World");
}
struct CooperativeSink {
always_interrupted: bool,
interrupt_once: bool,
permanent_error: bool,
flush_error: bool,
gate: Option<std::sync::mpsc::Receiver<()>>,
started: Option<oneshot::Sender<()>>,
dropped: Option<oneshot::Sender<()>>,
written: Arc<AtomicU64>,
}
impl Write for CooperativeSink {
fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
if let Some(started) = self.started.take() {
let _sent = started.send(());
}
if let Some(gate) = self.gate.take() {
gate.recv().map_err(std::io::Error::other)?;
}
if self.always_interrupted || std::mem::take(&mut self.interrupt_once) {
return Err(std::io::ErrorKind::Interrupted.into());
}
if self.permanent_error {
return Err(std::io::Error::new(
std::io::ErrorKind::BrokenPipe,
"owned sink failure",
));
}
let count = bytes.len().min(3);
self.written
.fetch_add(u64::try_from(count).unwrap_or(u64::MAX), Ordering::Relaxed);
Ok(count)
}
fn flush(&mut self) -> std::io::Result<()> {
if self.flush_error {
Err(std::io::Error::new(
std::io::ErrorKind::BrokenPipe,
"owned flush failure",
))
} else {
Ok(())
}
}
}
impl Drop for CooperativeSink {
fn drop(&mut self) {
if let Some(dropped) = self.dropped.take() {
let _sent = dropped.send(());
}
}
}
#[tokio::test]
async fn cooperative_writer_cancelled_finish_stops_retries_and_releases_permits() {
for vectorized in [false, true] {
for gated in [false, true] {
let state = RunState::new(CancellationToken::new());
let semaphore = Arc::new(BufferSemaphore::new(64, 64, 64));
let written = Arc::new(AtomicU64::new(0));
let (started_tx, started_rx) = oneshot::channel();
let (dropped_tx, dropped_rx) = oneshot::channel();
let (release_tx, gate_rx) = std::sync::mpsc::channel();
let sink = CooperativeSink {
always_interrupted: !gated,
interrupt_once: false,
permanent_error: false,
flush_error: false,
gate: gated.then_some(gate_rx),
started: Some(started_tx),
dropped: Some(dropped_tx),
written: written.clone(),
};
let mut writer = SequentialWriter::new(sink, vectorized, state.clone());
writer
.set_next_term_data_source(
0..64,
Some(semaphore.acquire_many(64).await.unwrap()),
immediate_future(Bytes::from(vec![7u8; 64])),
)
.await
.unwrap();
let finishing = tokio::spawn(writer.finish());
tokio::time::timeout(Duration::from_secs(5), started_rx)
.await
.unwrap()
.unwrap();
assert_eq!(semaphore.available_permits(), 0);
finishing.abort();
assert!(finishing.await.unwrap_err().is_cancelled());
assert!(state.is_cancelled());
if gated {
release_tx.send(()).unwrap();
}
tokio::time::timeout(Duration::from_secs(5), dropped_rx)
.await
.unwrap()
.unwrap();
assert_eq!(written.load(Ordering::Relaxed), if gated { 3 } else { 0 });
assert_eq!(semaphore.available_permits(), 64);
}
}
}
#[tokio::test]
async fn cooperative_writer_preserves_short_writes_interrupted_and_typed_errors() {
for vectorized in [false, true] {
for (permanent_error, flush_error) in [(false, false), (true, false), (false, true)] {
let state = RunState::new(CancellationToken::new());
let written = Arc::new(AtomicU64::new(0));
let sink = CooperativeSink {
always_interrupted: false,
interrupt_once: true,
permanent_error,
flush_error,
gate: None,
started: None,
dropped: None,
written: written.clone(),
};
let mut writer = SequentialWriter::new(sink, vectorized, state.clone());
writer
.set_next_term_data_source(
0..64,
None,
immediate_future(Bytes::from(vec![7u8; 64])),
)
.await
.unwrap();
let result = writer.finish().await;
if permanent_error || flush_error {
assert!(result.is_err());
assert!(
matches!(state.check_error(), Err(SdxError::Io(error)) if error.kind() == std::io::ErrorKind::BrokenPipe && error.to_string() == if permanent_error { "owned sink failure" } else { "owned flush failure" })
);
} else {
assert_eq!(result.unwrap(), 64);
assert_eq!(written.load(Ordering::Relaxed), 64);
assert!(!state.is_cancelled());
}
}
}
}
#[tokio::test]
async fn sequential_writer_rejects_non_sequential_range() {
let state = RunState::new(CancellationToken::new());
let (mut writer, _receiver) = SequentialWriter::new_streaming(state);
writer
.set_next_term_data_source(0..5, None, immediate_future(Bytes::from("Hello")))
.await
.unwrap();
let result = writer
.set_next_term_data_source(10..15, None, immediate_future(Bytes::from("World")))
.await;
assert!(result.is_err());
}
#[tokio::test]
async fn sequential_writer_reports_size_mismatch() {
let state = RunState::new(CancellationToken::new());
let (mut writer, _receiver) = SequentialWriter::new_streaming(state);
writer
.set_next_term_data_source(0..10, None, immediate_future(Bytes::from("Hi")))
.await
.unwrap();
let result = writer.finish().await;
assert!(result.is_err());
}
#[tokio::test]
async fn sequential_writer_releases_permit_after_write() {
let sem = Arc::new(BufferSemaphore::new(10, 10, 10));
let state = RunState::new(CancellationToken::new());
let (mut writer, mut receiver) = SequentialWriter::new_streaming(state);
let permit1 = sem.acquire_many(5).await.unwrap();
let permit2 = sem.acquire_many(5).await.unwrap();
assert_eq!(sem.available_permits(), 0);
writer
.set_next_term_data_source(0..5, Some(permit1), immediate_future(Bytes::from("Hello")))
.await
.unwrap();
writer
.set_next_term_data_source(5..6, Some(permit2), immediate_future(Bytes::from(" ")))
.await
.unwrap();
writer.finish().await.unwrap();
assert_eq!(sem.available_permits(), 0);
while let Some(item) = receiver.recv().await {
match item {
SequentialRetrievalItem::Data { receiver, permit } => {
let _ = receiver.await.unwrap();
drop(permit);
}
SequentialRetrievalItem::Finish => break,
}
}
assert_eq!(sem.available_permits(), 10);
}
#[tokio::test]
async fn sequential_writer_background_thread_writes_and_flushes() {
let state = RunState::new(CancellationToken::new());
let mut writer = SequentialWriter::new(Vec::new(), false, state);
writer
.set_next_term_data_source(0..5, None, immediate_future(Bytes::from("Hello")))
.await
.unwrap();
writer
.set_next_term_data_source(5..11, None, immediate_future(Bytes::from(" World")))
.await
.unwrap();
let total = writer.finish().await.unwrap();
assert_eq!(total, 11);
}
#[tokio::test]
async fn unordered_writer_yields_completion_order_with_offsets() {
let state = RunState::new(CancellationToken::new());
let (mut writer, mut receiver, _progress) = UnorderedWriter::new_streaming(state);
writer
.set_next_term_data_source(
0..5,
None,
delayed_future(Bytes::from("Hello"), Duration::from_millis(80)),
)
.await
.unwrap();
writer
.set_next_term_data_source(
5..6,
None,
delayed_future(Bytes::from(" "), Duration::from_millis(40)),
)
.await
.unwrap();
writer
.set_next_term_data_source(6..11, None, immediate_future(Bytes::from("World")))
.await
.unwrap();
writer.finish().await.unwrap();
let mut items = Vec::new();
while let Some(result) = receiver.recv().await {
let term = result.unwrap();
items.push((term.byte_range.start, term.data.to_vec()));
drop(term.permit);
}
items.sort_by_key(|(offset, _)| *offset);
let out: Vec<u8> = items.into_iter().flat_map(|(_, data)| data).collect();
assert_eq!(&out, b"Hello World");
}
#[tokio::test]
async fn download_stream_yields_chunks_in_order() {
let server = MockServer::start().await;
let chunk_a = vec![7u8; 64];
let chunk_b = vec![9u8; 64];
let chunk_c = vec![3u8; 64];
let payload = serialize_payload(&[&chunk_a, &chunk_b, &chunk_c]);
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}},
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 1, "end": 2}},
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 2, "end": 3}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 3}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
}),
)
.await;
xorb_range_mock(&server, 0, (payload.len() - 1) as u64, payload).await;
let ctx = test_stream_context(&server, 1_048_576);
let (out, _sizes) = drain(make_stream(ctx, None)).await;
let mut expected = chunk_a.clone();
expected.extend_from_slice(&chunk_b);
expected.extend_from_slice(&chunk_c);
assert_eq!(out, expected);
}
async fn assert_reservation_retry_after_failed_init(cancel: bool) {
let server = MockServer::start().await;
let decoded = vec![7; 128];
let payload = serialize_payload(&[&decoded]);
let response = ResponseTemplate::new(206)
.insert_header(
"Content-Range",
format!(
"bytes 0-{}/{}",
payload.len().saturating_sub(1),
payload.len()
),
)
.set_body_bytes(vec![0; payload.len()]);
Mock::given(method("GET"))
.respond_with(if cancel {
response.set_delay(Duration::from_secs(5))
} else {
response
})
.mount(&server)
.await;
let mut ctx = test_stream_context(&server, 4096);
let block = Arc::new(XorbBlock {
hash: XORB_HASH.to_owned(),
chunk_range: (0, 1),
url: server.uri(),
bytes: ByteRange::new(0, (payload.len().saturating_sub(1)) as u64),
data: OnceCell::new(),
decoded_budget: 128,
reservation: Mutex::new(None),
reservation_started: AtomicBool::new(false),
publication_gate: None,
});
let loader_block = Arc::clone(&block);
let loader_context = ctx.clone();
let loader = tokio::spawn(async move {
loader_block
.retrieve_data(&loader_context, READ_TOKEN)
.await
});
if cancel {
tokio::time::timeout(Duration::from_secs(2), async {
loop {
if !server.received_requests().await.unwrap().is_empty() {
break;
}
tokio::task::yield_now().await;
}
})
.await
.unwrap();
assert!(block.reservation_started.load(Ordering::Acquire));
assert_eq!(
ctx.buffer_semaphore.available_permits(),
ctx.buffer_semaphore.total_permits().saturating_sub(128)
);
loader.abort();
assert!(matches!(loader.await, Err(error) if error.is_cancelled()));
} else {
assert!(loader.await.unwrap().is_err());
}
assert!(block.data.get().is_none());
assert!(!block.reservation_started.load(Ordering::Acquire));
assert!(block.reservation.lock().unwrap().is_none());
assert_eq!(
ctx.buffer_semaphore.available_permits(),
ctx.buffer_semaphore.total_permits()
);
let directory = tempfile::tempdir().unwrap();
let cache = Arc::new(ChunkCache::new(directory.path(), 1024).unwrap());
cache
.put(XORB_HASH, (0, 1), &[0, 128], &decoded)
.await
.unwrap();
ctx.chunk_cache = Some(cache);
let data = block.clone().retrieve_data(&ctx, READ_TOKEN).await.unwrap();
assert_eq!(data.data.as_ref(), decoded.as_slice());
assert!(block.reservation_started.load(Ordering::Acquire));
assert_eq!(
ctx.buffer_semaphore.available_permits(),
ctx.buffer_semaphore.total_permits().saturating_sub(128)
);
drop(data);
drop(block);
assert_eq!(
ctx.buffer_semaphore.available_permits(),
ctx.buffer_semaphore.total_permits()
);
}
#[tokio::test]
async fn error_initialization_releases_reservation_and_allows_retry() {
assert_reservation_retry_after_failed_init(false).await;
}
#[tokio::test]
async fn cancelled_initialization_releases_reservation_and_allows_retry() {
assert_reservation_retry_after_failed_init(true).await;
}
async fn assert_reservation_publication(cache_hit: bool) {
let server = MockServer::start().await;
let decoded = vec![7; 128];
let payload = serialize_payload(&[&decoded]);
let mut ctx = test_stream_context(&server, 4096);
let directory = tempfile::tempdir().unwrap();
if cache_hit {
let cache = Arc::new(ChunkCache::new(directory.path(), 1024).unwrap());
cache
.put(XORB_HASH, (0, 1), &[0, 128], &decoded)
.await
.unwrap();
ctx.chunk_cache = Some(cache);
} else {
xorb_range_mock(
&server,
0,
(payload.len().saturating_sub(1)) as u64,
payload.clone(),
)
.await;
}
let (ready_tx, ready_rx) = oneshot::channel();
let (release_tx, release_rx) = std::sync::mpsc::channel();
let block = Arc::new(XorbBlock {
hash: XORB_HASH.to_owned(),
chunk_range: (0, 1),
url: format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
bytes: ByteRange::new(0, (payload.len().saturating_sub(1)) as u64),
data: OnceCell::new(),
decoded_budget: 128,
reservation: Mutex::new(None),
reservation_started: AtomicBool::new(false),
publication_gate: Some(Arc::new(PublicationGate {
ready: Mutex::new(Some(ready_tx)),
release: Mutex::new(release_rx),
})),
});
block.reserve(&ctx, &mut None).await.unwrap();
let loader_block = Arc::clone(&block);
let loader_context = ctx.clone();
let loader = tokio::spawn(async move {
loader_block
.retrieve_data(&loader_context, READ_TOKEN)
.await
});
ready_rx.await.unwrap();
assert!(block.data.get().is_none());
block.reserve(&ctx, &mut None).await.unwrap();
let used = ctx
.buffer_semaphore
.total_permits()
.saturating_sub(ctx.buffer_semaphore.available_permits());
let unused_reservation = block.reservation.lock().unwrap().is_some();
release_tx.send(()).unwrap();
let data = loader.await.unwrap().unwrap();
assert_eq!(data.data.as_ref(), decoded.as_slice());
assert_eq!(
used, 128,
"one backing block must retain exactly one reservation before publication"
);
assert!(!unused_reservation);
assert_eq!(
ctx.xorb_fetch_count.load(Ordering::Relaxed),
u64::from(!cache_hit)
);
drop(data);
drop(block);
assert_eq!(
ctx.buffer_semaphore.available_permits(),
ctx.buffer_semaphore.total_permits()
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn cache_hit_reservation_publication_keeps_single_permit() {
assert_reservation_publication(true).await;
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn network_reservation_publication_keeps_single_permit() {
assert_reservation_publication(false).await;
}
#[tokio::test]
async fn download_stream_with_chunk_cache_serves_second_download_from_disk() {
let server = MockServer::start().await;
let chunk_a = vec![7u8; 64];
let chunk_b = vec![9u8; 64];
let payload = serialize_payload(&[&chunk_a, &chunk_b]);
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}},
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 1, "end": 2}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 2}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
}),
)
.await;
xorb_range_mock(&server, 0, (payload.len() - 1) as u64, payload).await;
let dir = tempfile::tempdir().unwrap();
let cache =
Arc::new(crate::cache::ChunkCache::new(dir.path().to_path_buf(), 1 << 20).unwrap());
let mut ctx = test_stream_context(&server, 1_048_576);
ctx.chunk_cache = Some(cache.clone());
let mut expected = chunk_a.clone();
expected.extend_from_slice(&chunk_b);
let (first, _) = drain(make_stream(ctx.clone(), None)).await;
assert_eq!(first, expected);
assert_eq!(ctx.xorb_fetch_count.load(Ordering::Relaxed), 1);
for _ in 0..500 {
if cache.entry_count().await.unwrap() == 1 {
break;
}
tokio::time::sleep(Duration::from_millis(10)).await;
}
assert_eq!(cache.entry_count().await.unwrap(), 1);
let (second, _) = drain(make_stream(ctx.clone(), None)).await;
assert_eq!(second, expected);
assert_eq!(ctx.xorb_fetch_count.load(Ordering::Relaxed), 1);
}
#[tokio::test]
async fn streaming_xorb_rejects_full_body_for_nonzero_range() {
let server = MockServer::start().await;
let first = serialize_payload(&[b"AAAA"]);
let second = serialize_payload(&[b"BBBB"]);
let mut full = first.clone();
full.extend_from_slice(&second);
Mock::given(method("GET"))
.respond_with(ResponseTemplate::new(200).set_body_bytes(full.clone()))
.mount(&server)
.await;
let block = Arc::new(XorbBlock {
hash: XORB_HASH.to_owned(),
chunk_range: (1, 2),
url: server.uri(),
bytes: ByteRange::new(first.len() as u64, full.len() as u64 - 1),
data: OnceCell::new(),
decoded_budget: 1_048_576,
reservation: Mutex::new(None),
reservation_started: AtomicBool::new(false),
#[cfg(test)]
publication_gate: None,
});
let result = block
.clone()
.retrieve_data(&test_stream_context(&server, 1_048_576), READ_TOKEN)
.await;
assert!(matches!(
result,
Err(SdxError::Transfer(TransferError::InvalidResponse(_)))
));
assert!(block.data.get().is_none());
}
fn queued_download_stream(
receiver: UnboundedReceiver<SequentialRetrievalItem>,
run_state: Arc<RunState>,
) -> DownloadStream {
DownloadStream {
receiver,
pending_data: None,
finished: false,
run_state,
start_signal: None,
#[cfg(not(target_family = "wasm"))]
runtime: test_runtime(),
}
}
#[tokio::test]
async fn timed_out_next_preserves_queued_and_active_data() {
let state = RunState::new(CancellationToken::new());
let semaphore = Arc::new(BufferSemaphore::new(1, 1, 1));
let (tx, rx) = unbounded_channel();
let mut stream = queued_download_stream(rx, state);
let deadline = std::time::Duration::from_millis(1);
assert!(tokio::time::timeout(deadline, stream.next()).await.is_err());
let (data_tx, data_rx) = oneshot::channel();
tx.send(SequentialRetrievalItem::Data {
receiver: data_rx,
permit: Some(semaphore.acquire_many(1).await.unwrap()),
})
.unwrap();
tx.send(SequentialRetrievalItem::Finish).unwrap();
for _ in 0..2 {
assert!(tokio::time::timeout(deadline, stream.next()).await.is_err());
assert_eq!(semaphore.available_permits(), 0);
assert!(!data_tx.is_closed());
}
let expected = Bytes::from_static(b"preserved download chunk");
data_tx.send(expected.clone()).unwrap();
assert_eq!(stream.next().await.unwrap(), Some(expected));
assert_eq!(semaphore.available_permits(), 1);
assert!(stream.next().await.unwrap().is_none());
}
#[tokio::test]
async fn timed_out_next_preserves_background_error() {
let state = RunState::new(CancellationToken::new());
let (tx, rx) = unbounded_channel();
let (data_tx, data_rx) = oneshot::channel();
tx.send(SequentialRetrievalItem::Data {
receiver: data_rx,
permit: None,
})
.unwrap();
tx.send(SequentialRetrievalItem::Finish).unwrap();
let mut stream = queued_download_stream(rx, state.clone());
assert!(
tokio::time::timeout(std::time::Duration::from_millis(1), stream.next())
.await
.is_err()
);
assert!(
tokio::time::timeout(std::time::Duration::from_millis(1), stream.next())
.await
.is_err()
);
state.set_error(SdxError::StreamInternal(
"delayed producer error".to_owned(),
));
drop(data_tx);
assert!(
matches!(stream.next().await, Err(SdxError::StreamInternal(message))
if message == "delayed producer error")
);
assert!(stream.next().await.unwrap().is_none());
}
#[tokio::test]
async fn cancelling_stream_releases_timed_out_pending_data() {
let state = RunState::new(CancellationToken::new());
let semaphore = Arc::new(BufferSemaphore::new(1, 1, 1));
let (tx, rx) = unbounded_channel();
let (data_tx, data_rx) = oneshot::channel();
tx.send(SequentialRetrievalItem::Data {
receiver: data_rx,
permit: Some(semaphore.acquire_many(1).await.unwrap()),
})
.unwrap();
let mut stream = queued_download_stream(rx, state);
assert!(
tokio::time::timeout(std::time::Duration::from_millis(1), stream.next())
.await
.is_err()
);
stream.cancel();
assert_eq!(semaphore.available_permits(), 1);
assert!(data_tx.is_closed());
assert!(stream.next().await.unwrap().is_none());
}
#[tokio::test]
async fn dropping_stream_releases_timed_out_pending_data() {
let state = RunState::new(CancellationToken::new());
let semaphore = Arc::new(BufferSemaphore::new(1, 1, 1));
let (tx, rx) = unbounded_channel();
let (data_tx, data_rx) = oneshot::channel();
tx.send(SequentialRetrievalItem::Data {
receiver: data_rx,
permit: Some(semaphore.acquire_many(1).await.unwrap()),
})
.unwrap();
let mut stream = queued_download_stream(rx, state);
assert!(
tokio::time::timeout(std::time::Duration::from_millis(1), stream.next())
.await
.is_err()
);
drop(stream);
assert_eq!(semaphore.available_permits(), 1);
assert!(data_tx.is_closed());
}
#[tokio::test]
async fn cancelled_stream_with_closed_data_sender_finishes_cleanly() {
let state = RunState::new(CancellationToken::new());
let semaphore = Arc::new(BufferSemaphore::new(1, 1, 1));
let permit = semaphore.acquire_many(1).await.unwrap();
let (data_tx, data_rx) = oneshot::channel();
let (tx, rx) = unbounded_channel();
tx.send(SequentialRetrievalItem::Data {
receiver: data_rx,
permit: Some(permit),
})
.unwrap();
state.cancel();
drop(data_tx);
let mut stream = DownloadStream {
receiver: rx,
pending_data: None,
finished: false,
run_state: state,
start_signal: None,
#[cfg(not(target_family = "wasm"))]
runtime: test_runtime(),
};
assert!(stream.next().await.unwrap().is_none());
assert_eq!(semaphore.available_permits(), 1);
}
#[tokio::test]
async fn download_stream_reports_incompatible_full_body_response() {
let server = MockServer::start().await;
let first = serialize_payload(&[b"AAAA"]);
let mut full = first.clone();
full.extend_from_slice(&serialize_payload(&[b"BBBB"]));
reconstruction_mock(&server, 0, 3, 0,
json!([{ "hash": XORB_HASH, "unpacked_length": 4, "range": {"start": 1, "end": 2}}]),
json!({XORB_HASH: [{ "url": format!("{}/xorb", server.uri()),
"ranges": [{"chunks": {"start": 1, "end": 2}, "bytes": {"start": first.len(), "end": full.len() - 1}}]
}]})).await;
Mock::given(method("GET"))
.and(path("/xorb"))
.respond_with(ResponseTemplate::new(200).set_body_bytes(full))
.mount(&server)
.await;
let mut stream = make_stream(test_stream_context(&server, 1_048_576), Some(0..4));
let result = stream.next().await;
assert!(
matches!(
result,
Err(SdxError::Transfer(TransferError::InvalidResponse(_)))
),
"unexpected stream result: {result:?}"
);
}
#[tokio::test]
async fn streaming_xorb_rejects_unexpected_chunk_count_before_caching() {
let server = MockServer::start().await;
let full = serialize_payload(&[b"AAAA", b"BBBB"]);
let range = ByteRange::new(0, full.len() as u64 - 1);
Mock::given(method("GET"))
.respond_with(
ResponseTemplate::new(206)
.insert_header(
"Content-Range",
format!("bytes 0-{}/{}", range.end, full.len()),
)
.set_body_bytes(full),
)
.mount(&server)
.await;
let block = Arc::new(XorbBlock {
hash: XORB_HASH.to_owned(),
chunk_range: (1, 2),
url: server.uri(),
bytes: range,
data: OnceCell::new(),
decoded_budget: 1_048_576,
reservation: Mutex::new(None),
reservation_started: AtomicBool::new(false),
#[cfg(test)]
publication_gate: None,
});
let dir = tempfile::tempdir().unwrap();
let cache =
Arc::new(crate::cache::ChunkCache::new(dir.path().to_path_buf(), 1 << 20).unwrap());
let mut ctx = test_stream_context(&server, 1_048_576);
ctx.chunk_cache = Some(cache.clone());
let result = block.retrieve_data(&ctx, READ_TOKEN).await;
assert!(matches!(
result,
Err(SdxError::FetchChunkCountMismatch {
expected: 1,
actual: 2,
..
})
));
assert_eq!(cache.entry_count().await.unwrap(), 0);
}
#[tokio::test]
async fn download_stream_accepts_exact_full_body_response() {
let server = MockServer::start().await;
let payload = serialize_payload(&[b"AAAA", b"BBBB"]);
reconstruction_mock(&server, 0, 4095, 0,
json!([{ "hash": XORB_HASH, "unpacked_length": 8, "range": {"start": 0, "end": 2}}]),
json!({XORB_HASH: [{ "url": format!("{}/xorb", server.uri()),
"ranges": [{"chunks": {"start": 0, "end": 2}, "bytes": {"start": 0, "end": payload.len() - 1}}]
}]})).await;
Mock::given(method("GET"))
.and(path("/xorb"))
.respond_with(ResponseTemplate::new(200).set_body_bytes(payload))
.mount(&server)
.await;
let (out, _) = drain(make_stream(test_stream_context(&server, 1_048_576), None)).await;
assert_eq!(out, b"AAAABBBB");
}
#[tokio::test]
async fn download_stream_eof_after_last_chunk() {
let server = MockServer::start().await;
let chunk = vec![5u8; 64];
let payload = serialize_payload(&[&chunk]);
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 1}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
}),
)
.await;
xorb_range_mock(&server, 0, (payload.len() - 1) as u64, payload).await;
let ctx = test_stream_context(&server, 1_048_576);
let mut stream = make_stream(ctx, None);
let first = stream.next().await.unwrap().unwrap();
assert_eq!(first, chunk);
assert!(stream.next().await.unwrap().is_none());
assert!(stream.next().await.unwrap().is_none());
}
async fn pending_prefetch_task() -> (
AbortOnDropHandle<Result<Option<TermBlock>, SdxError>>,
oneshot::Receiver<()>,
) {
let (started_tx, started_rx) = oneshot::channel();
let (dropped_tx, dropped_rx) = oneshot::channel();
let handle = tokio::spawn(async move {
let _guard = ExitGuard::new(move || {
let _sent = dropped_tx.send(());
});
started_tx.send(()).unwrap();
std::future::pending::<Result<Option<TermBlock>, SdxError>>().await
});
started_rx.await.unwrap();
(AbortOnDropHandle::new(handle), dropped_rx)
}
#[tokio::test]
async fn dropping_term_manager_aborts_queued_prefetch() {
let server = MockServer::start().await;
let mut manager = ReconstructionTermManager::new(
test_stream_context(&server, 1_048_576),
FILE_ID.to_owned(),
READ_TOKEN.to_owned(),
0..0,
)
.await
.unwrap();
let (handle, dropped) = pending_prefetch_task().await;
manager.prefetch_queue.push_back(handle);
drop(manager);
tokio::time::timeout(std::time::Duration::from_secs(1), dropped)
.await
.unwrap()
.unwrap();
}
#[tokio::test]
async fn cancelling_next_file_terms_aborts_actively_popped_prefetch() {
let server = MockServer::start().await;
let mut manager = ReconstructionTermManager::new(
test_stream_context(&server, 1_048_576),
FILE_ID.to_owned(),
READ_TOKEN.to_owned(),
0..0,
)
.await
.unwrap();
let (handle, dropped) = pending_prefetch_task().await;
manager.prefetch_queue.push_back(handle);
let mut next = Box::pin(manager.next_file_terms());
std::future::poll_fn(|cx| {
assert!(next.as_mut().poll(cx).is_pending());
std::task::Poll::Ready(())
})
.await;
drop(next);
assert!(manager.prefetch_queue.is_empty());
tokio::time::timeout(std::time::Duration::from_secs(1), dropped)
.await
.unwrap()
.unwrap();
drop(manager);
}
#[tokio::test]
async fn download_stream_empty_file_yields_immediate_eof() {
let server = MockServer::start().await;
reconstruction_mock(&server, 0, 4095, 0, json!([]), json!({})).await;
let ctx = test_stream_context(&server, 1_048_576);
let (out, _sizes) = drain(make_stream(ctx, None)).await;
assert!(out.is_empty());
}
#[tokio::test]
async fn download_stream_byte_range_honors_start_offset() {
let server = MockServer::start().await;
let chunk = vec![7u8; 64];
let payload = serialize_payload(&[&chunk]);
reconstruction_mock(
&server,
16,
63,
16,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 1}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
}),
)
.await;
xorb_range_mock(&server, 0, (payload.len() - 1) as u64, payload).await;
let ctx = test_stream_context(&server, 1_048_576);
let (out, _sizes) = drain(make_stream(ctx, Some(16..64))).await;
assert_eq!(out, chunk[16..64]);
}
#[tokio::test]
async fn cancelled_retained_stream_discards_queue_and_releases_shared_budget() {
for unordered in [false, true] {
for mode in 0..4 {
let server = MockServer::start().await;
let chunk = vec![7u8; 64];
let payload = serialize_payload(&[&chunk]);
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}},
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}}
]),
json!({XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [{"chunks": {"start": 0, "end": 1},
"bytes": {"start": 0, "end": payload.len().saturating_sub(1)}}]
}]}),
)
.await;
xorb_payload_mock(&server, payload).await;
let ctx = test_stream_context(&server, 64);
let state;
if unordered {
let mut stream = make_unordered_stream(ctx.clone(), None);
assert_eq!(stream.next().await.unwrap().unwrap().1, chunk);
tokio::time::timeout(Duration::from_secs(5), async {
while stream.receiver.is_empty() {
tokio::task::yield_now().await;
}
})
.await
.unwrap();
assert_eq!(ctx.buffer_semaphore.available_permits(), 0);
state = stream.run_state.clone();
match mode {
1 => stream.cancel(),
2 => state.cancel(),
3 => state.set_error(SdxError::Transfer(TransferError::NotFound(
"owned queued failure".to_owned(),
))),
_ => {}
}
let result = stream.next().await;
if mode == 0 {
assert_eq!(result.unwrap().unwrap().1, chunk);
} else if mode == 3 {
assert!(
matches!(result, Err(SdxError::Transfer(TransferError::NotFound(message)))
if message == "owned queued failure")
);
} else {
assert!(result.unwrap().is_none());
}
assert!(stream.next().await.unwrap().is_none());
assert!(stream.receiver.is_empty());
tokio::time::timeout(Duration::from_secs(5), async {
while ctx.buffer_semaphore.available_permits() != 64 {
tokio::task::yield_now().await;
}
})
.await
.unwrap();
let mut sibling = make_unordered_stream(ctx.clone(), None);
assert_eq!(
tokio::time::timeout(Duration::from_secs(5), sibling.next())
.await
.unwrap()
.unwrap()
.unwrap()
.1,
chunk
);
assert_eq!(sibling.next().await.unwrap().unwrap().1, chunk);
assert!(sibling.next().await.unwrap().is_none());
assert!(stream.next().await.unwrap().is_none());
} else {
let mut stream = make_stream(ctx.clone(), None);
assert_eq!(stream.next().await.unwrap().unwrap(), chunk);
tokio::time::timeout(Duration::from_secs(5), async {
while stream.receiver.is_empty() {
tokio::task::yield_now().await;
}
})
.await
.unwrap();
assert_eq!(ctx.buffer_semaphore.available_permits(), 0);
state = stream.run_state.clone();
match mode {
1 => stream.cancel(),
2 => state.cancel(),
3 => state.set_error(SdxError::Transfer(TransferError::NotFound(
"owned queued failure".to_owned(),
))),
_ => {}
}
let result = stream.next().await;
if mode == 0 {
assert_eq!(result.unwrap().unwrap(), chunk);
} else if mode == 3 {
assert!(
matches!(result, Err(SdxError::Transfer(TransferError::NotFound(message)))
if message == "owned queued failure")
);
} else {
assert!(result.unwrap().is_none());
}
assert!(stream.next().await.unwrap().is_none());
assert!(stream.receiver.is_empty());
tokio::time::timeout(Duration::from_secs(5), async {
while ctx.buffer_semaphore.available_permits() != 64 {
tokio::task::yield_now().await;
}
})
.await
.unwrap();
let mut sibling = make_stream(ctx.clone(), None);
assert_eq!(
tokio::time::timeout(Duration::from_secs(5), sibling.next())
.await
.unwrap()
.unwrap()
.unwrap(),
chunk
);
assert_eq!(sibling.next().await.unwrap().unwrap(), chunk);
assert!(sibling.next().await.unwrap().is_none());
assert!(stream.next().await.unwrap().is_none());
}
assert_eq!(
state.total_bytes_delivered(),
if mode == 0 { 128 } else { 64 }
);
}
}
}
#[tokio::test]
async fn download_stream_buffer_semaphore_bounds_in_flight_bytes() {
let server = MockServer::start().await;
let chunks: Vec<Vec<u8>> = (0..32u8).map(|i| vec![i; 64]).collect();
let payload = serialize_payload(
chunks
.iter()
.map(Vec::as_slice)
.collect::<Vec<_>>()
.as_slice(),
);
let terms: serde_json::Value = chunks
.iter()
.enumerate()
.map(|(i, chunk)| {
json!({
"hash": XORB_HASH,
"unpacked_length": chunk.len(),
"range": {"start": i as u64, "end": i as u64 + 1}
})
})
.collect();
let serialized_chunk_length = serialize_payload(&[chunks[0].as_slice()]).len() as u64;
let ranges: serde_json::Value = (0..32u64)
.map(|i| {
json!({
"chunks": {"start": i, "end": i + 1},
"bytes": {"start": i * serialized_chunk_length, "end": (i + 1) * serialized_chunk_length - 1}
})
})
.collect();
reconstruction_mock(
&server,
0,
4095,
0,
terms,
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": ranges
}]
}),
)
.await;
xorb_payload_mock(&server, payload).await;
let cap = 256u64;
let ctx = test_stream_context(&server, cap);
let mut stream = make_unordered_stream(ctx.clone(), None);
let mut expected = Vec::new();
for chunk in &chunks {
expected.extend_from_slice(chunk);
}
stream.start();
tokio::time::timeout(Duration::from_secs(5), async {
while ctx.buffer_semaphore.available_permits() != 0 || stream.receiver.is_empty() {
stream.run_state.check_background_error().unwrap();
tokio::task::yield_now().await;
}
})
.await
.expect("producer did not fill the buffer before consumption");
let peak_held = cap.saturating_sub(ctx.buffer_semaphore.available_permits());
assert_eq!(peak_held, cap);
assert!(peak_held > 0);
let initial = stream.receiver.try_recv().unwrap().unwrap();
{
let backing = initial
.permit
.as_ref()
.unwrap()
._backing_block
.as_ref()
.unwrap();
let decoded = backing.data.get().unwrap();
let decoded_bytes = u64::try_from(decoded.data.len()).unwrap();
assert!(decoded_bytes > 0);
assert!(decoded_bytes <= decoded._buffer_permit.num_permits());
assert!(decoded._buffer_permit.num_permits() <= cap);
}
let mut waiting = Box::pin(ctx.buffer_semaphore.acquire_many(1));
assert!(futures_util::poll!(&mut waiting).is_pending());
drop(waiting);
let mut received = std::collections::BTreeMap::new();
let (offset, chunk) = stream.process_term(Ok(initial)).unwrap().unwrap();
assert!(received.insert(offset, chunk).is_none());
while let Some((offset, chunk)) = stream.next().await.unwrap() {
assert!(received.insert(offset, chunk).is_none());
let available = ctx.buffer_semaphore.available_permits();
let held = cap
.checked_sub(available)
.expect("buffer capacity exceeded its cap");
assert!(held <= cap);
}
assert_eq!(received.len(), chunks.len());
let actual: Vec<u8> = received
.into_values()
.flat_map(|chunk| chunk.to_vec())
.collect();
assert_eq!(actual, expected);
assert_eq!(ctx.buffer_semaphore.available_permits(), cap);
}
#[tokio::test]
async fn download_unordered_stream_yields_completion_order() {
let server = MockServer::start().await;
let chunk_a = vec![7u8; 64];
let chunk_b = vec![9u8; 64];
let payload_a = serialize_payload(&[&chunk_a]);
let payload_b = serialize_payload(&[&chunk_b]);
let split = payload_a.len() as u64;
let final_byte = split + payload_b.len() as u64 - 1;
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}},
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 1, "end": 2}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 1}, "bytes": {"start": 0, "end": split - 1}},
{"chunks": {"start": 1, "end": 2}, "bytes": {"start": split, "end": final_byte}}
]
}]
}),
)
.await;
let mut payload = payload_a;
payload.extend_from_slice(&payload_b);
xorb_payload_mock(&server, payload).await;
let ctx = test_stream_context(&server, 1_048_576);
let mut stream = make_unordered_stream(ctx, None);
let mut expected = chunk_a.clone();
expected.extend_from_slice(&chunk_b);
let mut pieces: Vec<(u64, Vec<u8>)> = Vec::new();
while let Some((offset, chunk)) = stream.next().await.unwrap() {
pieces.push((offset, chunk.to_vec()));
}
pieces.sort_by_key(|(offset, _)| *offset);
let mut out = Vec::new();
let offsets: Vec<u64> = pieces.iter().map(|(offset, _)| *offset).collect();
for (_, data) in pieces {
out.extend_from_slice(&data);
}
assert_eq!(offsets, vec![0, 64]);
assert_eq!(out, expected);
}
#[tokio::test]
async fn download_stream_cancel_stops_promptly() {
let server = MockServer::start().await;
let chunk_a = vec![7u8; 64];
let chunk_b = vec![9u8; 64];
let payload = serialize_payload(&[&chunk_a, &chunk_b]);
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}},
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 1, "end": 2}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 2}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
}),
)
.await;
xorb_range_mock(&server, 0, (payload.len() - 1) as u64, payload).await;
let ctx = test_stream_context(&server, 1_048_576);
let mut stream = make_stream(ctx, None);
let first = stream.next().await.unwrap().unwrap();
assert_eq!(first, chunk_a);
stream.cancel();
assert!(stream.next().await.unwrap().is_none());
assert!(stream.next().await.unwrap().is_none());
}
#[tokio::test]
async fn download_stream_drop_cancels_background_task() {
let server = MockServer::start().await;
let chunk = vec![5u8; 64];
let payload = serialize_payload(&[&chunk]);
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 1}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
}),
)
.await;
xorb_range_mock(&server, 0, (payload.len() - 1) as u64, payload).await;
let ctx = test_stream_context(&server, 1_048_576);
let mut stream = make_stream(ctx, None);
let first = stream.next().await.unwrap().unwrap();
assert_eq!(first, chunk);
drop(stream);
tokio::task::yield_now().await;
}
async fn blocking_stream_fixture() -> (MockServer, StreamContext) {
let server = MockServer::start().await;
let payload = serialize_payload(&[&[5u8; 64]]);
let last_byte = u64::try_from(payload.len())
.unwrap()
.checked_sub(1)
.unwrap();
reconstruction_mock(
&server, 0, 4095, 0,
json!([{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}}]),
json!({XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [{"chunks": {"start": 0, "end": 1}, "bytes": {"start": 0, "end": last_byte}}]
}]}),
).await;
xorb_range_mock(&server, 0, last_byte, payload).await;
let context = test_stream_context(&server, 1_048_576);
(server, context)
}
async fn check_blocking_streams_inside_runtime() {
let (_server, context) = blocking_stream_fixture().await;
let mut ordered = make_stream(context.clone(), None);
let mut output = Vec::new();
while let Some(bytes) = ordered.blocking_next().unwrap() {
output.extend_from_slice(&bytes);
}
assert_eq!(output, vec![5u8; 64]);
assert!(ordered.blocking_next().unwrap().is_none());
let mut unordered = make_unordered_stream(context.clone(), None);
let (offset, bytes) = unordered.blocking_next().unwrap().unwrap();
assert_eq!(offset, 0);
assert_eq!(&bytes[..], &[5u8; 64]);
assert!(unordered.blocking_next().unwrap().is_none());
let mut ordered_cancelled = make_stream(context.clone(), None);
ordered_cancelled.cancel();
assert!(ordered_cancelled.blocking_next().unwrap().is_none());
let mut unordered_cancelled = make_unordered_stream(context, None);
unordered_cancelled.cancel();
assert!(unordered_cancelled.blocking_next().unwrap().is_none());
}
#[tokio::test(flavor = "current_thread")]
async fn blocking_next_works_inside_current_thread_runtime() {
check_blocking_streams_inside_runtime().await;
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn blocking_next_works_inside_multi_thread_runtime() {
check_blocking_streams_inside_runtime().await;
}
#[test]
fn unordered_blocking_next_works_from_plain_thread() {
let runtime = Runtime::new().unwrap();
let (server, mut stream) = runtime.block_on(async {
let (server, context) = blocking_stream_fixture().await;
(server, make_unordered_stream(context, None))
});
drop(runtime);
let (offset, bytes) = stream.blocking_next().unwrap().unwrap();
assert_eq!(offset, 0);
assert_eq!(&bytes[..], &[5u8; 64]);
assert!(stream.blocking_next().unwrap().is_none());
drop(server);
}
#[test]
fn blocking_next_works_from_plain_thread() {
let rt = Runtime::new().unwrap();
let (server, mut stream) = rt.block_on(async {
let server = MockServer::start().await;
let chunk = vec![5u8; 64];
let payload = serialize_payload(&[&chunk]);
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 1}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
}),
)
.await;
xorb_range_mock(&server, 0, (payload.len() - 1) as u64, payload).await;
let ctx = test_stream_context(&server, 1_048_576);
(server, make_stream(ctx, None))
});
drop(rt);
let handle = std::thread::spawn(move || {
let mut out = Vec::new();
while let Some(chunk) = stream.blocking_next().unwrap() {
out.extend_from_slice(&chunk);
}
(out, stream)
});
let (out, _stream) = handle.join().unwrap();
assert_eq!(out, vec![5u8; 64]);
drop(server);
}
#[tokio::test]
async fn download_stream_matches_reconstruct_output() {
let full_server = MockServer::start().await;
let stream_server = MockServer::start().await;
let chunk_a = vec![7u8; 64];
let chunk_b = vec![9u8; 64];
let payload = serialize_payload(&[&chunk_a, &chunk_b]);
let terms = json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}},
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 1, "end": 2}}
]);
let full_xorbs = json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", full_server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 2}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
});
let stream_xorbs = json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", stream_server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 2}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
});
Mock::given(method("GET"))
.and(path(format!("/v2/reconstructions/{FILE_ID}")))
.and(header("authorization", format!("Bearer {READ_TOKEN}")))
.respond_with(ResponseTemplate::new(200).set_body_json(v2_response_body(
0,
terms.clone(),
full_xorbs,
)))
.mount(&full_server)
.await;
xorb_range_mock(&full_server, 0, (payload.len() - 1) as u64, payload.clone()).await;
reconstruction_mock(&stream_server, 0, 4095, 0, terms, stream_xorbs).await;
xorb_range_mock(
&stream_server,
0,
(payload.len() - 1) as u64,
payload.clone(),
)
.await;
let mut expected = chunk_a.clone();
expected.extend_from_slice(&chunk_b);
let transfer = TransferClient::new(reqwest::Client::new());
let file = reconstruction::reconstruct(
&transfer,
None,
&full_server.uri(),
READ_TOKEN,
FILE_ID,
None,
)
.await
.unwrap();
assert_eq!(file.data, expected);
let ctx = test_stream_context(&stream_server, 1_048_576);
let (out, _sizes) = drain(make_stream(ctx, None)).await;
assert_eq!(out, expected);
}
#[tokio::test]
async fn download_stream_surfaces_background_errors() {
let server = MockServer::start().await;
let chunk = vec![5u8; 64];
let payload = serialize_payload(&[&chunk]);
reconstruction_mock(
&server,
0,
4095,
0,
json!([
{"hash": XORB_HASH, "unpacked_length": 64, "range": {"start": 0, "end": 1}}
]),
json!({
XORB_HASH: [{
"url": format!("{}/transfer/xorb/default/{XORB_HASH}", server.uri()),
"ranges": [
{"chunks": {"start": 0, "end": 1}, "bytes": {"start": 0, "end": payload.len() - 1}}
]
}]
}),
)
.await;
let _ = payload;
let ctx = test_stream_context(&server, 1_048_576);
let mut stream = make_stream(ctx, None);
let mut surfaced: Option<SdxError> = None;
loop {
match stream.next().await {
Ok(Some(_)) => {}
Ok(None) => break,
Err(error) => {
surfaced = Some(error);
break;
}
}
}
if !matches!(
surfaced,
Some(SdxError::Transfer(TransferError::NotFound(_)))
) {
for _ in 0..500 {
if stream.run_state.error_message().is_some() {
break;
}
tokio::time::sleep(Duration::from_millis(1)).await;
}
surfaced = stream.run_state.check_error().err();
}
assert!(
matches!(
surfaced,
Some(SdxError::Transfer(TransferError::NotFound(_)))
),
"background xorb fetch failure was swallowed or surfaced a wrong error; got {surfaced:?}"
);
}
}