From 9e7de578162d7226fb6a1ca0690ef3e34bf2b822 Mon Sep 17 00:00:00 2001 From: Ilker Manap Date: Sun, 25 Oct 2026 16:50:58 +0100 Subject: [PATCH] The reference describes a guardrail policy's services Co-Authored-By: Claude Opus 5.5 --- docs/reference.md | 70 ++++++++++++++++++++++++++++++++ internal/docgen/reference_gen.go | 11 +++++ internal/docgen/render.go | 1 + 3 files changed, 82 insertions(+) diff --git a/docs/reference.md b/docs/reference.md index e9d5469..f91ab53 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -382,6 +382,15 @@ rather than repeated. | `facility` | `Facility` | [Server](#server) | | `federation` | `Federation` | [Server](#server) | | `endpoints` | `[]Endpoint` | [Server](#server) | +| `name` | `string` | [Service](#service) | +| `url` | `string` | [Service](#service) | +| `header_files` | `map[string]string` | [Service](#service) | +| `body` | `string` | [Service](#service) | +| `blocked` | `string` | [Service](#service) | +| `reason` | `string` | [Service](#service) | +| `on` | `string` | [Service](#service) | +| `action` | `string` | [Service](#service) | +| `timeout` | `time.Duration` | [Service](#service) | | `stopped` | `bool` | [ServingSettings](#servingsettings) | | `bin` | `string` | [SimConfig](#simconfig) | | `python` | `string` | [TRTLLMConfig](#trtllmconfig) | @@ -3292,6 +3301,67 @@ Endpoints is the phase-1 static replica list. It is only consulted when no model declares a profile, which is what makes a router-only smoke test against sim-engines possible without a control plane. +## Service + +### `name` + +`string` + +Name says which service decided, in the verdict's rule. + +### `url` + +`string` + +URL is POSTed the body. + +### `header_files` + +`map[string]string` + +HeaderFiles are headers whose values are read from files each time, +so a rotated key needs no restart: {Authorization: /etc/…/lakera}. + +### `body` + +`string` + +Body is the request, a template given .Text; {{json .Text}} writes it +as a JSON string. Empty is {"input": }. + +### `blocked` + +`string` + +Blocked is where in the answer the service says the text is unsafe: +a dotted path, numbers for list items (results.0.flagged). True, a +number above zero, a non-empty list or string other than "false" is +unsafe. + +### `reason` + +`string` + +Reason is where it says why, for the verdict; optional. + +### `on` + +`string` + +On: input, output or both. Empty is input. + +### `action` + +`string` + +Action on unsafe: block or flag. Empty is block. + +### `timeout` + +`time.Duration` + +Timeout bounds one call. Empty is 3s; past it the policy's fail says. + ## ServingSettings ### `stopped` diff --git a/internal/docgen/reference_gen.go b/internal/docgen/reference_gen.go index 7c29d3d..f438361 100644 --- a/internal/docgen/reference_gen.go +++ b/internal/docgen/reference_gen.go @@ -485,6 +485,17 @@ var Reference = []Block{ {Key: "federation", Type: "Federation", Doc: "Federation is how this cluster takes part in federation with other\nllmgw clusters. The peers themselves are added at runtime, with\n`llmgw ctl federation add`, and kept in the store.", Nested: "config.Federation"}, {Key: "endpoints", Type: "[]Endpoint", Doc: "Endpoints is the phase-1 static replica list. It is only consulted when\nno model declares a profile, which is what makes a router-only smoke test\nagainst sim-engines possible without a control plane.", Nested: ""}, }}, + {Package: "guard", Name: "Service", Title: "Service", Doc: "", Fields: []Field{ + {Key: "name", Type: "string", Doc: "Name says which service decided, in the verdict's rule.", Nested: ""}, + {Key: "url", Type: "string", Doc: "URL is POSTed the body.", Nested: ""}, + {Key: "header_files", Type: "map[string]string", Doc: "HeaderFiles are headers whose values are read from files each time,\nso a rotated key needs no restart: {Authorization: /etc/…/lakera}.", Nested: ""}, + {Key: "body", Type: "string", Doc: "Body is the request, a template given .Text; {{json .Text}} writes it\nas a JSON string. Empty is {\"input\": }.", Nested: ""}, + {Key: "blocked", Type: "string", Doc: "Blocked is where in the answer the service says the text is unsafe:\na dotted path, numbers for list items (results.0.flagged). True, a\nnumber above zero, a non-empty list or string other than \"false\" is\nunsafe.", Nested: ""}, + {Key: "reason", Type: "string", Doc: "Reason is where it says why, for the verdict; optional.", Nested: ""}, + {Key: "on", Type: "string", Doc: "On: input, output or both. Empty is input.", Nested: ""}, + {Key: "action", Type: "string", Doc: "Action on unsafe: block or flag. Empty is block.", Nested: ""}, + {Key: "timeout", Type: "time.Duration", Doc: "Timeout bounds one call. Empty is 3s; past it the policy's fail says.", Nested: ""}, + }}, {Package: "config", Name: "ServingSettings", Title: "ServingSettings", Doc: "", Fields: []Field{ {Key: "stopped", Type: "bool", Doc: "Stopped takes every model down and answers every request for one with\n503 (system_stopped), leaving the control planes, agents and mirror\nrunning and every model's definition as it is: llmgw stop sets it,\nllmgw start clears it, and the models come back as their catalog\nentries ask. In force on every control plane within seconds.", Nested: ""}, }}, diff --git a/internal/docgen/render.go b/internal/docgen/render.go index 82c0c9a..a10e3e2 100644 --- a/internal/docgen/render.go +++ b/internal/docgen/render.go @@ -31,6 +31,7 @@ var Sources = []string{ "internal/router/admission/controller.go", "internal/accounting/cost.go", "internal/guard/policy.go", + "internal/guard/service.go", "internal/guard/judge.go", "internal/config/oidc.go", "internal/config/ldap.go",