func AfterBroadcastGroupCmd(callback func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)))
AfterBroadcastGroupCmd registers a callback function to be executed after broadcast group command:
Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func AfterCreateGroupCmd(callback func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)))
AfterCreateGroupCmd registers a callback function to be executed after create group command:
Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func AfterJoinGroupCmd(callback func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)))
AfterJoinGroupCmd registers a callback function to be executed after join group command:
Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func AfterLeaveGroupCmd(callback func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)))
AfterLeaveGroupCmd registers a callback function to be executed after leave group command:
Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func Announce(groupID string, ver uint8, cmd uint16, message []byte, reliable bool)
Announce sends a broadcast message to the other members in the group without having the "sender": MUST not be called by client directly for security reason
[NOTE] Uses mutex lock internally. [NOTE] This function is asynchronous.
Parameters
groupID - Target group ID. senderUSer - User that sends the broadcast. ver - Command version used for the broadcast message. cmd - Command ID used for the broadcast message. message - Message byte array to be sent as the broadcast. reliable - If true, UDP will become RUDP.
func BeforeBroadcastGroupCmd(callback func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)))
BeforeBroadcastGroupCmd registers a callback function to be executed before broadcast group command:
Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func BeforeCreateGroupCmd(callback func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)))
BeforeCreateGroupCmd registers a callback function to be executed before create group command:
Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func BeforeJoinGroupCmd(callback func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)))
BeforeJoinGroupCmd registers a callback function to be executed before join group command:
Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func BeforeLeaveGroupCmd(callback func(ver uint8, cmd uint16, payload []byte, userData *user.User, next func(error)))
BeforeLeaveGroupCmd registers a callback function to be executed before leave group command:
Parameters
ver - Command ver sent from the client.
cmd - Command ID sent from the client.
payload - Command payload sent from the client.
userData - User data representing the client that sent the command.
next - The function to signal the command to move on to the next operation of the same ver and command ID.
This function must be called at the end of all operations in the callback.
If you pass an error, it will not proceed to the next operations of the same command ver and ID.
func Broadcast(groupID string, senderUser *user.User, ver uint8, cmd uint16, message []byte, reliable bool)
Broadcast Sends a broadcast message to the other members in the group
[NOTE] Uses mutex lock internally. [NOTE] This function is asynchronous. [NOTE] This function may fail silently.
Parameters
groupID - Target group ID. senderUSer - User that sends the broadcast. ver - Command version used for the broadcast message. cmd - Command ID used for the broadcast message. message - Message byte array to be sent as the broadcast. reliable - If true, UDP will become RUDP.
func ExposeCommands()
ExposeCommands exposes commands to the client to work with the Group package
The following commands will be exposed to the client:
func ExposePufferCommands()
ExposePufferCommands exposes puffer commands to the client to work with the Group package
The following commands will be exposed to the client:
func GetGroupIDList(userData *user.User) []string
GetGroupIDList returns an array of group IDs
[NOTE] Uses mutex lock internally.
Parameters
userData *user.User - Target user to retrieve the list of group IDs from.
func GetLatestGroupID(userData *user.User) string
GetLatestGroupID returns the newest group ID the user joined or created
[NOTE] Uses mutex lock internally.
Parameters
userData *user.User - Target user to retrieve the last group ID joined.
func GetMemberMeshNodes(groupID string) []string
GetMemberMeshNodes returns an array of member mesh nodes that are participating the group
[NOTE] Uses mutex lock internally.
Parameters
groupID string - Target group ID to retrieve the list of server internal addresses that group is stored.
func IsJoinError(err error) bool
IsJoinError returns true if the given error is or contains a GroupJoinError.
func IsLeaveError(err error) bool
IsLeaveError returns true if the given error is or contains a GroupLeaveError.
func IsNewGroupError(err error) bool
IsNewGroupError returns true if the given error is or contains a GroupNewError.
func Join(groupID string, userData *user.User, ver uint8, cmd uint16, message []byte, callback func(error))
Join Joins a group and notify the other members of the group on joining the group If message is nil or empty, broadcast will NOT be sent
[NOTE] Uses mutex lock internally. [NOTE] This function is asynchronous.
Error Cases
+------------------------------+-------------------------------------------+ | Error | Reason | +------------------------------+-------------------------------------------+ | User is already in the group | The user is already a member of the group | | Failed to add a member | The group trying to join does not exist | | Reliable Response timed out | Internal network failed and timed out | +------------------------------+-------------------------------------------+
Parameters
groupID - Target group ID to join.
userData - User to join the group.
ver - Command version used for the message sent when join is successful.
cmd - Command ID used for the message sent when join is successful.
message - Message byte array to be sent when join is successful.
If message is either nil or empty, the message will not be sent.
callback func(error) - Callback invoked when join operation is completed.
func Leave(groupID string, userData *user.User, ver uint8, cmd uint16, message []byte, callback func(error))
Leave Leaves from a group and notify the other members on leaving If message is nil or empty, broadcast will NOT be sent
[NOTE] Uses mutex lock internally. [NOTE] This function is asynchronous.
Error Cases
+--------------------------+-----------------------------------------+ | Error | Reason | +--------------------------+-----------------------------------------+ | User is not in the group | The user is not a member of the group | | Group not found | The group to leave from does not exists | +--------------------------+-----------------------------------------+
Parameters
groupID - Target group ID to leave from.
userData - User to leave the group.
ver - Command version used for the message sent when leave is successful.
cmd - Command ID used for the message sent when leave is successful.
message - Message byte array to be sent when leave is successful.
If message is either nil or empty, the message will not be sent.
callback func(error) - Callback invoked when join operation is completed.
func NewGroup(userData *user.User, allowEmpty bool, join bool, ttl int64, interval int64) (string, error)
NewGroup Creates a new group and returns the group ID as a string to the callback function.
[NOTE] Uses mutex lock internally.
Error Cases
┌────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Error │ Reason │ ├────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ Invalid TTL │ TTL must be greater than 10 seconds │ ├────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ Node is offline │ A new group cannot be created on a server node that is in offline state (marked and ready to shutdown) │ ├────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ Allow empty and join false │ Allow empty false must be followed by join true, otherwise the new group will be deleted immediately. │ └────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Parameters
allowEmpty - If true, the group will not be deleted until TTL expires even if all members leave join - If true, the creator user will join the group automatically ttl - TTL of the group in seconds. The value must be greater than 10 interval - Broadcast interval in milliseconds. Interval below 100ms will be forced to 0. If it's 0, no packet merge
func SetOnDiscardCustomMessage(custom func(groupID string, userID string, userSID string) (message []byte))
SetOnDiscardCustomMessage sets a custom function to create a custom message to be sent to members on user discard
[CRITICALLY IMPORTANT] Using pointer variables that are defined outside of the callback closure
in the callback closure will cause those pointers to be not garbage collected leading to memory leak.
[CRITICALLY IMPORTANT] If the callback is blocked, it will lead to a goroutine leak and the join operation will be blocked.
custom func(groupID string, userID string, userSID string) []byte - Custom function to create custom message byte array.
func SetOnRejoinCustomMessage(custom func(groupID string, userID string, userSID string) (message []byte))
SetOnRejoinCustomMessage assigns a callback on rejoin to create a custom message
[CRITICALLY IMPORTANT] Using pointer variables that are defined outside of the callback closure
in the callback closure will cause those pointers to be not garbage collected leading to memory leak.
[CRITICALLY IMPORTANT] If the callback is blocked, it will lead to a goroutine leak and the leave operation will be blocked.
custom func(groupID string, userID string, userSID string) []byte - Custom function to create custom message byte array.
func SetOnTickByID(groupID string, cb func(groupID string), interval int64) error
SetOnTickByID assigns a callback to a given group ID to be executed at every given interval in seconds.
[CRITICALLY IMPORTANT] Using pointer variables that are defined outside of the callback closure
in the callback closure will cause those pointers to be not garbage collected leading to memory leak.
[CRITICALLY IMPORTANT] If the callback is blocked, it will lead to a goroutine leak and the tick will be blocked entirely.
[IMPORTANT] The interval evaluation is executed every 2 seconds.
func Setup(confpath string)
Setup optionally loads configurations
configpath string - Absolute path for the configuration file to read.
func SetupAsTCPServer()
SetupAsTCPServer Sets up group package as TCP server
func SetupAsUDPServer()
SetupAsUDPServer Sets up group package as UDP/RUDP server
Group group data structure
type Group struct {
ID string
AllowEmpty bool
// remote member mesh node list
RemoteMemberNodes map[string]bool
// user ID as key and user SID as value
MemberSIDs map[string]string
// If true, the group is static and never discarded
IsStatic bool
TTL int64
sync.RWMutex
// contains filtered or unexported fields
}
func GetGroupByID(groupID string) *Group
GetGroupByID returns a group instance by its ID.
[IMPORTANT] If the group does not exist or the given ID.
Member member of a group data structure
type Member struct {
UID string
SID string
MeshEndPoint string
}
SendData represents internally used data
type SendData struct {
GroupID string `json:"groupID"`
Ver uint8 `json:"ver"`
Cmd uint16 `json:"cmd"`
Message []byte `json:"message"`
Reliable bool `json:"reliable"`
}
SyncGroupData represents internally used data
type SyncGroupData struct {
GroupID string `json:"groupID"`
MeshEndpoint string `json:"meshEndPoint"`
Method string `json:"method"`
}