Merge C19 OpenAPI for the admin API and a Terraform provider

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-05 00:06:34 +02:00
commit 9dc82f73d4
37 files changed
+11095 -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)
@@ -997,7 +1008,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.
@@ -1083,7 +1112,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) {
@@ -1181,15 +1210,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
@@ -1217,7 +1244,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) {
@@ -1227,7 +1254,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
@@ -1428,7 +1455,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
@@ -1523,7 +1550,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.
@@ -1623,7 +1650,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.