Merge features-c2: the docs portal and its links in English and Turkish

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:15:25 +02:00
commit e8a62b23b7
201 files changed
+26276 -630

No files matched your search

+15 -1
View File
@@ -1,4 +1,5 @@
// Command gen writes docs/reference.md from the configuration structs.
// Command gen writes docs/reference.md from the configuration structs, and
// docs/admin-api.openapi.json from the admin API route table.
//
// Run by `go generate ./...`, and checked by a test, so the reference cannot
// quietly stop describing the code.
@@ -10,7 +11,9 @@ import (
"path/filepath"
"runtime"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
"gitea.mynodes.xyz/ilker/llmgw/internal/docgen"
"gitea.mynodes.xyz/ilker/llmgw/internal/docgen/openapi"
)
func main() {
@@ -43,4 +46,15 @@ func main() {
os.Exit(1)
}
fmt.Printf("docs/reference.md and internal/docgen/reference_gen.go: %d blocks\n", len(blocks))
spec, err := openapi.Generate(root, adminapi.Routes, adminapi.PathParams)
if err != nil {
fmt.Fprintln(os.Stderr, "error:", err)
os.Exit(1)
}
if err := os.WriteFile(filepath.Join(root, "docs", "admin-api.openapi.json"), spec, 0o644); err != nil {
fmt.Fprintln(os.Stderr, "error:", err)
os.Exit(1)
}
fmt.Printf("docs/admin-api.openapi.json: %d routes\n", len(adminapi.Routes))
}
+672
View File
@@ -0,0 +1,672 @@
// Package openapi generates the admin API's OpenAPI 3.1 document from its
// route table, adminapi.Routes.
//
// The schemas are read from the Go types the handlers decode and write, by
// reflection, following encoding/json's rules — tag names, omitted fields,
// embedded structs flattened — so the document says what goes over the wire
// rather than what someone remembered to write down. Their descriptions are
// the types' and fields' doc comments, read from the source, which is why
// generating needs the repository and is done by `go generate` rather than
// at run time: the binary serves the document built into it.
package openapi
import (
"bytes"
"encoding"
"encoding/json"
"fmt"
"go/ast"
"go/parser"
"go/token"
"os"
"path"
"path/filepath"
"reflect"
"slices"
"sort"
"strings"
"time"
"unicode"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
)
// Module is the import path the repository's packages are under; a type
// from any other is described without comments.
const Module = "gitea.mynodes.xyz/ilker/llmgw"
// Generate renders the document for routes, reading doc comments from the
// repository at root.
func Generate(root string, routes []adminapi.Route, pathParams map[string]string) ([]byte, error) {
g := &generator{root: root, docs: map[string]map[string]typeDoc{}, names: map[reflect.Type]string{}}
// Every named struct reachable from a body first, so a name two
// packages share can be told apart before either is written: by the name
// alone where it is unique, with its package where it is not.
for _, r := range routes {
for _, v := range []any{r.Request, r.Response} {
if v != nil {
g.collect(reflect.TypeOf(v))
}
}
}
g.collect(errorType)
g.assignNames()
errorSchema := g.schema(errorType)
paths := map[string]*object{}
var order []string
tags := map[string]bool{}
for _, r := range routes {
item, ok := paths[r.Path]
if !ok {
item = &object{}
paths[r.Path] = item
order = append(order, r.Path)
}
op, err := g.operation(r, pathParams)
if err != nil {
return nil, err
}
tags[tagOf(r.Path)] = true
item.set(strings.ToLower(r.Method), op)
}
slices.Sort(order)
var pathsObj object
for _, p := range order {
pathsObj.set(p, *paths[p])
}
var schemas object
names := make([]string, 0, len(g.schemas))
for n := range g.schemas {
names = append(names, n)
}
sort.Strings(names)
for _, n := range names {
schemas.set(n, g.schemas[n])
}
var tagList []any
for _, t := range sortedKeys(tags) {
tagList = append(tagList, obj("name", t))
}
doc := obj(
"openapi", "3.1.0",
"info", obj(
"title", "llmgw admin API",
"version", "v1",
"description", infoDescription,
),
"servers", []any{obj("url", "http://127.0.0.1:9090",
"description", "The admin listener at its default address, admin_listen.")},
"security", []any{obj("adminToken", []any{})},
"tags", tagList,
"paths", pathsObj,
"components", obj(
"securitySchemes", obj("adminToken", obj(
"type", "http",
"scheme", "bearer",
"description", "The admin token: the contents of /var/lib/llmgw/admin-token on the "+
"control plane (admin_token_file), readable by root and the server. "+
"Sent as Authorization: Bearer TOKEN.",
)),
"parameters", obj("Actor", obj(
"name", "X-Llmgw-Actor",
"in", "header",
"required", false,
"description", "Who the change is recorded as made by in the audit log: letters, digits "+
"and ._-@, at most 64. unknown when absent.",
"schema", obj("type", "string"),
)),
"responses", obj(
"Error", obj("description", "Refused: the error says why.",
"content", obj("application/json", obj("schema", errorSchema))),
"Unauthorized", obj("description", "The admin token is missing or wrong.",
"content", obj("application/json", obj("schema", errorSchema))),
),
"schemas", schemas,
),
)
b, err := marshal(doc)
if err != nil {
return nil, err
}
var out bytes.Buffer
if err := json.Indent(&out, b, "", " "); err != nil {
return nil, err
}
out.WriteByte('\n')
return out.Bytes(), nil
}
const infoDescription = "The control plane's management API: what `llmgw ctl` and the console use.\n\n" +
"It is served on the admin listener (admin_listen, 127.0.0.1:9090 by default), which stays on " +
"loopback unless admin_remote is set: reach it from elsewhere through an SSH tunnel. Every path " +
"under /api needs the admin token as a bearer token.\n\n" +
"The listener also refuses, before the token is looked at: a Host header that is a name rather " +
"than an address or localhost; a request another site's page sent; and any method but GET and " +
"HEAD whose Content-Type is not application/json, even one with no body.\n\n" +
"Durations in bodies are integer nanoseconds, as Go encodes them. Generated from the route " +
"table in internal/control/adminapi; see docs/admin-api.md."
// operation builds one route's operation object.
func (g *generator) operation(r adminapi.Route, pathParams map[string]string) (object, error) {
var op object
op.set("operationId", operationID(r.Method, r.Path))
op.set("summary", r.Summary)
if r.Description != "" {
op.set("description", r.Description)
}
op.set("tags", []any{tagOf(r.Path)})
var params []any
segs := strings.Split(strings.Trim(r.Path, "/"), "/")
for i, s := range segs {
if !strings.HasPrefix(s, "{") {
continue
}
name := strings.Trim(s, "{}")
key := s
if i > 0 {
key = segs[i-1] + "/" + s
}
desc, ok := pathParams[key]
if !ok {
return nil, fmt.Errorf("%s %s: no description of %s in adminapi.PathParams", r.Method, r.Path, key)
}
params = append(params, obj("name", name, "in", "path", "required", true,
"description", desc, "schema", obj("type", "string")))
}
for _, q := range r.Query {
t := q.Type
if t == "" {
t = "string"
}
p := obj("name", q.Name, "in", "query")
if q.Required {
p.set("required", true)
}
p.set("description", q.Description)
p.set("schema", obj("type", t))
params = append(params, p)
}
if r.Method != "GET" && r.Method != "HEAD" {
params = append(params, obj("$ref", "#/components/parameters/Actor"))
}
if len(params) > 0 {
op.set("parameters", params)
}
if r.Request != nil {
body := obj("required", !r.OptionalBody,
"content", obj("application/json", obj("schema", g.schema(reflect.TypeOf(r.Request)))))
op.set("requestBody", body)
}
status := r.Status
if status == 0 {
status = 200
}
content := obj("application/json", obj("schema", g.schema(reflect.TypeOf(r.Response))))
if r.CSV {
content.set("text/csv", obj("schema", obj("type", "string")))
}
desc := "OK"
if status == 202 {
desc = "Accepted: started, and running on."
}
op.set("responses", obj(
fmt.Sprint(status), obj("description", desc, "content", content),
"401", obj("$ref", "#/components/responses/Unauthorized"),
"default", obj("$ref", "#/components/responses/Error"),
))
return op, nil
}
// operationID is the method and the path's words, getModelsNameTarget.
func operationID(method, p string) string {
var b strings.Builder
b.WriteString(strings.ToLower(method))
for _, s := range strings.Split(strings.TrimPrefix(p, "/api/v1/"), "/") {
for _, w := range strings.FieldsFunc(s, func(r rune) bool { return !unicode.IsLetter(r) && !unicode.IsDigit(r) }) {
b.WriteString(strings.ToUpper(w[:1]) + w[1:])
}
}
return b.String()
}
// tagOf groups an operation by the first word of its path.
func tagOf(p string) string {
first, _, _ := strings.Cut(strings.TrimPrefix(p, "/api/v1/"), "/")
return strings.TrimSuffix(first, ".json")
}
// --- schemas ---
type typeDoc struct {
doc string
fields map[string]string
}
type generator struct {
root string
docs map[string]map[string]typeDoc
names map[reflect.Type]string
schemas map[string]any
seen []reflect.Type
}
var (
timeType = reflect.TypeOf(time.Time{})
durationType = reflect.TypeOf(time.Duration(0))
rawType = reflect.TypeOf(json.RawMessage{})
errorType = reflect.TypeOf(adminapi.ErrorView{})
marshalerType = reflect.TypeOf((*json.Marshaler)(nil)).Elem()
textType = reflect.TypeOf((*encoding.TextMarshaler)(nil)).Elem()
)
// collect records every named struct reachable from t.
func (g *generator) collect(t reflect.Type) {
for t.Kind() == reflect.Pointer || t.Kind() == reflect.Slice || t.Kind() == reflect.Array || t.Kind() == reflect.Map {
if t == rawType {
return
}
t = t.Elem()
}
if t.Kind() != reflect.Struct || special(t) {
return
}
if t.Name() != "" {
if slices.Contains(g.seen, t) {
return
}
g.seen = append(g.seen, t)
}
for _, f := range fields(t) {
g.collect(f.typ)
}
}
// assignNames names each struct's schema: by its name alone when it is the
// admin API's own, with its package's otherwise — catalog.Model,
// modelserve.Job. Qualified always rather than only on a collision, so a
// type added elsewhere one day cannot rename a schema clients already use.
func (g *generator) assignNames() {
own := reflect.TypeOf(adminapi.Route{}).PkgPath()
for _, t := range g.seen {
n := t.Name()
if t.PkgPath() != own {
n = path.Base(t.PkgPath()) + "." + n
}
g.names[t] = n
}
g.schemas = map[string]any{}
}
func (g *generator) nameOf(t reflect.Type) string { return g.names[t] }
// special is a type encoded other than by its fields.
func special(t reflect.Type) bool {
if t == timeType || t == durationType || t == rawType {
return true
}
return t.Implements(marshalerType) || reflect.PointerTo(t).Implements(marshalerType) ||
t.Implements(textType) || reflect.PointerTo(t).Implements(textType)
}
func ref(name string) object { return obj("$ref", "#/components/schemas/"+name) }
// schema describes t, adding the named structs it reaches to the components.
func (g *generator) schema(t reflect.Type) any {
switch {
case t == timeType:
return obj("type", "string", "format", "date-time")
case t == durationType:
return obj("type", "integer", "format", "int64", "description", "A duration, in nanoseconds.")
case t == rawType:
return obj("description", "Any JSON value.")
case t.Implements(textType) || reflect.PointerTo(t).Implements(textType):
return obj("type", "string")
case t.Implements(marshalerType) || reflect.PointerTo(t).Implements(marshalerType):
return obj("description", "Encoded by the type's own JSON encoding.")
}
switch t.Kind() {
case reflect.Bool:
return obj("type", "boolean")
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Uint8, reflect.Uint16, reflect.Uint32:
return obj("type", "integer")
case reflect.Int64, reflect.Uint, reflect.Uint64:
return obj("type", "integer", "format", "int64")
case reflect.Float32, reflect.Float64:
return obj("type", "number")
case reflect.String:
return obj("type", "string")
case reflect.Pointer:
return g.schema(t.Elem())
case reflect.Slice, reflect.Array:
if t.Elem().Kind() == reflect.Uint8 {
return obj("type", "string", "contentEncoding", "base64")
}
return obj("type", "array", "items", g.schema(t.Elem()))
case reflect.Map:
return obj("type", "object", "additionalProperties", g.schema(t.Elem()))
case reflect.Interface:
return obj()
case reflect.Struct:
if t.Name() == "" {
return g.structSchema(t, "")
}
name := g.names[t]
if name == "" {
// Reached only through a body collect did not walk, which would be
// a bug here; named anyway rather than inlined so it shows.
name = t.Name()
g.names[t] = name
}
if _, ok := g.schemas[name]; !ok {
g.schemas[name] = nil // placeholder: a type that contains itself
g.schemas[name] = g.structSchema(t, g.typeDocOf(t).doc)
}
return ref(name)
}
return obj()
}
func (g *generator) structSchema(t reflect.Type, doc string) object {
s := obj("type", "object")
if doc != "" {
s.set("description", doc)
}
var props object
for _, f := range fields(t) {
var p any
if f.asString {
p = obj("type", "string")
} else {
p = g.schema(f.typ)
}
if d := g.typeDocOf(f.owner).fields[f.goName]; d != "" {
p = withDescription(p, d)
}
props.set(f.name, p)
}
s.set("properties", props)
return s
}
// withDescription puts a field's comment on its schema. A reference keeps
// its own description where it is declared; in 3.1 a sibling description
// beside $ref is allowed and is the field's.
func withDescription(p any, d string) any {
o, ok := p.(object)
if !ok {
return p
}
if prev, ok := o.get("description"); ok {
d = d + "\n\n" + prev.(string)
}
o = slices.Clone(o)
o.set("description", d)
return o
}
// field is one key of a struct's JSON.
type field struct {
name string
goName string
owner reflect.Type // the struct it is declared in, for its comment
typ reflect.Type
asString bool
depth int
}
// fields lists a struct's JSON keys as encoding/json writes them: exported
// fields, by tag name, "-" left out, embedded structs without a name of
// their own flattened, and a key at a shallower depth winning over the same
// key from deeper in.
func fields(t reflect.Type) []field {
var out []field
var walk func(t reflect.Type, depth int)
walk = func(t reflect.Type, depth int) {
for i := 0; i < t.NumField(); i++ {
sf := t.Field(i)
tag := sf.Tag.Get("json")
if tag == "-" {
continue
}
name, opts, _ := strings.Cut(tag, ",")
ft := sf.Type
if sf.Anonymous && name == "" {
et := ft
if et.Kind() == reflect.Pointer {
et = et.Elem()
}
if et.Kind() == reflect.Struct && !special(et) {
walk(et, depth+1)
continue
}
}
if !sf.IsExported() {
continue
}
if name == "" {
name = sf.Name
}
out = append(out, field{name: name, goName: sf.Name, owner: t, typ: ft, depth: depth,
asString: slices.Contains(strings.Split(opts, ","), "string")})
}
}
walk(t, 0)
// The shallowest of each name, in the order they were met.
best := map[string]int{}
for _, f := range out {
if d, ok := best[f.name]; !ok || f.depth < d {
best[f.name] = f.depth
}
}
var kept []field
taken := map[string]bool{}
for _, f := range out {
if f.depth == best[f.name] && !taken[f.name] {
taken[f.name] = true
kept = append(kept, f)
}
}
return kept
}
// typeDocOf reads a type's comment and its fields' from its package's source.
func (g *generator) typeDocOf(t reflect.Type) typeDoc {
pkg := t.PkgPath()
if pkg != Module && !strings.HasPrefix(pkg, Module+"/") {
return typeDoc{}
}
docs, ok := g.docs[pkg]
if !ok {
docs = parseDocs(filepath.Join(g.root, filepath.FromSlash(strings.TrimPrefix(strings.TrimPrefix(pkg, Module), "/"))))
g.docs[pkg] = docs
}
return docs[t.Name()]
}
// parseDocs reads the struct types declared in a directory and their
// comments. A directory it cannot read gives no comments rather than an
// error: the document is still right, only quieter.
func parseDocs(dir string) map[string]typeDoc {
out := map[string]typeDoc{}
entries, err := os.ReadDir(dir)
if err != nil {
return out
}
fset := token.NewFileSet()
for _, e := range entries {
n := e.Name()
if e.IsDir() || !strings.HasSuffix(n, ".go") || strings.HasSuffix(n, "_test.go") {
continue
}
f, err := parser.ParseFile(fset, filepath.Join(dir, n), nil, parser.ParseComments)
if err != nil {
continue
}
for _, d := range f.Decls {
gd, ok := d.(*ast.GenDecl)
if !ok || gd.Tok != token.TYPE {
continue
}
for _, sp := range gd.Specs {
ts := sp.(*ast.TypeSpec)
doc := ts.Doc
if doc == nil && len(gd.Specs) == 1 {
doc = gd.Doc
}
td := typeDoc{doc: text(doc), fields: map[string]string{}}
if st, ok := ts.Type.(*ast.StructType); ok {
for _, fl := range st.Fields.List {
c := fl.Doc
if c == nil {
c = fl.Comment
}
for _, name := range fieldNames(fl) {
td.fields[name] = text(c)
}
}
}
out[ts.Name.Name] = td
}
}
}
return out
}
func fieldNames(fl *ast.Field) []string {
if len(fl.Names) > 0 {
var out []string
for _, n := range fl.Names {
out = append(out, n.Name)
}
return out
}
// Embedded: named by its type.
t := fl.Type
if s, ok := t.(*ast.StarExpr); ok {
t = s.X
}
switch x := t.(type) {
case *ast.Ident:
return []string{x.Name}
case *ast.SelectorExpr:
return []string{x.Sel.Name}
}
return nil
}
// text is a comment as prose: the comment markers gone, lines within a
// paragraph joined, paragraphs kept apart.
func text(g *ast.CommentGroup) string {
if g == nil {
return ""
}
var paras []string
var cur []string
for _, line := range strings.Split(g.Text(), "\n") {
line = strings.TrimSpace(line)
if line == "" {
if len(cur) > 0 {
paras = append(paras, strings.Join(cur, " "))
cur = nil
}
continue
}
cur = append(cur, line)
}
if len(cur) > 0 {
paras = append(paras, strings.Join(cur, " "))
}
return strings.Join(paras, "\n\n")
}
// --- an object that keeps its keys in order ---
type kv struct {
k string
v any
}
// object is a JSON object written in the order its keys were set, so the
// document reads in the order it was meant to — openapi, info, paths — and
// a struct's properties in the order its fields are declared.
type object []kv
func obj(pairs ...any) object {
var o object
for i := 0; i+1 < len(pairs); i += 2 {
o.set(pairs[i].(string), pairs[i+1])
}
return o
}
func (o *object) set(k string, v any) {
for i := range *o {
if (*o)[i].k == k {
(*o)[i].v = v
return
}
}
*o = append(*o, kv{k, v})
}
func (o object) get(k string) (any, bool) {
for _, p := range o {
if p.k == k {
return p.v, true
}
}
return nil, false
}
// MarshalJSON writes the keys in order.
func (o object) MarshalJSON() ([]byte, error) {
var b bytes.Buffer
b.WriteByte('{')
for i, p := range o {
if i > 0 {
b.WriteByte(',')
}
k, err := marshal(p.k)
if err != nil {
return nil, err
}
b.Write(k)
b.WriteByte(':')
v, err := marshal(p.v)
if err != nil {
return nil, err
}
b.Write(v)
}
b.WriteByte('}')
return b.Bytes(), nil
}
// marshal is json.Marshal without escaping <, > and &, which are common in
// the descriptions and harmless in a document nobody puts in a page.
func marshal(v any) ([]byte, error) {
var b bytes.Buffer
enc := json.NewEncoder(&b)
enc.SetEscapeHTML(false)
if err := enc.Encode(v); err != nil {
return nil, err
}
return bytes.TrimRight(b.Bytes(), "\n"), nil
}
func sortedKeys(m map[string]bool) []string {
out := make([]string, 0, len(m))
for k := range m {
out = append(out, k)
}
sort.Strings(out)
return out
}
+163
View File
@@ -0,0 +1,163 @@
package openapi
import (
"encoding/json"
"os"
"path/filepath"
"runtime"
"strings"
"testing"
"gitea.mynodes.xyz/ilker/llmgw/internal/control/adminapi"
)
func repoRoot(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("cannot locate this test")
}
return filepath.Join(filepath.Dir(file), "..", "..", "..")
}
func generated(t *testing.T) map[string]any {
t.Helper()
b, err := Generate(repoRoot(t), adminapi.Routes, adminapi.PathParams)
if err != nil {
t.Fatal(err)
}
var doc map[string]any
if err := json.Unmarshal(b, &doc); err != nil {
t.Fatalf("the document is not JSON: %v", err)
}
return doc
}
// at walks a decoded document by keys.
func at(t *testing.T, v any, keys ...string) any {
t.Helper()
for _, k := range keys {
m, ok := v.(map[string]any)
if !ok {
t.Fatalf("%s: not an object", strings.Join(keys, "."))
}
v, ok = m[k]
if !ok {
t.Fatalf("no %s (of %s)", k, strings.Join(keys, "."))
}
}
return v
}
func TestTheAdminAPIDocumentIsNotStale(t *testing.T) {
// Like the configuration reference: a description of the API that is not
// regenerated describes some earlier week's API, and the server serves the
// committed copy to every client generated from it.
want, err := Generate(repoRoot(t), adminapi.Routes, adminapi.PathParams)
if err != nil {
t.Fatal(err)
}
got, err := os.ReadFile(filepath.Join(repoRoot(t), "docs", "admin-api.openapi.json"))
if err != nil {
t.Fatalf("docs/admin-api.openapi.json is missing; run go generate ./internal/docgen: %v", err)
}
if string(got) != string(want) {
t.Error("docs/admin-api.openapi.json no longer matches the admin API's routes and types.\n" +
"Run: go generate ./internal/docgen")
}
}
func TestEveryReferenceInTheDocumentResolves(t *testing.T) {
doc := generated(t)
var walk func(v any)
n := 0
walk = func(v any) {
switch x := v.(type) {
case map[string]any:
if r, ok := x["$ref"].(string); ok {
n++
parts := strings.Split(strings.TrimPrefix(r, "#/"), "/")
at(t, doc, parts...)
}
for _, e := range x {
walk(e)
}
case []any:
for _, e := range x {
walk(e)
}
}
}
walk(doc)
if n < 50 {
t.Errorf("only %d references; the schemas are not being shared", n)
}
}
func TestABodyIsDescribedByItsGoType(t *testing.T) {
doc := generated(t)
scale := at(t, doc, "paths", "/api/v1/models/{name}/scale", "post")
if r := at(t, scale, "requestBody", "content", "application/json", "schema", "$ref"); r != "#/components/schemas/ScaleRequest" {
t.Errorf("scale's body is %v", r)
}
props := at(t, doc, "components", "schemas", "ScaleRequest", "properties").(map[string]any)
// The tag's name, not the field's.
for _, k := range []string{"min", "max", "idle_timeout"} {
if _, ok := props[k]; !ok {
t.Errorf("ScaleRequest has no %s: %v", k, props)
}
}
// The field's comment is its description, and a duration says its unit.
if d := at(t, props, "max", "description").(string); !strings.Contains(d, "follows Min") {
t.Errorf("max lost its comment: %q", d)
}
if d := at(t, props, "idle_timeout", "description").(string); !strings.Contains(d, "nanoseconds") {
t.Errorf("idle_timeout does not say it is nanoseconds: %q", d)
}
// A type from another package is named with its package.
if r := at(t, doc, "paths", "/api/v1/models", "post", "requestBody", "content", "application/json", "schema", "$ref"); r != "#/components/schemas/catalog.Model" {
t.Errorf("adding a model takes %v", r)
}
}
func TestAnEmbeddedStructsFieldsAreItsOwn(t *testing.T) {
// CapacityView embeds bench.Capacity, and encoding/json writes the
// embedded fields at the top level: so must the schema.
doc := generated(t)
props := at(t, doc, "components", "schemas", "CapacityView", "properties").(map[string]any)
for _, k := range []string{"measured_by", "model", "profile"} {
if _, ok := props[k]; !ok {
t.Errorf("CapacityView has no %s: %v", k, props)
}
}
}
func TestEveryChangeNeedsTheTokenAndNamesItsActor(t *testing.T) {
doc := generated(t)
if s := at(t, doc, "components", "securitySchemes", "adminToken", "scheme"); s != "bearer" {
t.Errorf("scheme %v", s)
}
if len(at(t, doc, "security").([]any)) != 1 {
t.Error("the token is not required document-wide")
}
del := at(t, doc, "paths", "/api/v1/models/{name}", "delete")
found := false
for _, p := range at(t, del, "parameters").([]any) {
if p.(map[string]any)["$ref"] == "#/components/parameters/Actor" {
found = true
}
}
if !found {
t.Error("removing a model does not take X-Llmgw-Actor")
}
if _, ok := at(t, del, "responses").(map[string]any)["401"]; !ok {
t.Error("removing a model does not say it can be refused for the token")
}
}
func TestAPathParameterWithNoDescriptionIsAnError(t *testing.T) {
routes := []adminapi.Route{{Method: "GET", Path: "/api/v1/things/{id}", Summary: "x", Response: adminapi.Result{}}}
if _, err := Generate(repoRoot(t), routes, adminapi.PathParams); err == nil {
t.Error("a parameter nobody described was let through")
}
}
+21 -3
View File
@@ -44,6 +44,10 @@ var Reference = []Block{
{Key: "concurrency", Type: "int", Doc: "Concurrency is how many of one batch's requests are in flight at\nonce; 4 unless set. They queue in the lowest admission band, behind\nevery interactive request.", Nested: ""},
{Key: "retain_days", Type: "int", Doc: "RetainDays is how long a batch's answer and error files are kept;\n30 unless set. Uploaded files are kept until deleted.", Nested: ""},
}},
{Package: "config", Name: "Cache", Title: "Cache", Doc: "", Fields: []Field{
{Key: "max_bytes", Type: "int64", Doc: "MaxBytes bounds every project's answers together; 128 MB unless set.\nPast it, the answers used longest ago go first.", Nested: ""},
{Key: "max_entry_bytes", Type: "int64", Doc: "MaxEntryBytes bounds one answer; a longer one is not kept. 1 MB\nunless set.", Nested: ""},
}},
{Package: "catalog", Name: "Canary", Title: "Canary", Doc: "", Fields: []Field{
{Key: "model", Type: "string", Doc: "Model is the candidate: a catalog model, usually this one at newer\nweights, which clients cannot name themselves.", Nested: ""},
{Key: "percent", Type: "int", Doc: "Percent of requests go to it, 0 to 100.", Nested: ""},
@@ -65,6 +69,7 @@ var Reference = []Block{
{Key: "port_range", Type: "[]int", Doc: "PortRange is the per-node range for engine HTTP and dist-init ports.", Nested: ""},
{Key: "mgmt_interface", Type: "string", Doc: "MgmtInterface is the ethernet interface NCCL bootstraps over.", Nested: ""},
{Key: "timezone", Type: "string", Doc: "Timezone is where models' scaling schedules are read, an IANA name\nlike Europe/Istanbul; empty is the control plane's own.", Nested: ""},
{Key: "eval_dir", Type: "string", Doc: "EvalDir is where quality suites are read from by name, for `llmgw ctl\neval MODEL --suite NAME`, a model's eval gate and the console. The\nsuites the binary carries (arithmetic, json-format) are found when it\nhas none of the name; a suite here of the same name replaces one.", Nested: ""},
{Key: "enabled", Type: "bool", Doc: "Enabled runs the control plane even when configuration declares no\nmodels.\n\nWithout it, a deployment whose catalog lives entirely in the database\ncannot start: control plane mode is inferred from the config file, so an\nempty models block means \"router only\", the process refuses to start for\nwant of anything to serve, and the models it would have loaded are never\nread. That is a cluster that cannot be managed at runtime because it is\nmanaged at runtime. AgentListen cannot carry this signal — it has a\ndefault, so every deployment would become a control plane.", Nested: ""},
{Key: "lease_ttl", Type: "time.Duration", Doc: "LeaseTTL is how long this control plane's claim to be the one placing\nwork stands without being renewed.\n\nOnly meaningful with a shared store, where a second control plane can\nsee the claim. Long enough to survive a slow query or a brief network\nstall, short enough that a standby takes over before anyone has finished\nreading the alert. Zero takes the default.", Nested: ""},
}},
@@ -84,6 +89,11 @@ var Reference = []Block{
{Key: "labels", Type: "map[string]string", Doc: "Labels picks nodes carrying all of these.", Nested: ""},
{Key: "engines", Type: "map[string]string", Doc: "Engines are laid over the cluster's: a version, or \"\" for none.", Nested: ""},
}},
{Package: "catalog", Name: "EvalGate", Title: "EvalGate", Doc: "", Fields: []Field{
{Key: "suite", Type: "string", Doc: "Suite is a suite's name in control.eval_dir, or one the binary\ncarries (arithmetic, json-format).", Nested: ""},
{Key: "min_score", Type: "float64", Doc: "MinScore is the score, 0 to 1, to pass at; zero is the suite's own\nthreshold.", Nested: ""},
{Key: "judge", Type: "string", Doc: "Judge grades the suite's rubric cases, instead of the judge it names.", Nested: ""},
}},
{Package: "catalog", Name: "External", Title: "External", Doc: "", Fields: []Field{
{Key: "url", Type: "string", Doc: "URL is the provider's base address, without /v1: https://api.openai.com.", Nested: ""},
{Key: "model", Type: "string", Doc: "Model is what the provider calls it; requests are rewritten to it.", Nested: ""},
@@ -104,6 +114,7 @@ var Reference = []Block{
{Key: "contact", Type: "string", Doc: "Contact is where someone without a key should go — an address, a URL, a\nchannel name. Rendered as a link when it is one, as text otherwise.", Nested: ""},
{Key: "notice", Type: "string", Doc: "Notice is an optional line of your own, for whatever the reader needs to\nknow that this page cannot guess.", Nested: ""},
{Key: "language", Type: "string", Doc: "Language is what the web portal speaks to someone who has not chosen\na language with the switcher at the foot of every page and whose\nbrowser asks for none it speaks: \"en\" or \"tr\". Empty is English.", Nested: ""},
{Key: "docs_sign_in", Type: "bool", Doc: "DocsSignIn serves the docs portal at /docs only to someone signed in.\nOff, the portal is public like this page: its client guide is for the\nperson who has no account yet, and the operator documents describe\nllmgw in general — no address, model or key of this installation —\nwhich the project's repository publishes anyway. On, a visitor is sent\nto sign in, and without accounts the portal needs an API key.", Nested: ""},
}},
{Package: "engines", Name: "LlamaCppConfig", Title: "LlamaCppConfig", Doc: "", Fields: []Field{
{Key: "bin", Type: "string", Doc: "Bin is the llama-server binary. It is the server, not the CLI: the\ngateway talks OpenAI over HTTP and needs the one that serves it.\nEmpty means the agent installs llama.cpp itself, at the version the\ncontrol plane asks for. Setting it opts out of that.", Nested: ""},
@@ -130,6 +141,7 @@ var Reference = []Block{
{Key: "adapters", Type: "[]Adapter", Doc: "Adapters are LoRA adapters served on this model's replicas, each asked\nfor by its own name as though it were a model. Every replica loads\nevery adapter, applying one only to a request that names it.", Nested: ""},
{Key: "fallbacks", Type: "[]string", Doc: "", Nested: ""},
{Key: "canary", Type: "*Canary", Doc: "Canary sends a share of this model's requests to another catalog\nmodel — the same model at new weights — to compare the two before\nmoving to it (`llmgw ctl model canary`).", Nested: "catalog.Canary"},
{Key: "eval", Type: "*EvalGate", Doc: "Eval is a quality suite new weights must pass before they replace\nthis model's: `llmgw ctl model update` and `model promote` run it\nagainst them first, and stop below its score.", Nested: "catalog.EvalGate"},
{Key: "routing_profile", Type: "string", Doc: "RoutingProfile selects how the router scores endpoints for this model.", Nested: ""},
{Key: "slo", Type: "SLO", Doc: "", Nested: "catalog.SLO"},
{Key: "context_length", Type: "int", Doc: "ContextLength is how many tokens one request may use, prompt and\ncompletion together, and MaxOutput bounds the completion alone. Zero\nmeans unknown, which is what every model was until now.\n\nThe gateway knew neither, so an over-long prompt was not refused: it was\nadmitted, given a replica, and failed at the engine, and a client sizing\nits prompts from /v1/models had nothing to read. Worse, the number is not\nthe one an operator writes in the engine's arguments — llama.cpp divides\n--ctx-size across its parallel slots, so a pool of 8192 across four slots\nis 2048 a request, and nothing said so.", Nested: ""},
@@ -249,6 +261,7 @@ var Reference = []Block{
{Key: "tag_labels", Type: "[]string", Doc: "TagLabels are the request tags (metadata, x-llmgw-tags) counted in\nllmgw_tagged_requests_total and llmgw_tagged_tokens_total, by value.\nOnly these: a tag is the client's to set, and every value of one is\na series. The first 100 values of each are counted apart, the rest as\n\"other\". Empty counts none; the usage records keep every tag anyway.", Nested: ""},
{Key: "max_body_bytes", Type: "int64", Doc: "MaxBodyBytes bounds the request body the router will read.", Nested: ""},
{Key: "batch", Type: "Batch", Doc: "Batch is the Files and Batch APIs (/v1/files, /v1/batches): a file of\nrequests served at the lowest priority, its answers written to\nanother. Needs the store.", Nested: "config.Batch"},
{Key: "cache", Type: "Cache", Doc: "Cache bounds the answers kept for the projects that reuse them\n(llmgw keys cache). Which projects do, and for how long, is theirs\nto set; this is only how much memory it may take.", Nested: "config.Cache"},
{Key: "trusted_proxies", Type: "[]string", Doc: "TrustedProxies are the reverse proxies in front of the client port,\nas addresses or CIDR prefixes. Their X-Forwarded-For, -Proto and -Host\nare believed; anyone else's are not, since they decide the address\nwritten into the setup scripts and whose attempts are counted where.", Nested: ""},
{Key: "timeouts", Type: "Timeouts", Doc: "", Nested: "config.Timeouts"},
{Key: "scoring", Type: "Scoring", Doc: "", Nested: "config.Scoring"},
@@ -309,7 +322,7 @@ var Reference = []Block{
{Key: "debug_pprof", Type: "bool", Doc: "DebugPprof serves Go's profiler on the admin listener, behind the token.\nOff by default: a heap profile holds the API keys requests presented.", Nested: ""},
{Key: "agent_insecure", Type: "bool", Doc: "AgentInsecure lets a control plane run its agent port without\nagent_tls: plaintext, and any machine that reaches it may register as\nany node — be given replicas, and so be sent users' prompts — or, in\nthe other direction, a machine in the path may tell every agent what\nto run. Refused unless said here, and then the port listens on\nloopback unless agent_listen names an address. For one machine, a\ntest, or a network nothing untrusted reaches.", Nested: ""},
{Key: "monitoring", Type: "Monitoring", Doc: "Monitoring is where the dashboard reads its history from.", Nested: "config.Monitoring"},
{Key: "tracing", Type: "Tracing", Doc: "Tracing sends a trace of each inference request to an OpenTelemetry\ncollector. Off unless an endpoint is set here or in\nOTEL_EXPORTER_OTLP_ENDPOINT.", Nested: "config.Tracing"},
{Key: "tracing", Type: "obs.Tracing", Doc: "Tracing sends traces to an OpenTelemetry collector: each inference\nrequest, and on a control plane each placement, replica start and\nmodel job. Off unless an endpoint is set here or in\nOTEL_EXPORTER_OTLP_ENDPOINT.", Nested: "obs.Tracing"},
{Key: "mirror", Type: "Mirror", Doc: "Mirror points the control plane at a model mirror it can administer.\nEmpty means there is none, and /admin/mirror stays unmounted.", Nested: "config.Mirror"},
{Key: "engines", Type: "map[string]string", Doc: "Engines are the engines every node installs, and at which version. The\nagents install them themselves — the right build for their hardware,\nchecked against its publisher's checksum and seen to run — so a node is\nnever trusted to already have what somebody once put there.\n\nUnset keeps DefaultEngines. A version replaces the default; an empty\none leaves that engine to be installed by hand.", Nested: ""},
{Key: "engine_overrides", Type: "[]EngineOverride", Doc: "EngineOverrides give some nodes different engines from the rest: a\nvLLM built for CUDA 12 on the Volta cards CUDA 13 dropped, or none at\nall on nodes meant only for llama.cpp. Each picks nodes and lays its\nengines over the cluster's, in order, later ones last; an empty version\nremoves that engine from the nodes it picks.", Nested: ""},
@@ -330,6 +343,9 @@ var Reference = []Block{
{Package: "engines", Name: "SimConfig", Title: "SimConfig", Doc: "", Fields: []Field{
{Key: "bin", Type: "string", Doc: "Bin is the llmgw binary itself; the engine is one of its subcommands.\nEmpty means whatever started this agent, which is right almost always.", Nested: ""},
}},
{Package: "engines", Name: "TRTLLMConfig", Title: "TRTLLMConfig", Doc: "", Fields: []Field{
{Key: "python", Type: "string", Doc: "Python is the interpreter of the environment TensorRT-LLM is installed\nin: <venv>/bin/python for a virtual environment, python3 in NVIDIA's\ncontainer. Naming it is what makes this node offer the engine; empty\noffers nothing.\n\nThe interpreter rather than trtllm-serve, because llmgw starts the\nserver through a few lines of its own that make it demand the\ngateway's key, which trtllm-serve has no option for.", Nested: ""},
}},
{Package: "config", Name: "Threads", Title: "Threads", Doc: "", Fields: []Field{
{Key: "store", Type: "string", Doc: "Store is the SQLite file. Empty means nothing is kept.", Nested: ""},
{Key: "retain_hours", Type: "int", Doc: "RetainHours is how long idle conversations and notes are kept. Required\nwith Store: a store with no expiry keeps everything anyone typed, by\nomission.", Nested: ""},
@@ -349,9 +365,9 @@ var Reference = []Block{
{Key: "max_calls_per_turn", Type: "int", Doc: "MaxCallsPerTurn stops an answer calling more tools than this.", Nested: ""},
{Key: "validate_arguments", Type: "bool", Doc: "ValidateArguments checks a call's arguments against the parameters\nschema the request declared for the tool.", Nested: ""},
}},
{Package: "config", Name: "Tracing", Title: "Tracing", Doc: "", Fields: []Field{
{Package: "obs", Name: "Tracing", Title: "Tracing", Doc: "", Fields: []Field{
{Key: "endpoint", Type: "string", Doc: "Endpoint is the collector, for example http://otel.internal:4318.\nEmpty falls back to OTEL_EXPORTER_OTLP_ENDPOINT, and to no tracing.", Nested: ""},
{Key: "sample_ratio", Type: "float64", Doc: "SampleRatio is the share of requests traced, 0 to 1, when the caller\ndid not decide it with a sampled traceparent of its own. Zero takes 1.", Nested: ""},
{Key: "sample_ratio", Type: "float64", Doc: "SampleRatio is the share of traces kept, 0 to 1, of those nobody\nupstream already decided. Zero takes 1. A request with a sampled\ntraceparent of its own is kept, and an agent keeps every start the\ncontrol plane kept, whatever their own ratio says.", Nested: ""},
}},
{Package: "engines", Name: "VLLMConfig", Title: "VLLMConfig", Doc: "", Fields: []Field{
{Key: "bin", Type: "string", Doc: "Bin is the vllm executable.", Nested: ""},
@@ -409,6 +425,7 @@ var Reference = []Block{
{Key: "discovery", Type: "discovery.Options", Doc: "", Nested: "discovery.Options"},
{Key: "engines", Type: "engines.Config", Doc: "", Nested: "engines.Config"},
{Key: "supervisor", Type: "supervisor.Config", Doc: "", Nested: "supervisor.Config"},
{Key: "tracing", Type: "obs.Tracing", Doc: "Tracing sends this node's part of each replica start — the weights\nfetched, the engine launched, the wait for it to answer — to an\nOpenTelemetry collector, inside the control plane's trace of that\nstart. Give it the collector server.yaml's tracing names. Off unless\nan endpoint is set here or in OTEL_EXPORTER_OTLP_ENDPOINT.", Nested: "obs.Tracing"},
}},
{Package: "config", Name: "Band", Title: "config.Band", Doc: "", Fields: []Field{
{Key: "name", Type: "string", Doc: "", Nested: ""},
@@ -424,6 +441,7 @@ var Reference = []Block{
{Key: "vllm", Type: "VLLMConfig", Doc: "", Nested: "engines.VLLMConfig"},
{Key: "sglang", Type: "SGLangConfig", Doc: "", Nested: "engines.SGLangConfig"},
{Key: "llamacpp", Type: "LlamaCppConfig", Doc: "", Nested: "engines.LlamaCppConfig"},
{Key: "trtllm", Type: "TRTLLMConfig", Doc: "TRTLLM is TensorRT-LLM, which the agent does not install: a node\noffers it only when its interpreter is named here.", Nested: "engines.TRTLLMConfig"},
{Key: "sim", Type: "SimConfig", Doc: "", Nested: "engines.SimConfig"},
}},
{Package: "guard", Name: "Config", Title: "guard.Config", Doc: "", Fields: []Field{
+2
View File
@@ -20,6 +20,7 @@ var Sources = []string{
"internal/agent/engines/llamacpp.go",
"internal/agent/engines/vllm.go",
"internal/agent/engines/sglang.go",
"internal/agent/engines/trtllm.go",
"internal/agent/engines/sim.go",
"internal/agent/supervisor/supervisor.go",
"internal/tlsconf/tlsconf.go",
@@ -31,6 +32,7 @@ var Sources = []string{
"internal/config/oidc.go",
"internal/notify/notify.go",
"internal/secrets/secrets.go",
"internal/obs/trace.go",
}
// notReference are files with koanf tags that an operator never writes.