emitter

package
v3.0.6 Latest Latest
Warning

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

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

Documentation

Overview

Package emitter provides broadcast capabilities for Socket.IO via Redis pub/sub.

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

Package emitter provides types and interfaces for broadcasting messages to Socket.IO servers using Redis pub/sub.

Package emitter provides an API for broadcasting messages to Socket.IO servers via Redis 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.

Package emitter provides a sharded broadcast operator for emitting events via Redis Sharded Pub/Sub.

Index

Constants

View Source
const (
	// DefaultEmitterKey is the default Redis key prefix for the emitter.
	DefaultEmitterKey = "socket.io"
)

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 in sharded mode 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 Redis. 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 *redis.RedisClient,
	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 *redis.RedisClient,
	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 REMOTE_DISCONNECT request 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.

func (*BroadcastOperator) Except

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

func (*BroadcastOperator) In

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

func (*BroadcastOperator) SocketsJoin

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

SocketsJoin makes all matching socket instances join the specified rooms. This sends a REMOTE_JOIN request 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 REMOTE_LEAVE request to all Socket.IO servers in the cluster.

func (*BroadcastOperator) To

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

func (*BroadcastOperator) Volatile

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
}

BroadcastOperatorInterface defines the common interface for broadcast operators. Both BroadcastOperator and ShardedBroadcastOperator implement this interface.

type BroadcastOptions

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

	// BroadcastChannel is the Redis channel used for broadcasting packets to clients.
	// Format: "{key}#{nsp}#" or "{key}#{nsp}#{room}#" for room-specific broadcasts.
	BroadcastChannel string

	// RequestChannel is the Redis channel used for inter-server requests.
	// Format: "{key}-request#{nsp}#"
	RequestChannel string

	// Parser is the encoder/decoder for serializing messages.
	Parser redis.Parser

	// Sharded indicates whether to use Redis sharded Pub/Sub (SPUBLISH).
	// Set to true when using Redis Cluster with sharded Pub/Sub (Redis 7.0+).
	Sharded bool

	// SubscriptionMode controls how room-specific channels are computed.
	// This should match the adapter's subscriptionMode setting.
	SubscriptionMode redis.SubscriptionMode
}

BroadcastOptions contains configuration for broadcasting messages to Redis 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 in sharded mode for cluster communication.

type DisconnectSocketsMessage

type DisconnectSocketsMessage = adapter.DisconnectSocketsMessage

DisconnectSocketsMessage is an alias for adapter.DisconnectSocketsMessage. It is used in sharded mode for disconnection operations.

type Emitter

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

Emitter broadcasts messages to Socket.IO servers using Redis pub/sub. 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 *redis.RedisClient, opts *EmitterOptions, nsps ...string) *Emitter

NewEmitter creates and initializes a new Emitter with the given Redis 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 *redis.RedisClient, opts *EmitterOptions, nsps ...string)

Construct initializes the Emitter with the given Redis 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

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

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 Redis 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

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 wrapper for the key setting.

func (*EmitterOptions) GetRawParser

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

GetRawParser returns the raw Optional wrapper for the parser setting.

func (*EmitterOptions) GetRawSharded

func (o *EmitterOptions) GetRawSharded() types.Optional[bool]

GetRawSharded returns the raw Optional wrapper for the sharded setting.

func (*EmitterOptions) GetRawSubscriptionMode

func (o *EmitterOptions) GetRawSubscriptionMode() types.Optional[redis.SubscriptionMode]

GetRawSubscriptionMode returns the raw Optional wrapper for the subscriptionMode setting.

func (*EmitterOptions) Key

func (o *EmitterOptions) Key() string

Key returns the Redis key prefix, or empty string if not set.

func (*EmitterOptions) Parser

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

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

func (*EmitterOptions) SetKey

func (o *EmitterOptions) SetKey(key string)

SetKey sets the Redis key prefix for channel names.

func (*EmitterOptions) SetParser

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

SetParser sets the parser for encoding messages sent to Redis.

func (*EmitterOptions) SetSharded

func (o *EmitterOptions) SetSharded(sharded bool)

SetSharded enables or disables Redis sharded Pub/Sub. When true, uses SPUBLISH command for Redis Cluster sharded Pub/Sub (Redis 7.0+).

func (*EmitterOptions) SetSubscriptionMode

func (o *EmitterOptions) SetSubscriptionMode(mode redis.SubscriptionMode)

SetSubscriptionMode sets the subscription mode for sharded Pub/Sub. This should match the adapter's subscriptionMode setting.

func (*EmitterOptions) Sharded

func (o *EmitterOptions) Sharded() bool

Sharded returns whether sharded Pub/Sub is enabled. Returns false if not set.

func (*EmitterOptions) SubscriptionMode

func (o *EmitterOptions) SubscriptionMode() redis.SubscriptionMode

SubscriptionMode returns the subscription mode. Returns DynamicSubscriptionMode if not set.

type EmitterOptionsInterface

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

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

	// SetSharded enables or disables Redis sharded Pub/Sub.
	// When enabled, uses SPUBLISH for Redis Cluster sharded Pub/Sub (Redis 7.0+).
	SetSharded(bool)
	// GetRawSharded returns the raw Optional wrapper for the sharded setting.
	GetRawSharded() types.Optional[bool]
	// Sharded returns whether sharded Pub/Sub is enabled.
	Sharded() bool

	// SetSubscriptionMode sets the subscription mode for sharded Pub/Sub.
	// This should match the adapter's subscriptionMode setting.
	SetSubscriptionMode(redis.SubscriptionMode)
	// GetRawSubscriptionMode returns the raw Optional wrapper for the subscriptionMode setting.
	GetRawSubscriptionMode() types.Optional[redis.SubscriptionMode]
	// SubscriptionMode returns the subscription mode.
	SubscriptionMode() redis.SubscriptionMode
}

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

type Packet

type Packet = redis.RedisPacket

Packet is an alias for redis.RedisPacket. It represents a Socket.IO packet with routing options.

type Request

type Request = redis.RedisRequest

Request is an alias for redis.RedisRequest. It represents an inter-server request message.

type Response

type Response = redis.RedisResponse

Response is an alias for redis.RedisResponse. It represents an inter-server response message.

type ServerSideEmitMessage

type ServerSideEmitMessage = adapter.ServerSideEmitMessage

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

type ShardedBroadcastOperator

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

ShardedBroadcastOperator allows targeting, excluding, and flagging rooms for event emission via Redis Sharded Pub/Sub. This operator uses SPUBLISH instead of PUBLISH, which is required for Redis Cluster mode. It encodes messages using the ClusterMessage format, which is compatible with ShardedRedisAdapter.

func MakeShardedBroadcastOperator

func MakeShardedBroadcastOperator() *ShardedBroadcastOperator

MakeShardedBroadcastOperator creates a new ShardedBroadcastOperator with default values.

func NewShardedBroadcastOperator

func NewShardedBroadcastOperator(
	redisClient *redis.RedisClient,
	broadcastOptions *BroadcastOptions,
	rooms *types.Set[socket.Room],
	exceptRooms *types.Set[socket.Room],
	flags *socket.BroadcastFlags,
) *ShardedBroadcastOperator

NewShardedBroadcastOperator creates and initializes a new ShardedBroadcastOperator.

func (*ShardedBroadcastOperator) Compress

Compress sets the compress flag for the broadcast.

func (*ShardedBroadcastOperator) Construct

func (b *ShardedBroadcastOperator) Construct(
	redisClient *redis.RedisClient,
	broadcastOptions *BroadcastOptions,
	rooms *types.Set[socket.Room],
	exceptRooms *types.Set[socket.Room],
	flags *socket.BroadcastFlags,
)

Construct initializes the ShardedBroadcastOperator with the given parameters.

func (*ShardedBroadcastOperator) DisconnectSockets

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

DisconnectSockets disconnects the matching socket instances.

func (*ShardedBroadcastOperator) Emit

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

Emit emits an event to all targeted clients using SPUBLISH (for Redis Cluster). This method uses the ClusterMessage format, which is compatible with ShardedRedisAdapter.

func (*ShardedBroadcastOperator) Except

Except excludes one or more rooms from event emission.

func (*ShardedBroadcastOperator) In

In is an alias for To, targeting one or more rooms for event emission.

func (*ShardedBroadcastOperator) SocketsJoin

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

SocketsJoin makes the matching socket instances join the specified rooms.

func (*ShardedBroadcastOperator) SocketsLeave

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

SocketsLeave makes the matching socket instances leave the specified rooms.

func (*ShardedBroadcastOperator) To

To targets one or more rooms for event emission.

func (*ShardedBroadcastOperator) Volatile

Volatile sets the volatile flag, allowing event data to be lost if the client is not ready.

type SocketsJoinLeaveMessage

type SocketsJoinLeaveMessage = adapter.SocketsJoinLeaveMessage

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL