import argparse
import copy
import datetime
import hmac
import json
import os
import sys
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from urllib.parse import parse_qs, unquote, urlsplit
REPO_ROOT = Path(__file__).resolve().parents[2]
DEFAULT_FIXTURE = REPO_ROOT / "docs" / "agent-api" / "summary.v1.json"
LOCK = threading.Lock()
MESH_PRICE = 3.6
ROUTES = {
"/v1/summary": {"GET"},
"/v1/refresh": {"POST"},
"/v1/sharing": {"PUT"},
"/v1/workers": {"PUT"},
"/v1/price": {"PUT"},
"/v2/offers": {"GET"},
}
OFFER_PREFIX = "/v2/offers/"
PRICE_FIELDS = {"scope", "price_per_hour"}
OFFER_CATEGORIES = [
"Machine learning & AI", "Languages & frameworks", "Developer tools", "Data science",
"Databases & storage", "Web servers", "Sandbox kits",
]
_T = [
("pytorch", "PyTorch", 0, "PyTorch", True, "pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime", "service", True, 8, 7.2, 3,
"Tensors and dynamic neural networks in Python with strong GPU acceleration. Ready for training and inference jobs."),
("ollama", "Ollama", 0, "Ollama", True, "ollama/ollama:0.5.4", "service", True, 6, 5.4, 5,
"Run open large language models locally behind a simple HTTP API. Pulls weights on demand."),
("vllm", "vLLM", 0, "vLLM", True, "vllm/vllm-openai:v0.6.4", "service", True, 24, 18.0, 1,
"High-throughput, memory-efficient LLM serving with an OpenAI-compatible API."),
("tensorflow", "TensorFlow", 0, "TensorFlow", True, "tensorflow/tensorflow:2.18.0", "service", False, None, 3.6, 2,
"End-to-end open source machine learning platform with a comprehensive ecosystem of tools."),
("python", "Python", 1, "Python", True, "python:3.12-slim", "sandbox", False, None, 1.8, 9,
"The official slim Python 3.12 image: a clean interpreter for scripts, notebooks and batch jobs."),
("node", "Node.js", 1, "Node.js", True, "node:22-slim", "sandbox", False, None, 1.8, 6,
"JavaScript runtime built on Chrome's V8 engine, with npm. Slim Debian base."),
("golang", "Go", 1, "Docker Official Images", True, "golang:1.23", "sandbox", False, None, 1.8, 4,
"Build fast, reliable and efficient software at scale with the Go toolchain."),
("rust", "Rust", 1, "Docker Official Images", True, "rust:1.83-slim", "sandbox", False, None, 2.1, 3,
"The Rust compiler and cargo, for systems code that needs to be fast and safe."),
("code-server", "code-server", 2, "Coder", True, "codercom/code-server:4.96.2", "service", False, None, 2.7, 7,
"VS Code in the browser, on this machine. Consumers get a full remote IDE over the mesh."),
("jupyter", "Jupyter SciPy", 3, "Jupyter", True, "jupyter/scipy-notebook:2024-12-09", "service", False, None, 2.4, 8,
"Notebook server with the scientific Python stack: NumPy, pandas, SciPy, Matplotlib and more."),
("postgres", "PostgreSQL", 4, "Docker Official Images", True, "postgres:16-alpine", "service", False, None, 2.2, 5,
"The world's most advanced open source relational database, on Alpine."),
("redis", "Redis", 4, "Docker Official Images", True, "redis:7-alpine", "service", False, None, 1.4, 4,
"In-memory data store used as a database, cache and message broker."),
("nginx", "NGINX", 5, "NGINX", True, "nginx:1.27-alpine", "service", False, None, 0.9, 6,
"Lightweight HTTP server and reverse proxy. Serves static sites and fronts other environments."),
("playwright", "Playwright", 6, "Microsoft", True, "mcr.microsoft.com/playwright:v1.49.1", "sandbox", False, None, 3.0, 2,
"Headless Chromium, Firefox and WebKit for browser automation and end-to-end tests."),
("community-sd", "Stable Diffusion WebUI", 0, "community", False, "ghcr.io/example/sd-webui:1.10", "service", True, 12, 9.0, 0,
"Community image for text-to-image generation. Needs a recent NVIDIA card."),
]
OFFERS = {}
for (_id, _name, _cat, _pub, _ver, _img, _kind, _gpu, _vram, _price, _hosts, _desc) in _T:
OFFERS[_id] = {
"template": {"id": _id, "name": _name, "description": _desc, "category": OFFER_CATEGORIES[_cat],
"publisher": _pub, "verified": _ver, "icon_url": None, "image": _img, "kind": _kind,
"tier": "standard", "gpu_required": _gpu, "min_vram_gb": _vram},
"default_price_per_hour": _price, "price_basis": "mesh" if _hosts >= 3 else "suggested", "hosts": _hosts,
"subscribed": False, "price_mode": None, "price_per_hour": None, "deployment_id": None, "state": None,
"fits": False if _gpu else True,
"fit_reason": ("needs %d GB VRAM" % _vram if _vram else "needs a GPU") if _gpu else None,
}
for _id, _mode, _price in (("python", "auto", None), ("code-server", "fixed", 4.5)):
_o = OFFERS[_id]
_o.update(subscribed=True, price_mode=_mode, deployment_id="stub-dep-" + _id, state="healthy",
price_per_hour=_price if _price is not None else _o["default_price_per_hour"])
def _fake_logs():
base = datetime.datetime.now(datetime.timezone.utc)
def lines(spec):
out = []
for i, (level, msg) in enumerate(spec):
ts = (base - datetime.timedelta(seconds=(len(spec) - i) * 37)).strftime("%Y-%m-%dT%H:%M:%SZ")
out.append("%s %5s %s" % (ts, level, msg))
return out
agent = [("INFO", "agent started, version stub, pid 4242"), ("INFO", "hub reachable at https://hub.zakuro.ai")] * 3
agent += [("WARN", "hub summary refresh slow (2.4s)"), ("INFO", "starting broker"),
("ERROR", "zakuro worker directory can't be found: /Users/stub/.zakuro/worker"),
("WARN", "retrying worker spawn in 30s (attempt 2 of 5)"), ("INFO", "refresh ok, 2 nodes online")] * 20
broker = [("INFO", "listening on 127.0.0.1:7421"), ("INFO", "registered with hub as stub-node"),
("WARN", "no workers connected yet"), ("INFO", "heartbeat ok token=…redacted")] * 10
worker = [("INFO", "w0 waiting for work"), ("INFO", "w0 job 8f2c accepted"), ("INFO", "w0 job 8f2c done in 12.4s")] * 15
return {"agent.log": lines(agent), "broker.log": lines(broker), "workers/w0.log": lines(worker)}
LOGS = _fake_logs()
def now_iso():
return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
def write_agent_json(home, port, token):
agent_dir = Path(home).expanduser() / "agent"
agent_dir.mkdir(parents=True, exist_ok=True)
os.chmod(str(agent_dir), 0o700)
path = agent_dir / "agent.json"
path.write_text(json.dumps({"v": 1, "port": port, "token": token, "pid": os.getpid(), "version": "stub"}))
os.chmod(str(path), 0o600)
return path
class State:
def __init__(self, summary, fail_price, is_admin=True):
self.s = summary
self.fail_price = fail_price
self.is_admin = is_admin
if self.s.get("account") is not None:
self.s["account"]["is_admin"] = is_admin
def this_mac_device(self):
for device in self.s.get("devices") or []:
if device.get("this_mac"):
return device
return None
def apply(self, path, payload):
mac = self.s["this_mac"]
workers = mac["workers"]
if path == "/v1/sharing":
if not isinstance(payload.get("on"), bool):
return (400, "invalid_input", "on must be a boolean")
mac["sharing"] = payload["on"]
mac["broker"] = "running" if payload["on"] else "stopped"
workers["running"] = workers["desired"] if payload["on"] else 0
workers["busy"] = min(workers["busy"], workers["running"])
return None
if path == "/v1/workers":
count = payload.get("count")
if not isinstance(count, int) or isinstance(count, bool) or not 0 <= count <= workers["max"]:
return (400, "invalid_input", "count must be an integer in 0..%d" % workers["max"])
workers["desired"] = count
if mac["sharing"]:
workers["running"] = count
workers["busy"] = min(workers["busy"], count)
device = self.this_mac_device()
if device is not None:
device["workers"] = count
return None
if path == "/v1/price":
if self.fail_price:
return (502, "hub_error", "stub: the hub rejected the price")
if not set(payload.keys()) <= PRICE_FIELDS:
return (400, "invalid_input", "unknown field in price body")
scope = payload.get("scope")
if scope not in ("device", "default"):
return (400, "invalid_input", "scope must be device or default")
if "price_per_hour" not in payload:
return (400, "invalid_input", "price_per_hour is required (null falls back)")
value = payload["price_per_hour"]
bounds = self.s["prices"]["bounds"]
if value is not None and (isinstance(value, bool) or not isinstance(value, (int, float))
or not bounds["min"] <= value <= bounds["max"]):
return (400, "invalid_input", "price_per_hour must be within %s..%s" % (bounds["min"], bounds["max"]))
prices = self.s["prices"]
price = prices["this_mac"]
if scope == "default":
prices["default_per_hour"] = value
else:
price["per_hour"] = value
price["state"] = "set" if value is not None else "inherited"
fallback = prices["default_per_hour"] if prices["default_per_hour"] is not None else MESH_PRICE
price["effective_per_hour"] = price["per_hour"] if price["state"] == "set" else fallback
device = self.this_mac_device()
if device is not None:
device["effective_price_per_hour"] = {"min": price["effective_per_hour"], "max": price["effective_per_hour"]}
return None
return (404, "not_found", path)
def make_handler(state, port, token):
allowed_hosts = {"127.0.0.1:%d" % port, "localhost:%d" % port}
class Handler(BaseHTTPRequestHandler):
server_version = "zc-agent-stub"
def log_message(self, fmt, *args):
sys.stderr.write("stub-agent: %s %s\n" % (self.command, self.path))
def reply(self, status, body):
data = json.dumps(body).encode()
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def fail(self, status, code, message):
self.reply(status, {"error": {"code": code, "message": message}})
def guard(self):
if self.headers.get("Origin") is not None:
self.fail(403, "forbidden", "requests with an Origin header are refused")
return False
if self.headers.get("Host") not in allowed_hosts:
self.fail(403, "forbidden", "Host must be 127.0.0.1:%d or localhost:%d" % (port, port))
return False
header = self.headers.get("Authorization") or ""
if not hmac.compare_digest(header, "Bearer " + token):
self.fail(401, "unauthorized", "missing or invalid token")
return False
return True
def summary(self):
with LOCK:
state.s["as_of"] = now_iso()
return copy.deepcopy(state.s)
def handle_put(self, path):
length = int(self.headers.get("Content-Length") or 0)
try:
payload = json.loads(self.rfile.read(length) or b"{}")
except ValueError:
payload = None
if not isinstance(payload, dict):
self.fail(400, "invalid_input", "body must be a JSON object")
return
with LOCK:
error = state.apply(path, payload)
if error is not None:
self.fail(*error)
return
self.reply(200, self.summary())
def offers(self):
with LOCK:
return {"node": "stub-node-pubkey", "categories": list(OFFER_CATEGORIES),
"offers": copy.deepcopy(sorted(OFFERS.values(), key=lambda o: (
OFFER_CATEGORIES.index(o["template"]["category"]), o["template"]["name"])))}
def put_offer(self, template_id):
length = int(self.headers.get("Content-Length") or 0)
try:
payload = json.loads(self.rfile.read(length) or b"{}")
except ValueError:
payload = None
if not isinstance(payload, dict) or not isinstance(payload.get("subscribed"), bool):
self.fail(422, "invalid_input", "subscribed must be a boolean")
return
price = payload.get("price", "default")
if payload["subscribed"] and not (price == "default" or (
isinstance(price, (int, float)) and not isinstance(price, bool) and price > 0)):
self.fail(422, "invalid_input", "price must be \"default\" or a number > 0")
return
with LOCK:
o = OFFERS.get(template_id)
if o is None:
self.fail(404, "not_found", "unknown template")
return
if payload["subscribed"] and o["fits"] is False:
self.fail(409, "does_not_fit", o["fit_reason"])
return
if payload["subscribed"]:
o["subscribed"], o["state"] = True, "healthy"
o["deployment_id"] = o["deployment_id"] or "stub-dep-" + template_id
if price == "default":
o["price_mode"], o["price_per_hour"] = "auto", o["default_price_per_hour"]
else:
o["price_mode"], o["price_per_hour"] = "fixed", price
else:
o.update(subscribed=False, price_mode=None, price_per_hour=None, deployment_id=None, state=None)
out = copy.deepcopy(o)
time.sleep(0.4) self.reply(200, out)
def logs(self, path):
if self.command != "GET":
self.fail(405, "method_not_allowed", "%s not allowed on %s" % (self.command, path))
return
if not state.is_admin:
self.fail(403, "admin_only", "Log access is for admin accounts")
return
now = now_iso()
if path == "/v2/logs":
files = [{"name": n, "size": sum(len(l) + 1 for l in ls) * 40, "modified": now} for n, ls in LOGS.items()]
self.reply(200, {"files": files})
return
name = unquote(path[len("/v2/logs/"):])
if name not in LOGS:
self.fail(404, "not_found", "no such log")
return
try:
n = int(parse_qs(urlsplit(self.path).query).get("tail", ["500"])[0])
except ValueError:
n = 500
n = max(1, min(5000, n))
ls = LOGS[name]
self.reply(200, {"name": name, "lines": ls[-n:], "truncated": len(ls) > n,
"size": sum(len(l) + 1 for l in ls) * 40, "modified": now})
def route(self):
if not self.guard():
return
path = urlsplit(self.path).path
if path == "/v2/logs" or path.startswith("/v2/logs/"):
self.logs(path)
return
if path == "/v2/offers" and self.command == "GET":
self.reply(200, self.offers())
return
if path.startswith(OFFER_PREFIX) and self.command == "PUT":
self.put_offer(path[len(OFFER_PREFIX):])
return
methods = ROUTES.get(path)
if methods is None:
self.fail(404, "not_found", path)
return
if self.command not in methods:
self.fail(405, "method_not_allowed", "%s not allowed on %s" % (self.command, path))
return
if self.command == "PUT":
self.handle_put(path)
else:
self.reply(200, self.summary())
do_GET = do_POST = do_PUT = do_DELETE = do_PATCH = do_HEAD = do_OPTIONS = route
return Handler
def main():
parser = argparse.ArgumentParser(description="Stub of the zc agent local API v1")
parser.add_argument("--port", type=int, default=4720)
parser.add_argument("--home", default="~/.zakuro-stub")
parser.add_argument("--token", default="stub-token")
parser.add_argument("--fixture", default=str(DEFAULT_FIXTURE))
parser.add_argument("--fail-price", action="store_true", help="answer PUT /v1/price with 502 hub_error")
parser.add_argument("--not-admin", action="store_true", help="account.is_admin false; /v2/logs answers 403 admin_only")
parser.add_argument("--summary-version", type=int, default=1, help="serve this v (2 exercises 'Update zc')")
parser.add_argument("--problem", action="append", default=None, help="replace problems with these codes")
args = parser.parse_args()
summary = json.loads(Path(args.fixture).read_text())
summary["v"] = args.summary_version
if args.problem is not None:
summary["problems"] = [
{"code": code, "message": "stub: %s" % code, "hint": "stub hint for %s" % code, "detail": None}
for code in args.problem
]
path = write_agent_json(args.home, args.port, args.token)
handler = make_handler(State(summary, args.fail_price, not args.not_admin), args.port, args.token)
server = ThreadingHTTPServer(("127.0.0.1", args.port), handler)
print("stub agent on http://127.0.0.1:%d (token %r); agent.json at %s" % (args.port, args.token, path))
print("point the app at it: defaults write ai.zakuro.Zakuro ZakuroHome %s" % Path(args.home).expanduser())
try:
server.serve_forever()
except KeyboardInterrupt:
pass
finally:
server.server_close()
if __name__ == "__main__":
main()