Allow host-provided QUIC time sources

[thethorne48]

Some WASM hosts advance monotonic time and schedule wakeups through host-managed events rather than the browser timer APIs used by Iroh today. In those environments, QUIC deadlines can stall while the isolate is suspended between I/O events.

I would like to add an unstable endpoint-level time source with two operations:

fn now(&self) -> QuicInstant;
fn sleep_until(&self, deadline: QuicInstant)
    -> Pin<Box<dyn Future<Output = ()> + Send>>;

Iroh would adapt these futures internally to noq’s AsyncTimer; resetting a timer would replace and drop the obsolete sleep future. The default runtime would remain unchanged.

Non-goals are replacing task spawning, sockets, tracing, or shutdown, and no host-specific dependency would be added to Iroh. The API would remain behind an unstable feature.

I plan to work on this. Before opening the implementation for review, does this API boundary and placement on endpoint::Builder match the project’s preferred direction?

[matheus23]

Some WASM hosts advance monotonic time and schedule wakeups through host-managed events rather than the browser timer APIs used by Iroh today. In those environments, QUIC deadlines can stall while the isolate is suspended between I/O events.

Can you say more about those environments? This would be useful to know.
It's likely that we don't support those environments yet, the Wasm compilation support in iroh today is specifically just for browser support. Even e.g. nodejs is supported via FFI instead.
Is something like that maybe an option for your environment?

If not, perhaps making iroh compile to wasm-wasi is a better way of supporting your environment?

[thethorne48]

The environment is Cloudflare Workers / Durable Objects (workerd). It's browser-adjacent — wasm32-unknown-unknown + wasm-bindgen, browser-style globals — but the timing semantics are stricter than a browser:

• As a side-channel mitigation, Date.now() / performance.now() are frozen during synchronous execution and only advance at I/O event boundaries. QUIC math that samples "now" mid-slice (pacing, RTT, loss detection) sees time standing still.
• Wakeups are host-managed. setTimeout exists, but the isolate can be suspended between events (Durable Objects hibernate), so the host's own scheduling — not a browser timer — is the reliable source of deadline wakeups.

The other routes you mentioned don't apply here: Workers can't load native code, so the Node.js-style FFI path is out, and wasm-wasi doesn't fit because the entire platform surface (sockets, events, alarms) is JS host APIs — which is also where our transport lives. We're already running an iroh endpoint in this environment on unstable-custom-transports (related: #2676); time is the remaining host dependency that can't be injected.

That's what shaped the proposal: a small QuicTimeSource trait (host-provided now() plus a host-armed sleep future), adapted internally to noq's timer. Iroh keeps owning spawning, tracing, sockets, and shutdown. We have a working implementation with tests on a branch — happy to open a draft PR if the direction seems reasonable, or adjust the shape first if you'd rather.

[matheus23]

This sounds like a really tough environment for hosting a QUIC implementation.
QUIC is quite sensitive to proper timing.

Was your idea to "simulate" proper time by using setTimeout(1ms) in a loop?

[thethorne48]

No, that felt a bit heavy-handed to me, I was thinking of something that integrates more natively with noq.

The model is event-driven. At each host I/O boundary we observe Date.now() and monotonically advance the QUIC clock. When noq creates, resets, completes, or drops a sleep, Rust notifies JS that the deadline set changed. JS then queries the earliest deadline and arms one setTimeout for its remaining duration.

The timeout is tagged with the clock generation and deadline. When it fires, Rust rejects stale callbacks, advances virtual time to max(host_elapsed, deadline), and wakes every due sleep future. QUIC progress may create a new earliest deadline, which triggers another one-shot rearm through a coalesced microtask.

So we do not attempt to fabricate continuously advancing time during a synchronous Worker turn. Time advances only when the host resumes execution for I/O or a requested deadline, which matches workerd’s execution model. The important property is that a QUIC loss/pacing deadline itself creates the host event needed to resume the isolate.

Your observation on #2676 matches what we saw in deployed Workers. We have already validated the host-driven clock end to end with iroh-over-WSS streaming R2 data: without external deadline wakeups, QUIC can stall after carrier interruption; with the one-shot deadline scheduler, retransmission deadlines fire and the stream resumes. So frozen time is a demonstrated liveness problem. We have not yet isolated whether noq’s zero-elapsed pacing estimate explains every bounded-queue saturation event, but we can instrument that separately.

We have this one-shot deadline implementation and cancellation/reset tests on a branch. I opened it as a draft #4466 if seeing the concrete code would help evaluate whether this timing model is viable.