use super::router::{is_own_worker, meets_vram, runs_payload, ResourceRequirements};
use super::worker::Worker;
use serde::{Deserialize, Serialize};
use std::sync::RwLock;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum Placement {
#[default]
OwnFirst,
BestPriceMesh,
MeshOnly,
}
impl Placement {
pub fn as_str(self) -> &'static str {
match self {
Placement::OwnFirst => "own_first",
Placement::BestPriceMesh => "best_price_mesh",
Placement::MeshOnly => "mesh_only",
}
}
pub fn parse(s: &str) -> Result<Placement, String> {
match s.trim() {
"own_first" => Ok(Placement::OwnFirst),
"best_price_mesh" => Ok(Placement::BestPriceMesh),
"mesh_only" => Ok(Placement::MeshOnly),
other => Err(format!(
"unknown placement {other:?}: expected one of own_first, best_price_mesh, mesh_only"
)),
}
}
}
impl<'de> Deserialize<'de> for Placement {
fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
let s = String::deserialize(d)?;
Placement::parse(&s).map_err(serde::de::Error::custom)
}
}
static HUB_DEFAULT: RwLock<Option<Placement>> = RwLock::new(None);
pub fn set_hub_default(p: Option<Placement>) {
if let Ok(mut g) = HUB_DEFAULT.write() {
*g = p;
}
}
fn hub_default() -> Option<Placement> {
if let Some(p) = HUB_DEFAULT.read().ok().and_then(|g| *g) {
return Some(p);
}
std::env::var("ZAKURO_DEFAULT_PLACEMENT")
.ok()
.and_then(|v| Placement::parse(&v).ok())
}
pub fn resolve(requested: Option<Placement>) -> (Placement, &'static str) {
resolve_with(requested, hub_default())
}
fn resolve_with(requested: Option<Placement>, hub: Option<Placement>) -> (Placement, &'static str) {
match (requested, hub) {
(Some(p), _) => (p, "request"),
(None, Some(p)) => (p, "hub_default"),
(None, None) => (Placement::OwnFirst, "default"),
}
}
pub fn validate_raw(raw: &str) -> Result<(), String> {
let Ok(v) = serde_json::from_str::<serde_json::Value>(raw) else {
return Ok(());
};
match v.get("placement") {
None | Some(serde_json::Value::Null) => Ok(()),
Some(serde_json::Value::String(s)) => Placement::parse(s).map(|_| ()),
Some(other) => Err(format!(
"placement must be a string, got {other}: expected one of own_first, best_price_mesh, mesh_only"
)),
}
}
#[derive(Debug, Clone, Serialize)]
pub struct Candidate {
pub worker_id: String,
pub worker: String,
pub scope: &'static str,
#[serde(skip_serializing_if = "Option::is_none")]
pub broker: Option<String>,
pub price_per_hour: f64,
#[serde(skip_serializing_if = "Option::is_none")]
pub excluded: Option<&'static str>,
pub chosen: bool,
}
#[derive(Debug, Clone, Serialize)]
pub struct Chosen {
pub scope: &'static str,
#[serde(skip_serializing_if = "Option::is_none")]
pub worker: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub broker: Option<String>,
}
#[derive(Debug, Clone, Serialize)]
pub struct RoutingRecord {
pub policy: &'static str,
pub policy_source: &'static str,
pub enforced: bool,
pub candidates: Vec<Candidate>,
#[serde(skip_serializing_if = "Option::is_none")]
pub chosen: Option<Chosen>,
pub note: String,
}
const MAX_CANDIDATES: usize = 24;
impl RoutingRecord {
pub fn to_header(&self) -> String {
let mut r = self.clone();
if r.candidates.len() > MAX_CANDIDATES {
let extra = r.candidates.len() - MAX_CANDIDATES;
r.candidates.truncate(MAX_CANDIDATES);
r.note
.push_str(&format!(" (+{extra} candidates not listed)"));
}
let json = serde_json::to_string(&r).unwrap_or_default();
let mut out = String::with_capacity(json.len());
for c in json.chars() {
if c.is_ascii() && !c.is_ascii_control() {
out.push(c);
} else {
let mut buf = [0u16; 2];
for u in c.encode_utf16(&mut buf) {
out.push_str(&format!("\\u{u:04x}"));
}
}
}
out
}
pub fn finish_local(&mut self, worker_id: &str, broker: &str) {
let mut name = None;
for c in &mut self.candidates {
if c.worker_id == worker_id {
c.chosen = true;
c.excluded = None;
name = Some(c.worker.clone());
}
}
self.chosen = Some(Chosen {
scope: "local",
worker: name,
broker: Some(broker.to_string()),
});
}
pub fn finish_remote(&mut self, worker: Option<&str>) {
let mut broker = None;
let mut name = worker.map(str::to_string);
if let Some(w) = worker {
for c in &mut self.candidates {
if c.scope == "mesh" && c.worker == w {
c.chosen = true;
c.excluded = None;
broker = c.broker.clone();
name = Some(c.worker.clone());
}
}
}
self.chosen = Some(Chosen {
scope: "mesh",
worker: name,
broker,
});
}
}
#[derive(Debug, Clone)]
pub struct Plan {
pub route_remote: bool,
pub record: RoutingRecord,
}
pub fn pin_is_elsewhere(
node_key: &super::node_identity::NodeKey,
target_node: Option<&str>,
) -> bool {
target_node.is_some_and(|tn| !super::node_identity::node_filter_matches(node_key, tn))
}
fn ineligible(w: &Worker, local: bool, req: &ResourceRequirements) -> Option<&'static str> {
if !runs_payload(w, req.python.as_deref()) {
return Some("runtime");
}
if !req.tags.iter().all(|t| w.tags.contains(t)) {
return Some("capability");
}
if local {
return None;
}
if req
.worker_type
.as_deref()
.is_some_and(|t| w.worker_type != t)
{
return Some("capability");
}
if !meets_vram(w, req.min_vram_gb) {
return Some("vram");
}
if !w.can_handle(req.cpus, req.memory_bytes, req.gpus) {
return Some("capability");
}
if req.timeout_secs > 0.0 && w.max_timeout_secs > 0.0 && w.max_timeout_secs < req.timeout_secs {
return Some("capability");
}
None
}
pub fn plan(
policy: Placement,
source: &'static str,
healthy: &[Worker],
own_ip: Option<&str>,
req: &ResourceRequirements,
pinned_elsewhere: bool,
) -> Plan {
let mut candidates: Vec<Candidate> = healthy
.iter()
.map(|w| {
let local = is_own_worker(w, own_ip);
Candidate {
worker_id: w.id.clone(),
worker: w.name.clone(),
scope: if local { "local" } else { "mesh" },
broker: if local { None } else { w.source_node.clone() },
price_per_hour: w.pricing.price_per_hour,
excluded: ineligible(w, local, req),
chosen: false,
}
})
.collect();
let cheapest = |scope: &str, cands: &[Candidate]| {
cands
.iter()
.filter(|c| c.scope == scope && c.excluded.is_none())
.map(|c| c.price_per_hour)
.fold(None, |m: Option<f64>, p| Some(m.map_or(p, |m| m.min(p))))
};
let local_best = cheapest("local", &candidates);
let peer_best = cheapest("mesh", &candidates);
let (route_remote, note) = if pinned_elsewhere {
(
true,
"target_node pins another broker; local workers excluded".to_string(),
)
} else {
match policy {
Placement::MeshOnly => (true, "mesh_only: never run on this broker".to_string()),
Placement::OwnFirst => (
false,
"own_first: local worker if one matches, else the mesh".to_string(),
),
Placement::BestPriceMesh => match (local_best, peer_best) {
(Some(l), Some(p)) if p < l => (
true,
format!("best_price_mesh: cheapest peer {p} < best local {l} ¥/h"),
),
(Some(l), Some(p)) => (
false,
format!("best_price_mesh: best local {l} <= cheapest peer {p} ¥/h (tie stays local)"),
),
(Some(_), None) => (
false,
"best_price_mesh: no eligible peer worker, staying local".to_string(),
),
(None, _) => (
true,
"best_price_mesh: no eligible local worker, publishing to the mesh".to_string(),
),
},
}
};
for c in candidates.iter_mut().filter(|c| c.excluded.is_none()) {
c.excluded = match (c.scope, route_remote) {
("local", true) if pinned_elsewhere => Some("pinned_elsewhere"),
("local", true) if policy == Placement::MeshOnly => Some("policy"),
("local", true) => Some("price"),
("mesh", false) if policy == Placement::BestPriceMesh => Some("price"),
("mesh", false) => Some("not_local"),
_ => None,
};
}
Plan {
route_remote,
record: RoutingRecord {
policy: policy.as_str(),
policy_source: source,
enforced: true,
candidates,
chosen: None,
note,
},
}
}
pub fn enforced_on_direct_paths(policy: Placement) -> bool {
policy == Placement::MeshOnly
}
pub fn record_direct(
policy: Placement,
source: &'static str,
healthy: &[Worker],
own_ip: Option<&str>,
req: &ResourceRequirements,
chosen: &Worker,
broker: &str,
) -> RoutingRecord {
let mut plan = plan(policy, source, healthy, own_ip, req, false);
let local = is_own_worker(chosen, own_ip);
let mut rec = plan.record.clone();
match policy {
Placement::MeshOnly => {
rec.note = "mesh_only: enforced, selection limited to peer workers".to_string();
}
Placement::OwnFirst => {
rec.enforced = local;
rec.note = if local {
"own_first: not applied on this path (no mesh dispatch); the chosen worker is local"
.to_string()
} else {
"own_first: not applied on this path (no mesh dispatch); the worker was chosen by the routing strategy over all workers and is a peer worker".to_string()
};
}
Placement::BestPriceMesh => {
rec.enforced = false;
rec.note = "best_price_mesh: not applied on this path; the worker was chosen by the routing strategy over all workers".to_string();
}
}
if policy != Placement::MeshOnly {
for c in &mut rec.candidates {
if matches!(c.excluded, Some("policy" | "price" | "not_local")) {
c.excluded = None;
}
}
}
if local {
rec.finish_local(&chosen.id, broker);
} else {
rec.finish_remote(Some(&chosen.name));
}
plan.record = rec;
plan.record
}
#[cfg(test)]
mod tests {
use super::*;
use crate::broker::worker::{test_registration, WorkerRegistry};
fn reg(name: &str, uri: &str, price: f64, source: Option<&str>) -> Worker {
let r = WorkerRegistry::new();
let mut w = r.register(test_registration(name, uri.to_string(), price));
w.source_node = source.map(str::to_string);
w
}
fn req() -> ResourceRequirements {
ResourceRequirements::default()
}
#[test]
fn parses_known_values_and_rejects_unknown_with_a_clear_message() {
assert_eq!(Placement::parse("own_first"), Ok(Placement::OwnFirst));
assert_eq!(Placement::parse("mesh_only"), Ok(Placement::MeshOnly));
let e = Placement::parse("cheapest").unwrap_err();
assert!(
e.contains("own_first") && e.contains("best_price_mesh") && e.contains("mesh_only")
);
assert!(validate_raw(r#"{"placement":"nope"}"#).is_err());
assert!(validate_raw(r#"{"placement":7}"#).is_err());
assert!(validate_raw(r#"{"placement":"mesh_only"}"#).is_ok());
assert!(validate_raw(r#"{"cpus":2}"#).is_ok());
let r: ResourceRequirements = serde_json::from_str(r#"{"placement":"mesh_only"}"#).unwrap();
assert_eq!(r.placement, Some(Placement::MeshOnly));
assert!(serde_json::from_str::<ResourceRequirements>(r#"{"placement":"x"}"#).is_err());
}
#[test]
fn precedence_is_request_then_hub_then_own_first() {
use Placement::*;
assert_eq!(
resolve_with(Some(MeshOnly), Some(BestPriceMesh)),
(MeshOnly, "request")
);
assert_eq!(
resolve_with(None, Some(BestPriceMesh)),
(BestPriceMesh, "hub_default")
);
assert_eq!(resolve_with(None, None), (OwnFirst, "default"));
assert_eq!(Placement::default(), OwnFirst);
}
#[test]
fn mesh_only_never_goes_local() {
let ws = vec![
reg("mine", "http://127.0.0.1:1", 1.0, None),
reg("theirs", "http://10.0.0.9:1", 9.0, Some("peer-a")),
];
let p = plan(Placement::MeshOnly, "request", &ws, None, &req(), false);
assert!(p.route_remote);
let local = p
.record
.candidates
.iter()
.find(|c| c.scope == "local")
.unwrap();
assert_eq!(local.excluded, Some("policy"));
}
#[test]
fn own_first_stays_local_and_marks_peers_not_local() {
let ws = vec![
reg("mine", "http://127.0.0.1:1", 50.0, None),
reg("theirs", "http://10.0.0.9:1", 1.0, Some("peer-a")),
];
let p = plan(Placement::OwnFirst, "default", &ws, None, &req(), false);
assert!(!p.route_remote);
let peer = p
.record
.candidates
.iter()
.find(|c| c.scope == "mesh")
.unwrap();
assert_eq!(peer.excluded, Some("not_local"));
}
#[test]
fn best_price_mesh_goes_remote_only_when_a_peer_is_strictly_cheaper() {
let cheaper_peer = vec![
reg("mine", "http://127.0.0.1:1", 40.0, None),
reg("theirs", "http://10.0.0.9:1", 3.6, Some("peer-a")),
];
let p = plan(
Placement::BestPriceMesh,
"request",
&cheaper_peer,
None,
&req(),
false,
);
assert!(p.route_remote, "{}", p.record.note);
assert_eq!(
p.record
.candidates
.iter()
.find(|c| c.scope == "local")
.unwrap()
.excluded,
Some("price")
);
let dearer_peer = vec![
reg("mine", "http://127.0.0.1:1", 3.6, None),
reg("theirs", "http://10.0.0.9:1", 40.0, Some("peer-a")),
];
let p = plan(
Placement::BestPriceMesh,
"request",
&dearer_peer,
None,
&req(),
false,
);
assert!(!p.route_remote);
assert_eq!(
p.record
.candidates
.iter()
.find(|c| c.scope == "mesh")
.unwrap()
.excluded,
Some("price")
);
let tie = vec![
reg("mine", "http://127.0.0.1:1", 3.6, None),
reg("theirs", "http://10.0.0.9:1", 3.6, Some("peer-a")),
];
assert!(
!plan(
Placement::BestPriceMesh,
"request",
&tie,
None,
&req(),
false
)
.route_remote
);
}
#[test]
fn best_price_mesh_ignores_ineligible_peers_and_reports_why() {
let mut gpu_less = reg("cheap-no-vram", "http://10.0.0.9:1", 1.0, Some("peer-a"));
gpu_less.hardware.gpu_vram_gb = Some(8);
let ws = vec![reg("mine", "http://127.0.0.1:1", 40.0, None), gpu_less];
let mut r = req();
r.min_vram_gb = Some(24);
let p = plan(Placement::BestPriceMesh, "request", &ws, None, &r, false);
assert!(!p.route_remote);
assert_eq!(
p.record
.candidates
.iter()
.find(|c| c.scope == "mesh")
.unwrap()
.excluded,
Some("vram")
);
let mut r = req();
r.python = Some("3.99".into());
let p = plan(Placement::OwnFirst, "default", &ws, None, &r, false);
assert!(p
.record
.candidates
.iter()
.all(|c| c.excluded == Some("runtime")));
}
#[test]
fn a_pin_to_another_broker_excludes_local_workers_under_any_policy() {
let ws = vec![reg("mine", "http://127.0.0.1:1", 1.0, None)];
let p = plan(Placement::OwnFirst, "default", &ws, None, &req(), true);
assert!(p.route_remote);
assert_eq!(p.record.candidates[0].excluded, Some("pinned_elsewhere"));
}
#[test]
fn decision_payload_is_ascii_json_with_the_choice() {
let ws = vec![
reg("m\u{00fc}ne", "http://127.0.0.1:1", 5.0, None),
reg("theirs", "http://10.0.0.9:1", 1.0, Some("peer-a")),
];
let mut p = plan(
Placement::BestPriceMesh,
"hub_default",
&ws,
None,
&req(),
false,
);
assert!(p.route_remote);
p.record.finish_remote(Some("theirs"));
let h = p.record.to_header();
assert!(h.is_ascii());
assert!(axum_free_header_ok(&h));
let v: serde_json::Value = serde_json::from_str(&h).unwrap();
assert_eq!(v["policy"], "best_price_mesh");
assert_eq!(v["policy_source"], "hub_default");
assert_eq!(v["chosen"]["scope"], "mesh");
assert_eq!(v["chosen"]["worker"], "theirs");
assert_eq!(v["chosen"]["broker"], "peer-a");
let cands = v["candidates"].as_array().unwrap();
assert_eq!(cands.len(), 2);
let local = cands.iter().find(|c| c["scope"] == "local").unwrap();
assert_eq!(local["excluded"], "price");
assert_eq!(local["worker"], "m\u{00fc}ne");
let mut l = plan(Placement::OwnFirst, "default", &ws, None, &req(), false);
let id = ws[0].id.clone();
l.record.finish_local(&id, "node-x");
assert_eq!(l.record.chosen.as_ref().unwrap().scope, "local");
assert!(l.record.candidates.iter().any(|c| c.chosen));
}
fn axum_free_header_ok(h: &str) -> bool {
tiny_http::Header::from_bytes(b"X-Zakuro-Routing".as_slice(), h.as_bytes()).is_ok()
}
}