wire

package

v0.2.0 Latest Latest Go to latest Published: Mar 25, 2026 License: MIT Imports: 2 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/jpl-au/tether

Links

Open Source Insights

Documentation ¶

Overview ¶

Package wire defines the encoding abstraction for server-to-client updates. The Format type selects which Encoder implementation serialises updates into bytes for the transport layer.

Currently the only supported format is JSON. Additional formats (e.g. HTML fragments) will be added in future.

Index ¶

type Encoder
type Format
type JSONEncoder
- func (JSONEncoder) Encode(u Update) ([]byte, error)
type Morph
type Patch
type Update

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Encoder ¶

type Encoder interface {
	Encode(u Update) ([]byte, error)
}

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
)

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.

func (JSONEncoder) Encode ¶

func (JSONEncoder) Encode(u Update) ([]byte, error)

Encode serialises u as a compact JSON object, omitting empty fields.

type Morph ¶

type Morph struct {
	Key  string
	HTML []byte
}

Morph is a structural change applied via idiomorph. An empty Key targets the root element.

type Patch ¶

type Patch struct {
	Key  string
	HTML []byte
}

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
	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 ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL