dnet

README

dnet

Simply take your websocket utilization to large scale level. SIMPLE, MINIMAL & POWERFUL!

Documentation

Index

• func AuthLink(link string) (userID, linkID string, status int)
• func Connect(w http.ResponseWriter, r *http.Request, allowedOrigin ...string)
• func GetIP(r *http.Request) (ip string, err error)
• func Init(options ...Options)
• func IsCtxt(v any) bool
• func IsDnetContext(v any) bool
• func IsEContext(v any) bool
• func LastSeen(handler ActionHandler)
• func NewLink(userID, linkID string, minutes ...time.Duration) (link string, err error)
• func On(action string, handlers ...ActionHandler)
• func SendTicket(r *http.Request, w http.ResponseWriter, ID string)
• func Use(handlers ...ActionHandler)
• type ActionHandler
• type Ctx
  • func ToCtx(v any) (ctx *Ctx, ok bool)
  • func (c *Ctx) All(statusAndData ...interface{})
  • func (c *Ctx) AuthTicket(infoText ...string) (ID string, ok bool)
  • func (c *Ctx) Bind(v interface{}) (err error)
  • func (c *Ctx) Binder(v interface{}, msg ...string) (ok bool)
  • func (c *Ctx) Broadcast(statusAndData ...interface{})
  • func (c *Ctx) Clear()
  • func (c *Ctx) CreateRoom(roomID string, usersIDS ...string)
  • func (c *Ctx) Del(key string)
  • func (c *Ctx) Dispose()
  • func (c *Ctx) Fire(action string)
  • func (c *Ctx) Get(key string) (val interface{}, err error)
  • func (c *Ctx) Logout()
  • func (c *Ctx) MarkAuthed(ID string)
  • func (c *Ctx) Multicast(userIDs []string, statusAndData ...interface{})
  • func (c *Ctx) Next()
  • func (c *Ctx) Refire()
  • func (c *Ctx) RoomAll(ID string, statusAndData ...interface{})
  • func (c *Ctx) RoomBroadcast(ID string, statusAndData ...interface{})
  • func (c *Ctx) Rooms(roomsIDs ...string)
  • func (c *Ctx) Send(ID string, statusAndData ...interface{})
  • func (c *Ctx) SendBack(statusAndData ...interface{})
  • func (c *Ctx) SendMe(statusAndData ...interface{})
  • func (c *Ctx) Set(key string, val interface{})
• type DnetContext
• type EContext
  • func Context(action string, userID ...string) EContext
  • func ToEContext(v any) (ctx *EContext, ok bool)
  • func (c *EContext) Broadcast(statusAndData ...interface{})
  • func (c *EContext) Fire(action string)
  • func (c *EContext) Multicast(userIDs []string, statusAndData ...interface{})
  • func (c *EContext) Refire()
  • func (c *EContext) Send(ID string, statusAndData ...interface{})
• type Hub
  • func (h *Hub) Run()
• type MainRouter
  • func (r *MainRouter) Route(IncomingAction string, context *Ctx)
• type Map
  • func Msg(msg string) (simpleMsgResponse Map)
• type Options
• type Subrouter
  • func Router(path string) Subrouter
  • func (r Subrouter) On(action string, handlers ...ActionHandler)
  • func (r *Subrouter) Router(path string) Subrouter
  • func (r *Subrouter) Use(handlers ...ActionHandler)

Functions

func AuthLink

func AuthLink(link string) (userID, linkID string, status int)

AuthLink validates and authenticates verification link.

link: represents the link from the client generated by the Link () function. It returns user ID if succeeds.

status: indicates the results of the link validation. Where,

0 means link expired

1 stands for bad request i.e client side has sent the wrong link

2 means everything is fine! and with this status you can get the user ID.

func Connect

func Connect(w http.ResponseWriter, r *http.Request, allowedOrigin ...string)

Connect inits connection in the given endpoint

func GetIP

func GetIP(r *http.Request) (ip string, err error)

GetIP returns the IP address from the client request

func Init

func Init(options ...Options)

Init initializes dnet hub monitoring. You should pass your configurations in this function if you are using v1.0.208-beta and above. Otherwise you should stick with Config() function

It should be called only once

func IsCtxt

func IsCtxt(v any) bool

IsCtx tests the given value v if it's of Ctx type

func IsDnetContext

func IsDnetContext(v any) bool

IsDnetContext tests the given value v if it's a dnet context i.e dnet.EContext or dnet.Ctx

func IsEContext

func IsEContext(v any) bool

IsEContext tests the given value v if it's an external context - EContext

func LastSeen

func LastSeen(handler ActionHandler)

LastSeen is called when the authenticated user gets offline or logs out It's very useful for setting the last seen of the user connection

func NewLink

func NewLink(userID, linkID string, minutes ...time.Duration) (link string, err error)

NewLink generates a link to use for user verification.

ID is a Unique identifier stored in the link througth aes encryption.

minutes is a life time of the link in minutes i.e after that amount of time the link becomes expired. Default time is 60 minutes

func On

func On(action string, handlers ...ActionHandler)

On method takes ActionHandlers to be called when the given action fired by the dnet-client

func SendTicket

func SendTicket(r *http.Request, w http.ResponseWriter, ID string)

SendTicket sends an encrypted ticket to the user.

func Use

func Use(handlers ...ActionHandler)

Use adds root-level middlewares which will be called before any action is matched.

Types

type ActionHandler

type ActionHandler func(*Ctx)

ActionHandler is a function wich receives Ctx

type Ctx

type Ctx struct {

	//ID of the user owning the connection
	ID string

	// Rec is an id of the recipient
	Rec string

	// Authed  tells if the connection is authenticated or not
	Authed bool
	// IP address of the connection
	IP string
	// contains filtered or unexported fields
}

Ctx is a middleman between the websocket connection and the Hub. Ctx is stored in the dnet hub and hence it is an inside and persistent context.

func ToCtx

func ToCtx(v any) (ctx *Ctx, ok bool)

ToCtx converts the given value v to *dnet.Ctx.

ok is returned when the assertion succeed

func (*Ctx) All

func (c *Ctx) All(statusAndData ...interface{})

All sends to anyone connected to the websocket Dnet instance including the sender of the message

func (*Ctx) AuthTicket

func (c *Ctx) AuthTicket(infoText ...string) (ID string, ok bool)

AuthTicket authenticates the ticket and returns the user ID provided in the SendTicket().

ok is also returned to inform you if user authentication fails or not. If failed you, all you can do is simply "return" to finish your reponse cycle since AuthTicket helps you to respond to the client with the infoText you provide or the default infoText

Infotext is a message to send back to the client when user authentication fails. It defaults to "Please login to access this resource" if you do not provide it.

func (*Ctx) Bind

func (c *Ctx) Bind(v interface{}) (err error)

Bind extracts raw data, stores it in the passed pointer v and returns any raised error

func (*Ctx) Binder

func (c *Ctx) Binder(v interface{}, msg ...string) (ok bool)

Binder extracts raw data, stores it in the passed pointer v and implicitly sends 422 Unprocessable entities to the client when it's unable to decode data. You can provide a custom client error message by passing it as msg argument. In addition to sending a client friendly error to the client it also logs a raised error in console

It returns true on success and false on failure. You can use this value to stop the execution in the caller function by just using a return statement.

Use Bind(v interface{}) if you want to explicitly handle errors

func (*Ctx) Broadcast

func (c *Ctx) Broadcast(statusAndData ...interface{})

Broadcast sends data to all execept the sender

func (*Ctx) Clear

func (c *Ctx) Clear()

Clear empties context values. That is, deletes every value in the context values and resets the value store anew.

func (*Ctx) CreateRoom

func (c *Ctx) CreateRoom(roomID string, usersIDS ...string)

CreateRoom is for creating a new room.... if it finds a room exist it only adds the given the room

func (*Ctx) Del

func (c *Ctx) Del(key string)

Del deletes context value's field with a given keyc

func (*Ctx) Dispose

func (c *Ctx) Dispose()

Dispose discards the client connection without calling LastSeen for saving any lastSeen info for the clinet connection Useful for expired unauthorized client connections

func (*Ctx) Fire

func (c *Ctx) Fire(action string)

Fire sets which action to fire to the client. It's recommended to keep the action in path form to maintain maintain uniformity, If you do not set the action to fire, the action you listened for it will be fired backward to the client too.

func (*Ctx) Get

func (c *Ctx) Get(key string) (val interface{}, err error)

Get gets data stored in the connection

func (*Ctx) Logout

func (c *Ctx) Logout()

Logout calls the LastSeen function to ensure user last seen data is saved before discarding the client connection

func (*Ctx) MarkAuthed

func (c *Ctx) MarkAuthed(ID string)

MarkAuthed marks this connection as authenticated. Hence, no ticket authentication required.

Use this when you have your own authentication mechanism or just for testing purposes.

func (*Ctx) Multicast

func (c *Ctx) Multicast(userIDs []string, statusAndData ...interface{})

Multicast sends to the given users IDs (useful for sharing something to multiple users

func (*Ctx) Next

func (c *Ctx) Next()

Next pushes the next middleware in the list

func (*Ctx) Refire

func (c *Ctx) Refire()

Refire resets action to the initial action before calling any Fire("/action") method. In fact, the action becomes the same as it was fired by the client.

func (*Ctx) RoomAll

func (c *Ctx) RoomAll(ID string, statusAndData ...interface{})

RoomAll sends to the members of the room. (useful for chat rooms.. and sending data to all people under the same role or cartegory )

func (*Ctx) RoomBroadcast

func (c *Ctx) RoomBroadcast(ID string, statusAndData ...interface{})

RoomBroadcast sends to all members of the registered room except the sender

func (*Ctx) Rooms

func (c *Ctx) Rooms(roomsIDs ...string)

Rooms assigns this connnection to the chatrooms it relates to

func (*Ctx) Send

func (c *Ctx) Send(ID string, statusAndData ...interface{})

Send sends to one client only

func (*Ctx) SendBack

func (c *Ctx) SendBack(statusAndData ...interface{})

SendBack sends back to the sender's sending connection only.

Use sendMe() if you want to send to all of the sender's connections including the sending connection.

func (*Ctx) SendMe

func (c *Ctx) SendMe(statusAndData ...interface{})

SendMe sends to all of the sender's open connections

func (*Ctx) Set

func (c *Ctx) Set(key string, val interface{})

Set stores value in the connection.

type DnetContext

type DnetContext interface {
	*Ctx | *EContext
}

type EContext

type EContext struct {

	//ID is  a user id to assocaite it with the user connection
	ID string
	// contains filtered or unexported fields
}

EContext is an external context which provides functionalities for sending data to the websocket's connections from a normal http connection. It interfaces the dnet hub and dnet sending functionalities to the normal http connection. EContext is not stored inside the dnet hub and hence it is called external and immidiate context.

func Context

func Context(action string, userID ...string) EContext

Context creates an external context for sending data to the websocket connections from a normal http connection.

func ToEContext

func ToEContext(v any) (ctx *EContext, ok bool)

ToEContext converts the given value v to *dnet.EContext.

ok is returned when the assertion succeed

func (*EContext) Broadcast

func (c *EContext) Broadcast(statusAndData ...interface{})

Broadcast sends data to alll dnet contexts in the hub

func (*EContext) Fire

func (c *EContext) Fire(action string)

Fire sets which action to fire to the client. It's recommended to keep the action in path form to maintain maintain uniformity, If you do not set the action to fire, the action you listened for it will be fired backward to the client too.

func (*EContext) Multicast

func (c *EContext) Multicast(userIDs []string, statusAndData ...interface{})

Multicast sends to the given users IDs (useful for sharing something to multiple users

func (*EContext) Refire

func (c *EContext) Refire()

Refire resets action to the initial action before calling any Fire("/action") method.

func (*EContext) Send

func (c *EContext) Send(ID string, statusAndData ...interface{})

Send sends to only one client of the specified ID

type Hub

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

Hub maintains and manages dnet contexts

func (*Hub) Run

func (h *Hub) Run()

Run method is for starting the Hub

type MainRouter

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

MainRouter routes websocket actions

func (*MainRouter) Route

func (r *MainRouter) Route(IncomingAction string, context *Ctx)

Route performs routing websocket actions based on the incoming action

type Map

type Map map[string]interface{}

Map models json data to be sent to the client by creating a map[string]interface{}

func Msg

func Msg(msg string) (simpleMsgResponse Map)

Msg models the msg to a simple msg:string map

type Options

type Options struct {
	TicketAge time.Duration
	MaxSize   int64
}

Options is used to take all the

type Subrouter

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

Subrouter is for grouping actions, and creating middleware subjected to the particular group

func Router

func Router(path string) Subrouter

Router creates a subrouter for grouping related actions.

func (Subrouter) On

func (r Subrouter) On(action string, handlers ...ActionHandler)

On method is adding Event handlders to the router by prefixing it with the Matcher path

func (*Subrouter) Router

func (r *Subrouter) Router(path string) Subrouter

func (*Subrouter) Use

func (r *Subrouter) Use(handlers ...ActionHandler)

Use adds middlewares to the subrouter which will be called before any other subrouter actions