soma_api/
route_inventory.rs

1// `RestRoute` (the generic route-metadata shape) and `CapabilitiesResponse`
2// live in `soma-http-api` (plan section 3.11) — reusable across any product
3// built on this workspace. `REST_ROUTES` below is Soma's own concrete route
4// table and stays here.
5pub use soma_http_api::route_inventory::{CapabilitiesResponse, RestRoute};
6
7pub(crate) const GATEWAY_ROUTE_PATH: &str = "/v1/gateway/{action}";
8
9pub const REST_ROUTES: &[RestRoute] = &[
10    RestRoute {
11        method: "GET",
12        path: "/health",
13        action: None,
14        auth: "public",
15        description: "Fast liveness probe.",
16    },
17    RestRoute {
18        method: "GET",
19        path: "/readyz",
20        action: None,
21        auth: "public",
22        description: "Readiness probe; 503 when the upstream dependency is unreachable.",
23    },
24    RestRoute {
25        method: "GET",
26        path: "/metrics",
27        action: None,
28        auth: "public",
29        description: "Prometheus metrics (text exposition format; requires the observability feature).",
30    },
31    RestRoute {
32        method: "GET",
33        path: "/status",
34        action: None,
35        auth: "public",
36        description: "Local redacted runtime status.",
37    },
38    RestRoute {
39        method: "GET",
40        path: "/openapi.json",
41        action: None,
42        auth: "public",
43        description: "Generated OpenAPI schema.",
44    },
45    RestRoute {
46        method: "GET",
47        path: "/v1/capabilities",
48        action: None,
49        auth: "mounted auth policy",
50        description: "Direct REST route inventory and server metadata.",
51    },
52    RestRoute {
53        method: "GET",
54        path: "/v1/providers",
55        action: None,
56        auth: "mounted auth policy",
57        description: "Live provider catalog, including dropped provider tools and MCP primitives.",
58    },
59    RestRoute {
60        method: "POST",
61        path: "/v1/tools/{action}",
62        action: None,
63        auth: "mounted auth policy; requires the provider tool scope when scoped",
64        description: "Generic REST execution route for provider-backed tools.",
65    },
66    RestRoute {
67        method: "POST",
68        path: GATEWAY_ROUTE_PATH,
69        action: None,
70        auth: "mounted auth policy; read actions require soma:read, admin actions require soma:admin",
71        description: "Gateway management and discovery action dispatch.",
72    },
73    RestRoute {
74        method: "POST",
75        path: "/v1/greet",
76        action: Some("greet"),
77        auth: "mounted auth policy; requires soma:read when scoped",
78        description: "Return a greeting.",
79    },
80    RestRoute {
81        method: "POST",
82        path: "/v1/echo",
83        action: Some("echo"),
84        auth: "mounted auth policy; requires soma:read when scoped",
85        description: "Echo a message back unchanged.",
86    },
87    RestRoute {
88        method: "GET",
89        path: "/v1/status",
90        action: Some("status"),
91        auth: "mounted auth policy; requires soma:read when scoped",
92        description: "Return authenticated service status.",
93    },
94    RestRoute {
95        method: "GET",
96        path: "/v1/python/environments",
97        action: Some("python_environment_status"),
98        auth: "mounted auth policy; requires soma:write and soma:admin",
99        description: "Inspect immutable Python environment cache state.",
100    },
101    RestRoute {
102        method: "POST",
103        path: "/v1/python/environments/prune-plan",
104        action: Some("python_environment_prune_plan"),
105        auth: "mounted auth policy; requires soma:write and soma:admin",
106        description: "Preview a bounded prune of stale non-ready cache entries.",
107    },
108    RestRoute {
109        method: "POST",
110        path: "/v1/python/environments/prune",
111        action: Some("python_environment_prune"),
112        auth: "mounted auth policy; requires soma:write and confirmation",
113        description: "Apply a bounded prune of stale non-ready cache entries.",
114    },
115    RestRoute {
116        method: "POST",
117        path: "/v1/python/environments/repair",
118        action: Some("python_environment_repair"),
119        auth: "mounted auth policy; requires soma:write and confirmation",
120        description: "Repair one managed Python provider environment.",
121    },
122    RestRoute {
123        method: "POST",
124        path: "/v1/python/environments/update",
125        action: Some("python_environment_update"),
126        auth: "mounted auth policy; requires soma:write and confirmation",
127        description: "Prepare and atomically activate one immutable provider update.",
128    },
129    RestRoute {
130        method: "GET",
131        path: "/v1/python/workers",
132        action: Some("python_worker_status"),
133        auth: "mounted auth policy; requires soma:write and soma:admin",
134        description: "Inspect persistent Python worker state and bounded redacted logs.",
135    },
136    RestRoute {
137        method: "POST",
138        path: "/v1/python/workers/cancel",
139        action: Some("python_worker_cancel"),
140        auth: "mounted auth policy; requires soma:write and confirmation",
141        description: "Cancel one active persistent Python invocation.",
142    },
143    RestRoute {
144        method: "POST",
145        path: "/v1/python/workers/reset",
146        action: Some("python_worker_reset"),
147        auth: "mounted auth policy; requires soma:write and confirmation",
148        description: "Clear one persistent Python worker quarantine.",
149    },
150    RestRoute {
151        method: "GET",
152        path: "/v1/python/generations",
153        action: Some("python_generation_status"),
154        auth: "mounted auth policy; requires soma:read when scoped",
155        description: "Inspect active and retained Python provider generations.",
156    },
157    RestRoute {
158        method: "POST",
159        path: "/v1/python/generations/rollback",
160        action: Some("python_generation_rollback"),
161        auth: "mounted auth policy; requires soma:write and confirmation",
162        description: "Atomically reactivate a retained Python provider generation.",
163    },
164    RestRoute {
165        method: "POST",
166        path: "/v1/python/graduation/status",
167        action: Some("python_graduation_status"),
168        auth: "mounted auth policy; requires soma:read and soma:admin",
169        description: "Inspect digest-bound Python graduation state.",
170    },
171    RestRoute {
172        method: "POST",
173        path: "/v1/python/graduation/apply",
174        action: Some("python_graduation_apply"),
175        auth: "mounted auth policy; requires soma:write, soma:admin, and confirmation",
176        description: "Run a confirmed Python graduation operation.",
177    },
178    RestRoute {
179        method: "GET",
180        path: "/v1/help",
181        action: Some("help"),
182        auth: "mounted auth policy",
183        description: "Return the action catalog and route help.",
184    },
185];
186
187pub(crate) fn capabilities_response() -> CapabilitiesResponse {
188    soma_http_api::route_inventory::capabilities_response(
189        "soma-mcp",
190        env!("CARGO_PKG_VERSION"),
191        "direct_routes",
192        REST_ROUTES,
193    )
194}
195
196#[cfg(test)]
197#[path = "route_inventory_tests.rs"]
198mod tests;
soma_api/route_inventory.rs

soma_api/
route_inventory.rs
