wspulse

README

wspulse/core

Shared types for the wspulse WebSocket ecosystem.

This module provides Frame, Codec, JSONCodec, and sentinel errors used by both wspulse/server and wspulse/client-go. It has zero external dependencies (Go stdlib only).

Status: v0 — API is being stabilized. Module path: github.com/wspulse/core.

---

Install

go get github.com/wspulse/core

---

Quick Start

import wspulse "github.com/wspulse/core"

// Create a frame
frame := wspulse.Frame{
    ID:      "msg-001",
    Type:    "msg",
    Payload: []byte(`{"text":"hello"}`),
}

// Encode with the default JSON codec
data, err := wspulse.JSONCodec.Encode(frame)
if err != nil {
    log.Fatal(err)
}

// Decode
decoded, err := wspulse.JSONCodec.Decode(data)
if err != nil {
    log.Fatal(err)
}

fmt.Println(decoded.Type) // "msg"

// Check the codec's WebSocket frame type
wspulse.JSONCodec.FrameType() // wspulse.TextMessage (1)

Sentinel errors

if errors.Is(err, wspulse.ErrConnectionClosed) {
    // connection was already closed
}
if errors.Is(err, wspulse.ErrSendBufferFull) {
    // outbound buffer full, frame was dropped
}

---

Public API

Symbol	Description
Frame	Transport unit: ID, Type, Payload []byte
Codec	Interface: Encode(Frame), Decode([]byte), FrameType() int
JSONCodec	Default codec — JSON text frames
TextMessage	WebSocket text frame type constant (1)
BinaryMessage	WebSocket binary frame type constant (2)
ErrConnectionClosed	Sentinel: connection is closed
ErrSendBufferFull	Sentinel: send buffer full, frame dropped

---

Related

• wspulse/server — WebSocket server library
• wspulse/client-go — Go WebSocket client with auto-reconnect

---

License

MIT

Documentation

Index

• Constants
• Variables
• type Codec
• type Frame

Constants

const (
	// TextMessage denotes a UTF-8 encoded text WebSocket frame (opcode 1).
	TextMessage = 1

	// BinaryMessage denotes a binary WebSocket frame (opcode 2).
	BinaryMessage = 2
)

WebSocket message type constants. These mirror the standard WebSocket frame types without importing gorilla/websocket, keeping this module free of external dependencies.

Variables

var (
	// ErrConnectionClosed is returned when sending to a connection that has already been closed.
	ErrConnectionClosed = errors.New("wspulse: connection is closed")

	// ErrSendBufferFull is returned when the outbound buffer is full.
	// The frame is dropped; handle backpressure at the application layer.
	ErrSendBufferFull = errors.New("wspulse: send buffer full, frame dropped")
)

Sentinel errors shared across the wspulse ecosystem.

Types

type Codec

type Codec interface {
	// Encode serializes f into bytes ready to be sent as a WebSocket frame.
	Encode(f Frame) ([]byte, error)

	// Decode deserializes received WebSocket bytes into a Frame.
	Decode(data []byte) (Frame, error)

	// FrameType returns the WebSocket message type to use when sending:
	// TextMessage (1) or BinaryMessage (2).
	FrameType() int
}

Codec encodes and decodes Frames for transmission over a WebSocket connection.

var JSONCodec Codec = jsonCodec{}

JSONCodec is the default Codec. Frames are encoded as JSON text frames. Frame.Payload must be valid JSON bytes (e.g. the output of json.Marshal).

type Frame

type Frame struct {
	// ID uniquely identifies this frame. Used for ACK correlation.
	// If empty on Send, no ID is set on the wire.
	ID string

	// Type classifies the frame purpose. wspulse does not interpret this value.
	// Conventional values: "msg" (user data), "sys" (system event), "ack" (acknowledgement).
	Type string

	// Payload is the encoded message body. Its format is determined by the Codec.
	Payload []byte
}

Frame is the minimal transport unit for all WebSocket communication. Payload bytes are opaque to the wspulse layer; their format depends on the Codec in use. When using JSONCodec (the default), Payload must be valid JSON bytes (e.g. output of json.Marshal). When using a binary codec, Payload is the codec-encoded bytes.