Documentation
¶
Overview ¶
Package buscodec is the runtime's canonical message-bus codec (ADR-0036). Every thestack broker MUST encode bus payloads through this package and MUST NOT import encoding/json or call cbor.Marshal/Unmarshal directly. The default codec is CBOR (fxamacker/cbor with canonical encoding); a CodecI seam allows swapping for replay or debug builds.
Field tags: the default CBOR codec (fxamacker/cbor) honours `cbor:` tags and otherwise uses the Go field name — it does NOT read `json:` tags. Encode/Decode are symmetric through a single codec, so this is internally consistent; the `json:` tags several DTOs carry only take effect under the opt-in jsonCodec (NewJSON, for human-readable replay) and do not change the CBOR wire. Do not assume a `json:`-named key appears on the CBOR wire.
Versioning: this package does NOT impose envelope versioning on the wire. Per-message versioning is a payload concern — brokers that need it (e.g. chlocalbroker) carry a uint8 V field on the struct.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var PackageProps = packageprops.Props{ WASMWASI: packageprops.WASMCompiles, WASMJS: packageprops.WASMCompiles, WASMFreestanding: packageprops.WASMCompiles, }
PackageProps records this package's curated properties (ADR-0080). Seeded by `boxer code analysis golang wasmsurvey props generate`; curate by hand. The same group's `props verify` reconciles it.
Functions ¶
func Encode ¶
Encode is the generic call-site helper. Routes through the per-type registry if T is registered, else through Default(). Centralises the eh.Errorf wrap so brokers don't repeat it per payload type.
func Register ¶
Register installs a per-type codec for T. Subsequent Encode[T] / Decode[T] / Reply[T] calls route through `codec` instead of Default(). Passing nil unregisters T (so the next call falls back to Default()).
Goroutine-safe; intended for package-init or test setup. Re-registering overwrites the previous codec without warning.
func Reply ¶
func Reply[T any](pub PublishFunc, subject string, v T) (err error)
Reply folds the broker-side "encode v and publish on subject" pattern — replaces the per-broker replyJSON helpers.
func SetDefault ¶
func SetDefault(c CodecI)
SetDefault swaps the process-wide codec. Intended for init-time use by tests, debug builds, or capture-replay tools. Reads after the call observe the new codec; concurrent SetDefault calls race with each other but not with Default — Default is always safe.
Types ¶
type CodecI ¶
type CodecI interface {
// Name returns a short stable identifier (e.g. "cbor", "json"). Used
// for diagnostics and content-type emission.
Name() (n string)
// ContentType returns the MIME type for the wire format.
ContentType() (ct string)
// Encode serialises v into a freshly-allocated slice.
Encode(v any) (b []byte, err error)
// Decode populates v from b. v MUST be a non-nil pointer.
Decode(b []byte, v any) (err error)
}
CodecI is the wire-format contract. Implementations must be goroutine- safe. Encode may pool buffers internally but the returned slice is caller-owned: callers may retain it past the call.
type PublishFunc ¶
PublishFunc matches inprocbus.Client.Publish so brokers can pass their client's Publish into Reply without an adapter.
Source Files