The admin API described in OpenAPI 3.1: generated from a route table by docgen, served at /api/v1/openapi.json

adminapi.Routes lists every endpoint with its query parameters and Go values
of the bodies it reads and answers with; internal/docgen/openapi turns that
into docs/admin-api.openapi.json by reflection, the way encoding/json encodes
the types, with the fields' comments as descriptions. A test fails when an
endpoint is registered and not in the table, another when the committed
document is stale. The binary embeds it and serves it with the token.

Handlers that wrote map literals and decoded anonymous structs now use named
types, so the document can see them. GET /api/v1/models/{name} answers with a
model's whole definition as it is in force, which a tool managing it needs.
docs/admin-api.md: reaching the API, the token, what a request must carry.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5.5 committed 2026-10-04 23:47:59 +02:00
1 parent 30f7f3474a
commit a95c519bc5
17 files changed
+7643 -62

No files matched your search

+46 -19
View File
@@ -75,13 +75,26 @@ func (a *API) SetRevoker(f func(ctx context.Context, nodeID string, at time.Time
a.revoke = f
}
// Mux is where the endpoints are mounted. An *http.ServeMux is one; a test
// that records the patterns is another, and is how the route table is checked
// against what is actually served.
type Mux interface {
HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
}
// Register mounts the endpoints on a mux under /api/v1.
func (a *API) Register(mux *http.ServeMux) {
//
// Every pattern registered here, or by the register helpers it calls, must
// also be in Routes: that table is what the OpenAPI document is generated
// from, and a test fails when the two disagree.
func (a *API) Register(mux Mux) {
mux.HandleFunc("GET /api/v1/summary", a.summary)
// Adding a model is a write, and the only one this API has. It lives here
// rather than on the client-facing listener for the same reason the rest of
// it does: reaching this port already means holding the control plane.
mux.HandleFunc("GET /api/v1/openapi.json", serveOpenAPI)
// Changes to the catalog live here rather than on the client-facing
// listener for the same reason the rest of this does: reaching this port
// already means holding the control plane.
mux.HandleFunc("POST /api/v1/models", a.addModel)
mux.HandleFunc("GET /api/v1/models/{name}", a.getModel)
mux.HandleFunc("DELETE /api/v1/models/{name}", a.removeModel)
mux.HandleFunc("POST /api/v1/models/{name}/scale", a.scaleModel)
mux.HandleFunc("POST /api/v1/models/{name}/resources", a.setResources)
@@ -97,9 +110,7 @@ func (a *API) Register(mux *http.ServeMux) {
writeError(w, http.StatusNotImplemented, "this control plane has no store")
return
}
var req struct {
Class string `json:"class"`
}
var req ClassRequest
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "the request is not valid JSON: "+err.Error())
return
@@ -109,7 +120,7 @@ func (a *API) Register(mux *http.ServeMux) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"model": m.Name, "class": m.EffectiveClass()})
writeJSON(w, http.StatusOK, ClassView{Model: m.Name, Class: m.EffectiveClass()})
})
mux.HandleFunc("PUT /api/v1/models/{name}/capacity", a.putCapacity)
mux.HandleFunc("GET /api/v1/capacity", a.listCapacity)
@@ -953,7 +964,25 @@ func (a *API) addModel(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"added": m.Name})
writeJSON(w, http.StatusOK, ModelAdded{Added: m.Name})
}
// getModel answers with one model's whole definition as it is in force: what
// was added, with the defaults the catalog filled in. The listing shows a
// model's state and only the names of its profiles; this is what a tool
// managing the definition — Terraform, say — compares against what it wants.
//
// By its name only, not an alias: an alias answering would let a tool believe
// a model it manages exists when it is another one.
func (a *API) getModel(w http.ResponseWriter, r *http.Request) {
name := r.PathValue("name")
for _, m := range a.ctl.Catalog().Models() {
if m.Name == name {
writeJSON(w, http.StatusOK, m)
return
}
}
writeError(w, http.StatusNotFound, "no model named "+name+" is in the catalog")
}
// ScaleRequest is how many replicas a model should run.
@@ -1039,7 +1068,7 @@ func (a *API) removeModel(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"removed": name})
writeJSON(w, http.StatusOK, Removed{Removed: name})
}
func (a *API) summary(w http.ResponseWriter, _ *http.Request) {
@@ -1137,15 +1166,13 @@ func (a *API) removeNode(w http.ResponseWriter, r *http.Request) {
}
inv.Remove(id)
a.ctl.Reconciler().Notify()
writeJSON(w, http.StatusOK, map[string]string{"id": id, "removed": "true"})
writeJSON(w, http.StatusOK, NodeRemoved{ID: id, Removed: "true"})
}
func (a *API) setNodeState(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id")
var body struct {
State string `json:"state"`
}
var body NodeStateRequest
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
@@ -1173,7 +1200,7 @@ func (a *API) setNodeState(w http.ResponseWriter, r *http.Request) {
// is usually about to do something to it.
a.ctl.Reconciler().Notify()
writeJSON(w, http.StatusOK, map[string]string{"id": id, "state": st.String()})
writeJSON(w, http.StatusOK, NodeStateView{ID: id, State: st.String()})
}
func writeJSON(w http.ResponseWriter, code int, v any) {
@@ -1183,7 +1210,7 @@ func writeJSON(w http.ResponseWriter, code int, v any) {
}
func writeError(w http.ResponseWriter, code int, msg string) {
writeJSON(w, code, map[string]string{"error": msg})
writeJSON(w, code, ErrorView{Error: msg})
}
// profileChanged reports whether a replica is running a profile the catalog no
@@ -1384,7 +1411,7 @@ func (a *API) retryModel(w http.ResponseWriter, r *http.Request) {
return
}
was := a.ctl.Reconciler().Retry(name)
writeJSON(w, http.StatusOK, map[string]bool{"was_parked": was})
writeJSON(w, http.StatusOK, RetryView{WasParked: was})
}
// requestFinder looks a request up by the id it was given. Asked of the usage
@@ -1477,7 +1504,7 @@ func (a *API) upgradeNode(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadGateway, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"node": r.PathValue("id"), "version": req.Version})
writeJSON(w, http.StatusOK, UpgradeView{Node: r.PathValue("id"), Version: req.Version})
}
// SetServe supplies what serves a model from the registry.
@@ -1577,7 +1604,7 @@ func (a *API) rollbackModel(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"result": msg})
writeJSON(w, http.StatusOK, Result{Result: msg})
}
// OriginRequest names the repository a model's weights came from.
+10 -6
View File
@@ -8,7 +8,13 @@ import (
"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
)
func (a *API) registerCanary(mux *http.ServeMux) {
// CanaryPercentRequest changes the share of a model's requests its canary
// takes.
type CanaryPercentRequest struct {
Percent int `json:"percent"`
}
func (a *API) registerCanary(mux Mux) {
need := func(w http.ResponseWriter) bool {
if a.serve == nil {
writeError(w, http.StatusNotImplemented, "a canary needs a mirror and a store, and this control plane lacks one")
@@ -45,9 +51,7 @@ func (a *API) registerCanary(mux *http.ServeMux) {
if !need(w) {
return
}
var req struct {
Percent int `json:"percent"`
}
var req CanaryPercentRequest
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "the request is not valid JSON: "+err.Error())
return
@@ -57,7 +61,7 @@ func (a *API) registerCanary(mux *http.ServeMux) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"result": msg})
writeJSON(w, http.StatusOK, Result{Result: msg})
})
mux.HandleFunc("DELETE /api/v1/models/{name}/canary", func(w http.ResponseWriter, r *http.Request) {
if !need(w) {
@@ -68,7 +72,7 @@ func (a *API) registerCanary(mux *http.ServeMux) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"result": msg})
writeJSON(w, http.StatusOK, Result{Result: msg})
})
mux.HandleFunc("POST /api/v1/models/{name}/promote", func(w http.ResponseWriter, r *http.Request) {
if !need(w) {
+1 -4
View File
@@ -34,10 +34,7 @@ type RailView struct {
// sends traffic over the fabric for seconds a rail, so it is a POST and only
// ever run when asked.
func (a *API) fabricTest(w http.ResponseWriter, r *http.Request) {
var body struct {
A, B, Fabric string
Seconds int
}
var body FabricTestRequest
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
+12 -7
View File
@@ -66,7 +66,17 @@ func (a *API) guardTarget(ctx context.Context, target string) (guard.Attachment,
return guard.Attachment{}, fmt.Errorf("%q: attach to org, team, project, key or user", kind)
}
func (a *API) registerGuard(mux *http.ServeMux) {
// GuardAttachmentRequest attaches a policy to a part of the tenancy tree, a
// key or a person, or with DELETE takes it off again.
type GuardAttachmentRequest struct {
// Target is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT (or the ID
// after the colon), key:KEY-ID or user:USER-ID.
Target string `json:"target"`
// Policy is a policy's name in server.yaml's guard.policies.
Policy string `json:"policy"`
}
func (a *API) registerGuard(mux Mux) {
mux.HandleFunc("GET /api/v1/guard", func(w http.ResponseWriter, r *http.Request) {
if a.guard == nil {
writeError(w, http.StatusNotImplemented, "no guard policies: define them under guard: in server.yaml")
@@ -97,12 +107,7 @@ func (a *API) registerGuard(mux *http.ServeMux) {
writeError(w, http.StatusNotImplemented, "no guard policies: define them under guard: in server.yaml")
return
}
var at struct {
// Target is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT
// (or the ID after the colon), key:KEY-ID or user:USER-ID.
Target string `json:"target"`
Policy string `json:"policy"`
}
var at GuardAttachmentRequest
if err := json.NewDecoder(r.Body).Decode(&at); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
+24 -7
View File
@@ -50,7 +50,26 @@ type QuotaRequest struct {
Limit store.Resources `json:"limit"`
}
func (a *API) registerQuotas(mux *http.ServeMux) {
// QuotaSet is the scope a quota was set on, as org:ID, team:ID or
// project:ID whatever name it was asked by.
type QuotaSet struct {
Scope string `json:"scope"`
}
// OwnerRequest sets the part of the tenancy tree a model's capacity counts
// against: org:NAME, team:ORG/TEAM or project:ORG/TEAM/PROJECT, or their IDs.
// Empty makes the model shared.
type OwnerRequest struct {
Owner string `json:"owner"`
}
// OwnerView is a model's owner now, as scope:ID.
type OwnerView struct {
Model string `json:"model"`
Owner string `json:"owner"`
}
func (a *API) registerQuotas(mux Mux) {
mux.HandleFunc("GET /api/v1/quotas", func(w http.ResponseWriter, r *http.Request) {
if a.quotas == nil {
writeError(w, http.StatusNotImplemented, "this control plane has no store")
@@ -78,7 +97,7 @@ func (a *API) registerQuotas(mux *http.ServeMux) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"scope": key})
writeJSON(w, http.StatusOK, QuotaSet{Scope: key})
})
mux.HandleFunc("DELETE /api/v1/quotas/{scope}", func(w http.ResponseWriter, r *http.Request) {
if a.quotas == nil {
@@ -90,16 +109,14 @@ func (a *API) registerQuotas(mux *http.ServeMux) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"removed": key})
writeJSON(w, http.StatusOK, Removed{Removed: key})
})
mux.HandleFunc("POST /api/v1/models/{name}/owner", func(w http.ResponseWriter, r *http.Request) {
if a.models == nil || a.quotas == nil {
writeError(w, http.StatusNotImplemented, "this control plane has no store")
return
}
var req struct {
Owner string `json:"owner"`
}
var req OwnerRequest
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "the request is not valid JSON: "+err.Error())
return
@@ -118,7 +135,7 @@ func (a *API) registerQuotas(mux *http.ServeMux) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"model": m.Name, "owner": m.Owner})
writeJSON(w, http.StatusOK, OwnerView{Model: m.Name, Owner: m.Owner})
})
}
+84
View File
@@ -0,0 +1,84 @@
package adminapi
// The small bodies the endpoints read and answer with. Named types rather
// than maps and anonymous structs, so the OpenAPI document generated from
// Routes describes exactly what a handler decodes and writes: a map literal
// in a handler is a shape no generator can see.
// ErrorView is every refusal: a 4xx or 5xx status with what went wrong.
type ErrorView struct {
Error string `json:"error"`
}
// Result is what a change that has no other answer says it did.
type Result struct {
Result string `json:"result"`
}
// ModelAdded names the model added to the catalog.
type ModelAdded struct {
Added string `json:"added"`
}
// Removed names what was taken away: a model, or a quota's scope.
type Removed struct {
Removed string `json:"removed"`
}
// ClassRequest sets a model's capacity class: critical, standard or
// opportunistic, or empty to go back to what its scaling implies.
type ClassRequest struct {
Class string `json:"class"`
}
// ClassView is a model's capacity class now.
type ClassView struct {
Model string `json:"model"`
Class string `json:"class"`
}
// RetryView says whether the model had been parked, given up on after
// failing to start, before it was retried.
type RetryView struct {
WasParked bool `json:"was_parked"`
}
// NodeStateRequest cordons, drains or readies a node: ready (or uncordon),
// cordoned (or cordon), draining (or drain).
type NodeStateRequest struct {
State string `json:"state"`
}
// NodeStateView is a node's state after the change.
type NodeStateView struct {
ID string `json:"id"`
State string `json:"state"`
}
// NodeRemoved names the node forgotten. Removed is the string "true".
type NodeRemoved struct {
ID string `json:"id"`
Removed string `json:"removed"`
}
// UpgradeView is the release a node was told to run.
type UpgradeView struct {
Node string `json:"node"`
Version string `json:"version"`
}
// FabricTestRequest is a bandwidth test between two nodes.
type FabricTestRequest struct {
A string `json:"a"`
B string `json:"b"`
// Fabric is the declared fabric to test over; empty is the one the two
// nodes share.
Fabric string `json:"fabric,omitempty"`
// Seconds each rail is measured for, from 1 to 30.
Seconds int `json:"seconds,omitempty"`
}
// ReplayRequest names the model a kept request is sent to again.
type ReplayRequest struct {
Model string `json:"model"`
}
+1 -3
View File
@@ -60,9 +60,7 @@ func (a *API) replayRequest(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusNotImplemented, "this control plane does not route requests")
return
}
var req struct {
Model string `json:"model"`
}
var req ReplayRequest
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil || req.Model == "" {
writeError(w, http.StatusBadRequest, "say which model: {\"model\": \"...\"}")
return
+249
View File
@@ -0,0 +1,249 @@
package adminapi
import (
"net/http"
llmgw "gitea.mynodes.xyz/ilker/llmgw"
"gitea.mynodes.xyz/ilker/llmgw/internal/bench"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/fabrics"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/modelserve"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/nvlink"
"gitea.mynodes.xyz/ilker/llmgw/internal/guard"
"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
"gitea.mynodes.xyz/ilker/llmgw/internal/store"
)
// Route is one endpoint as the OpenAPI document describes it.
//
// A table written by hand beside Register rather than read out of the
// handlers, because what a handler decodes and answers is not visible from
// outside it. The table is checked against Register by a test, so an endpoint
// cannot be added without being described; the bodies are Go values whose
// types the generator reads, so a field added to one is in the document the
// next time it is generated.
type Route struct {
Method string
Path string
// Summary is one line; Description, when there is more to say, the rest.
Summary string
Description string
// Query is the query parameters the handler reads.
Query []Param
// Request is a value of the body's type; nil reads none.
Request any
// OptionalBody is set when the body may be left out.
OptionalBody bool
// Response is a value of the type a success answers with.
Response any
// Status is the success status; zero is 200.
Status int
// CSV is set when the answer is CSV unless JSON is asked for.
CSV bool
}
// Param is a query parameter.
type Param struct {
Name string
Description string
// Type is a JSON Schema type: string when empty, or integer, number,
// boolean.
Type string
Required bool
}
// PathParams describes the parameters in Routes' paths, by the segment
// before them and their name.
var PathParams = map[string]string{
"models/{name}": "The model's name in the catalog.",
"nodes/{id}": "The node's ID, as `llmgw ctl nodes` lists it.",
"jobs/{id}": "The job's ID, as starting it answered.",
"requests/{id}": "The request's ID: the x-request-id a client was answered with.",
"fabrics/{id}": "The physical fabric's ID, as GET /api/v1/fabrics lists it.",
"quotas/{scope}": "The scope: org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT, or their IDs after the colon.",
}
// Routes is every endpoint Register mounts.
var Routes = []Route{
// The document itself.
{Method: "GET", Path: "/api/v1/openapi.json", Summary: "This document",
Description: "The admin API in OpenAPI 3.1, generated from the route table and built into the binary.",
Response: map[string]any{}},
// The fleet.
{Method: "GET", Path: "/api/v1/summary", Summary: "The whole fleet in one answer",
Response: Summary{}},
{Method: "GET", Path: "/api/v1/nodes", Summary: "Every node, with its cards, load and fabrics",
Response: []NodeView{}},
{Method: "POST", Path: "/api/v1/nodes/{id}/state", Summary: "Cordon, drain or ready a node",
Request: NodeStateRequest{}, Response: NodeStateView{}},
{Method: "POST", Path: "/api/v1/nodes/{id}/upgrade", Summary: "Have a node run a release",
Request: UpgradeRequest{}, Response: UpgradeView{}},
{Method: "POST", Path: "/api/v1/nodes/{id}/engines", Summary: "Choose an engine's build for a node",
Description: "The node installs the build chosen. Build is auto, a build such as cu129, or none.",
Request: NodeEngineRequest{}, Response: NodeEngineRequest{}},
{Method: "DELETE", Path: "/api/v1/nodes/{id}", Summary: "Forget a node that has gone",
Description: "Only a node that is lost, or unreachable with nothing on it; its certificate is revoked.",
Response: NodeRemoved{}},
{Method: "GET", Path: "/api/v1/nodes/{id}/logs", Summary: "The last lines of a node's logs",
Query: []Param{
{Name: "lines", Type: "integer", Description: "How many lines; 300 when absent, at most 2000."},
{Name: "source", Description: "Which log: agent when absent, or an engine the node lists in sources."},
},
Response: LogsView{}},
{Method: "GET", Path: "/api/v1/fabrics", Summary: "The physical fabrics and the names nodes give them",
Response: fabrics.Report{}},
{Method: "GET", Path: "/api/v1/fabrics/{id}/topology", Summary: "One fabric's map, with the cluster's adapters live on it",
Response: TopologyView{}},
{Method: "GET", Path: "/api/v1/nvlink", Summary: "The multi-node NVLink domains and what keeps nodes out of them",
Response: nvlink.Report{}},
{Method: "POST", Path: "/api/v1/fabric-test", Summary: "Measure bandwidth between two nodes, rail by rail",
Request: FabricTestRequest{}, Response: FabricTestView{}},
{Method: "GET", Path: "/api/v1/weights/orphans", Summary: "Weights on nodes that no model uses",
Response: []OrphanView{}},
{Method: "POST", Path: "/api/v1/weights/collect", Summary: "Delete weights that no model uses",
Request: CollectRequest{}, OptionalBody: true, Response: []CollectResult{}},
// The catalog.
{Method: "GET", Path: "/api/v1/models", Summary: "Every model, with its replicas and state",
Response: []ModelView{}},
{Method: "POST", Path: "/api/v1/models", Summary: "Add a model to the catalog",
Description: "Kept in the store across restarts. Refused when the name is taken, a model in " +
"configuration has it, or the definition would make the catalog invalid.",
Request: catalog.Model{}, Response: ModelAdded{}},
{Method: "GET", Path: "/api/v1/models/{name}", Summary: "One model's definition, as it is in force",
Description: "With the defaults the catalog filled in. By its name only, not an alias.",
Response: catalog.Model{}},
{Method: "DELETE", Path: "/api/v1/models/{name}", Summary: "Remove a model added at runtime",
Description: "A model declared in configuration is refused: it would come back on the next restart.",
Response: Removed{}},
{Method: "POST", Path: "/api/v1/models/{name}/scale", Summary: "Set how many replicas a model runs",
Request: ScaleRequest{}, Response: ScaleResponse{}},
{Method: "POST", Path: "/api/v1/models/{name}/resources", Summary: "Set what a model's profiles reserve of a node",
Request: ResourcesRequest{}, Response: catalog.Model{}},
{Method: "POST", Path: "/api/v1/models/{name}/class", Summary: "Set a model's capacity class",
Request: ClassRequest{}, Response: ClassView{}},
{Method: "POST", Path: "/api/v1/models/{name}/owner", Summary: "Set the part of the tenancy tree a model's capacity counts against",
Request: OwnerRequest{}, Response: OwnerView{}},
{Method: "POST", Path: "/api/v1/models/{name}/adapters", Summary: "Replace a model's LoRA adapters",
Description: "Each new file is read first, to check it is an adapter for the model's architecture.",
Request: AdaptersRequest{}, Response: AdaptersRequest{}},
{Method: "POST", Path: "/api/v1/models/{name}/retry", Summary: "Try a parked model again",
Response: RetryView{}},
{Method: "GET", Path: "/api/v1/models/{name}/target", Summary: "How many replicas a throughput needs, and whether they fit",
Query: []Param{{Name: "tokens_per_sec", Type: "number", Required: true,
Description: "The output tokens a second wanted of the model."}},
Response: TargetView{}},
{Method: "GET", Path: "/api/v1/models/{name}/headroom", Summary: "How many more replicas of a model fit now, and where",
Query: []Param{{Name: "limit", Type: "integer",
Description: "The most to try placing; 16 when absent or past 64."}},
Response: HeadroomView{}},
{Method: "PUT", Path: "/api/v1/models/{name}/capacity", Summary: "Record what a replica was measured to serve",
Description: "Replaces an earlier measurement of the same model on the same profile.",
Request: bench.Capacity{}, Response: bench.Capacity{}},
{Method: "GET", Path: "/api/v1/capacity", Summary: "Every recorded measurement",
Response: []CapacityView{}},
{Method: "GET", Path: "/api/v1/replicas", Summary: "Every replica, with its shards",
Query: []Param{{Name: "model", Description: "Only this model's replicas."}},
Response: []ReplicaView{}},
{Method: "GET", Path: "/api/v1/explain-placement", Summary: "Why a model could not be placed",
Query: []Param{{Name: "model", Required: true, Description: "The model's name or an alias."}},
Response: ExplainView{}},
{Method: "POST", Path: "/api/v1/restart", Summary: "Restart replicas, every replica of some models, or all",
Request: RestartRequest{}, Response: RestartResult{}, Status: http.StatusAccepted},
// Serving from the registry, and newer weights.
{Method: "GET", Path: "/api/v1/plan", Summary: "How a registry repository would be served here",
Query: []Param{
{Name: "repo", Required: true, Description: "The repository, owner/name."},
{Name: "format", Description: "gguf or safetensors; gguf when absent."},
{Name: "context", Type: "integer", Description: "The context length to plan for, in tokens."},
},
Response: modelserve.Plan{}},
{Method: "POST", Path: "/api/v1/models/serve", Summary: "Fetch a registry repository and serve it",
Request: modelserve.Request{}, Response: modelserve.Job{}, Status: http.StatusAccepted},
{Method: "GET", Path: "/api/v1/jobs", Summary: "Every job since the control plane started",
Response: []modelserve.Job{}},
{Method: "GET", Path: "/api/v1/jobs/{id}", Summary: "One job",
Response: modelserve.Job{}},
{Method: "GET", Path: "/api/v1/updates", Summary: "Newer weights the registry has for models",
Response: []modelserve.UpdateInfo{}},
{Method: "POST", Path: "/api/v1/updates/check", Summary: "Ask the registry now, about one model or every one",
Request: CheckRequest{}, OptionalBody: true, Response: []modelserve.UpdateInfo{}},
{Method: "POST", Path: "/api/v1/models/{name}/update", Summary: "Move a model to its repository's newer weights",
Response: modelserve.Job{}, Status: http.StatusAccepted},
{Method: "POST", Path: "/api/v1/models/{name}/rollback", Summary: "Go back to the weights the last update replaced",
Response: Result{}},
{Method: "POST", Path: "/api/v1/models/{name}/origin", Summary: "Record the repository a model's weights came from",
Request: OriginRequest{}, Response: OriginView{}},
{Method: "GET", Path: "/api/v1/canaries", Summary: "Every canary, and how its two sides serve",
Response: []modelserve.CanaryView{}},
{Method: "POST", Path: "/api/v1/models/{name}/canary", Summary: "Start a canary of a model's newer weights",
Request: catalog.Canary{}, Response: modelserve.Job{}, Status: http.StatusAccepted},
{Method: "PUT", Path: "/api/v1/models/{name}/canary", Summary: "Change the share of requests a canary takes",
Request: CanaryPercentRequest{}, Response: Result{}},
{Method: "DELETE", Path: "/api/v1/models/{name}/canary", Summary: "Take a canary out: its share first, then the candidate",
Response: Result{}},
{Method: "POST", Path: "/api/v1/models/{name}/promote", Summary: "Make a canary's weights the model's",
Response: modelserve.Job{}, Status: http.StatusAccepted},
// Tenancy: quotas and guardrails.
{Method: "GET", Path: "/api/v1/quotas", Summary: "Every capacity quota, with what its scope holds now",
Response: []QuotaView{}},
{Method: "PUT", Path: "/api/v1/quotas", Summary: "Set a scope's capacity quota",
Description: "Replaces the scope's quota whole. The scope may be named by path or by ID; the answer names it by ID.",
Request: QuotaRequest{}, Response: QuotaSet{}},
{Method: "DELETE", Path: "/api/v1/quotas/{scope}", Summary: "Remove a scope's capacity quota",
Response: Removed{}},
{Method: "GET", Path: "/api/v1/guard", Summary: "The guardrail policies and where they are attached",
Response: GuardView{}},
{Method: "POST", Path: "/api/v1/guard/attachments", Summary: "Attach a guardrail policy",
Request: GuardAttachmentRequest{}, Response: guard.Attachment{}},
{Method: "DELETE", Path: "/api/v1/guard/attachments", Summary: "Detach a guardrail policy",
Request: GuardAttachmentRequest{}, Response: guard.Attachment{}},
// Usage, requests and the record of changes.
{Method: "GET", Path: "/api/v1/usage", Summary: "What each group of the tenancy tree spent",
Query: []Param{
{Name: "by", Description: "org, team or project; team when absent."},
{Name: "since", Description: "A duration back from now, like 24h; 24h when absent."},
},
Response: []ScopeUsageView{}},
{Method: "GET", Path: "/api/v1/usage/export", Summary: "Usage totals by period and dimension, as CSV or JSON",
Query: []Param{
{Name: "from", Description: "A date (2026-09-01) or an RFC 3339 time; the first of this month when absent."},
{Name: "to", Description: "A date or an RFC 3339 time; now when absent."},
{Name: "period", Description: "hour, day or month; day when absent."},
{Name: "by", Description: "Dimensions, comma-separated: org, team, project, user, key, model."},
{Name: "format", Description: "json for JSON; CSV otherwise."},
},
Response: []store.ExportRow{}, CSV: true},
{Method: "GET", Path: "/api/v1/requests/{id}", Summary: "What one request went through",
Response: RequestView{}},
{Method: "GET", Path: "/api/v1/requests/{id}/body", Summary: "A kept request and its answer",
Response: store.RequestBody{}},
{Method: "POST", Path: "/api/v1/requests/{id}/replay", Summary: "Send a kept request again, to any model",
Request: ReplayRequest{}, Response: ReplayView{}},
{Method: "GET", Path: "/api/v1/audit", Summary: "Changes made, newest first",
Query: []Param{
{Name: "since", Description: "How far back: 90m, 24h, 7d; 7d when absent."},
{Name: "limit", Type: "integer", Description: "The most events to answer with."},
{Name: "actor", Description: "Only changes by this actor."},
{Name: "contains", Description: "Only events whose action or target contains this."},
},
Response: []store.AuditEvent{}},
// Operations.
{Method: "POST", Path: "/api/v1/notify/test", Summary: "Send a test notification to every webhook",
Response: []notify.Result{}},
{Method: "POST", Path: "/api/v1/metrics/range", Summary: "Several Prometheus range queries at once",
Description: "Read from the Prometheus monitoring.prometheus names; configured is false without one.",
Request: MetricsRequest{}, Response: MetricsResult{}},
}
// serveOpenAPI answers with the document generated from Routes, as it was
// when this binary was built.
func serveOpenAPI(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write(llmgw.AdminOpenAPI)
}
+119
View File
@@ -0,0 +1,119 @@
package adminapi
import (
"net/http"
"slices"
"strings"
"testing"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
)
// patterns records what Register mounts.
type patterns []string
func (p *patterns) HandleFunc(pattern string, _ func(http.ResponseWriter, *http.Request)) {
*p = append(*p, pattern)
}
func TestEveryRegisteredEndpointIsInTheRouteTable(t *testing.T) {
// The OpenAPI document is generated from Routes, so an endpoint missing
// from it is one no client generated from the document can call, and one
// in it that is not served is a promise the server breaks.
a, _ := setup(t, testModels())
var got patterns
a.Register(&got)
table := map[string]bool{}
for _, r := range Routes {
key := r.Method + " " + r.Path
if table[key] {
t.Errorf("%s is in Routes twice", key)
}
table[key] = true
}
served := map[string]bool{}
for _, p := range got {
served[p] = true
if !table[p] {
t.Errorf("%s is registered and not in Routes: describe it there", p)
}
}
for key := range table {
if !served[key] {
t.Errorf("%s is in Routes and not registered", key)
}
}
}
func TestEveryRouteSaysWhatItAnswers(t *testing.T) {
for _, r := range Routes {
if r.Summary == "" || r.Response == nil {
t.Errorf("%s %s needs a summary and a response type", r.Method, r.Path)
}
if r.Request != nil && (r.Method == "GET" || r.Method == "HEAD") {
t.Errorf("%s %s reads a body on a GET", r.Method, r.Path)
}
for _, seg := range strings.Split(strings.Trim(r.Path, "/"), "/") {
if !strings.HasPrefix(seg, "{") {
continue
}
found := false
for k := range PathParams {
if strings.HasSuffix(k, "/"+seg) && strings.Contains(r.Path, k) {
found = true
}
}
if !found {
t.Errorf("%s %s: %s is not described in PathParams", r.Method, r.Path, seg)
}
}
}
}
func TestTheAPIServesItsOwnDescription(t *testing.T) {
a, _ := setup(t, testModels())
var doc struct {
OpenAPI string `json:"openapi"`
Paths map[string]map[string]any `json:"paths"`
}
if code := call(t, a, "GET", "/api/v1/openapi.json", "", &doc); code != 200 {
t.Fatalf("status %d", code)
}
if doc.OpenAPI != "3.1.0" {
t.Errorf("openapi %q", doc.OpenAPI)
}
// What is built in is the document generated when it was last committed;
// internal/docgen's test is what fails when that is stale. This checks the
// two ends meet: every route the table has is in what is served.
for _, r := range Routes {
if _, ok := doc.Paths[r.Path][strings.ToLower(r.Method)]; !ok {
t.Errorf("the served document has no %s %s", r.Method, r.Path)
}
}
}
func TestOneModelsDefinitionIsReadByItsNameAlone(t *testing.T) {
a, _ := setup(t, testModels())
var m catalog.Model
if code := call(t, a, "GET", "/api/v1/models/llama", "", &m); code != 200 {
t.Fatalf("status %d", code)
}
if m.Name != "llama" || m.Source != "/m" || len(m.Profiles) != 1 || m.Profiles[0].TP != 8 {
t.Errorf("got %+v", m)
}
if m.Scaling.Min != 2 || m.Scaling.Max != 4 {
t.Errorf("scaling %+v", m.Scaling)
}
if !slices.Equal(m.Aliases, []string{"l"}) {
t.Errorf("aliases %v", m.Aliases)
}
// An alias answering would let a tool that manages "l" believe it exists
// when what it found is llama.
if code := call(t, a, "GET", "/api/v1/models/l", "", nil); code != http.StatusNotFound {
t.Errorf("an alias answered %d", code)
}
if code := call(t, a, "GET", "/api/v1/models/nothing", "", nil); code != http.StatusNotFound {
t.Errorf("a missing model answered %d", code)
}
}
+17 -13
View File
@@ -65,6 +65,20 @@ func (a *API) listOrphans(w http.ResponseWriter, _ *http.Request) {
writeJSON(w, http.StatusOK, a.Orphans())
}
// CollectRequest limits a sweep to one node. Empty means every node, which
// is the common case after removing a model from the catalog.
type CollectRequest struct {
Node string `json:"node,omitempty"`
}
// CollectResult is what was deleted on one node, or why nothing was.
type CollectResult struct {
Node string `json:"node"`
Files int `json:"files"`
Bytes int64 `json:"bytes"`
Error string `json:"error,omitempty"`
}
// collectWeights deletes them.
//
// A proposal, not an instruction: each node checks every path again before
@@ -79,26 +93,16 @@ func (a *API) collectWeights(w http.ResponseWriter, r *http.Request) {
return
}
var body struct {
// Node limits it to one node. Empty means every node, which is the
// common case after removing a model from the catalog.
Node string `json:"node,omitempty"`
}
var body CollectRequest
// An empty body is the "all nodes" case and must not be an error.
_ = json.NewDecoder(r.Body).Decode(&body)
type result struct {
Node string `json:"node"`
Files int `json:"files"`
Bytes int64 `json:"bytes"`
Error string `json:"error,omitempty"`
}
out := make([]result, 0)
out := make([]CollectResult, 0)
for _, o := range a.Orphans() {
if body.Node != "" && o.Node != body.Node {
continue
}
res := result{Node: o.Node, Files: len(o.Paths), Bytes: o.Bytes}
res := CollectResult{Node: o.Node, Files: len(o.Paths), Bytes: o.Bytes}
// A node that has gone since the list was built is reported rather than
// failing the whole sweep: the other nodes' space is still worth
// freeing, and this one will be offered again next time.