Documentation
¶
Overview ¶
Package refusal names why locksql refused a statement. Every refusal carries a stable code an agent can act on, the place of the statement it points at when one is known, and a rewrite hint.
A refusal never carries more than the agent could already see: the reason and the hint are written by locksql (never the database's text), and the token of a span is a word or a punctuation sign of the agent's own statement, never a literal.
Index ¶
Constants ¶
const MaxToken = 40
MaxToken bounds the token of a span, in bytes.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ( // Parsing and statement shape. UnsupportedSyntax Code = "E_UNSUPPORTED_SYNTAX" MultiStatement Code = "E_MULTI_STATEMENT" ForbiddenToken Code = "E_FORBIDDEN_TOKEN" StatementKind Code = "E_STATEMENT_KIND" InvalidSQL Code = "E_INVALID_SQL" UnknownName Code = "E_UNKNOWN_NAME" TooComplex Code = "E_TOO_COMPLEX" Size Code = "E_SIZE" // Constructs refused at every tier. Forbidden Code = "E_FORBIDDEN" Function Code = "E_FUNCTION" SystemObject Code = "E_SYSTEM_OBJECT" // Limits and policy. NoLimit Code = "E_NO_LIMIT" LimitTooHigh Code = "E_LIMIT_TOO_HIGH" Tier Code = "E_TIER" DatabaseNotServed Code = "E_DATABASE_NOT_SERVED" UnmaskOff Code = "E_UNMASK_OFF" Cost Code = "E_COST" // KAnon is no longer emitted (v0.5.2): a k-anonymity count under k // is a warning on the approval screen. The code stays known so that // past audit records keep it, and is never reused. // // Deprecated: no refusal carries it. KAnon Code = "E_K_ANON" Engine Code = "E_ENGINE" Placeholder Code = "E_PLACEHOLDER" MaskedFilter Code = "E_MASKED_FILTER" MaskedExpression Code = "E_MASKED_EXPRESSION" MaskedOrder Code = "E_MASKED_ORDER" MaskedSetOp Code = "E_MASKED_SET_OP" MaskUncertain Code = "E_MASK_UNCERTAIN" MaskedWrite Code = "E_MASKED_WRITE" // Policy is the fail-closed code of a refusal no check named: it // should never be seen, and is a bug to report. Policy Code = "E_POLICY" )
The refusal codes. docs/usage.md describes each one.
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; // locksql_request_change 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