web-cortex-framework 2.5.1__tar.gz → 2.5.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/Cargo.lock +2 -2
  2. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/Cargo.toml +1 -1
  3. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/PKG-INFO +2 -2
  4. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/README.md +1 -1
  5. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/agent.rs +33 -3
  6. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/app.rs +39 -4
  7. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/devices.rs +64 -7
  8. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/errors.rs +4 -1
  9. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/lib.rs +20 -2
  10. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/server.rs +53 -17
  11. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/status.rs +76 -1
  12. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/ws.rs +21 -2
  13. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/pyproject.toml +1 -1
  14. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/__init__.py +1 -1
  15. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/client.py +14 -2
  16. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/diagnostics.py +2 -1
  17. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/errors.py +1 -1
  18. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/LICENSE +0 -0
  19. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/Cargo.toml +0 -0
  20. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/agent/provider.rs +0 -0
  21. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/agent/registry.rs +0 -0
  22. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/agent/session.rs +0 -0
  23. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/agent/vision.rs +0 -0
  24. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/audit.rs +0 -0
  25. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/auth.rs +0 -0
  26. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/bridge.rs +0 -0
  27. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/context.rs +0 -0
  28. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/db.rs +0 -0
  29. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/files.rs +0 -0
  30. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/flow.rs +0 -0
  31. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/http.rs +0 -0
  32. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/ledger.rs +0 -0
  33. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/manifest.rs +0 -0
  34. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/mcp.rs +0 -0
  35. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/middleware.rs +0 -0
  36. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/openapi.rs +0 -0
  37. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/router.rs +0 -0
  38. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/templates.rs +0 -0
  39. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/src/typegen.rs +0 -0
  40. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-core/tests/diagnostics.rs +0 -0
  41. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-py/Cargo.toml +0 -0
  42. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-py/src/behaviour.rs +0 -0
  43. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/crates/webcortex-py/src/lib.rs +0 -0
  44. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/_bridge.py +0 -0
  45. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/app.py +0 -0
  46. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/cli.py +0 -0
  47. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/contextpack.py +0 -0
  48. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/media.py +0 -0
  49. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/schema.py +0 -0
  50. {web_cortex_framework-2.5.1 → web_cortex_framework-2.5.2}/python/webcortex/starters.py +0 -0
@@ -2662,7 +2662,7 @@ dependencies = [
2662
2662
 
2663
2663
  [[package]]
2664
2664
  name = "webcortex-core"
2665
- version = "2.5.1"
2665
+ version = "2.5.2"
2666
2666
  dependencies = [
2667
2667
  "base64 0.23.1",
2668
2668
  "bytes",
@@ -2690,7 +2690,7 @@ dependencies = [
2690
2690
 
2691
2691
  [[package]]
2692
2692
  name = "webcortex-py"
2693
- version = "2.5.1"
2693
+ version = "2.5.2"
2694
2694
  dependencies = [
2695
2695
  "bytes",
2696
2696
  "futures",
@@ -3,7 +3,7 @@ members = ["crates/webcortex-core", "crates/webcortex-py"]
3
3
  resolver = "3"
4
4
 
5
5
  [workspace.package]
6
- version = "2.5.1"
6
+ version = "2.5.2"
7
7
  edition = "2024"
8
8
  license = "Apache-2.0"
9
9
  rust-version = "1.88"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: web-cortex-framework
3
- Version: 2.5.1
3
+ Version: 2.5.2
4
4
  Classifier: Development Status :: 3 - Alpha
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: License :: OSI Approved :: Apache Software License
@@ -527,7 +527,7 @@ tested, the known limits, and what v2 added to the surface.
527
527
 
528
528
  ## Status
529
529
 
530
- v2.5.1. Working and tested: the manifest IR, router, native ops (static /
530
+ v2.5.2. Working and tested: the manifest IR, router, native ops (static /
531
531
  query / proxy / page / files / flow), the free-threaded Python bridge,
532
532
  authentication and scopes, rate limiting, CORS, security headers, graceful
533
533
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -499,7 +499,7 @@ tested, the known limits, and what v2 added to the surface.
499
499
 
500
500
  ## Status
501
501
 
502
- v2.5.1. Working and tested: the manifest IR, router, native ops (static /
502
+ v2.5.2. Working and tested: the manifest IR, router, native ops (static /
503
503
  query / proxy / page / files / flow), the free-threaded Python bridge,
504
504
  authentication and scopes, rate limiting, CORS, security headers, graceful
505
505
  shutdown, Behaviours with concurrent leaves, the agent runtime with handoffs,
@@ -510,6 +510,9 @@ impl AgentRuntime {
510
510
  let SuspendedRun { state: mut st, calls, gated, mut results, approval_id, .. } = suspended;
511
511
  let call = &calls[gated];
512
512
  app.recorder().run_started(&st.run_id, &st.def.name, &st.caller.id, st.depth);
513
+ // The approved call runs before `drive` does; dropped there, the run
514
+ // is cancelled just the same.
515
+ let mut guard = CancelGuard { app, run_id: Some(st.run_id.clone()) };
513
516
 
514
517
  if approve {
515
518
  self.audit.record(AuditEvent::approval_decided(
@@ -539,17 +542,29 @@ impl AgentRuntime {
539
542
  results.push(tool_result(&call.id, &json!({"error": msg}), true));
540
543
  }
541
544
 
542
- match self.execute_calls(app, &mut st, &calls, gated + 1, results).await {
545
+ let result = match self.execute_calls(app, &mut st, &calls, gated + 1, results).await {
543
546
  CallsOutcome::Done(results) => {
544
547
  st.conversation.messages.push(Message { role: "user".into(), content: Value::Array(results) });
545
548
  self.drive(app, st).await
546
549
  }
547
550
  CallsOutcome::Suspended { gated, results } => self.suspend(app, st, calls, gated, results),
548
- }
551
+ };
552
+ guard.run_id = None;
553
+ result
549
554
  }
550
555
 
551
556
  /// The main loop. Everything mutable lives in `st`.
552
- async fn drive(&self, app: &App, mut st: RunState) -> RunResult {
557
+ async fn drive(&self, app: &App, st: RunState) -> RunResult {
558
+ // The future driving a run is dropped when its request times out or
559
+ // its client goes away; the run then never reaches `finish`. The
560
+ // guard takes it out of the status view's in-flight list either way.
561
+ let mut guard = CancelGuard { app, run_id: Some(st.run_id.clone()) };
562
+ let result = self.drive_steps(app, st).await;
563
+ guard.run_id = None;
564
+ result
565
+ }
566
+
567
+ async fn drive_steps(&self, app: &App, mut st: RunState) -> RunResult {
553
568
  let max_steps = st.entry.max_steps.unwrap_or(12);
554
569
 
555
570
  loop {
@@ -1169,6 +1184,21 @@ fn outcome_code(status: RunStatus, steps: &[Step]) -> Option<&'static str> {
1169
1184
  }
1170
1185
  }
1171
1186
 
1187
+ /// Reports a run as cancelled if it is dropped before `drive` returns.
1188
+ struct CancelGuard<'a> {
1189
+ app: &'a App,
1190
+ run_id: Option<String>,
1191
+ }
1192
+
1193
+ impl Drop for CancelGuard<'_> {
1194
+ fn drop(&mut self) {
1195
+ if let Some(run_id) = self.run_id.take() {
1196
+ tracing::info!(run_id = %run_id, "agent run cancelled before it finished (timeout or client gone)");
1197
+ self.app.recorder().run_cancelled(&run_id);
1198
+ }
1199
+ }
1200
+ }
1201
+
1172
1202
  /// Hand a finished run to the live status view.
1173
1203
  fn record_finished(app: &App, r: &RunResult, cost_usd: Option<f64>) {
1174
1204
  let status = serde_json::to_value(r.status).ok();
@@ -333,7 +333,7 @@ impl App {
333
333
  /// same scopes as the route it is mounted on.
334
334
  pub fn authorize(&self, method: &str, path: &str, principal: &Principal) -> Result<&Route, WebCortexResponse> {
335
335
  let matched = self.router.find(method, path).map_err(|e| match e {
336
- MatchError::NotFound => WebCortexResponse::coded(404, "WC201", format!("no route for {method} {path}")),
336
+ MatchError::NotFound => self.no_route(method, path),
337
337
  MatchError::MethodNotAllowed => WebCortexResponse::coded(405, "WC202", format!("{method} not allowed on {path}")),
338
338
  })?;
339
339
  let route = self
@@ -446,12 +446,47 @@ impl App {
446
446
  all
447
447
  }
448
448
 
449
+ /// The 404 for a path no route matches. Under a device prefix, naming a
450
+ /// device that was never declared, it is WC501 "unknown device" rather
451
+ /// than WC201, whose hint sends the reader looking for a route.
452
+ fn no_route(&self, method: &str, path: &str) -> WebCortexResponse {
453
+ if let Some(name) = self.undeclared_device_in(path) {
454
+ return WebCortexResponse::coded(
455
+ 404,
456
+ "WC501",
457
+ format!("no device named {name:?} (no route for {method} {path})"),
458
+ );
459
+ }
460
+ WebCortexResponse::coded(404, "WC201", format!("no route for {method} {path}"))
461
+ }
462
+
463
+ /// The device segment of `path`, when `path` sits under the prefix of a
464
+ /// declared device's routes and names a device that does not exist.
465
+ fn undeclared_device_in<'p>(&self, path: &'p str) -> Option<&'p str> {
466
+ if self.devices().is_empty() {
467
+ return None;
468
+ }
469
+ for route in &self.manifest.routes {
470
+ let Op::Device { device, .. } = &route.op else { continue };
471
+ let Some(at) = route.path.find(&format!("/{device}/")) else { continue };
472
+ let prefix = &route.path[..at];
473
+ if prefix.is_empty() {
474
+ continue;
475
+ }
476
+ let Some(rest) = path.strip_prefix(prefix).and_then(|r| r.strip_prefix('/')) else { continue };
477
+ let Some((name, _)) = rest.split_once('/') else { continue };
478
+ if !name.is_empty() && name.len() <= 64 && self.devices().get(name).is_none() {
479
+ return Some(name);
480
+ }
481
+ return None;
482
+ }
483
+ None
484
+ }
485
+
449
486
  pub async fn dispatch(&self, mut req: WebCortexRequest) -> WebCortexResponse {
450
487
  let matched = match self.router.find(&req.method, &req.path) {
451
488
  Ok(m) => m,
452
- Err(MatchError::NotFound) => {
453
- return WebCortexResponse::coded(404, "WC201", format!("no route for {} {}", req.method, req.path));
454
- }
489
+ Err(MatchError::NotFound) => return self.no_route(&req.method, &req.path),
455
490
  Err(MatchError::MethodNotAllowed) => {
456
491
  let allowed = self.router.allowed_methods(&req.path).join(", ");
457
492
  let mut res = WebCortexResponse::coded(
@@ -36,6 +36,8 @@ pub const MAX_TELEMETRY_BYTES: usize = 64 * 1024;
36
36
  const KEEP_INSIGHTS: usize = 32;
37
37
  /// Events buffered per subscriber before a slow one starts missing them.
38
38
  const CHANNEL_CAPACITY: usize = 64;
39
+ /// Arrival times kept for the frame rate, whatever `keep` is.
40
+ const RATE_WINDOW: usize = 32;
39
41
 
40
42
  pub fn now_ms() -> u64 {
41
43
  std::time::SystemTime::now()
@@ -124,12 +126,18 @@ pub fn sniff(data: &[u8]) -> Option<&'static str> {
124
126
  pub struct Device {
125
127
  pub def: DeviceDef,
126
128
  frames: Mutex<VecDeque<Arc<Frame>>>,
129
+ /// When the newest frames arrived, for `recent_fps`. Separate from the
130
+ /// ring, which may hold a single frame (`keep=1`) and so no interval.
131
+ arrivals: Mutex<VecDeque<u64>>,
127
132
  telemetry: Mutex<Option<(u64, Arc<Value>)>>,
128
133
  insights: Mutex<VecDeque<Value>>,
129
134
  seq: AtomicU64,
130
135
  last_ingest: Mutex<Option<Instant>>,
131
136
  frames_in: AtomicU64,
132
137
  frames_dropped: AtomicU64,
138
+ /// Frames refused as invalid (not an image, empty, over max_frame_bytes,
139
+ /// sent to a sensor). Over a WebSocket these are otherwise invisible.
140
+ frames_rejected: AtomicU64,
133
141
  tx: broadcast::Sender<Event>,
134
142
  }
135
143
 
@@ -139,12 +147,14 @@ impl Device {
139
147
  Self {
140
148
  def,
141
149
  frames: Mutex::new(VecDeque::new()),
150
+ arrivals: Mutex::new(VecDeque::new()),
142
151
  telemetry: Mutex::new(None),
143
152
  insights: Mutex::new(VecDeque::new()),
144
153
  seq: AtomicU64::new(0),
145
154
  last_ingest: Mutex::new(None),
146
155
  frames_in: AtomicU64::new(0),
147
156
  frames_dropped: AtomicU64::new(0),
157
+ frames_rejected: AtomicU64::new(0),
148
158
  tx,
149
159
  }
150
160
  }
@@ -152,6 +162,14 @@ impl Device {
152
162
  /// Accept one encoded frame. The type is sniffed from the bytes; the
153
163
  /// declared content type is only a fallback for the error message.
154
164
  pub fn push_frame(&self, data: Bytes) -> Result<u64, IngestError> {
165
+ let result = self.accept_frame(data);
166
+ if matches!(result, Err(IngestError::Invalid(_))) {
167
+ self.frames_rejected.fetch_add(1, Ordering::Relaxed);
168
+ }
169
+ result
170
+ }
171
+
172
+ fn accept_frame(&self, data: Bytes) -> Result<u64, IngestError> {
155
173
  if self.def.kind == DeviceKind::Sensor {
156
174
  return Err(IngestError::Invalid(format!(
157
175
  "{:?} is a sensor; send telemetry, not frames",
@@ -172,7 +190,9 @@ impl Device {
172
190
  IngestError::Invalid("frame is not a PNG, JPEG, GIF or WebP image".into())
173
191
  })?;
174
192
  {
175
- let interval = Duration::from_secs_f64(1.0 / self.def.max_fps);
193
+ // try_: a vanishingly small max_fps overflows a Duration, and the
194
+ // panic took the request (or the device's socket) down with it.
195
+ let interval = Duration::try_from_secs_f64(1.0 / self.def.max_fps).unwrap_or(Duration::MAX);
176
196
  let mut last = self.last_ingest.lock().unwrap_or_else(|p| p.into_inner());
177
197
  if last.is_some_and(|t| t.elapsed() < interval) {
178
198
  self.frames_dropped.fetch_add(1, Ordering::Relaxed);
@@ -186,6 +206,13 @@ impl Device {
186
206
  fn store(&self, media_type: &'static str, data: Bytes) -> u64 {
187
207
  let seq = self.seq.fetch_add(1, Ordering::SeqCst) + 1;
188
208
  let frame = Arc::new(Frame { seq, media_type, data, at_ms: now_ms() });
209
+ {
210
+ let mut arrivals = self.arrivals.lock().unwrap_or_else(|p| p.into_inner());
211
+ arrivals.push_back(frame.at_ms);
212
+ while arrivals.len() > RATE_WINDOW {
213
+ arrivals.pop_front();
214
+ }
215
+ }
189
216
  {
190
217
  let mut frames = self.frames.lock().unwrap_or_else(|p| p.into_inner());
191
218
  frames.push_back(frame.clone());
@@ -240,15 +267,15 @@ impl Device {
240
267
  self.tx.subscribe()
241
268
  }
242
269
 
243
- /// Frames per second over the frames still held in the ring, or 0 when
244
- /// fewer than two are held or the newest is over ten seconds old.
270
+ /// Frames per second over the last few arrivals, or 0 when fewer than two
271
+ /// have arrived or the newest is over ten seconds old.
245
272
  pub fn recent_fps(&self) -> f64 {
246
- let frames = self.frames.lock().unwrap_or_else(|p| p.into_inner());
247
- let (Some(first), Some(last)) = (frames.front(), frames.back()) else { return 0.0 };
248
- if frames.len() < 2 || now_ms().saturating_sub(last.at_ms) > 10_000 || last.at_ms <= first.at_ms {
273
+ let arrivals = self.arrivals.lock().unwrap_or_else(|p| p.into_inner());
274
+ let (Some(&first), Some(&last)) = (arrivals.front(), arrivals.back()) else { return 0.0 };
275
+ if arrivals.len() < 2 || now_ms().saturating_sub(last) > 10_000 || last <= first {
249
276
  return 0.0;
250
277
  }
251
- let fps = (frames.len() - 1) as f64 * 1000.0 / (last.at_ms - first.at_ms) as f64;
278
+ let fps = (arrivals.len() - 1) as f64 * 1000.0 / (last - first) as f64;
252
279
  (fps * 100.0).round() / 100.0
253
280
  }
254
281
 
@@ -262,6 +289,7 @@ impl Device {
262
289
  "telemetry_at_ms": self.telemetry().map(|(at, _)| at),
263
290
  "frames_in": self.frames_in.load(Ordering::Relaxed),
264
291
  "frames_dropped": self.frames_dropped.load(Ordering::Relaxed),
292
+ "frames_rejected": self.frames_rejected.load(Ordering::Relaxed),
265
293
  "subscribers": self.tx.receiver_count(),
266
294
  "insights": self.insights.lock().unwrap_or_else(|p| p.into_inner()).len(),
267
295
  "max_fps": self.def.max_fps,
@@ -314,6 +342,7 @@ impl DeviceHub {
314
342
  "max_fps": d.def.max_fps,
315
343
  "frames_in": d.frames_in.load(Ordering::Relaxed),
316
344
  "frames_dropped": d.frames_dropped.load(Ordering::Relaxed),
345
+ "frames_rejected": d.frames_rejected.load(Ordering::Relaxed),
317
346
  "last_frame_age_ms": latest.map(|f| now.saturating_sub(f.at_ms)),
318
347
  "last_telemetry_age_ms": d.telemetry().map(|(at, _)| now.saturating_sub(at)),
319
348
  "subscribers": d.tx.receiver_count(),
@@ -723,6 +752,34 @@ mod tests {
723
752
  assert!(d.push_telemetry(big).is_err());
724
753
  }
725
754
 
755
+ #[test]
756
+ fn the_frame_rate_is_measured_even_when_only_one_frame_is_kept() {
757
+ // 2.5.1 measured fps over the ring, so a keep=1 camera always read 0.
758
+ let d = Device::new(def(1000.0, 1));
759
+ for _ in 0..5 {
760
+ d.push_frame(Bytes::from_static(PNG)).unwrap();
761
+ std::thread::sleep(Duration::from_millis(20));
762
+ }
763
+ let fps = d.recent_fps();
764
+ assert!(fps > 10.0 && fps < 60.0, "fps {fps}");
765
+ }
766
+
767
+ #[test]
768
+ fn a_tiny_max_fps_drops_frames_instead_of_panicking() {
769
+ let d = Device::new(def(1e-300, 2));
770
+ d.push_frame(Bytes::from_static(PNG)).unwrap();
771
+ assert_eq!(d.push_frame(Bytes::from_static(PNG)), Err(IngestError::TooFast));
772
+ }
773
+
774
+ #[test]
775
+ fn rejected_frames_are_counted() {
776
+ let d = Device::new(def(1000.0, 2));
777
+ assert!(d.push_frame(Bytes::from_static(b"nope")).is_err());
778
+ assert!(d.push_frame(Bytes::new()).is_err());
779
+ assert_eq!(d.describe()["frames_rejected"], 2);
780
+ assert_eq!(d.describe()["frames_in"], 0);
781
+ }
782
+
726
783
  #[test]
727
784
  fn a_sensor_takes_telemetry_not_frames() {
728
785
  let mut s = def(10.0, 4);
@@ -108,6 +108,8 @@ pub static CATALOGUE: &[ErrorInfo] = &[
108
108
  "The request conflicts with the current state of the resource; re-read it and retry."),
109
109
  e!("WC215", "http", Some(503), "Unavailable",
110
110
  "A subsystem this route needs is not running in this process (for example the agent runtime). Check the server log at boot."),
111
+ e!("WC216", "http", Some(408), "Request body too slow",
112
+ "The client announced a body but did not finish sending it within request_timeout (agent_timeout on agent, behaviour and flow routes). Send the whole body promptly, or raise the limit on WebCortex(...)."),
111
113
 
112
114
  // ---- WC3xx agents and providers -------------------------------------
113
115
  e!("WC300", "agent", Some(502), "Agent run failed",
@@ -167,7 +169,7 @@ pub static CATALOGUE: &[ErrorInfo] = &[
167
169
  e!("WC504", "devices", Some(429), "Frame faster than max_fps",
168
170
  "The device is sending faster than its max_fps; the frame was dropped. Slow the sender or raise max_fps."),
169
171
  e!("WC505", "devices", Some(422), "Invalid frame or telemetry",
170
- "The frame is not a PNG/JPEG/GIF/WebP, is over max_frame_bytes, or the telemetry is not a JSON body."),
172
+ "The frame is not a PNG/JPEG/GIF/WebP, is over max_frame_bytes, or the telemetry is not a JSON body (a body that is not JSON at all is answered 400; the rest 422)."),
171
173
  e!("WC506", "devices", Some(502), "Camera unreachable",
172
174
  "A pulled IP camera did not answer with a snapshot. Check its URL, its bearer_env, and that it is reachable from the server."),
173
175
 
@@ -208,6 +210,7 @@ pub fn code_for_status(status: u16) -> &'static str {
208
210
  403 => "WC602",
209
211
  404 => "WC207",
210
212
  405 => "WC202",
213
+ 408 => "WC216",
211
214
  409 => "WC214",
212
215
  413 => "WC204",
213
216
  422 => "WC206",
@@ -47,13 +47,31 @@ pub fn init_tracing(default_level: &str) {
47
47
  let filter = EnvFilter::try_from_env("WEBCORTEX_LOG")
48
48
  .unwrap_or_else(|_| EnvFilter::new(default_level));
49
49
  // Colour only on a terminal: redirected to a file or a platform's log
50
- // collector, escape codes are noise around every field. NO_COLOR is honoured.
51
- let ansi = std::io::IsTerminal::is_terminal(&std::io::stdout()) && std::env::var_os("NO_COLOR").is_none();
50
+ // collector, escape codes are noise around every field. NO_COLOR is honoured
51
+ // when set to anything but the empty string, as no-color.org specifies.
52
+ let ansi = use_colour(
53
+ std::io::IsTerminal::is_terminal(&std::io::stdout()),
54
+ std::env::var_os("NO_COLOR").as_deref(),
55
+ );
52
56
  let _ = fmt().with_env_filter(filter).with_target(false).with_ansi(ansi).try_init();
53
57
  }
54
58
 
59
+ fn use_colour(terminal: bool, no_color: Option<&std::ffi::OsStr>) -> bool {
60
+ terminal && no_color.is_none_or(|v| v.is_empty())
61
+ }
62
+
55
63
  #[cfg(test)]
56
64
  mod tests {
65
+ #[test]
66
+ fn colour_only_on_a_terminal_without_no_color() {
67
+ use std::ffi::OsStr;
68
+ assert!(super::use_colour(true, None));
69
+ assert!(!super::use_colour(false, None));
70
+ assert!(!super::use_colour(true, Some(OsStr::new("1"))));
71
+ // no-color.org: an empty NO_COLOR does not disable colour.
72
+ assert!(super::use_colour(true, Some(OsStr::new(""))));
73
+ }
74
+
57
75
  use super::*;
58
76
  use manifest::derive_tool_name;
59
77
 
@@ -23,7 +23,7 @@ use std::panic::AssertUnwindSafe;
23
23
  use hyper::body::Incoming;
24
24
  use hyper::service::service_fn;
25
25
  use hyper::{Request, Response};
26
- use hyper_util::rt::{TokioExecutor, TokioIo};
26
+ use hyper_util::rt::{TokioExecutor, TokioIo, TokioTimer};
27
27
  use hyper_util::server::conn::auto;
28
28
  use std::convert::Infallible;
29
29
  use std::net::SocketAddr;
@@ -39,6 +39,17 @@ const MAX_BODY_BYTES: usize = 32 * 1024 * 1024;
39
39
  /// connection is cut off, as before.
40
40
  const DRAIN_BYTES: usize = 8 * 1024 * 1024;
41
41
  const DRAIN_TIME: std::time::Duration = std::time::Duration::from_secs(2);
42
+ /// The longest a connection may take to send a request's headers, and the
43
+ /// longest an idle keep-alive connection is held open waiting for the next
44
+ /// one. Without it a client that opens connections and sends nothing (or a
45
+ /// header a byte at a time) holds a socket each, indefinitely.
46
+ const MAX_HEADER_READ_SECS: u64 = 30;
47
+
48
+ /// The header read timeout for this app: its request timeout, at most
49
+ /// [`MAX_HEADER_READ_SECS`], at least one second.
50
+ fn header_read_timeout(request_timeout_secs: u64) -> std::time::Duration {
51
+ std::time::Duration::from_secs(request_timeout_secs.clamp(1, MAX_HEADER_READ_SECS))
52
+ }
42
53
 
43
54
  pub async fn serve(app: Arc<App>) -> Result<(), String> {
44
55
  serve_with_shutdown(app, shutdown_signal()).await
@@ -100,19 +111,29 @@ where
100
111
  }
101
112
  };
102
113
  let app = app.clone();
114
+ let header_timeout = header_read_timeout(app.manifest.server.request_timeout_secs);
103
115
  let permit = tracker.clone().acquire_owned().await.ok();
104
116
  tokio::spawn(async move {
105
117
  let _permit = permit;
118
+ // hyper's header timeout starts once it reads; the auto
119
+ // builder's protocol sniff before that waits forever, so
120
+ // a client that connects and sends nothing is dropped here.
121
+ if tokio::time::timeout(header_timeout, stream.readable()).await.is_err() {
122
+ tracing::debug!(%peer, "connection sent nothing; closed");
123
+ return;
124
+ }
106
125
  let io = TokioIo::new(stream);
107
126
  let svc = service_fn(move |req| {
108
127
  let app = app.clone();
109
128
  let client_ip = peer.ip().to_string();
110
129
  async move { Ok::<_, Infallible>(handle(app, req, client_ip).await) }
111
130
  });
112
- if let Err(e) = auto::Builder::new(TokioExecutor::new())
113
- .serve_connection_with_upgrades(io, svc)
114
- .await
115
- {
131
+ let mut builder = auto::Builder::new(TokioExecutor::new());
132
+ // hyper applies a header read timeout only when it has a
133
+ // timer; without one, slow or silent clients were held forever.
134
+ builder.http1().timer(TokioTimer::new()).header_read_timeout(header_timeout);
135
+ builder.http2().timer(TokioTimer::new());
136
+ if let Err(e) = builder.serve_connection_with_upgrades(io, svc).await {
116
137
  tracing::debug!(%peer, error = %e, "connection closed");
117
138
  }
118
139
  });
@@ -362,9 +383,28 @@ async fn route_request(
362
383
  return (res, principal_id);
363
384
  }
364
385
 
365
- let body = match read_body(req).await {
366
- Ok(b) => b,
367
- Err(mut res) => {
386
+ // A model loop routinely outlasts an ordinary handler's ceiling, and a
387
+ // timeout drops the run mid-flight.
388
+ let limits = &app.manifest.server;
389
+ let secs = if app.runs_a_model_loop(&method, &path) {
390
+ limits.agent_timeout_secs.max(limits.request_timeout_secs)
391
+ } else {
392
+ limits.request_timeout_secs
393
+ };
394
+
395
+ // The body is read under the same limit: a client that announces a body
396
+ // and then sends it a byte at a time must not hold the request open.
397
+ let body_timeout = std::time::Duration::from_secs(secs.max(1));
398
+ let body = match tokio::time::timeout(body_timeout, read_body(req)).await {
399
+ Ok(Ok(b)) => b,
400
+ Ok(Err(mut res)) => {
401
+ finish_cors(app, &mut res, origin.as_deref());
402
+ return (res, principal_id);
403
+ }
404
+ Err(_) => {
405
+ let mut res =
406
+ WebCortexResponse::coded(408, "WC216", "the request body did not arrive within the request timeout");
407
+ res.headers.push(("connection".into(), "close".into()));
368
408
  finish_cors(app, &mut res, origin.as_deref());
369
409
  return (res, principal_id);
370
410
  }
@@ -374,14 +414,6 @@ async fn route_request(
374
414
  let mut res = if let Some(rest) = path.strip_prefix(&prefix) {
375
415
  control_plane(app, &method, rest, &body, &principal, request_id).await
376
416
  } else {
377
- // A model loop routinely outlasts an ordinary handler's ceiling, and a
378
- // timeout drops the run mid-flight.
379
- let limits = &app.manifest.server;
380
- let secs = if app.runs_a_model_loop(&method, &path) {
381
- limits.agent_timeout_secs.max(limits.request_timeout_secs)
382
- } else {
383
- limits.request_timeout_secs
384
- };
385
417
  let timeout = std::time::Duration::from_secs(secs);
386
418
  let dispatch = app.dispatch(WebCortexRequest {
387
419
  method,
@@ -435,7 +467,11 @@ async fn read_body(req: Request<Incoming>) -> Result<Bytes, WebCortexResponse> {
435
467
  let mut body = req.into_body();
436
468
  let mut buf = bytes::BytesMut::new();
437
469
  while let Some(frame) = body.frame().await {
438
- let Ok(frame) = frame else { return Err(too_large()) };
470
+ // A body that fails to decode (a malformed chunk size, a connection
471
+ // cut mid-body) is a bad request, not an oversized one.
472
+ let Ok(frame) = frame else {
473
+ return Err(WebCortexResponse::coded(400, "WC205", "malformed or incomplete request body"));
474
+ };
439
475
  let Ok(data) = frame.into_data() else { continue };
440
476
  if buf.len() + data.len() > MAX_BODY_BYTES {
441
477
  let _ = tokio::time::timeout(DRAIN_TIME, async {
@@ -63,7 +63,7 @@ impl Histogram {
63
63
  }
64
64
  // A bucket's upper bound can lie above every sample in it; the true
65
65
  // maximum is known exactly, and no percentile can exceed it.
66
- round3(upper.min(max_us.max(1)) as f64 / 1000.0)
66
+ round3(upper.min(max_us) as f64 / 1000.0)
67
67
  }
68
68
 
69
69
  /// p50/p95/p99, none of them above `max_us`, the largest sample recorded.
@@ -182,6 +182,8 @@ pub enum Target {
182
182
  }
183
183
 
184
184
  struct LiveRun {
185
+ /// The agent the run started as; `agent` follows handoffs.
186
+ entry: String,
185
187
  agent: String,
186
188
  caller: String,
187
189
  depth: u32,
@@ -200,6 +202,9 @@ struct AgentTally {
200
202
  step_limit: u64,
201
203
  max_tokens: u64,
202
204
  awaiting_approval: u64,
205
+ /// Runs abandoned before they finished: the request timed out, or the
206
+ /// client went away and the run was dropped with it.
207
+ cancelled: u64,
203
208
  tokens: u64,
204
209
  largest_run_tokens: u64,
205
210
  }
@@ -349,6 +354,7 @@ impl Recorder {
349
354
  book.in_flight.insert(
350
355
  run_id.to_string(),
351
356
  LiveRun {
357
+ entry: agent.to_string(),
352
358
  agent: agent.to_string(),
353
359
  caller: caller.to_string(),
354
360
  depth,
@@ -413,6 +419,38 @@ impl Recorder {
413
419
  }
414
420
  }
415
421
 
422
+ /// A run that was dropped before it finished: its request timed out or its
423
+ /// client disconnected, and the future driving it went with them. Without
424
+ /// this it stayed "in flight" for the life of the process.
425
+ pub fn run_cancelled(&self, run_id: &str) {
426
+ let mut book = self.runs.lock().unwrap_or_else(|p| p.into_inner());
427
+ let Some(live) = book.in_flight.remove(run_id) else { return };
428
+ let tally = book.by_agent.entry(live.entry.clone()).or_default();
429
+ tally.runs += 1;
430
+ tally.cancelled += 1;
431
+ tally.tokens = tally.tokens.saturating_add(live.tokens);
432
+ tally.largest_run_tokens = tally.largest_run_tokens.max(live.tokens);
433
+ if book.recent.len() >= RECENT_RUNS {
434
+ book.recent.pop_front();
435
+ }
436
+ book.recent.push_back(json!({
437
+ "run_id": run_id,
438
+ "agent": live.agent,
439
+ "path": [live.entry],
440
+ "caller": live.caller,
441
+ "depth": live.depth,
442
+ "outcome": "cancelled",
443
+ "code": null,
444
+ "steps": live.steps,
445
+ "tool_calls": null,
446
+ "tokens": live.tokens,
447
+ "tree_tokens": null,
448
+ "cost_usd": null,
449
+ "duration_ms": live.started.elapsed().as_millis() as u64,
450
+ "finished_at_ms": unix_ms(),
451
+ }));
452
+ }
453
+
416
454
  pub fn watcher_run(&self, name: &str, status: &str, code: Option<&str>) {
417
455
  let mut w = self.watchers.lock().unwrap_or_else(|p| p.into_inner());
418
456
  let t = w.entry(name.to_string()).or_default();
@@ -672,6 +710,43 @@ mod tests {
672
710
  assert!(s["p99_ms"].as_f64().unwrap() >= 0.1);
673
711
  }
674
712
 
713
+ #[test]
714
+ fn a_cancelled_run_leaves_in_flight_and_is_counted() {
715
+ let r = Recorder::new(&manifest());
716
+ r.run_started("run1", "desk", "alice", 0);
717
+ r.run_progress("run1", "billing", 3, 120);
718
+ r.run_cancelled("run1");
719
+ r.run_cancelled("run1"); // a second drop is a no-op
720
+ let (runs, tally) = r.runs();
721
+ assert!(runs["in_flight"].as_array().unwrap().is_empty());
722
+ assert_eq!(runs["recent"][0]["outcome"], "cancelled");
723
+ assert_eq!(runs["recent"][0]["agent"], "billing");
724
+ assert_eq!(runs["recent"][0]["tokens"], 120);
725
+ assert_eq!(tally["desk"].cancelled, 1);
726
+ assert_eq!(tally["desk"].runs, 1);
727
+ // A run that finished normally is not touched by a late cancel.
728
+ r.run_started("run2", "desk", "alice", 0);
729
+ r.run_finished(RunSummary {
730
+ run_id: "run2", agent: "desk", path: &["desk".to_string()], status: "completed",
731
+ steps: 1, tool_calls: 0, tokens: 5, tree_tokens: 5, cost_usd: None, code: None,
732
+ });
733
+ r.run_cancelled("run2");
734
+ let (_, tally) = r.runs();
735
+ assert_eq!(tally["desk"].cancelled, 1);
736
+ assert_eq!(tally["desk"].completed, 1);
737
+ }
738
+
739
+ #[test]
740
+ fn a_percentile_of_zero_latency_samples_is_zero() {
741
+ // The cap used max(1) µs, so all-zero samples reported p50 0.001 ms
742
+ // against a max of 0.0.
743
+ let slot = Slot::new("GET /".into());
744
+ slot.record(200, 0);
745
+ let v = slot.describe().unwrap();
746
+ assert_eq!(v["max_ms"], 0.0);
747
+ assert_eq!(v["p50_ms"], 0.0);
748
+ }
749
+
675
750
  #[test]
676
751
  fn no_percentile_exceeds_the_maximum() {
677
752
  // 2.5.0 printed "p95 0.256ms max 0.162ms": the bucket's upper bound
@@ -32,7 +32,8 @@ use tokio::sync::broadcast::error::RecvError;
32
32
  use tokio_tungstenite::WebSocketStream;
33
33
  use tokio_tungstenite::tungstenite::Message;
34
34
  use tokio_tungstenite::tungstenite::handshake::derive_accept_key;
35
- use tokio_tungstenite::tungstenite::protocol::{Role, WebSocketConfig};
35
+ use tokio_tungstenite::tungstenite::protocol::frame::coding::CloseCode;
36
+ use tokio_tungstenite::tungstenite::protocol::{CloseFrame, Role, WebSocketConfig};
36
37
 
37
38
  type Socket = WebSocketStream<TokioIo<hyper::upgrade::Upgraded>>;
38
39
 
@@ -165,7 +166,25 @@ async fn ingest(app: Arc<App>, name: String, principal: Principal, mut ws: Socke
165
166
  Ok(v) => device.push_telemetry(v).err().map(|e| error(e.code(), e.message())),
166
167
  Err(e) => Some(error("WC505", format!("telemetry must be JSON: {e}"))),
167
168
  },
168
- Ok(Message::Close(_)) | Err(_) => break,
169
+ Ok(Message::Close(_)) => break,
170
+ Err(tokio_tungstenite::tungstenite::Error::Capacity(e)) => {
171
+ // A frame over the socket's ceiling: say why before closing,
172
+ // in the log and (if the device still reads) a 1009 close,
173
+ // rather than a bare reset nobody can explain.
174
+ tracing::warn!(device = %name, error = %e, max_frame_bytes = device.def.max_frame_bytes,
175
+ "device socket closed: message too large");
176
+ let _ = ws
177
+ .send(Message::Close(Some(CloseFrame {
178
+ code: CloseCode::Size,
179
+ reason: "[WC505] message over max_frame_bytes".into(),
180
+ })))
181
+ .await;
182
+ break;
183
+ }
184
+ Err(e) => {
185
+ tracing::debug!(device = %name, error = %e, "device socket error");
186
+ break;
187
+ }
169
188
  Ok(_) => None,
170
189
  };
171
190
  if let Some(reply) = reply
@@ -7,7 +7,7 @@ build-backend = "maturin"
7
7
  # The split is for ergonomics, the same way djangorestframework imports as
8
8
  # `rest_framework`.
9
9
  name = "web-cortex-framework"
10
- version = "2.5.1"
10
+ version = "2.5.2"
11
11
  description = "A Rust-cored Python web framework where every route is also an agent tool."
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.12"
@@ -25,7 +25,7 @@ def doctor(app: "WebCortex", *, online: bool = False, url: str | None = None,
25
25
  return app.doctor(online=online, url=url, key=key)
26
26
 
27
27
 
28
- __version__ = "2.5.1"
28
+ __version__ = "2.5.2"
29
29
 
30
30
  __all__ = [
31
31
  "WebCortex",
@@ -45,7 +45,17 @@ OP_CONT, OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG = 0x0, 0x1, 0x2, 0x8, 0x
45
45
 
46
46
 
47
47
  class WebSocketError(ConnectionError):
48
- pass
48
+ """A refused upgrade, a closed socket, or an error message from the server.
49
+
50
+ For a server error message, ``code`` and ``hint`` carry the catalogued
51
+ code (``WC306``, ``WC203``, …) and what to do about it; both are ``None``
52
+ otherwise.
53
+ """
54
+
55
+ def __init__(self, message: str, *, code: str | None = None, hint: str | None = None) -> None:
56
+ super().__init__(message)
57
+ self.code = code
58
+ self.hint = hint
49
59
 
50
60
 
51
61
  class WebSocket:
@@ -295,7 +305,9 @@ class AgentSocket:
295
305
  elif kind == "result":
296
306
  return event["result"]
297
307
  elif kind == "error":
298
- raise WebSocketError(event.get("message", "agent error"))
308
+ code = event.get("code")
309
+ message = event.get("message", "agent error")
310
+ raise WebSocketError(f"[{code}] {message}" if code else message, code=code, hint=event.get("hint"))
299
311
 
300
312
  def close(self) -> None:
301
313
  self.ws.close()
@@ -427,7 +427,8 @@ def render_status(s: dict) -> str:
427
427
  devices = s.get("devices", {})
428
428
  for d in devices.get("devices", []):
429
429
  out.append(f" device {d['name']}: {'connected' if d['connected'] else 'idle'}, {d['fps']} fps, "
430
- f"{d['frames_in']} in, {d['frames_dropped']} dropped, {d['subscribers']} subscriber(s)")
430
+ f"{d['frames_in']} in, {d['frames_dropped']} dropped, {d.get('frames_rejected', 0)} rejected, "
431
+ f"{d['subscribers']} subscriber(s)")
431
432
  for w in devices.get("watchers", []):
432
433
  st = w["stats"]
433
434
  out.append(f" watcher {w['name']}: {st.get('runs', 0)} runs, {st.get('failed', 0)} failed"
@@ -24,7 +24,7 @@ CODE_RE = re.compile(r"\bWC\d{3}\b")
24
24
  DOCS_URL = "https://slimboi34.github.io/web_cortex_framework/error-codes/"
25
25
 
26
26
  _STATUS_DEFAULTS = {
27
- 400: "WC205", 401: "WC601", 403: "WC602", 404: "WC207", 405: "WC202", 409: "WC214",
27
+ 400: "WC205", 401: "WC601", 403: "WC602", 404: "WC207", 405: "WC202", 408: "WC216", 409: "WC214",
28
28
  413: "WC204", 422: "WC206", 423: "WC502", 426: "WC213", 429: "WC401", 500: "WC001",
29
29
  502: "WC300", 503: "WC215", 504: "WC203", 508: "WC403",
30
30
  }