Skip to main content

allot_shared/
api.rs

1use serde::{Deserialize, Serialize};
2
3use crate::{
4    types::{
5        EndCause, Holder, JobClass, JobProfile, JobRun, Lease, LeaseKind, LeaseState, NoiseReport,
6        SessionKey, SessionUsage,
7    },
8    ui::Notice,
9};
10
11/// Response of `GET /health`.
12#[cfg_attr(any(feature = "schema", test), derive(schemars::JsonSchema))]
13#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
14pub struct HealthResponse {
15    /// Daemon version, from its `Cargo.toml`.
16    pub version: String,
17    /// Daemon process ID.
18    pub pid: u32,
19    /// Seconds since the daemon started.
20    pub uptime_secs: u64,
21    /// Why the last change to `config.toml` was rejected; the daemon keeps the config it had
22    /// until the file is fixed.
23    #[serde(default, skip_serializing_if = "Option::is_none")]
24    pub config_error: Option<String>,
25}
26
27/// How a request states the resources a job needs.
28#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
29#[serde(rename_all = "snake_case")]
30#[non_exhaustive]
31pub enum ProfileSpec {
32    /// A named class, resolved through the daemon's config.
33    Class(JobClass),
34    /// A named preset from the daemon's config, for example `cpu_small`. The lease records it
35    /// as a custom profile with no class.
36    Preset(String),
37    /// Explicit values.
38    Custom(JobProfile),
39}
40
41/// Body of `POST /can-fit`.
42#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
43pub struct CanFitRequest {
44    /// Resources the job needs.
45    pub profile: ProfileSpec,
46    /// How the job would share the machine.
47    pub kind: LeaseKind,
48    /// The fewest cores the job can start with. Without it the class or preset's minimum
49    /// applies, and a custom profile keeps all its cores.
50    #[serde(default, skip_serializing_if = "Option::is_none")]
51    pub min_cores: Option<f32>,
52    /// The command, so the daemon can raise the profile from similar past runs.
53    #[serde(default, skip_serializing_if = "Option::is_none")]
54    pub label: Option<String>,
55    /// Working directory of the command; part of what makes runs similar.
56    #[serde(default, skip_serializing_if = "Option::is_none")]
57    pub cwd: Option<String>,
58}
59
60/// The reason a verdict gives when ending every lease would still leave too little room, so
61/// only something outside Allot can make the request fit, if anything can.
62pub const REASON_BEYOND_LEASES: &str = "more than the machine can free";
63
64/// The admission engine's answer. Response of `POST /can-fit`.
65#[cfg_attr(any(feature = "schema", test), derive(schemars::JsonSchema))]
66#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
67pub struct Verdict {
68    /// Whether the job could start now.
69    pub fits: bool,
70    /// Human-readable explanations, one per limiting or notable factor.
71    pub reasons: Vec<String>,
72    /// Expected wait before the job fits, when the daemon can estimate it.
73    pub wait_estimate_secs: Option<u64>,
74    /// Where a benchmark at the head of the queue stands; `None` for other requests.
75    #[serde(default, skip_serializing_if = "Option::is_none")]
76    pub benchmark: Option<BenchmarkProgress>,
77}
78
79/// Where a waiting benchmark lease stands, so its holder can report progress.
80#[cfg_attr(any(feature = "schema", test), derive(schemars::JsonSchema))]
81#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
82#[serde(tag = "phase", rename_all = "snake_case")]
83#[non_exhaustive]
84pub enum BenchmarkProgress {
85    /// Other leases are still active; nothing new starts until they end.
86    Draining {
87        /// Active leases left.
88        active_leases: u32,
89    },
90    /// The machine has drained and its background load is being averaged.
91    Measuring {
92        /// Seconds averaged so far.
93        measured_secs: u64,
94        /// Seconds the average must cover.
95        needed_secs: u64,
96        /// Average total CPU load so far, in percent.
97        cpu_avg_pct: f32,
98        /// Average load of the busiest GPU engine so far, in percent.
99        gpu_avg_pct: f32,
100    },
101    /// The average is above the quiet limits. The lease is granted anyway, marked as not
102    /// quiet, once `grant_anyway_in_secs` have passed.
103    Noisy {
104        /// Average total CPU load over the quiet window, in percent.
105        cpu_avg_pct: f32,
106        /// Average load of the busiest GPU engine over the quiet window, in percent.
107        gpu_avg_pct: f32,
108        /// CPU limit of a quiet machine.
109        cpu_limit_pct: f32,
110        /// GPU limit of a quiet machine.
111        gpu_limit_pct: f32,
112        /// Seconds until the lease is granted without quiet.
113        grant_anyway_in_secs: u64,
114    },
115}
116
117/// Body of `POST /leases`.
118#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
119pub struct AcquireRequest {
120    /// Session asking for the lease.
121    pub holder: Holder,
122    /// Resources to reserve.
123    pub profile: ProfileSpec,
124    /// The fewest cores the job can start with. Without it the class or preset's minimum
125    /// applies, and a custom profile keeps all its cores.
126    #[serde(default, skip_serializing_if = "Option::is_none")]
127    pub min_cores: Option<f32>,
128    /// How the lease shares the machine.
129    pub kind: LeaseKind,
130    /// What the lease is for, usually the command that will run.
131    pub label: String,
132    /// Working directory of the command; part of what makes runs similar.
133    #[serde(default, skip_serializing_if = "Option::is_none")]
134    pub cwd: Option<String>,
135    /// How long the daemon may hold the request open waiting for the lease to become active.
136    pub wait_timeout_secs: u64,
137}
138
139/// Response of `POST /leases`.
140#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
141pub struct AcquireResponse {
142    /// The lease, `Active` if it was granted within the wait timeout and `Queued` otherwise.
143    pub lease: Lease,
144    /// Why the lease was granted or is still waiting.
145    pub verdict: Verdict,
146}
147
148/// Body of `POST /leases/{id}/wait`: keep waiting for a queued lease without losing its place.
149#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
150pub struct WaitRequest {
151    /// How long the daemon may hold the request open waiting for the lease to become active.
152    pub wait_timeout_secs: u64,
153}
154
155/// Query string of `POST /leases/{id}/heartbeat`, `POST /leases/{id}/wait`,
156/// `POST /leases/{id}/bind`, `DELETE /leases/{id}`, `GET /notices`, and
157/// `POST /notices/{id}/delivered`.
158///
159/// The daemon refuses a lease or notice call when the lease belongs to another session.
160#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
161pub struct LeaseOwner {
162    /// Session that claims to own the lease.
163    pub session: SessionKey,
164}
165
166/// Response of `POST /leases/{id}/heartbeat`.
167#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
168pub struct HeartbeatResponse {
169    /// Current state, so a holder of a queued lease learns when it becomes active.
170    pub state: LeaseState,
171    /// New expiry, in milliseconds since the Unix epoch.
172    pub expires_at_ms: i64,
173    /// Why the lease ended, once it has; for example [`EndCause::Killed`] when the user
174    /// stopped its job.
175    #[serde(default, skip_serializing_if = "Option::is_none")]
176    pub end_cause: Option<EndCause>,
177}
178
179/// Response of `DELETE /leases/{id}`.
180#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
181pub struct ReleaseResponse {
182    /// The lease in its final state.
183    pub lease: Lease,
184    /// Background load while a benchmark lease was active. Only the release that ends the
185    /// lease carries it, and only when at least one sample was taken during the lease.
186    #[serde(default, skip_serializing_if = "Option::is_none")]
187    pub noise: Option<NoiseReport>,
188}
189
190/// Response of `POST /leases/{id}/kill`.
191#[cfg_attr(any(feature = "schema", test), derive(schemars::JsonSchema))]
192#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
193pub struct KillResponse {
194    /// The lease, ended with cause `killed`.
195    pub lease: Lease,
196    /// Processes terminated, root first.
197    pub terminated: Vec<KilledProcess>,
198    /// Processes that could not be terminated, with what the OS said.
199    pub failed: Vec<UnkilledProcess>,
200    /// Processes in the tree left running on purpose, each with everything below it.
201    pub spared: Vec<UnkilledProcess>,
202    /// Why no process was terminated: the lease had no bound process tree, or its command had
203    /// already ended. The lease ended anyway. `None` when the bound tree was killed.
204    pub untouched_reason: Option<String>,
205}
206
207/// A process a kill terminated.
208#[cfg_attr(any(feature = "schema", test), derive(schemars::JsonSchema))]
209#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
210pub struct KilledProcess {
211    /// Process ID.
212    pub pid: u32,
213    /// Executable name, for example `cargo.exe`.
214    pub name: String,
215}
216
217/// A process in a killed tree that is still running.
218#[cfg_attr(any(feature = "schema", test), derive(schemars::JsonSchema))]
219#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
220pub struct UnkilledProcess {
221    /// Process ID.
222    pub pid: u32,
223    /// Executable name, for example `claude.exe`.
224    pub name: String,
225    /// Why it is still running.
226    pub reason: String,
227}
228
229/// Response of `POST /leases/{id}/remove`.
230#[cfg_attr(any(feature = "schema", test), derive(schemars::JsonSchema))]
231#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
232pub struct RemoveResponse {
233    /// The lease, ended with cause `removed` before it started.
234    pub lease: Lease,
235}
236
237/// Body of `POST /leases/{id}/bind`: the PreToolUse hook let a command run under the lease.
238#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
239pub struct BindRequest {
240    /// Claude Code's ID for the tool call that runs the command.
241    pub tool_use_id: String,
242    /// The command as the hook saw it, for the log.
243    #[serde(default, skip_serializing_if = "Option::is_none")]
244    pub command: Option<String>,
245}
246
247/// Response of `GET /notices`.
248#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
249pub struct NoticesResponse {
250    /// Kills and removals the session has not been told about yet, oldest first.
251    pub notices: Vec<Notice>,
252}
253
254/// Response of `POST /notices/{id}/delivered`.
255#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
256pub struct DeliveredResponse {
257    /// `true` when this call recorded the delivery; `false` when an earlier one already had,
258    /// so the session must not be told again.
259    pub delivered: bool,
260}
261
262/// Query string of `GET /leases`. Each filter is optional; an empty query lists every lease.
263#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
264pub struct LeaseQuery {
265    /// Only leases held by this session.
266    pub session: Option<SessionKey>,
267    /// Only leases in this state.
268    pub state: Option<LeaseState>,
269}
270
271/// Response of `GET /leases`.
272#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
273pub struct LeasesResponse {
274    /// Matching leases, oldest first.
275    pub leases: Vec<Lease>,
276}
277
278/// Response of `GET /sessions`.
279#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
280pub struct SessionsResponse {
281    /// Every registered session with its current usage.
282    pub sessions: Vec<SessionUsage>,
283}
284
285/// Body of `POST /sessions`. Registering the same session again is harmless; the daemon
286/// forgets a session once its holder process is gone.
287#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
288pub struct RegisterSessionRequest {
289    /// The session and its `claude.exe`.
290    pub holder: Holder,
291}
292
293/// Response of `GET /history`.
294#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
295pub struct HistoryResponse {
296    /// One entry per fingerprint, most recently run first.
297    pub jobs: Vec<JobSummary>,
298}
299
300/// What the history knows about one fingerprint.
301#[cfg_attr(any(feature = "schema", test), derive(schemars::JsonSchema))]
302#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
303pub struct JobSummary {
304    /// Normalized command plus working directory.
305    pub fingerprint: String,
306    /// Label of the most recent run.
307    pub command: String,
308    /// Working directory of the most recent run.
309    pub cwd: String,
310    /// Stored runs.
311    pub runs: u32,
312    /// Runs the estimate is based on: the most recent ones without an overlapping lease.
313    pub estimate_runs: u32,
314    /// End of the most recent run, in milliseconds since the Unix epoch.
315    pub last_ended_at_ms: i64,
316    /// What the runs needed: p90 of peak memory, of CPU and GPU load while busy, and of run
317    /// time. `None` when every run overlapped another lease.
318    pub learned: Option<JobProfile>,
319}
320
321/// Query string of `GET /history/runs`.
322#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
323pub struct HistoryRunsQuery {
324    /// Fingerprint whose runs to list.
325    pub fingerprint: String,
326    /// Most runs to return; the daemon's default when absent.
327    pub limit: Option<u32>,
328}
329
330/// Response of `GET /history/runs`.
331#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
332pub struct HistoryRunsResponse {
333    /// Runs with the fingerprint, newest first.
334    pub runs: Vec<JobRun>,
335}
336
337#[cfg(test)]
338mod tests {
339    use super::*;
340    use crate::test_support::{
341        assert_json_round_trip, sample_holder, sample_lease, sample_session_usage,
342    };
343
344    fn sample_verdict() -> Verdict {
345        Verdict {
346            fits: false,
347            reasons: vec!["RAM: 6144 MB requested, 4096 MB free after headroom".into()],
348            wait_estimate_secs: Some(90),
349            benchmark: None,
350        }
351    }
352
353    fn custom_profile() -> ProfileSpec {
354        ProfileSpec::Custom(JobProfile {
355            cores: 3.5,
356            ram_mb: 6144,
357            gpu_pct: 40.0,
358            vram_mb: 2048,
359            est_secs: 120,
360        })
361    }
362
363    #[test]
364    fn test_health_response_json_round_trip_preserves_every_field() {
365        assert_json_round_trip(&HealthResponse {
366            version: "0.1.0".into(),
367            pid: 4242,
368            uptime_secs: 3600,
369            config_error: Some("config.toml: invalid configuration: x".into()),
370        });
371    }
372
373    #[test]
374    fn test_can_fit_request_json_round_trip_preserves_both_profile_forms() {
375        assert_json_round_trip(&CanFitRequest {
376            profile: ProfileSpec::Class(JobClass::GpuHeavy),
377            kind: LeaseKind::Normal,
378            min_cores: None,
379            label: None,
380            cwd: None,
381        });
382        assert_json_round_trip(&CanFitRequest {
383            profile: custom_profile(),
384            kind: LeaseKind::BenchmarkExclusive,
385            min_cores: Some(2.0),
386            label: Some("cargo bench".into()),
387            cwd: Some(r"E:\work\app".into()),
388        });
389    }
390
391    #[test]
392    fn test_can_fit_request_without_label_and_cwd_deserializes_as_none() {
393        let request: CanFitRequest =
394            serde_json::from_str(r#"{"profile":{"class":"light"},"kind":"normal"}"#).unwrap();
395        assert_eq!((request.label, request.cwd), (None, None));
396    }
397
398    #[test]
399    fn test_profile_spec_json_is_externally_tagged() {
400        let class = serde_json::to_value(ProfileSpec::Class(JobClass::CpuHeavy)).unwrap();
401        assert_eq!(class, serde_json::json!({ "class": "cpu_heavy" }));
402        let custom = serde_json::to_value(custom_profile()).unwrap();
403        assert_eq!(custom["custom"]["ram_mb"], 6144);
404    }
405
406    #[test]
407    fn test_verdict_json_round_trip_preserves_every_field() {
408        assert_json_round_trip(&sample_verdict());
409        assert_json_round_trip(&Verdict {
410            fits: true,
411            reasons: vec![],
412            wait_estimate_secs: None,
413            benchmark: None,
414        });
415    }
416
417    #[test]
418    fn test_verdict_benchmark_progress_round_trips_every_phase() {
419        let phases = [
420            BenchmarkProgress::Draining { active_leases: 2 },
421            BenchmarkProgress::Measuring {
422                measured_secs: 4,
423                needed_secs: 10,
424                cpu_avg_pct: 6.5,
425                gpu_avg_pct: 0.0,
426            },
427            BenchmarkProgress::Noisy {
428                cpu_avg_pct: 12.5,
429                gpu_avg_pct: 1.0,
430                cpu_limit_pct: 10.0,
431                gpu_limit_pct: 10.0,
432                grant_anyway_in_secs: 35,
433            },
434        ];
435        for phase in phases {
436            assert_json_round_trip(&Verdict {
437                benchmark: Some(phase),
438                ..sample_verdict()
439            });
440        }
441        let value = serde_json::to_value(phases[0]).unwrap();
442        assert_eq!(
443            value,
444            serde_json::json!({ "phase": "draining", "active_leases": 2 })
445        );
446    }
447
448    #[test]
449    fn test_verdict_without_benchmark_field_deserializes_as_none() {
450        let verdict: Verdict =
451            serde_json::from_str(r#"{"fits":true,"reasons":[],"wait_estimate_secs":null}"#)
452                .unwrap();
453        assert_eq!(verdict.benchmark, None);
454    }
455
456    #[test]
457    fn test_acquire_request_json_round_trip_preserves_every_field() {
458        assert_json_round_trip(&AcquireRequest {
459            holder: sample_holder(),
460            profile: custom_profile(),
461            min_cores: Some(1.5),
462            kind: LeaseKind::Normal,
463            label: "cargo build --release".into(),
464            cwd: Some(r"E:\work\app".into()),
465            wait_timeout_secs: 30,
466        });
467    }
468
469    #[test]
470    fn test_acquire_response_json_round_trip_preserves_every_field() {
471        assert_json_round_trip(&AcquireResponse {
472            lease: sample_lease(),
473            verdict: sample_verdict(),
474        });
475    }
476
477    #[test]
478    fn test_lease_owner_json_round_trip_preserves_every_field() {
479        assert_json_round_trip(&LeaseOwner {
480            session: sample_holder().session,
481        });
482    }
483
484    #[test]
485    fn test_heartbeat_response_json_round_trip_preserves_every_field() {
486        assert_json_round_trip(&HeartbeatResponse {
487            state: LeaseState::Queued,
488            expires_at_ms: 1_793_000_060_000,
489            end_cause: None,
490        });
491        assert_json_round_trip(&HeartbeatResponse {
492            state: LeaseState::Expired,
493            expires_at_ms: 1_793_000_060_000,
494            end_cause: Some(EndCause::Killed),
495        });
496    }
497
498    #[test]
499    fn test_heartbeat_response_from_an_older_allotd_has_no_cause() {
500        let old: HeartbeatResponse =
501            serde_json::from_str(r#"{"state":"expired","expires_at_ms":5}"#).unwrap();
502        assert_eq!(old.end_cause, None);
503    }
504
505    #[test]
506    fn test_release_response_json_round_trip_preserves_every_field() {
507        assert_json_round_trip(&ReleaseResponse {
508            lease: sample_lease(),
509            noise: None,
510        });
511        assert_json_round_trip(&ReleaseResponse {
512            lease: sample_lease(),
513            noise: Some(NoiseReport {
514                avg_cpu_pct: 1.5,
515                peak_cpu_pct: 4.0,
516                avg_gpu_pct: 0.0,
517                peak_gpu_pct: 2.0,
518                quiet_at_start: true,
519            }),
520        });
521    }
522
523    #[test]
524    fn test_wait_request_json_round_trip_preserves_every_field() {
525        assert_json_round_trip(&WaitRequest {
526            wait_timeout_secs: 90,
527        });
528    }
529
530    #[test]
531    fn test_lease_query_json_round_trip_preserves_empty_and_full_filters() {
532        assert_json_round_trip(&LeaseQuery::default());
533        assert_json_round_trip(&LeaseQuery {
534            session: Some(sample_holder().session),
535            state: Some(LeaseState::Active),
536        });
537    }
538
539    #[test]
540    fn test_lease_query_missing_fields_deserialize_as_none() {
541        let query: LeaseQuery = serde_json::from_str("{}").unwrap();
542        assert_eq!(query, LeaseQuery::default());
543    }
544
545    #[test]
546    fn test_leases_response_json_round_trip_preserves_every_field() {
547        assert_json_round_trip(&LeasesResponse {
548            leases: vec![sample_lease()],
549        });
550    }
551
552    #[test]
553    fn test_sessions_response_json_round_trip_preserves_every_field() {
554        assert_json_round_trip(&SessionsResponse {
555            sessions: vec![sample_session_usage()],
556        });
557    }
558
559    #[test]
560    fn test_history_dtos_json_round_trip_preserve_every_field() {
561        let summary = JobSummary {
562            fingerprint: r"cargo build|e:\work\app".into(),
563            command: "cargo build".into(),
564            cwd: r"E:\work\app".into(),
565            runs: 5,
566            estimate_runs: 4,
567            last_ended_at_ms: 1_793_000_095_000,
568            learned: match custom_profile() {
569                ProfileSpec::Custom(profile) => Some(profile),
570                _ => None,
571            },
572        };
573        assert_json_round_trip(&HistoryResponse {
574            jobs: vec![
575                summary.clone(),
576                JobSummary {
577                    learned: None,
578                    ..summary
579                },
580            ],
581        });
582        assert_json_round_trip(&HistoryRunsQuery {
583            fingerprint: "cargo build|".into(),
584            limit: Some(10),
585        });
586        assert_json_round_trip(&HistoryRunsResponse { runs: Vec::new() });
587    }
588
589    #[test]
590    fn test_kill_and_remove_responses_json_round_trip_preserve_every_field() {
591        assert_json_round_trip(&KillResponse {
592            lease: sample_lease(),
593            terminated: vec![KilledProcess {
594                pid: 30_112,
595                name: "bash.exe".into(),
596            }],
597            failed: vec![UnkilledProcess {
598                pid: 30_140,
599                name: "cargo.exe".into(),
600                reason: "Access is denied.".into(),
601            }],
602            spared: vec![UnkilledProcess {
603                pid: 30_150,
604                name: "claude.exe".into(),
605                reason: "protected".into(),
606            }],
607            untouched_reason: None,
608        });
609        let untouched = KillResponse {
610            lease: sample_lease(),
611            terminated: Vec::new(),
612            failed: Vec::new(),
613            spared: Vec::new(),
614            untouched_reason: Some("the lease has no bound process tree".into()),
615        };
616        assert_json_round_trip(&untouched);
617        assert_json_round_trip(&RemoveResponse {
618            lease: sample_lease(),
619        });
620    }
621
622    #[test]
623    fn test_bind_request_without_command_omits_it() {
624        let request = BindRequest {
625            tool_use_id: "toolu_01AbC".into(),
626            command: None,
627        };
628        assert_json_round_trip(&request);
629        let value = serde_json::to_value(&request).unwrap();
630        assert_eq!(value, serde_json::json!({ "tool_use_id": "toolu_01AbC" }));
631        assert_json_round_trip(&BindRequest {
632            command: Some("cargo build".into()),
633            ..request
634        });
635    }
636
637    #[test]
638    fn test_notice_dtos_json_round_trip_preserve_every_field() {
639        assert_json_round_trip(&NoticesResponse {
640            notices: Vec::new(),
641        });
642        assert_json_round_trip(&DeliveredResponse { delivered: true });
643    }
644
645    #[test]
646    fn test_register_session_request_json_round_trip_preserves_every_field() {
647        assert_json_round_trip(&RegisterSessionRequest {
648            holder: sample_holder(),
649        });
650    }
651}