Documentation
¶
Overview ¶
Package wire defines the encoding abstraction for server-to-client updates.
The Format type selects which Encoder implementation serialises updates. Two formats are provided:
- JSON encodes as a single JSON object. This is the default.
- CBOR encodes as a binary CBOR map (RFC 8949) for smaller payloads and faster encoding.
Set Format on [tether.App].WireFormat for an app-wide default, or on [tether.StatefulConfig].WireFormat for a specific handler. Per-handler settings override the app default. The zero value is JSON.
Custom encoders can implement the Encoder interface and be wired in via a new Format constant.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CBOREncoder ¶ added in v0.3.2
type CBOREncoder struct{}
CBOREncoder encodes updates as CBOR (RFC 8949) using the same field names as the JSON encoder. The fxamacker/cbor library reads json struct tags when cbor tags are absent, so the [updateMessage] struct is shared between both encoders.
type Encoder ¶
Encoder serialises an Update into bytes for transport. The session calls Encode after each render-diff cycle; the resulting bytes are passed directly to Transport.Send.
type Format ¶
type Format int
Format selects the encoding used for updates sent from server to client. Pass one of the constants to [tether.StatefulConfig].WireFormat.
const ( // JSON encodes updates as a single JSON object containing // patches, morphs, signals, and side effects. This is the // default format. JSON Format = iota // CBOR encodes updates as a binary CBOR map (RFC 8949) using // the same field names as the JSON encoder. CBOR produces // smaller payloads and faster encoding at the cost of // human-readability. CBOR )
type JSONEncoder ¶
type JSONEncoder struct{}
JSONEncoder encodes updates as JSON with HTML escaping disabled. HTML escaping is intentionally off because patches carry pre-rendered HTML from the fluent template engine, which is responsible for escaping user-provided values. No secondary sanitisation is performed at the transport layer.
type Morph ¶
Morph is a structural change applied via idiomorph. An empty Key targets the root element.
type Patch ¶
Patch is a targeted content replacement. Key identifies a Dynamic-keyed element in the DOM; HTML replaces its innerHTML.
type Update ¶
type Update struct {
Patches []Patch
Morphs []Morph
Session string // if non-empty, client must adopt this session ID
URL string // if non-empty, push/replace browser URL
Replace bool // true for replaceState, false for pushState
Title string // if non-empty, set document.title
Flash map[string]string // key: CSS selector, value: plain text to display
Signals map[string]any // key: signal name, value: pushed to bound elements
Announce string // if non-empty, inject into an aria-live region
Toast string // if non-empty, show a global notification
ScrollTo string // if non-empty, scroll element into view
Download string // if non-empty, trigger a file download from this URL
EventID string // echoed from the triggering Event for correlation
}
Update is the format-agnostic representation of changes to send to the client. A single update can carry any combination of content patches (targeted key replacements), structural morphs (DOM mutations applied via idiomorph), URL changes (pushState/ replaceState), and side effects (signals, toasts, flashes). Combining them in one message lets the client apply everything atomically in a single pass.
Source Files