io

Documentation

Overview

Package io provides utility structures and functions to set up and manage socket.io servers and connections.

Index

• Constants
• func InitSockets(io ConnectionHandler, sockets []Socket, closer SocketCloser)
• func ParamsDecoder[Params any](params []byte, decoder func([]byte) (Params, error)) (output Params, err error)
• type ConnectionHandler
  • func NewConnectionHandler(io *IO) ConnectionHandler
• type EventListener
• type IO
• type Server
  • func (s *Server) IO(httpHandlers http.Handler, addr string, allowedOrigins []string) *IO
• type Socket
• type SocketClient
• type SocketCloser
• type StorageSize
  • func (s StorageSize) String() string
  • func (s StorageSize) Value() int64

Constants

const MaxHTTPBufferSize = 50 * MB

MaxHTTPBufferSize bounds the size of a single Socket.IO message (~50MB), large enough for media payloads while still rejecting abusive uploads.

Functions

func InitSockets

func InitSockets(
	io ConnectionHandler,
	sockets []Socket,
	closer SocketCloser,
)

InitSockets listens for incoming connections on the provided ConnectionHandler and binds the given slice of Socket definitions to each new client. It also blocks execution and gracefully shuts down the server upon receiving standard termination OS signals.

func ParamsDecoder

func ParamsDecoder[Params any](
	params []byte,
	decoder func([]byte) (Params, error),
) (output Params, err error)

ParamsDecoder converts a map of parameters into a specified generic type. It serializes the provided map into JSON data and then deserializes it into the target structure. In case of a type mismatch during the decoding process, it may return an [json.InvalidUnmarshalError] or an [json.UnmarshalTypeError].

Types

type ConnectionHandler

type ConnectionHandler interface {
	On(event string, handlers ...EventListener)
	Close(func(error))
}

ConnectionHandler defines the interface for socket connection management, allowing the binding of events and gracefully closing the connection.

func NewConnectionHandler

func NewConnectionHandler(io *IO) ConnectionHandler

NewConnectionHandler creates and returns a new instance of ConnectionHandler using the provided *IO instance.

type EventListener

type EventListener = events.Listener

[types.EventListener] alias for easier reference in the context of this package.

type IO

type IO = socket.Server

socket.Server alias for easier reference in the context of this package.

type Server

type Server struct {
	*xhttp.Server
}

Server wraps a [types.HttpServer] to provide socket.io initialization capabilities.

func (*Server) IO

func (s *Server) IO(
	httpHandlers http.Handler,
	addr string,
	allowedOrigins []string,
) *IO

IO initializes and returns a new socket.Server. It configures the underlying [types.HttpServer] with the provided http.Handler, binds it to the given addr, and sets up CORS using allowedOrigins.

type Socket

type Socket struct {
	Name    string
	Handler func(client *SocketClient) func(args ...any)
}

Socket represents a named socket event and its corresponding handler factory. The Handler function receives a socket.Socket client and returns the actual function to be executed when the event occurs.

type SocketClient

type SocketClient = socket.Socket

socket.Socket alias for easier reference in the context of this package.

type SocketCloser

type SocketCloser struct {
	// Notifier returns a context that is canceled when a shutdown signal is received,
	// along with its cancellation function.
	Notifier func() (context.Context, context.CancelFunc)
	// Exit terminates the application.
	Exit func(int)
}

SocketCloser manages the application lifecycle by listening for shutdown signals and executing termination steps.

type StorageSize

type StorageSize int64

StorageSize represents a data size in bytes.

const (

	// KB represents a kilobyte (1024 bytes).
	KB StorageSize = 1 << (10 * iota)

	// MB represents a megabyte (1024 kilobytes).
	MB

	// GB represents a gigabyte (1024 megabytes).
	GB

	// TB represents a terabyte (1024 gigabytes).
	TB

	// PB represents a petabyte (1024 terabytes).
	PB
)

const (
	// B represents a single byte.
	B StorageSize = 1
)

func (StorageSize) String

func (s StorageSize) String() string

func (StorageSize) Value

func (s StorageSize) Value() int64