feat(websocket): WsTimeouts request extension for WS pump knobs (WS-17)

- WsTimeouts { idle, write } request extension mirrors ChannelsPolicy:
  a deployment layers it on a WS route (bare-registry routes included)
  to set the pump knobs per route
- precedence: extension present replaces the router state entirely;
  absent falls back to SessionState (adapter-configured idle) and the
  crate default write window — a Default impl never clobbers the
  adapter-configured idle knob
- upgrade.rs module + handler docs now state the real defaults for
  bare-registry routes (60 s idle + 60 s write, 64-session semaphore,
  handler-private WsSessions) and the extension surface
- split_ws_to_bytes_idle_with_write exposes the WS-18 write window to
  run_channels_session; acceptance test drives a bare-registry route
  with a 150 ms extension idle window (1001 eviction observed)

Verification: scripts/verify.sh OK (343 passed), test-support suite
ok, clippy -D warnings clean, fmt clean

src/websocket/upgrade.rs

@@ -51,7 +51,7 @@ use axum::response::{IntoResponse, Response};
 use parking_lot::Mutex;
 
 use super::byte_adapter::{
-    split_ws_to_bytes_idle, WsPumps, INBOUND_WS_FRAME_CAP, INBOUND_WS_MESSAGE_CAP,
+    split_ws_to_bytes_idle_with_write, WsPumps, INBOUND_WS_FRAME_CAP, INBOUND_WS_MESSAGE_CAP,
 };
 
 /// Registry of live WS session pump handles (WS-08). The upgrade
@@ -196,7 +196,11 @@ impl WsSessions {
 /// session's pump handle is registered for the session's lifetime —
 /// the WS-08 eviction lever ([`WsSessions::abort`]). `idle_timeout`
 /// bounds the read stall (WS-01): `None` disables the knob, `Some(d)`
-/// closes the read with 1001 after `d` without an inbound WS message.
+/// closes the read with 1001 after `d` without inbound chunk
+/// progress. `write_timeout` bounds one outbound WS send (WS-18):
+/// `None` = the crate default window, `Some(d)` a deployment-set
+/// window.
+#[allow(clippy::too_many_arguments)]
 pub async fn run_channels_session(
     socket: axum::extract::ws::WebSocket,
     registry: Arc<OperationRegistry>,
@@ -204,8 +208,10 @@ pub async fn run_channels_session(
     policy: Arc<dyn ChannelLifecyclePolicy>,
     sessions: Option<WsSessions>,
     idle_timeout: Option<std::time::Duration>,
+    write_timeout: Option<std::time::Duration>,
 ) {
-    let (byte_stream, pumps) = split_ws_to_bytes_idle(socket, idle_timeout);
+    let (byte_stream, pumps) =
+        split_ws_to_bytes_idle_with_write(socket, idle_timeout, write_timeout);
     let pumps = Arc::new(pumps);
 
     let _guard = sessions.map(|sessions| {
@@ -316,6 +322,40 @@ impl alkcall::core::auth::IdentityProvider for NoopProvider {
 #[derive(Clone)]
 pub struct ChannelsPolicy(pub Arc<dyn ChannelLifecyclePolicy>);
 
+/// Per-request WS pump timeouts (WS-17): a deployment inserts
+/// `WsTimeouts` into the request extensions (a route layer on the WS
+/// route, mirroring [`ChannelsPolicy`]) to set the pump knobs per
+/// route instead of the router-state defaults. `idle` (WS-01) bounds
+/// the read staleness (no completed inbound chunk for the window →
+/// 1001 eviction); `write` (WS-18) bounds one outbound WS send (a peer
+/// that stops reading is evicted once a single send outlasts it);
+/// `None` disables a knob. Without the extension the
+/// [`SessionState`] values apply — the built-in surface carries
+/// `HttpAdapter::with_ws_idle_timeout` /
+/// `DEFAULT_WS_IDLE_TIMEOUT` for the read side and
+/// [`crate::websocket::DEFAULT_WS_WRITE_TIMEOUT`] for the write side,
+/// which is also what bare-registry routes (custom upgrade routes on
+/// a plain `Arc<OperationRegistry>` state) get: 60 s idle + 60 s
+/// write windows, 64-session semaphore, handler-private
+/// [`WsSessions`].
+#[derive(Clone, Copy, Debug)]
+pub struct WsTimeouts {
+    /// Idle-read window (WS-01); `None` disables the eviction.
+    pub idle: Option<std::time::Duration>,
+    /// Write-progress window (WS-18); `None` selects the crate
+    /// default (`DEFAULT_WS_WRITE_TIMEOUT`).
+    pub write: Option<std::time::Duration>,
+}
+
+impl Default for WsTimeouts {
+    fn default() -> Self {
+        Self {
+            idle: Some(crate::websocket::DEFAULT_WS_IDLE_TIMEOUT),
+            write: None,
+        }
+    }
+}
+
 /// The upgrade handler. Requires the resolved identity in request
 /// extensions (stashed by [`ws_bearer_auth`]) — a WS session without
 /// an identity cannot run `AccessControl::check`.
@@ -327,6 +367,16 @@ pub struct ChannelsPolicy(pub Arc<dyn ChannelLifecyclePolicy>);
 /// (`RouterState::ws_sessions`) unless a request extension carries
 /// one, so a stuck session stays evictable (WS-08).
 ///
+/// The pump timeout knobs (WS-01 read / WS-18 write) come from the
+/// [`WsTimeouts`] request extension when present, else from the
+/// router state (`HttpAdapter::with_ws_idle_timeout` for the read;
+/// the write side is fixed at
+/// [`crate::websocket::DEFAULT_WS_WRITE_TIMEOUT`] on the built-in
+/// surface). Bare-registry routes (`Arc<OperationRegistry>` state)
+/// carry no configurable state — they run the documented defaults
+/// above; a deployment overriding them inserts the `WsTimeouts`
+/// extension on its upgrade route.
+///
 /// Session cap (WS-09): one semaphore permit is acquired per upgrade,
 /// post-auth and pre-upgrade; when the configured cap
 /// (`HttpAdapter::with_ws_max_sessions`, default
@@ -338,6 +388,7 @@ pub async fn ws_upgrade_handler(
     axum::extract::State(state): axum::extract::State<SessionState>,
     axum::Extension(identity): axum::Extension<Identity>,
     policy: Option<axum::Extension<ChannelsPolicy>>,
+    timeouts: Option<axum::Extension<WsTimeouts>>,
     ws_upgrade: WebSocketUpgrade,
 ) -> Response {
     let Ok(permit) = state.session_slots.clone().try_acquire_owned() else {
@@ -356,13 +407,26 @@ pub async fn ws_upgrade_handler(
         .map(|axum::Extension(p)| p.0)
         .unwrap_or_else(|| Arc::new(NoCap));
     let registry = Arc::clone(state.registry());
-    let idle_timeout = state.idle_timeout();
+    let idle_timeout = match timeouts {
+        Some(axum::Extension(t)) => t.idle,
+        None => state.idle_timeout(),
+    };
+    let write_timeout = timeouts.and_then(|t| t.write);
     ws_upgrade
         .max_frame_size(INBOUND_WS_FRAME_CAP)
         .max_message_size(INBOUND_WS_MESSAGE_CAP)
         .on_upgrade(move |socket| async move {
             let _permit = permit;
-            run_channels_session(socket, registry, identity, policy, sessions, idle_timeout).await
+            run_channels_session(
+                socket,
+                registry,
+                identity,
+                policy,
+                sessions,
+                idle_timeout,
+                Some(write_timeout.unwrap_or(crate::websocket::DEFAULT_WS_WRITE_TIMEOUT)),
+            )
+            .await
         })
 }