perf: serve ranges from RAM cache, stream ZIPs, overlap ingest settle, O(1) chunk gate

Round 2 of benchmark-gated optimizations (benches/ROUND2.md; every change
gated by a before/after in examples/bench_round2.rs — an AFTER that did
not beat its BEFORE was to be rolled back; none needed it):

- Range requests (REST/DAV/shares) answered from the moka content cache
  for sub-10MB files: PG resolve + open/seek/read -> Bytes::slice.
  256KiB seeks: 1,730/s -> 3.7M/s (p50 552us -> 0.15us).
- Streaming folder/share ZIPs via tokio duplex: TTFB no longer scales
  with archive size (326ms -> 0.4ms on 192MiB corpus; total also faster).
  Content-Length dropped (size unknown up front).
- NC chunked-upload per-PUT gate: O(k) directory scan+stat -> in-RAM
  per-session counter (lazy rebuild on cold start). 1,000-chunk upload
  gate cost: 33.1s -> 0.09s cumulative.
- Delta download + commit-verify now use the CDC path's
  buffered(read_prefetch) read-ahead: 64-chunk drain at 5ms open
  latency 440ms -> 51ms; order preserved.
- CDC ingest settles batches on a spawned task (depth-1 pipeline) so
  the source stream keeps flowing during PG pin + backend writes;
  rollback ledger shared + lock-serialized so compensation stays exact
  on cancellation. 512MiB paced ingest: 60-69 -> 74-75 MB/s.
  OXICLOUD_INGEST_OVERLAP=0 restores inline settling (ops/bench hatch).
- Frontend: instant-upload BLAKE3 hashing moved off the main thread to
  a bounded Web Worker pool (File handles by reference); vitest gate
  asserts the pool beats sequential (first gate draft posting buffers
  was 2.6x slower and was rewritten — copies dominated).

Validation: cargo fmt + clippy -D warnings clean; 514 unit + 544
integration tests green; 270 frontend tests green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CBK1RdtzyP6759Muqe1K1w

src/interfaces/range_requests.rs

@@ -13,7 +13,7 @@ use http_range_header::parse_range_header;
 use std::sync::Arc;
 
 use crate::application::dtos::file_dto::FileDto;
-use crate::application::ports::file_ports::FileRetrievalUseCase;
+use crate::application::ports::file_ports::RangeContent;
 use crate::application::services::file_retrieval_service::FileRetrievalService;
 
 /// `If-None-Match` short-circuit: returns a `304 Not Modified` response
@@ -71,24 +71,32 @@ pub async fn range_response(
     let end = *range.end();
     let range_length = end - start + 1;
 
+    // Cache-aware: sub-threshold files already in the RAM content cache are
+    // answered with a zero-copy Bytes slice — no PG, no disk (benches/RANGE-CACHE.md).
     match retrieval
-        .get_file_range_stream(&file.id, start, Some(end + 1))
+        .get_file_range_preloaded(file, start, Some(end + 1))
         .await
     {
-        Ok(stream) => Some(
-            Response::builder()
-                .status(StatusCode::PARTIAL_CONTENT)
-                .header(header::CONTENT_TYPE, &*file.mime_type)
-                .header(header::CONTENT_LENGTH, range_length)
-                .header(
-                    header::CONTENT_RANGE,
-                    format!("bytes {}-{}/{}", start, end, file.size),
-                )
-                .header(header::ACCEPT_RANGES, "bytes")
-                .header(header::ETAG, etag)
-                .body(Body::from_stream(Box::into_pin(stream)))
-                .unwrap(),
-        ),
+        Ok(content) => {
+            let body = match content {
+                RangeContent::Bytes(b) => Body::from(b),
+                RangeContent::Stream(s) => Body::from_stream(Box::into_pin(s)),
+            };
+            Some(
+                Response::builder()
+                    .status(StatusCode::PARTIAL_CONTENT)
+                    .header(header::CONTENT_TYPE, &*file.mime_type)
+                    .header(header::CONTENT_LENGTH, range_length)
+                    .header(
+                        header::CONTENT_RANGE,
+                        format!("bytes {}-{}/{}", start, end, file.size),
+                    )
+                    .header(header::ACCEPT_RANGES, "bytes")
+                    .header(header::ETAG, etag)
+                    .body(body)
+                    .unwrap(),
+            )
+        }
         Err(err) => {
             tracing::error!("Error creating range stream: {}", err);
             None // fall through to the full download