mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
271 lines
23 KiB
HTML
271 lines
23 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0119</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hip-0119.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0119">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0119.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hip-0119</h1><p class="lede">HIP-119: Hanzo Service Conventions. Status Final. Hanzo architectural specification.</p><h1>HIP-0119: Hanzo Service Conventions</h1>
|
|
<h2>Abstract</h2>
|
|
<p>This is the one and only shape of a Hanzo backend service. Every first-party service — across Hanzo, <strong>and across Lux (LPs) and Zoo (ZIPs), which run on the same substrate</strong> — exposes the same listeners on the same ports, serves its API under the same prefix, answers health on the same paths, ships metrics the same way, is configured by the same environment variables, and is deployed by the same operator through the same CRD. Read this one document and you can build, deploy, probe, observe, and call any service in the estate without guessing.</p>
|
|
<p>It exists because the shape had drifted. The same service's liveness path was written three different ways in three places — <code>/api/health</code> in the committed manifest, <code>/v1/health</code> in the live cluster, <code>/health</code> in the binary — and a deploy that should have been a version bump became an outage. That is the cost of an unstated contract. This HIP states it.</p>
|
|
<p>The governing principle is <strong>decomplection</strong> (Hickey) expressed with <strong>one obvious way</strong> (Pike): product traffic and operational traffic are different concerns, so they live on different listeners; health is not an API call, so it is not versioned; readiness and liveness are different questions, so they have different paths. Nothing here is novel. It is the absence of choice that is the feature.</p>
|
|
<p>HIP-0400 defines the <code>Service</code>/<code>LLM</code> CRD (the deployment <em>mechanism</em>). HIP-0112 defines the request path through the estate (the <em>topology</em>). This HIP defines the <em>service itself</em> — the contract a process MUST satisfy to be a citizen of the platform. Where they touch, this HIP is authoritative on the service's own surface.</p>
|
|
<h2>Specification</h2>
|
|
<p>The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as in RFC 2119.</p>
|
|
<h3>§1 Two listeners, orthogonal</h3>
|
|
<p>A service MUST bind exactly two HTTP listeners, and they MUST NOT share a port:</p>
|
|
<p>| Listener | Port (default) | Env override | Serves | Auth | |----------|----------------|--------------|--------|------| | <strong>app</strong> | <code>8080</code> | <code>CLOUD_LISTEN</code> | the product API, under <code>/v1/*</code> only | per HIP-0111 | | <strong>ops</strong> | <code>9090</code> | <code>CLOUD_HEALTH_LISTEN</code> | <code>/healthz</code>, <code>/readyz</code>, <code>/metrics</code> | none (cluster-internal) |</p>
|
|
<p>The split is the contract, not an optimization. Operational traffic (probes, scrapes, drains) MUST NOT traverse the app listener, and the app listener MUST NOT serve operational endpoints. This is what makes a readiness flap independent of API load, lets <code>NetworkPolicy</code> expose <code>:9090</code> only to the cluster, and means a probe never carries a JWT. A service MAY bind additional protocol listeners (e.g. a ZAP transport per HIP-0114, gRPC); those are declared the same way, on their own ports, and are out of scope here.</p>
|
|
<h3>§2 API surface — <code>/v1/</code> and only <code>/v1/</code></h3>
|
|
<p>Every product endpoint MUST live under <code>/v1/</code>. A service MUST NOT serve a product endpoint at the root, under <code>/api/</code>, or under any other version prefix. The API evolves <strong>forward only</strong>: changes are additive, and <code>/v2</code> MUST NOT be introduced — breaking changes are made by adding fields/endpoints under <code>/v1</code>, never by versioning the namespace. (<code>api.<brand></code> is already the host; an <code>/api/</code> path prefix on top of it is redundant and is forbidden.)</p>
|
|
<h3>§3 Health and readiness — on the ops listener, unversioned</h3>
|
|
<p>Health is infrastructure, not API, so it is not versioned and it is not on the app listener.</p>
|
|
<ul><li><strong><code>GET /healthz</code></strong> (liveness) — MUST return <code>200</code> while the process is running</li></ul>
|
|
<p> and not wedged. It MUST NOT check downstream dependencies. A failing <code>/healthz</code> means "restart me."</p>
|
|
<ul><li><strong><code>GET /readyz</code></strong> (readiness) — MUST return <code>200</code> only when the service can serve</li></ul>
|
|
<p> product traffic (migrations applied, required deps reachable, caches warm). It MUST return <code>503</code> otherwise. A failing <code>/readyz</code> means "take me out of rotation," not "restart me."</p>
|
|
<p>Both MUST be on the <strong>ops</strong> listener (<code>:9090</code>), unauthenticated, and respond in under one second. Per-subsystem detail (e.g. <code>/v1/<sub>/health</code> inside a composed binary per HIP-0106) MAY exist on the app listener for diagnostics, but MUST NOT be what Kubernetes probes; probes target the ops listener.</p>
|
|
<h3>§4 Observability — <code>/metrics</code> on the ops listener</h3>
|
|
<p>A service MUST expose Prometheus metrics at <strong><code>GET /metrics</code></strong> on the ops listener. It MUST NOT expose <code>/metrics</code> on the app listener.</p>
|
|
<h3>§5 Configuration — environment, deterministic names</h3>
|
|
<p>Configuration is by environment variable. Names are stable and shared: <code>CLOUD_LISTEN</code>, <code>CLOUD_HEALTH_LISTEN</code>, <code>LOG_LEVEL</code>, <code>BRAND</code>, <code>DOMAIN</code>. Identity, datastore, and secret material follow the referenced HIPs (<code>IAM_*</code> per HIP-0111, <code>KMS_*</code> per HIP-0027). A service MUST start with zero required flags — every input has a documented env var and a working default for local single-node dev. Secrets MUST come from KMS (HIP-0027) and MUST NOT be baked into the image or committed in plaintext.</p>
|
|
<h3>§6 Identity & secrets</h3>
|
|
<p>Authentication and token validation MUST be done exactly as HIP-0111 specifies (<code>@hanzo/iam</code>, <code>/v1/iam/oauth/*</code>, <code><org>-<app></code> client IDs). Secrets MUST be sourced from KMS per HIP-0027. Neither is redefined here.</p>
|
|
<h3>§7 Deployment — the operator, through the CRD, and nothing else</h3>
|
|
<p>A first-party service MUST be deployed by the <strong>hanzo-operator</strong> reconciling a <code>Service</code> or <code>LLM</code> custom resource (HIP-0400). The CR is the single source of truth for image, ports, probes, env, and ingress; its committed form lives in <code>universe/infra/k8s/operator/crs/<svc>-v1.yaml</code>. Rolling a new version is one edit to <code>spec.image.tag</code> (the operator regenerates and rolls the Deployment). The CR's probe defaults MUST target the ops listener per §3; a service that follows this HIP does not specify probes per-deployment.</p>
|
|
<p>Out-of-band deploy paths — hand-run <code>kubectl</code>, bespoke GitHub Actions that <code>doctl</code>+<code>kubectl apply</code>, or the Dokploy PaaS (which is for <em>user</em> applications) — MUST NOT be the deploy mechanism for first-party platform services. There is one path; drift between a committed manifest and the live cluster is a defect, not a state.</p>
|
|
<h3>§8 Image & naming</h3>
|
|
<ul><li>Images are <code>ghcr.io/<org>/<svc>:vX.Y.Z</code> — <strong>v-prefixed semver</strong>. Floating tags</li></ul>
|
|
<p> (<code>:latest</code>, <code>:main</code>, branch names) MUST NOT be deployed (per HIP-0036).</p>
|
|
<ul><li>IAM client IDs are <code><org>-<app></code> (HIP-0111).</li><li>One service, one repo, one image, one CR. A binary that composes subsystems</li></ul>
|
|
<p> (HIP-0106) is still one service with one app listener and one ops listener.</p>
|
|
<h3>§9 Forbidden — the anti-patterns this HIP exists to kill</h3>
|
|
<ul><li>An <code>/api/</code> path prefix on any endpoint.</li><li>A versioned health path (<code>/v1/health</code>, <code>/v2/healthz</code>).</li><li>Health, readiness, or metrics on the <strong>app</strong> listener.</li><li>Kubernetes probes pointed at the app listener or at a product/API path.</li><li>A single listener serving both product and operational traffic.</li><li>Per-service bespoke ports for the same role (everyone's app is <code>:8080</code>, ops is</li></ul>
|
|
<p> <code>:9090</code>).</p>
|
|
<ul><li>Floating image tags in a CR; hand-deployed drift; a second deploy mechanism.</li></ul>
|
|
<h3>§10 One contract across Hanzo, Lux, and Zoo</h3>
|
|
<p>Lux and Zoo run on this same substrate (shared IAM, KMS, operator, gateway, ingress) under white-label branding. <strong>LPs and ZIPs adopt this HIP by reference and MUST NOT restate or fork the service contract.</strong> What differs between ecosystems is <em>values</em> — brand, domain, theme, the org segment of <code><org>-<app></code> and <code>ghcr.io/<org>/…</code> — never <em>shape</em>. An LP or ZIP that needs a backend service points at HIP-0119; the contract is identical up, down, left, right, in, and out. That identity is the whole point: it is what makes the platform one way.</p>
|
|
<h2>Reference implementation</h2>
|
|
<p><code>hanzo/cloud</code> (HIP-0106) is the reference: it binds the app listener (<code>CLOUD_LISTEN</code>, <code>:8080</code>) for <code>/v1/*</code> and the ops listener (<code>CLOUD_HEALTH_LISTEN</code>, <code>:9090</code>) for <code>/healthz</code>, <code>/readyz</code>, <code>/metrics</code>; the <code>cloud-api</code> <code>Service</code> CR probes the ops listener. iam and gateway follow the same split.</p>
|
|
<h2>Conformance checklist (build a service against this in one pass)</h2>
|
|
<ol><li>App listener on <code>:8080</code> (<code>CLOUD_LISTEN</code>); every product route under <code>/v1/</code>. No <code>/api/</code>.</li><li>Ops listener on <code>:9090</code> (<code>CLOUD_HEALTH_LISTEN</code>, default</li></ol>
|
|
<p> <code>127.0.0.1:9090</code>): <code>/healthz</code> (liveness, no deps), <code>/readyz</code> (readiness, deps), <code>/metrics</code> (Prometheus). Unauthenticated.</p>
|
|
<ol><li>Probes (in the CR) target <code>:9090/healthz</code> and <code>:9090/readyz</code>.</li><li>Starts with zero required flags; secrets from KMS (HIP-0027); auth via</li></ol>
|
|
<p> <code>@hanzo/iam</code> (HIP-0111).</p>
|
|
<ol><li>Image <code>ghcr.io/<org>/<svc>:vX.Y.Z</code>; deployed by one <code>Service</code>/<code>LLM</code> CR</li></ol>
|
|
<p> (HIP-0400) reconciled by the operator.</p>
|
|
<ol><li>Nothing from §9.</li></ol>
|
|
<h2>References</h2>
|
|
<ul><li>HIP-0027 Secrets Management · HIP-0519 One Identity Boundary</li><li>HIP-0068 Ingress · HIP-0106 Unified Cloud Binary · HIP-0111 IAM Authentication</li><li>HIP-0132 One Telemetry Plane · HIP-0400 Service CRD</li></ul>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hip-0119.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |