Skip to content

Commit b018f8f

Browse files
wezwez
committed
machine-info: add docs/examples to jsonschema
1 parent 3bc3da8 commit b018f8f

9 files changed

Lines changed: 661 additions & 8 deletions

File tree

‎crates/kumo-api-types/src/lib.rs‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -632,21 +632,56 @@ pub struct ReadyQueueStateResponse {
632632
pub states_by_ready_queue: HashMap<String, HashMap<String, QueueState>>,
633633
}
634634

635-
#[derive(Serialize, Clone, Deserialize, Debug, PartialEq)]
635+
#[derive(Serialize, Clone, Deserialize, Debug, PartialEq, ToSchema)]
636636
pub struct MachineInfoV1 {
637+
/// The NodeID of the system
638+
#[schema(example = "9745bb48-14d7-48f2-a1fb-7df8d5844217")]
637639
pub node_id: String,
640+
/// The hostname of the system, as reported by `gethostname(2)`
641+
#[schema(example = "mta1.example.com")]
638642
pub hostname: String,
643+
/// The MAC address of the primary, non-loopback, network interface
644+
#[schema(example = "02:02:02:02:02:02")]
639645
pub mac_address: String,
646+
/// The number of available CPUs as reported by
647+
/// <https://docs.rs/num_cpus/latest/num_cpus/fn.get.html>
648+
#[schema(example = 64)]
640649
pub num_cores: usize,
650+
/// The kernel version
651+
#[schema(example = "6.8.0-1016-aws")]
641652
pub kernel_version: Option<String>,
653+
/// Identifies the running platform
654+
#[schema(example = "linux/x86_64")]
642655
pub platform: String,
656+
/// The OS distribution
657+
#[schema(example = "ubuntu")]
643658
pub distribution: String,
659+
/// The OS version (which often includes the distribution)
660+
#[schema(example = "Linux (Ubuntu 24.04)")]
644661
pub os_version: String,
662+
/// Total physical memory installed in the instance
663+
#[schema(example = 1003929600)]
645664
pub total_memory_bytes: u64,
665+
/// If we detected that we're running in a container, the name
666+
/// of the container runtime
646667
pub container_runtime: Option<String>,
668+
/// Identifies the CPU. If you have a mixture of different CPUs,
669+
/// this will be a comma separated list of the different CPUs
670+
#[schema(example = "Intel(R) Xeon(R) CPU E5-2686 v4 @ 2.30GHz")]
647671
pub cpu_brand: String,
672+
/// Additional metadata hash(es) that can identify the running machine.
673+
/// For example, when running in AWS, the instance-id will be
674+
/// included.
675+
#[schema(
676+
example = "aws_instance_id=i-09aebefac97cf0000,machine_uid=ec22130d1de33cf52413457ac040000"
677+
)]
648678
pub fingerprint: String,
679+
/// The date/time at which the process was last started
649680
pub online_since: DateTime<Utc>,
681+
/// Which process is running. eg: `kumod` vs `tsa-daemon` vs. `proxy-server`.
682+
#[schema(example = "kumod")]
650683
pub process_kind: String,
684+
/// The version of KumoMTA that is running
685+
#[schema(example = "2026.02.24-2d1a3174")]
651686
pub version: String,
652687
}

‎crates/kumo-server-common/src/http_server/mod.rs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -416,7 +416,11 @@ where
416416
}
417417

418418
/// Returns information identifying this instance
419-
#[utoipa::path(get, tag = "debugging", path = "/api/machine-info")]
419+
#[utoipa::path(get, tag = "debugging", path = "/api/machine-info",
420+
responses(
421+
(status=200, description="Machine information", body=MachineInfoV1)
422+
),
423+
)]
420424
async fn machine_info(State(state): State<AppState>) -> Result<Json<MachineInfoV1>, AppError> {
421425
let online_since = ONLINE_SINCE.clone();
422426
match MACHINE_INFO.lock().as_ref() {

‎docs/reference/http/kumod/api_machine_info_get.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,70 @@ tags:
1414
from there and into these docs.
1515

1616
Returns information identifying this instance
17+
18+
## Responses
19+
### Status 200
20+
Machine information
21+
22+
23+
`Content-Type: application/json`
24+
25+
26+
This is an object value, with the following properties:
27+
28+
29+
* `container_runtime` - optional nullable `string`. If we detected that we're running in a container, the name
30+
of the container runtime
31+
32+
* `cpu_brand` - required `string`. Identifies the CPU. If you have a mixture of different CPUs,
33+
this will be a comma separated list of the different CPUs
34+
35+
* `distribution` - required `string`. The OS distribution
36+
37+
* `fingerprint` - required `string`. Additional metadata hash(es) that can identify the running machine.
38+
For example, when running in AWS, the instance-id will be
39+
included.
40+
41+
* `hostname` - required `string`. The hostname of the system, as reported by `gethostname(2)`
42+
43+
* `kernel_version` - optional nullable `string`. The kernel version
44+
45+
* `mac_address` - required `string`. The MAC address of the primary, non-loopback, network interface
46+
47+
* `node_id` - required `string`. The NodeID of the system
48+
49+
* `num_cores` - required `integer`. The number of available CPUs as reported by
50+
<https://docs.rs/num_cpus/latest/num_cpus/fn.get.html>
51+
52+
* `online_since` - required `string` (`date-time`). The date/time at which the process was last started
53+
54+
* `os_version` - required `string`. The OS version (which often includes the distribution)
55+
56+
* `platform` - required `string`. Identifies the running platform
57+
58+
* `process_kind` - required `string`. Which process is running. eg: `kumod` vs `tsa-daemon` vs. `proxy-server`.
59+
60+
* `total_memory_bytes` - required `integer` (`u-int64`). Total physical memory installed in the instance
61+
62+
* `version` - required `string`. The version of KumoMTA that is running
63+
64+
### Examples
65+
```json
66+
{
67+
"container_runtime": "string",
68+
"cpu_brand": "Intel(R) Xeon(R) CPU E5-2686 v4 @ 2.30GHz",
69+
"distribution": "ubuntu",
70+
"fingerprint": "aws_instance_id=i-09aebefac97cf0000,machine_uid=ec22130d1de33cf52413457ac040000",
71+
"hostname": "mta1.example.com",
72+
"kernel_version": "6.8.0-1016-aws",
73+
"mac_address": "02:02:02:02:02:02",
74+
"node_id": "9745bb48-14d7-48f2-a1fb-7df8d5844217",
75+
"num_cores": 64,
76+
"online_since": "1990-12-31T23:59:60Z",
77+
"os_version": "Linux (Ubuntu 24.04)",
78+
"platform": "linux/x86_64",
79+
"process_kind": "kumod",
80+
"total_memory_bytes": 1003929600,
81+
"version": "2026.02.24-2d1a3174"
82+
}
83+
```

‎docs/reference/http/kumod/schemas/MachineInfoV1.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# MachineInfoV1
2+
3+
!!! info
4+
This page was generated by extracting information from a JSON Schema
5+
data file for the API. It may be missing some information, or otherwise
6+
suggest approximate or placeholder values based on information in the
7+
schema file; this is due to limitations on how that data is extracted
8+
from the underlying Rust code and into the JSON Schema, and then again
9+
from there and into these docs.
10+
11+
12+
This is an object value, with the following properties:
13+
14+
15+
* `container_runtime` - optional nullable `string`. If we detected that we're running in a container, the name
16+
of the container runtime
17+
18+
* `cpu_brand` - required `string`. Identifies the CPU. If you have a mixture of different CPUs,
19+
this will be a comma separated list of the different CPUs
20+
21+
* `distribution` - required `string`. The OS distribution
22+
23+
* `fingerprint` - required `string`. Additional metadata hash(es) that can identify the running machine.
24+
For example, when running in AWS, the instance-id will be
25+
included.
26+
27+
* `hostname` - required `string`. The hostname of the system, as reported by `gethostname(2)`
28+
29+
* `kernel_version` - optional nullable `string`. The kernel version
30+
31+
* `mac_address` - required `string`. The MAC address of the primary, non-loopback, network interface
32+
33+
* `node_id` - required `string`. The NodeID of the system
34+
35+
* `num_cores` - required `integer`. The number of available CPUs as reported by
36+
<https://docs.rs/num_cpus/latest/num_cpus/fn.get.html>
37+
38+
* `online_since` - required `string` (`date-time`). The date/time at which the process was last started
39+
40+
* `os_version` - required `string`. The OS version (which often includes the distribution)
41+
42+
* `platform` - required `string`. Identifies the running platform
43+
44+
* `process_kind` - required `string`. Which process is running. eg: `kumod` vs `tsa-daemon` vs. `proxy-server`.
45+
46+
* `total_memory_bytes` - required `integer` (`u-int64`). Total physical memory installed in the instance
47+
48+
* `version` - required `string`. The version of KumoMTA that is running
49+
50+
### Examples
51+
```json
52+
{
53+
"container_runtime": "string",
54+
"cpu_brand": "Intel(R) Xeon(R) CPU E5-2686 v4 @ 2.30GHz",
55+
"distribution": "ubuntu",
56+
"fingerprint": "aws_instance_id=i-09aebefac97cf0000,machine_uid=ec22130d1de33cf52413457ac040000",
57+
"hostname": "mta1.example.com",
58+
"kernel_version": "6.8.0-1016-aws",
59+
"mac_address": "02:02:02:02:02:02",
60+
"node_id": "9745bb48-14d7-48f2-a1fb-7df8d5844217",
61+
"num_cores": 64,
62+
"online_since": "1990-12-31T23:59:60Z",
63+
"os_version": "Linux (Ubuntu 24.04)",
64+
"platform": "linux/x86_64",
65+
"process_kind": "kumod",
66+
"total_memory_bytes": 1003929600,
67+
"version": "2026.02.24-2d1a3174"
68+
}
69+
```

‎docs/reference/http/proxy-server/api_machine_info_get.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,70 @@ tags:
1414
from there and into these docs.
1515

1616
Returns information identifying this instance
17+
18+
## Responses
19+
### Status 200
20+
Machine information
21+
22+
23+
`Content-Type: application/json`
24+
25+
26+
This is an object value, with the following properties:
27+
28+
29+
* `container_runtime` - optional nullable `string`. If we detected that we're running in a container, the name
30+
of the container runtime
31+
32+
* `cpu_brand` - required `string`. Identifies the CPU. If you have a mixture of different CPUs,
33+
this will be a comma separated list of the different CPUs
34+
35+
* `distribution` - required `string`. The OS distribution
36+
37+
* `fingerprint` - required `string`. Additional metadata hash(es) that can identify the running machine.
38+
For example, when running in AWS, the instance-id will be
39+
included.
40+
41+
* `hostname` - required `string`. The hostname of the system, as reported by `gethostname(2)`
42+
43+
* `kernel_version` - optional nullable `string`. The kernel version
44+
45+
* `mac_address` - required `string`. The MAC address of the primary, non-loopback, network interface
46+
47+
* `node_id` - required `string`. The NodeID of the system
48+
49+
* `num_cores` - required `integer`. The number of available CPUs as reported by
50+
<https://docs.rs/num_cpus/latest/num_cpus/fn.get.html>
51+
52+
* `online_since` - required `string` (`date-time`). The date/time at which the process was last started
53+
54+
* `os_version` - required `string`. The OS version (which often includes the distribution)
55+
56+
* `platform` - required `string`. Identifies the running platform
57+
58+
* `process_kind` - required `string`. Which process is running. eg: `kumod` vs `tsa-daemon` vs. `proxy-server`.
59+
60+
* `total_memory_bytes` - required `integer` (`u-int64`). Total physical memory installed in the instance
61+
62+
* `version` - required `string`. The version of KumoMTA that is running
63+
64+
### Examples
65+
```json
66+
{
67+
"container_runtime": "string",
68+
"cpu_brand": "Intel(R) Xeon(R) CPU E5-2686 v4 @ 2.30GHz",
69+
"distribution": "ubuntu",
70+
"fingerprint": "aws_instance_id=i-09aebefac97cf0000,machine_uid=ec22130d1de33cf52413457ac040000",
71+
"hostname": "mta1.example.com",
72+
"kernel_version": "6.8.0-1016-aws",
73+
"mac_address": "02:02:02:02:02:02",
74+
"node_id": "9745bb48-14d7-48f2-a1fb-7df8d5844217",
75+
"num_cores": 64,
76+
"online_since": "1990-12-31T23:59:60Z",
77+
"os_version": "Linux (Ubuntu 24.04)",
78+
"platform": "linux/x86_64",
79+
"process_kind": "kumod",
80+
"total_memory_bytes": 1003929600,
81+
"version": "2026.02.24-2d1a3174"
82+
}
83+
```

‎docs/reference/http/proxy-server/schemas/MachineInfoV1.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# MachineInfoV1
2+
3+
!!! info
4+
This page was generated by extracting information from a JSON Schema
5+
data file for the API. It may be missing some information, or otherwise
6+
suggest approximate or placeholder values based on information in the
7+
schema file; this is due to limitations on how that data is extracted
8+
from the underlying Rust code and into the JSON Schema, and then again
9+
from there and into these docs.
10+
11+
12+
This is an object value, with the following properties:
13+
14+
15+
* `container_runtime` - optional nullable `string`. If we detected that we're running in a container, the name
16+
of the container runtime
17+
18+
* `cpu_brand` - required `string`. Identifies the CPU. If you have a mixture of different CPUs,
19+
this will be a comma separated list of the different CPUs
20+
21+
* `distribution` - required `string`. The OS distribution
22+
23+
* `fingerprint` - required `string`. Additional metadata hash(es) that can identify the running machine.
24+
For example, when running in AWS, the instance-id will be
25+
included.
26+
27+
* `hostname` - required `string`. The hostname of the system, as reported by `gethostname(2)`
28+
29+
* `kernel_version` - optional nullable `string`. The kernel version
30+
31+
* `mac_address` - required `string`. The MAC address of the primary, non-loopback, network interface
32+
33+
* `node_id` - required `string`. The NodeID of the system
34+
35+
* `num_cores` - required `integer`. The number of available CPUs as reported by
36+
<https://docs.rs/num_cpus/latest/num_cpus/fn.get.html>
37+
38+
* `online_since` - required `string` (`date-time`). The date/time at which the process was last started
39+
40+
* `os_version` - required `string`. The OS version (which often includes the distribution)
41+
42+
* `platform` - required `string`. Identifies the running platform
43+
44+
* `process_kind` - required `string`. Which process is running. eg: `kumod` vs `tsa-daemon` vs. `proxy-server`.
45+
46+
* `total_memory_bytes` - required `integer` (`u-int64`). Total physical memory installed in the instance
47+
48+
* `version` - required `string`. The version of KumoMTA that is running
49+
50+
### Examples
51+
```json
52+
{
53+
"container_runtime": "string",
54+
"cpu_brand": "Intel(R) Xeon(R) CPU E5-2686 v4 @ 2.30GHz",
55+
"distribution": "ubuntu",
56+
"fingerprint": "aws_instance_id=i-09aebefac97cf0000,machine_uid=ec22130d1de33cf52413457ac040000",
57+
"hostname": "mta1.example.com",
58+
"kernel_version": "6.8.0-1016-aws",
59+
"mac_address": "02:02:02:02:02:02",
60+
"node_id": "9745bb48-14d7-48f2-a1fb-7df8d5844217",
61+
"num_cores": 64,
62+
"online_since": "1990-12-31T23:59:60Z",
63+
"os_version": "Linux (Ubuntu 24.04)",
64+
"platform": "linux/x86_64",
65+
"process_kind": "kumod",
66+
"total_memory_bytes": 1003929600,
67+
"version": "2026.02.24-2d1a3174"
68+
}
69+
```

0 commit comments

Comments
 (0)