vws

README

Vinculum WebSockets

"The [vinculum is the] processing device at the core of every Borg vessel. It interconnects the minds of all the drones." -- Seven of Nine (In Voyager episode "Infinite Regress")

VWS (Vinculum WebSockets) is a simple, WebSocket based publish/subscribe protocol on top of WebSockets, with MQTT-esque fucntionality. This project, an add on to vinculum-bus, lets you expose an EventBus to clients over websockets using the server component, or to access such a server using the client component.

WebSocket Server

Expose your EventBus over WebSockets for real-time web applications:

• Real-time event streaming to web clients
• Bidirectional communication (subscribe + publish)
• Flexible authorization policies
• Built-in metrics and connection management
• Message transformations and filtering

📖 WebSocket Server Documentation

🔌 WebSocket Client

Connect to Vinculum WebSocket servers from Go applications:

• Auto-reconnection with exponential backoff
• Subscription management and persistence
• Thread-safe operations
• Builder pattern for easy configuration

📖 WebSocket Client Documentation

📋 Protocol

Both components implement the Vinculum WebSocket Protocol:

• JSON-based with compact message format
• MQTT-style topic patterns
• Request/response correlation
• Error handling and acknowledgments

The protocol should be easy to implement in other languages, such as JavaScript.

📖 Protocol Specification

License

MIT License - see LICENSE file for details.

---

Vinculum (Latin: "bond" or "link") - connecting your application components with reliable, observable messaging.

Documentation

Index

• Constants
• func ExtractTrace(ctx context.Context, msg WireMessage) context.Context
• func HeadersFromContext(ctx context.Context) map[string]string
• func InjectTrace(ctx context.Context, msg *WireMessage)
• type WireMessage

Constants

const (
	// Client to Server message kinds
	MessageKindSubscribe      = "s" // Subscribe to a topic pattern
	MessageKindUnsubscribe    = "u" // Unsubscribe from a topic pattern
	MessageKindUnsubscribeAll = "U" // Unsubscribe from all topics

	// Server to Client message kinds
	MessageKindAck  = "a" // Positive acknowledgment of client request
	MessageKindNack = "n" // Negative acknowledgment (error response)

	// Bidirectional - Event messages have no "k" field
	// They are identified by the presence of "t" (topic) and "d" (data) fields
	MessageKindEvent = "" // Event message
)

Message kind constants for the Vinculum WebSocket protocol. These correspond to the "k" (kind) field in wire messages.

Functions

func ExtractTrace

func ExtractTrace(ctx context.Context, msg WireMessage) context.Context

ExtractTrace extracts trace context from msg.Headers and returns a derived context. If Headers is empty or no propagator is configured, the original ctx is returned unchanged.

func HeadersFromContext

func HeadersFromContext(ctx context.Context) map[string]string

HeadersFromContext extracts propagation headers from ctx as a map, or nil if empty. This is used by the server's pre-allocated eventMsg map to avoid creating a WireMessage.

func InjectTrace

func InjectTrace(ctx context.Context, msg *WireMessage)

InjectTrace injects trace context from ctx into msg.Headers using the global propagator. If no propagator is configured (the default no-op), this is a no-op and Headers is unchanged.

Types

type WireMessage

type WireMessage struct {
	Kind    string            `json:"k,omitempty"` // Message kind/type (see MessageKind constants)
	Topic   string            `json:"t,omitempty"` // Topic or topic pattern
	Data    any               `json:"d,omitempty"` // Event data/payload
	Id      any               `json:"i,omitempty"` // Message identifier for request/response matching
	Error   string            `json:"e,omitempty"` // Error message (used with NACK)
	Headers map[string]string `json:"h,omitempty"` // Generic headers (e.g. W3C trace context)
}

WireMessage represents the JSON structure for WebSocket messages. This follows the Vinculum WebSocket protocol with short field names for efficiency.