emitter

package
v3.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 20, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package emitter provides broadcast capabilities for Socket.IO via PostgreSQL LISTEN/NOTIFY.

Package emitter provides an API for broadcasting messages to Socket.IO servers via PostgreSQL without requiring a full Socket.IO server instance.

Package emitter provides types and interfaces for broadcasting messages to Socket.IO servers using PostgreSQL LISTEN/NOTIFY.

Package emitter provides an API for broadcasting messages to Socket.IO servers via PostgreSQL without requiring a full Socket.IO server instance.

This is useful for sending messages from other processes or services that don't run a Socket.IO server but need to communicate with connected clients.

Index

Constants

View Source 
const (
	// DefaultEmitterKey is the default PostgreSQL channel prefix for the emitter.
	DefaultEmitterKey = "socket.io"

	// DefaultTableName is the default name for the attachment storage table.
	DefaultTableName = "socket_io_attachments"

	// DefaultPayloadThreshold is the default byte threshold for using attachment storage.
	// PostgreSQL's NOTIFY payload limit is 8000 bytes.
	DefaultPayloadThreshold = 8000
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BroadcastMessage 

type BroadcastMessage = adapter.BroadcastMessage

BroadcastMessage is an alias for adapter.BroadcastMessage. It is used for broadcasting.

type BroadcastOperator 

type BroadcastOperator struct {
	// contains filtered or unexported fields
}

BroadcastOperator provides a fluent API for broadcasting events to Socket.IO clients via PostgreSQL. It supports room targeting, exclusions, and broadcast flags through method chaining.

func MakeBroadcastOperator 

func MakeBroadcastOperator() *BroadcastOperator

MakeBroadcastOperator creates a new BroadcastOperator with empty room sets and default flags.

func NewBroadcastOperator 

func NewBroadcastOperator(
	client *postgres.PostgresClient,
	broadcastOptions *BroadcastOptions,
	rooms *types.Set[socket.Room],
	exceptRooms *types.Set[socket.Room],
	flags *socket.BroadcastFlags,
) *BroadcastOperator

NewBroadcastOperator creates and initializes a new BroadcastOperator with the given configuration. Nil parameters are replaced with safe defaults.

func (*BroadcastOperator) Compress 

func (b *BroadcastOperator) Compress(compress bool) BroadcastOperatorInterface

Compress sets the compress flag for the broadcast. When true, the message will be compressed before transmission.

func (*BroadcastOperator) Construct 

func (b *BroadcastOperator) Construct(
	client *postgres.PostgresClient,
	broadcastOptions *BroadcastOptions,
	rooms *types.Set[socket.Room],
	exceptRooms *types.Set[socket.Room],
	flags *socket.BroadcastFlags,
)

Construct initializes the BroadcastOperator with the given parameters. This method is called by NewBroadcastOperator and handles nil safety.

func (*BroadcastOperator) DisconnectSockets 

func (b *BroadcastOperator) DisconnectSockets(state bool) error

DisconnectSockets disconnects all matching socket instances. If state is true, the underlying transport connection will be closed. This sends a DISCONNECT_SOCKETS ClusterMessage to all Socket.IO servers in the cluster.

func (*BroadcastOperator) Emit 

func (b *BroadcastOperator) Emit(ev string, args ...any) error

Emit broadcasts an event with the given name and arguments to all targeted clients. Returns an error if the event name is reserved or if broadcasting fails.

The message is sent as a ClusterMessage in JSON format via pg_notify. If the payload exceeds the configured threshold (default: 8000 bytes) or contains binary data, the message is msgpack-encoded and stored in the attachment table, matching the Node.js adapter wire protocol.

func (*BroadcastOperator) Except 

func (b *BroadcastOperator) Except(room ...socket.Room) BroadcastOperatorInterface

Except excludes one or more rooms from the broadcast. Returns a new BroadcastOperator with the rooms added to the exclusion list.

func (*BroadcastOperator) In 

func (b *BroadcastOperator) In(room ...socket.Room) BroadcastOperatorInterface

In is an alias for To, targeting one or more rooms for the broadcast.

func (*BroadcastOperator) ServerSideEmit 

func (b *BroadcastOperator) ServerSideEmit(args ...any) error

ServerSideEmit sends a message to all Socket.IO servers in the cluster. The first argument should be the event name, followed by any data arguments. Note: Acknowledgements are not supported when using the emitter.

func (*BroadcastOperator) SocketsJoin 

func (b *BroadcastOperator) SocketsJoin(rooms ...socket.Room) error

SocketsJoin makes all matching socket instances join the specified rooms. This sends a SOCKETS_JOIN ClusterMessage to all Socket.IO servers in the cluster.

func (*BroadcastOperator) SocketsLeave 

func (b *BroadcastOperator) SocketsLeave(rooms ...socket.Room) error

SocketsLeave makes all matching socket instances leave the specified rooms. This sends a SOCKETS_LEAVE ClusterMessage to all Socket.IO servers in the cluster.

func (*BroadcastOperator) To 

func (b *BroadcastOperator) To(room ...socket.Room) BroadcastOperatorInterface

To targets one or more rooms for the broadcast. Returns a new BroadcastOperator with the additional rooms included.

func (*BroadcastOperator) Volatile 

func (b *BroadcastOperator) Volatile() BroadcastOperatorInterface

Volatile sets the volatile flag for the broadcast. When set, the event data may be lost if the client is not ready to receive.

type BroadcastOperatorInterface 

type BroadcastOperatorInterface interface {
	To(room ...socket.Room) BroadcastOperatorInterface
	In(room ...socket.Room) BroadcastOperatorInterface
	Except(room ...socket.Room) BroadcastOperatorInterface
	Compress(compress bool) BroadcastOperatorInterface
	Volatile() BroadcastOperatorInterface
	Emit(ev string, args ...any) error
	SocketsJoin(rooms ...socket.Room) error
	SocketsLeave(rooms ...socket.Room) error
	DisconnectSockets(state bool) error
	ServerSideEmit(args ...any) error
}

BroadcastOperatorInterface defines the common interface for broadcast operators.

type BroadcastOptions 

type BroadcastOptions struct {
	// Nsp is the Socket.IO namespace for the broadcast.
	Nsp string

	// BroadcastChannel is the PostgreSQL channel used for all messages.
	// Format: "{key}#{nsp}"
	BroadcastChannel string

	// TableName is the name of the attachment table for large payloads.
	TableName string

	// PayloadThreshold is the byte threshold above which payloads are stored in the attachment table.
	PayloadThreshold int
}

BroadcastOptions contains configuration for broadcasting messages via PostgreSQL channels. These options determine how messages are routed and encoded.

type ClusterMessage 

type ClusterMessage = adapter.ClusterMessage

ClusterMessage is an alias for adapter.ClusterMessage. It is used for cluster communication.

type DisconnectSocketsMessage 

type DisconnectSocketsMessage = adapter.DisconnectSocketsMessage

DisconnectSocketsMessage is an alias for adapter.DisconnectSocketsMessage. It is used for disconnection operations.

type Emitter 

type Emitter struct {
	// contains filtered or unexported fields
}

Emitter broadcasts messages to Socket.IO servers using PostgreSQL LISTEN/NOTIFY. It allows sending events to clients without running a full Socket.IO server.

func MakeEmitter 

func MakeEmitter() *Emitter

MakeEmitter creates a new Emitter with default options and the root namespace. Call Construct() to complete initialization before use.

func NewEmitter 

func NewEmitter(client *postgres.PostgresClient, opts *EmitterOptions, nsps ...string) *Emitter

NewEmitter creates and initializes a new Emitter with the given PostgreSQL client and options. An optional namespace can be provided; if not specified, the root namespace "/" is used.

func (*Emitter) Compress 

func (e *Emitter) Compress(compress bool) BroadcastOperatorInterface

Compress sets the compress flag for the broadcast. When true, the message will be compressed before sending.

func (*Emitter) Construct 

func (e *Emitter) Construct(client *postgres.PostgresClient, opts *EmitterOptions, nsps ...string)

Construct initializes the Emitter with the given PostgreSQL client, options, and namespace. This method sets up the broadcast and request channels based on the configured key prefix.

func (*Emitter) DisconnectSockets 

func (e *Emitter) DisconnectSockets(state bool) error

DisconnectSockets disconnects all matching socket instances. If state is true, the underlying connection will be closed.

func (*Emitter) Emit 

func (e *Emitter) Emit(ev string, args ...any) error

Emit broadcasts an event to all clients in the namespace. Returns an error if the event emission fails.

func (*Emitter) Except 

func (e *Emitter) Except(rooms ...socket.Room) BroadcastOperatorInterface

Except excludes specific room(s) from event emission. Returns a BroadcastOperatorInterface for method chaining.

func (*Emitter) In 

func (e *Emitter) In(rooms ...socket.Room) BroadcastOperatorInterface

In is an alias for To, targeting specific room(s) for event emission.

func (*Emitter) Of 

func (e *Emitter) Of(nsp string) *Emitter

Of returns a new Emitter for the specified namespace. If the namespace doesn't start with "/", it will be prepended.

func (*Emitter) ServerSideEmit 

func (e *Emitter) ServerSideEmit(args ...any) error

ServerSideEmit sends a message to all Socket.IO servers in the cluster. Note: Acknowledgements are not supported when using the emitter.

func (*Emitter) SocketsJoin 

func (e *Emitter) SocketsJoin(rooms ...socket.Room) error

SocketsJoin makes all matching socket instances join the specified rooms. This sends a request to all Socket.IO servers in the cluster.

func (*Emitter) SocketsLeave 

func (e *Emitter) SocketsLeave(rooms ...socket.Room) error

SocketsLeave makes all matching socket instances leave the specified rooms. This sends a request to all Socket.IO servers in the cluster.

func (*Emitter) To 

func (e *Emitter) To(rooms ...socket.Room) BroadcastOperatorInterface

To targets specific room(s) for event emission. Returns a BroadcastOperatorInterface for method chaining.

func (*Emitter) Volatile 

func (e *Emitter) Volatile() BroadcastOperatorInterface

Volatile sets a flag indicating the event data may be lost if the client is not ready to receive messages (e.g., due to network issues).

type EmitterOptions 

type EmitterOptions struct {
	// contains filtered or unexported fields
}

EmitterOptions holds configuration options for the PostgreSQL emitter. All fields are optional and will use default values if not explicitly set.

func DefaultEmitterOptions 

func DefaultEmitterOptions() *EmitterOptions

DefaultEmitterOptions creates a new EmitterOptions instance with default values.

func (*EmitterOptions) Assign 

func (o *EmitterOptions) Assign(data EmitterOptionsInterface) EmitterOptionsInterface

Assign copies non-nil option values from another EmitterOptionsInterface. This allows merging configuration from multiple sources.

func (*EmitterOptions) GetRawKey 

func (o *EmitterOptions) GetRawKey() types.Optional[string]

GetRawKey returns the raw Optional value for key.

func (*EmitterOptions) GetRawParser 

func (o *EmitterOptions) GetRawParser() types.Optional[postgres.Parser]

GetRawParser returns the raw Optional value for parser.

func (*EmitterOptions) GetRawPayloadThreshold 

func (o *EmitterOptions) GetRawPayloadThreshold() types.Optional[int]

GetRawPayloadThreshold returns the raw Optional value for payloadThreshold.

func (*EmitterOptions) GetRawTableName 

func (o *EmitterOptions) GetRawTableName() types.Optional[string]

GetRawTableName returns the raw Optional value for tableName.

func (*EmitterOptions) Key 

func (o *EmitterOptions) Key() string

Key returns the configured channel prefix, or empty string if not set.

func (*EmitterOptions) Parser 

func (o *EmitterOptions) Parser() postgres.Parser

Parser returns the configured parser, or nil if not set.

func (*EmitterOptions) PayloadThreshold 

func (o *EmitterOptions) PayloadThreshold() int

PayloadThreshold returns the configured payload threshold, or 0 if not set.

func (*EmitterOptions) SetKey 

func (o *EmitterOptions) SetKey(key string)

SetKey sets the PostgreSQL channel prefix.

func (*EmitterOptions) SetParser 

func (o *EmitterOptions) SetParser(parser postgres.Parser)

SetParser sets the parser for message encoding/decoding.

func (*EmitterOptions) SetPayloadThreshold 

func (o *EmitterOptions) SetPayloadThreshold(threshold int)

SetPayloadThreshold sets the byte threshold for attachment storage.

func (*EmitterOptions) SetTableName 

func (o *EmitterOptions) SetTableName(tableName string)

SetTableName sets the attachment table name.

func (*EmitterOptions) TableName 

func (o *EmitterOptions) TableName() string

TableName returns the configured table name, or empty string if not set.

type EmitterOptionsInterface 

type EmitterOptionsInterface interface {
	// SetKey sets the PostgreSQL channel prefix for notifications.
	SetKey(string)
	// GetRawKey returns the raw Optional wrapper for the key setting.
	GetRawKey() types.Optional[string]
	// Key returns the PostgreSQL channel prefix, or empty string if not set.
	Key() string

	// SetParser sets the parser for encoding messages.
	SetParser(postgres.Parser)
	// GetRawParser returns the raw Optional wrapper for the parser setting.
	GetRawParser() types.Optional[postgres.Parser]
	// Parser returns the parser, or nil if not set.
	Parser() postgres.Parser

	// SetTableName sets the attachment table name.
	SetTableName(string)
	// GetRawTableName returns the raw Optional wrapper for the tableName setting.
	GetRawTableName() types.Optional[string]
	// TableName returns the attachment table name, or empty string if not set.
	TableName() string

	// SetPayloadThreshold sets the byte threshold for attachment storage.
	SetPayloadThreshold(int)
	// GetRawPayloadThreshold returns the raw Optional wrapper for the payloadThreshold setting.
	GetRawPayloadThreshold() types.Optional[int]
	// PayloadThreshold returns the payload threshold, or 0 if not set.
	PayloadThreshold() int
}

EmitterOptionsInterface defines the interface for configuring emitter options. It provides getters and setters for all configurable options.

type NotificationMessage added in v3.0.2 

type NotificationMessage = postgres.NotificationMessage

NotificationMessage represents a message received via PostgreSQL LISTEN/NOTIFY.

type ServerSideEmitMessage 

type ServerSideEmitMessage = adapter.ServerSideEmitMessage

ServerSideEmitMessage is an alias for adapter.ServerSideEmitMessage. It is used for server-side emit operations.

type SocketsJoinLeaveMessage 

type SocketsJoinLeaveMessage = adapter.SocketsJoinLeaveMessage

SocketsJoinLeaveMessage is an alias for adapter.SocketsJoinLeaveMessage. It is used for join/leave operations.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.