Documentation
¶
Overview ¶
Package schemaread is the one strict read every typed message uses. It takes the functions a generated table gives a caller (load, measure, the JSON reader) as a Codec, detects the form of the incoming bytes or text (binary wire by its form byte, padded standard base64 of that wire, JSON text, or a legacy text the caller recognises), measures, loads, and refuses by name what the permissive load would only count: malformed, clamped, kind_mismatch, unknown_form, wire_damaged and an absent required field. A refusal reads `<NAME> REFUSED: <reason>; run: <help>`. Unknown fields are tolerated and counted. The reader counts each read once, on the form read, in counters a caller exports. The write side runs the same bounds before a byte is written, because the generated writer checks none of them.
The package imports no generated package: the generated table functions are passed in. The rules it holds are section 4.6 of the schema-tables union research (the facade rules) and the owner's S2: text transports carry both base64 and JSON, a reader accepts either, refuses damage by name and counts reads per form.
Index ¶
Constants ¶
const ( ReasonMalformed = "malformed" ReasonClamped = "clamped" ReasonKindMismatch = "kind_mismatch" ReasonUnknownForm = "unknown_form" ReasonWireDamaged = "wire_damaged" ReasonAbsentRequired = "absent_required" )
The refusal reasons, spelled as the generated tables spell them (UNION.md section 4.6).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Checker ¶
type Checker struct {
// contains filtered or unexported fields
}
Checker collects the first violation of a table's constraints.
type Codec ¶
type Codec[T any] struct { Name string // the refusal prefix, such as the message's type name Help string // the command a refusal points at: `run: <Help>` Reset func(*T) // restores the declared defaults before a load Forms []byte // the form bytes this reader knows; empty means {1} Measure func(wire []byte) error // the generated LoadMeasureReason shape; an error's text is the refusal reason LoadWire func(*T, []byte) Report // the generated Load over the whole wire, form byte included LoadJSON func(*T, []byte) Report // the generated FromJson Legacy func([]byte) bool // true when the input is the caller's legacy text LoadLegacy func(*T, []byte) Report // Constraints states the bounds of the table once, for the reader and the // writer: it calls the Checker for each field. A violation after a load is // a refusal; a violation before a write refuses the write. Constraints func(*T, *Checker) SaveWire func(*T) []byte // the generated Measure and Save, returning the whole wire SaveJSON func(*T) []byte // the generated ToJson }
Codec is one table's functions plus what the helper needs to refuse by name.
type Counts ¶
type Counts struct {
// contains filtered or unexported fields
}
Counts are the per-form read counters and the refusal and unknown-field tallies a caller exports.
type Form ¶
type Form int
Form is the form an incoming read arrived in.
type Reader ¶
type Reader[T any] struct { // contains filtered or unexported fields }
Reader reads one table strictly and counts its reads.
func (*Reader[T]) Check ¶
Check runs the table's constraints over v: what the reader refuses after a load, the writer refuses before it writes.
func (*Reader[T]) Detect ¶
Detect names the form of in. Legacy text is the caller's to recognise; JSON text opens with `{`; base64 text opens with a base64 character; anything else that is not printable text is the binary wire, whose form byte the load then checks.
type Refusal ¶
type Refusal struct {
Name string
Reason string
Field string // the field a constraint named, when one did
Help string
}
Refusal is the typed error of every refusal.
type Report ¶
type Report struct {
Unknown int // unknown field ids skipped (newer data): tolerated, counted
KindMismatch int // a known id with a changed kind, skipped
Clamped int // values clamped to the declared bounds
Malformed bool // framing damage, decode stopped
Reason string // a refusal the load names itself, such as unknown_form; empty otherwise
}
Report is what a load function tells the helper, the generated TableReport reduced to the fields the strict read decides on.
Source Files