websocket

Documentation

Index

• Variables
• func GetContext(c *neffos.Conn) context.Context
• func Handler(s *neffos.Server, IDGenerator ...IDGenerator) context.Handler
• func SetDefaultMarshaler(fn func(v interface{}) ([]byte, error))
• func SetDefaultUnmarshaler(fn func(data []byte, v interface{}) error)
• func Upgrade(ctx context.Context, idGen IDGenerator, s *neffos.Server) *neffos.Conn
• type CloseError
• type Conn
• type ConnHandler
• type Dialer
• type Events
• type GobwasDialerOptions
• type GobwasHeader
• type GorillaDialerOptions
• type IDGenerator
• type Message
• type MessageHandlerFunc
• type NSConn
• type Namespaces
• type RedisConfig
• type RedisStackExchange
• type Room
• type StackExchange
• type Struct
• type StructInjector
• type WithTimeout

Variables

var (
	// EnableDebug enables debug mode for websocket module,
	// for MVC this is done automatically
	// when the app's logger level is set to "debug".
	EnableDebug = neffos.EnableDebug
	// GorillaUpgrader is an upgrader type for the gorilla/websocket subprotocol implementation.
	// Should be used on `New` to construct the websocket server.
	GorillaUpgrader = gorilla.Upgrader
	// GobwasUpgrader is an upgrader type for the gobwas/ws subprotocol implementation.
	// Should be used on `New` to construct the websocket server.
	GobwasUpgrader = gobwas.Upgrader
	// DefaultGorillaUpgrader is a gorilla/websocket Upgrader with all fields set to the default values.
	DefaultGorillaUpgrader = gorilla.DefaultUpgrader
	// DefaultGobwasUpgrader is a gobwas/ws Upgrader with all fields set to the default values.
	DefaultGobwasUpgrader = gobwas.DefaultUpgrader
	// New constructs and returns a new websocket server.
	// Listens to incoming connections automatically, no further action is required from the caller.
	// The second parameter is the "connHandler", it can be
	// filled as `Namespaces`, `Events` or `WithTimeout`, same namespaces and events can be used on the client-side as well,
	// Use the `Conn#IsClient` on any event callback to determinate if it's a client-side connection or a server-side one.
	//
	// See examples for more.
	New = neffos.New
	// DefaultIDGenerator returns a universal unique identifier for a new connection.
	// It's the default `IDGenerator` if missing.
	DefaultIDGenerator = func(ctx context.Context) string {
		return neffos.DefaultIDGenerator(ctx.ResponseWriter(), ctx.Request())
	}

	// NewRedisStackExchange returns a new redis StackExchange.
	// The "channel" input argument is the channel prefix for publish and subscribe.
	NewRedisStackExchange = redis.NewStackExchange
	// NewNatsStackExchange returns a new nats StackExchange.
	// The "url" input argument is the connection string of your nats server.
	// The second variadic input argument can be used to use custom `nats.Option`s
	// such as authentication and more nats servers addresses.
	NewNatsStackExchange = nats.NewStackExchange
	// WithNatsOptions can be used as the second input argument of `NewNatsStackExchange`
	// to declare a struct-based configuration for the nats server(s).
	WithNatsOptions = nats.With

	// GorillaDialer is a `Dialer` type for the gorilla/websocket subprotocol implementation.
	// Should be used on `Dial` to create a new client/client-side connection.
	GorillaDialer = gorilla.Dialer
	// GobwasDialer is a `Dialer` type for the gobwas/ws subprotocol implementation.
	// Should be used on `Dial` to create a new client/client-side connection.
	GobwasDialer = gobwas.Dialer
	// DefaultGorillaDialer is a gorilla/websocket dialer with all fields set to the default values.
	DefaultGorillaDialer = gorilla.DefaultDialer
	// DefaultGobwasDialer is a gobwas/ws dialer with all fields set to the default values.
	DefaultGobwasDialer = gobwas.DefaultDialer
	// Dial establishes a new websocket client connection.
	// Context "ctx" is used for handshake timeout.
	// Dialer "dial" can be either `GorillaDialer` or `GobwasDialer`,
	// custom dialers can be used as well when complete the `Socket` and `Dialer` interfaces for valid client.
	// URL "url" is the endpoint of the websocket server, i.e "ws://localhost:8080/echo".
	// The last parameter, and the most important one is the "connHandler", it can be
	// filled as `Namespaces`, `Events` or `WithTimeout`, same namespaces and events can be used on the server-side as well.
	//
	// See examples for more.
	Dial = neffos.Dial
	// IsTryingToReconnect reports whether the returning "err" from the `Server#Upgrade`
	// is from a client that was trying to reconnect to the websocket server.
	//
	// Look the `Conn#WasReconnected` and `Conn#ReconnectTries` too.
	IsTryingToReconnect = neffos.IsTryingToReconnect
	// NewStruct returns the `Struct` Conn Handler based on ptr value.
	NewStruct = neffos.NewStruct
	// JoinConnHandlers combines two or more ConnHandlers as one.
	JoinConnHandlers = neffos.JoinConnHandlers
	// OnNamespaceConnect is the event name which its callback is fired right before namespace connect,
	// if non-nil error then the remote connection's `Conn.Connect` will fail and send that error text.
	// Connection is not ready to emit data to the namespace.
	OnNamespaceConnect = neffos.OnNamespaceConnect
	// OnNamespaceConnected is the event name which its callback is fired after namespace successfully connected.
	// Connection is ready to emit data back to the namespace.
	OnNamespaceConnected = neffos.OnNamespaceConnected
	// OnNamespaceDisconnect is the event name which its callback is fired when
	// remote namespace disconnection or local namespace disconnection is happening.
	// For server-side connections the reply matters, so if error returned then the client-side cannot disconnect yet,
	// for client-side the return value does not matter.
	OnNamespaceDisconnect = neffos.OnNamespaceDisconnect // if allowed to connect then it's allowed to disconnect as well.
	// OnRoomJoin is the event name which its callback is fired right before room join.
	OnRoomJoin = neffos.OnRoomJoin // able to check if allowed to join.
	// OnRoomJoined is the event name which its callback is fired after the connection has successfully joined to a room.
	OnRoomJoined = neffos.OnRoomJoined // able to broadcast messages to room.
	// OnRoomLeave is the event name which its callback is fired right before room leave.
	OnRoomLeave = neffos.OnRoomLeave // able to broadcast bye-bye messages to room.
	// OnRoomLeft is the event name which its callback is fired after the connection has successfully left from a room.
	OnRoomLeft = neffos.OnRoomLeft // if allowed to join to a room, then its allowed to leave from it.
	// OnAnyEvent is the event name which its callback is fired when incoming message's event is not declared to the ConnHandler(`Events` or `Namespaces`).
	OnAnyEvent = neffos.OnAnyEvent // when event no match.
	// OnNativeMessage is fired on incoming native/raw websocket messages.
	// If this event defined then an incoming message can pass the check (it's an invalid message format)
	// with just the Message's Body filled, the Event is "OnNativeMessage" and IsNative always true.
	// This event should be defined under an empty namespace in order this to work.
	OnNativeMessage = neffos.OnNativeMessage

	// IsSystemEvent reports whether the "event" is a system event,
	// OnNamespaceConnect, OnNamespaceConnected, OnNamespaceDisconnect,
	// OnRoomJoin, OnRoomJoined, OnRoomLeave and OnRoomLeft.
	IsSystemEvent = neffos.IsSystemEvent
	// Reply is a special type of custom error which sends a message back to the other side
	// with the exact same incoming Message's Namespace (and Room if specified)
	// except its body which would be the given "body".
	Reply = neffos.Reply
	// Marshal marshals the "v" value and returns a Message's Body.
	// The "v" value's serialized value can be customized by implementing a `Marshal() ([]byte, error) ` method,
	// otherwise the default one will be used instead ( see `SetDefaultMarshaler` and `SetDefaultUnmarshaler`).
	// Errors are pushed to the result, use the object's Marshal method to catch those when necessary.
	Marshal = neffos.Marshal
)

Functions

func GetContext

func GetContext(c *neffos.Conn) context.Context

GetContext returns the Iris Context from a websocket connection.

func Handler

func Handler(s *neffos.Server, IDGenerator ...IDGenerator) context.Handler

Handler returns an Iris handler to be served in a route of an Iris application. Accepts the neffos websocket server as its first input argument and optionally an Iris-specific `IDGenerator` as its second one.

func SetDefaultMarshaler

func SetDefaultMarshaler(fn func(v interface{}) ([]byte, error))

SetDefaultMarshaler changes the default json marshaler. See `Marshal` package-level function and `Message.Unmarshal` method for more.

func SetDefaultUnmarshaler

func SetDefaultUnmarshaler(fn func(data []byte, v interface{}) error)

SetDefaultUnmarshaler changes the default json unmarshaler. See `Message.Unmarshal` method and package-level `Marshal` function for more.

func Upgrade

func Upgrade(ctx context.Context, idGen IDGenerator, s *neffos.Server) *neffos.Conn

Upgrade upgrades the request and returns a new websocket Conn. Use `Handler` for higher-level implementation instead.

Types

type CloseError

type CloseError = neffos.CloseError

CloseError can be used to send and close a remote connection in the event callback's return statement.

type Conn

type Conn = neffos.Conn

Conn describes the main websocket connection's functionality. Its `Connection` will return a new `NSConn` instance. Each connection can connect to one or more declared namespaces. Each `NSConn` can join to multiple rooms.

type ConnHandler

type ConnHandler = neffos.ConnHandler

ConnHandler is the interface which namespaces and events can be retrieved through.

type Dialer

type Dialer = neffos.Dialer

Dialer is the definition type of a dialer, gorilla or gobwas or custom. It is the second parameter of the `Dial` function.

type Events

type Events = neffos.Events

Events completes the `ConnHandler` interface. It is a map which its key is the event name and its value the event's callback.

Events type completes the `ConnHandler` itself therefore, can be used as standalone value on the `New` and `Dial` functions to register events on empty namespace as well.

See `Namespaces`, `New` and `Dial` too.

type GobwasDialerOptions

type GobwasDialerOptions = gobwas.Options

GobwasDialerOptions is just an alias for the `gorilla/websocket.Dialer` struct type.

type GobwasHeader

type GobwasHeader = gobwas.Header

GobwasHeader is an alias to the adapter that allows the use of `http.Header` as handshake headers.

type GorillaDialerOptions

type GorillaDialerOptions = gorilla.Options

GorillaDialerOptions is just an alias for the `gobwas/ws.Dialer` struct type.

type IDGenerator

type IDGenerator func(context.Context) string

IDGenerator is an iris-specific IDGenerator for new connections.

type Message

type Message = neffos.Message

The Message is the structure which describes the incoming and outcoming data. Emitter's "body" argument is the `Message.Body` field. Emitter's return non-nil error is the `Message.Err` field. If native message sent then the `Message.Body` is filled with the body and when incoming native message then the `Message.Event` is the `OnNativeMessage`, native messages are allowed only when an empty namespace("") and its `OnNativeMessage` callback are present.

type MessageHandlerFunc

type MessageHandlerFunc = neffos.MessageHandlerFunc

MessageHandlerFunc is the definition type of the events' callback. Its error can be written to the other side on specific events, i.e on `OnNamespaceConnect` it will abort a remote namespace connection. See examples for more.

type NSConn

type NSConn = neffos.NSConn

NSConn describes a connection connected to a specific namespace, it emits with the `Message.Namespace` filled and it can join to multiple rooms. A single `Conn` can be connected to one or more namespaces, each connected namespace is described by this structure.

type Namespaces

type Namespaces = neffos.Namespaces

Namespaces completes the `ConnHandler` interface. Can be used to register one or more namespaces on the `New` and `Dial` functions. The key is the namespace literal and the value is the `Events`, a map with event names and their callbacks.

See `WithTimeout`, `New` and `Dial` too.

type RedisConfig

type RedisConfig = redis.Config

RedisConfig is used on the `NewRedisStackExchange` package-level function. Can be used to customize the redis client dialer.

type RedisStackExchange

type RedisStackExchange = redis.StackExchange

RedisStackExchange is a `neffos.StackExchange` for redis.

type Room

type Room = neffos.Room

Room describes a connected connection to a room, emits messages with the `Message.Room` filled to the specific room and `Message.Namespace` to the underline `NSConn`'s namespace.

type StackExchange

type StackExchange = neffos.StackExchange

StackExchange is an optional interface that can be used to change the way neffos sends messages to its clients, i.e communication between multiple neffos servers.

See `NewRedisStackExchange` to create a new redis StackExchange.

type Struct

type Struct = neffos.Struct

Struct completes the `ConnHandler` interface. It uses a structure to register a specific namespace and its events.

type StructInjector

type StructInjector = neffos.StructInjector

StructInjector can be used to customize the value creation that can is used on serving events.

type WithTimeout

type WithTimeout = neffos.WithTimeout

WithTimeout completes the `ConnHandler` interface. Can be used to register namespaces and events or just events on an empty namespace with Read and Write timeouts.

See `New` and `Dial`.