Documentation
¶
Overview ¶
Package refusal names why a console refused a request. Every refusal carries a stable code an agent can act on, the place of the request it points at when one is known, and a rewrite hint.
Products register their codes at init time (Register); lockkit itself defines only Policy, the fail-closed code. A refusal never carries more than the agent could already see: the reason and the hint are written by the product (never a backend's text), and the token of a span is a word or a punctuation sign of the agent's own request, never a literal.
Index ¶
Constants ¶
const MaxToken = 40
MaxToken bounds the token of a span, in bytes.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Code ¶
type Code string
Code is a stable refusal code. Codes are part of the client protocol and of the agent instructions: never rename one.
const Policy Code = "E_POLICY"
Policy is the fail-closed code of a refusal no check named: it should never be seen, and is a bug to report.
func Codes ¶
func Codes() []Code
Codes lists every code a refusal may carry, sorted; retired codes are left out.
type Error ¶
type Error struct {
Code Code
Reason string
// Hint overrides the code's default hint.
Hint string
// Pos is the byte offset, in the text the check read, of what the
// refusal points at; -1 when unknown. Token is the word or
// punctuation sign found there, "" for a literal or a quoted name.
Pos int
Token string
// Secret marks a statement that may carry a secret (a password): its
// literals must not be recorded.
Secret bool
}
Error is a refused statement. Reason is the prose message; it never quotes a literal of the statement nor any text from the database.
func From ¶
From returns the refusal err is or wraps. An error without a known code is still a refusal (fail closed), under the Policy code.
func (*Error) At ¶
At sets the position and the token and returns e. Pass "" as the token of a literal or a quoted name.
func (*Error) Info ¶
Info is the structured form of e. src is the statement the agent sent and base the offset in src of the text e's position counts in. A position outside src, or inside a character, gives no span.
type Info ¶
type Info struct {
Code Code `json:"code"`
Retry Retry `json:"retry"`
Hint string `json:"hint,omitempty"`
Span *Span `json:"span,omitempty"`
}
Info is the structured form of a refusal, sent to clients next to the prose message.
type Retry ¶
type Retry string
Retry is what an agent may do after a refusal.
const ( // RetryRewrite: the statement can be fixed. Rewrite it as the hint // says and plan it again; the console checks the new one in full. RetryRewrite Retry = "rewrite" // RetryAskUser: only the human can lift this. Tell the user; the // product's change request may queue a proposal. RetryAskUser Retry = "ask_user" // RetryStop: final for this question. Tell the user; do not reword, // split or retry it. RetryStop Retry = "stop" )
Source Files