Package matching

import "github.com/Diarkis/diarkis/matching"

Overview ▾

Package matching ▷

Match Maker - Distributed in-memory match making

Highly scalable and extremely fast match-making based on application defined match making conditions.


Match Maker configurations are explained below.

  "distributionRate": 30,
  "targetNodeType": "HTTP"

▶︎ Configuration Value

distributionRate - Default is 30

Ratio of sharded data saturation among the HTTP server nodes in per centage: e.i. 30 means 30%.

Node type to use for matchmaking - Default is HTTP

func Add

func Add(
    matchingID string,
    uniqueID string,
    tag string,
    props map[string]int,
    value map[string]interface{},
    ttl int64,
    limit int,

Add Adds a searchable matching candidate data.

[NOTE] In order to have long lasting (TTL longer than 60 seconds) searable items, the application must "add" searchable items repeatedly with TTL=60.

	matchingID - Matching profile ID to add the searchable data to.

	unqiueID   - Unique ID of the searchable ID.

	tag        - Tag is used to isolate and group add and search of matchmaking.

              If an empty string is given, it will be ignored.

	props      - Searchable condition properties.

	value      - Searchable data to be returned along with the search resilts.

	ttl        - TTL of the searchable item to be added in seconds. Maximum 60 seconds.

	limit      - Number of search node to propagate the searchable item data at a time.

func ClearDefinition

func ClearDefinition(matchingID string)

Clear Definition clears already defined match making definition

matchingID - Matching profile ID to clear the definition.

func Define

func Define(matchingID string, props map[string]int)

Define Defines a match making search schema:

This must be defined on HTTP server b/c all match making data is stored on HTTP servers. You may define as many matching definition as you require as long as each matchingID is unique.

matchingID - Unique matching profile ID.
props      - Matching profile condition properties.

func DefineByJSON

func DefineByJSON(jsonBytes []byte)

DefineByJSON defines multiple match making definitions from JSON string.

	"<matching ID>": {
		"<property name>": <property range value>
		"<property name>": <property range value>
		"<property name>": <property range value>

jsonBytes - Matching profile byte array data to be used to define the profile.

func ExposeCommands

func ExposeCommands()

func Remove

func Remove(matchingID string, uniqueIDList []string, limit int)

Remove removes a list of searchable matching candidate items by their unique IDs

[NOTE]: This function is very expensive as it will send a message to all related mesh nodes

matchingID   - Target matching profile ID to remove items from
uniqueIDList - A list of unique IDs of the searchable items to remove
limit        - Mesh network relay limit
func Search(searchIDList []string, tag string, props map[string]int, limit int, callback func(error, []interface{}))

Search Searches for matched data based on the given props' values

searchIDList - A list of matchingID to search by. The order of the list is the order of search attempts
tag          - A tag is used to isolate and group search meaning the search will not include tags that do not match
props        - A property map to act as match making conditions
limit        - A hard limit to the number of results
callback     - A callback with the search results or an error

func SetCustomJoinCondition

func SetCustomJoinCondition(callback func(string, *user.User) bool)

SetCustomJoinCondition assigns a on join evaluation callback to be called to evaluate if the user should join or not

func SetOnIssueTicket

func SetOnIssueTicket(cb func(userData *user.User) *TicketParams)

SetOnIssueTicket assigns a callback to be invoked when the built-in command issue ticket is called.

func SetOnTicketComplete

func SetOnTicketComplete(cb func(string, *user.User) []byte)

SetOnTicketComplete assigns a callback to be invoked when an issued ticket successfully completes.

The callback function must return a message byte array to be sent to all matched user clients.

func SetOnTicketMatch

func SetOnTicketMatch(cb func(userData *user.User, roomID string, memberIDs []string) bool)

SetOnTicketMatch assigns a callback to be invoked when a new match is made.

This callback is meant to execute a custom logic for matchmaking completion on every match found.

Returning a true will automatically completes the matchmaking.

func Setup

func Setup(confpath string)

Setup sets up MatchMaker on the server.

confpath - Absolute path of the configuration file to be loaded.

func Test

func Test(method string, data map[string]interface{}) ([]byte, error)

Test this is used ONLY in tests

type Ticket

Ticket represents a matchmaking ticket that manages a life cycle of issued ticket

OnMatch - Raised when a remote user matches. By returning true, you may compelte the ticket and raise OnComplete
type Ticket struct {
    OnMatch func(userData *user.User, roomID string, memberIDs []string) bool
    // contains filtered or unexported fields

func IssueTicket

func IssueTicket(params *TicketParams, userData *user.User) *Ticket

IssueTicket creates a new matchmaking ticket and returns a created ticket.

A matchmaking ticket will perform searches and add with the given properties and profile IDs and is event driven.

Usage Example:

// issue a new matchmaking ticket with the ticket parameters
ticket := matching.IssueTicket(ticketParams, userData)

ticket.OnMatch = func(userData *user.User, roomID string, memberIDs []string) bool {
	// if we return true, the matchmaking will be completed and onComplete callback will be invoked with success

// now we start the ticket

// call this to cancel the ticket

params   - Parameters of the ticket to be issued represented by TicketParams struct
userData - User that issues the ticket as the owner

func (*Ticket) IsTicketFinished

func (t *Ticket) IsTicketFinished() bool

IsTicketFinished returns true if the ticket has finished its entire operations.

func (*Ticket) Start

func (t *Ticket) Start() bool

Start starts the life cycle of a ticket.

func (*Ticket) Stop

func (t *Ticket) Stop() bool

Stop interrupts the ticket and stops all matchmaking opertions.

type TicketParams

TicketParams parameter struct for IssueTicket

ProfileIDs     - A list of profiles to add to and search against
Properties     - Matchmaking properties (conditions)
SearchInterval - The interval for search in milliseconds
TicketDuration - Duration of the ticket to be valid in seconds
type TicketParams struct {
    // Matchmaking profile IDs to use for search and add
    ProfileIDs []string
    // Matchmaking tag to apply. Leave this empty if not used
    Tag string
    // Matchmaking properties to use for search and add
    Properties map[string]int
    // Maximum number of matchmaking users per matchmaking.
    // When matched users reach this number, the matchmaking will complete as success
    MaxMembers uint8
    // Duration for the matchmaking ticket to be active in seconds
    TicketDuration uint8
    // Search execution interval in milliseconds
    SearchInterval uint16
    // Number of empty search results to tolarate before giving up and moving on to hosting (add)
    SearchTries uint8
    // How many search results to expect at most per search
    HowMany uint8
    // How many search and add as a set should be repeated within TicketDuration.
    // Leave this empty if you do not need to repeat the operation set.
    TicketLoop uint8