Documentation
¶
Overview ¶
Package events provides a transport-agnostic event channel builder for go-codex.
Define channels with codec-backed payload types; the builder returns a ChannelHandle with typed Decode and Encode helpers. Pass those helpers to any message broker (MQTT, AMQP, Kafka, NATS) — this package does not import any messaging library.
Spec generation is also available: Builder.AsyncAPISpec derives a complete AsyncAPI 2.6 document from the registered channels.
Typical usage:
b := events.NewBuilder(events.Info{Title: "User Events", Version: "1.0.0"})
b.AddServer("production", events.Server{
URL: "mqtt://broker.example.com",
Protocol: "mqtt",
})
userCreated := events.AddChannel[UserCreated](b, "user/created", userCreatedCodec,
events.ChannelConfig{
Subscribe: &events.OperationConfig{
Summary: "A user was created",
SchemaName: "UserCreatedEvent",
},
})
// In your broker callback (any library):
event, err := userCreated.Decode(msg.Payload()) // JSON → UserCreated, validates
payload, err := userCreated.Encode(event) // UserCreated → JSON
// AsyncAPI 2.6 spec:
doc, err := b.AsyncAPISpec()
yaml, _ := doc.MarshalYAML()
Encoding is JSON only. AddChannel uses format.JSON internally; for other formats construct a format.Format directly and call its Unmarshal/Marshal.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder accumulates channel registrations and produces AsyncAPI specs. Create one with NewBuilder.
func NewBuilder ¶
NewBuilder returns a Builder initialised with the given API metadata.
func (*Builder) AddSchema ¶
AddSchema registers a named schema in components/schemas. Use this to register reusable schemas that are referenced by SchemaName in channel configs but not inlined in any codec.
func (*Builder) AsyncAPISpec ¶
AsyncAPISpec builds a complete AsyncAPI 2.6 document from all registered channels. Returns an error if any non-empty SchemaName references a schema that will not be present in components/schemas (a dangling $ref).
type ChannelConfig ¶
type ChannelConfig struct {
Description string
// Subscribe describes the operation where the application receives messages.
// Set to nil to omit the subscribe operation from the spec.
Subscribe *OperationConfig
// Publish describes the operation where the application sends messages.
// Set to nil to omit the publish operation from the spec.
Publish *OperationConfig
}
ChannelConfig holds metadata for a channel registration.
At least one of Subscribe or Publish must be non-nil. When both are set, the same payload codec is used for both directions.
type ChannelHandle ¶
type ChannelHandle[T any] struct { // Topic is the channel name (e.g. "user/created", "orders.placed"). Topic string // Descriptor is the frozen asyncapi.ChannelItem built at registration time. Descriptor asyncapi.ChannelItem // Decode deserialises and validates a JSON payload into T. // All Refine constraints on the payload codec run automatically. Decode func(payload []byte) (T, error) // Encode serialises T to JSON bytes. Encode func(msg T) ([]byte, error) }
ChannelHandle is returned by AddChannel. It holds the frozen spec descriptor and codec-backed Decode/Encode helpers.
func AddChannel ¶
func AddChannel[T any]( b *Builder, topic string, codec codex.Codec[T], config ChannelConfig, ) *ChannelHandle[T]
AddChannel registers a channel with the builder and returns a ChannelHandle.
codec is used to decode and validate incoming payloads and to encode outgoing messages. The same codec applies to both subscribe and publish directions.
AddChannel is a free function (not a method) because Go requires type parameters to appear on free functions, not on method receivers.
The descriptor is built and frozen at call time; later mutations to config do not affect the registered channel or the returned handle.
type Info ¶
Info is an alias for asyncapi.Info. Using the alias avoids duplicating fields and keeps the two in sync automatically.
type OperationConfig ¶
type OperationConfig struct {
Summary string
Description string
Tags []string
// SchemaName, when non-empty, emits a $ref for the payload schema in the
// spec and registers the schema under that name in components/schemas.
SchemaName string
}
OperationConfig holds metadata for one direction (subscribe or publish) on a channel. It controls the operation entry in the AsyncAPI spec.
Source Files