Match Function

Open Match Match Function Edgegap's tutorial (basic)#

The Match Function is the core of the decision. It's this service that creates game proposals. It makes its decisions from profile's configuration. In this service, you can code any logic that will generate your match proposals

Prerequisites#

Go
C# (HTTP)

Install Golang 1.16^ on your computer

Front End tutorial

Create Your project#

Go
C# (HTTP)

Every Open Match service should be in its own project. Create a new folder named match-function for the OpenMatch match-function component.

In this folder, run the following command.

go mod init matchfunction

And create a file named main.go where the core logic of the component will be.

Implement Match Function base structure#

Go
C# (HTTP)

The first thing that we need for our Match Function is a gRPC server that will listen for a call from Open Match Core.

We will need two libraries for this step. You can install them with

go get google.golang.org/grpc

go get open-match.dev/open-match/pkg/pb

Now, in your main.go file, you can add the following code. This will create the gPRC server.

main.go (Override All)

package main

import (
    "fmt"
    "log"
    "net"

    "google.golang.org/grpc"
    "open-match.dev/open-match/pkg/pb"
)

const (
    matchFunctionServePort = 50502
    matchName              = "basics-match-function"
    // Link inside kubernetes
    openMatchQueryService = "open-match-query:50503"
)

func main() {
    log.Println("Starting Edgegap's Match Function!")

    server := grpc.NewServer()

    pb.RegisterMatchFunctionServer(server, nil)

    ln, err := net.Listen("tcp", fmt.Sprintf(":%d", matchFunctionServePort))

    if err != nil {
        log.Fatalf("TCP net listener initialization failed for port %v, got %s", 50502, err.Error())
    }

    log.Printf("TCP net listener initialized for port %v", matchFunctionServePort)
    err = server.Serve(ln)
    if err != nil {
        log.Fatalf("gRPC serve failed, got %s", err.Error())
    }
}

You can try it by starting your app with go run ./main.go. You should see

2021/01/26 12:27:50 Starting Edgegap's Match Function!
2021/01/26 12:27:50 TCP net listener initialized for port 50502

The first thing that we need for our Match Function is a HTTP API that will listen for a call from Open Match Core.

We need to change the configuration. You should change the configuration in Properties/launchSettings.json to the following.

Properties/launchSettings.json (Override All)

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:12575",
      "sslPort": 44387
    }
  },
  "profiles": {
    "front_end": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:51502",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Then, we will update Program.cs. We will add a logger and add a middleware to catch unhandled exceptions.

Program.cs (Override All)

using match_function;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using System;

var builder = WebApplication.CreateBuilder(args);

// Adding logging to Dependency Injection
var logger = LoggerFactory.Create(
    logBuilder => logBuilder.AddConsole(
        configuration =>
        {
            configuration.TimestampFormat = "[HH:mm:ss] ";
        })
    )
    .CreateLogger("MatchFunction");
builder.Services.AddSingleton<ILogger>(logger);

var app = builder.Build();


if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

// Handle Exceptions
app.Use(async (context, next) =>
{
    try
    {
        await next(context);
    }
    catch (Exception ex)
    {
        logger.LogError(ex, ex.Message);
        await context.Response.WriteAsJsonAsync(new { Message = ex.Message });
    }
});

// Handle the creation of match proposals
app.MapPost("/v1/matchfunction:run", MatchFunction.Handle);

app.Run();

Now, we will create a file named Core.cs. This file will contain all the classes that have logic inside.

In Core.cs, let's create a class named Constant. In this class, we will store all the constants for our match function.

In Core.cs, let's create a class named MatchFunction with a function Handle. In this function, we will match the players together.

Core.cs (Override All)

using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;
using System.Threading.Tasks;

namespace match_function
{
    // All the constants used in the program
    public static class Constant
    {
        public const string OpenMatchQueryService = "open-match-query:51503";
        public const string MatchName = "basics-match-function";
    }

    public static class MatchFunction
    {
        public static async Task Handle(HttpContext context, ILogger logger)
        {
        }
    } 
}

You can try it by starting your app with dotnet run. You should see

Building...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:51502
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: .../match-function

Create the Match Function#

The strength of Open Match comes from the customization of Match Function and Director services. We will now create the Match Function. This one aims to fetch Open Match tickets based on profiles. Match Function can be very complicated, but we will keep it simple and implement a basic Match Function in this tutorial.

The Match Function will fetch all the tickets that match the profile received in the request. The tickets will be categorized by pool name (Profiles contain pools). Then, we will go through each pool and create game proposals from the tickets in the pool. When the proposals are all created, we will send them back to Open Match Core

Go
C# (HTTP)

We will use gRPC to query the core and send back the proposals.

Below is the code for the Match Function. It should be placed in the main.go file under the main function.

main.go (Add to file)

type basicMatchFunction struct {
    queryServiceClient pb.QueryServiceClient
}

func (bmf *basicMatchFunction) Run(req *pb.RunRequest, stream pb.MatchFunction_RunServer) error {
    // Fetch tickets for the pools specified in the Match Profile.
    log.Printf("Generating proposals for function %v", req.GetProfile().GetName())

    poolTickets, err := matchfunction.QueryPools(stream.Context(), bmf.queryServiceClient, req.GetProfile().GetPools())
    if err != nil {
        log.Printf("Failed to query tickets for the given pools, got %s", err.Error())
        return err
    }

    // Generate proposals.
    proposals, err := makeMatches(req.GetProfile(), poolTickets)
    if err != nil {
        log.Printf("Failed to generate matches, got %s", err.Error())
        return err
    }

    log.Printf("Streaming %v proposals to Open Match", len(proposals))
    // Stream the generated proposals back to Open Match.
    for _, proposal := range proposals {
        if err := stream.Send(&pb.RunResponse{Proposal: proposal}); err != nil {
            log.Printf("Failed to stream proposals to Open Match, got %s", err.Error())
            return err
        }
    }

    return nil
}

func makeMatches(p *pb.MatchProfile, poolTickets map[string][]*pb.Ticket) ([]*pb.Match, error) {
    ticketsPerPoolPerMatch := 2
    var matches []*pb.Match
    count := 0
    for {
        insufficientTickets := false
        matchTickets := []*pb.Ticket{}
        for pool, tickets := range poolTickets {
            if len(tickets) < ticketsPerPoolPerMatch {
                // This pool is completely drained out. Stop creating matches.
                insufficientTickets = true
                break
            }

            // Remove the Tickets from this pool and add them to the match proposal.
            matchTickets = append(matchTickets, tickets[0:ticketsPerPoolPerMatch]...)
            poolTickets[pool] = tickets[ticketsPerPoolPerMatch:]
        }

        if insufficientTickets {
            break
        }

        matches = append(matches, &pb.Match{
            MatchId:       fmt.Sprintf("profile-%v-time-%v-%v", p.GetName(), time.Now().Format("2006-01-02T15:04:05.00"), count),
            MatchProfile:  p.GetName(),
            MatchFunction: matchName,
            Tickets:       matchTickets,
        })

        count++
    }

    return matches, nil
}

You will have to change your dependencies. They should look like this

main.go (Replace)

import (
    "fmt"
    "log"
    "net"
    "time"

    "google.golang.org/grpc"
    "open-match.dev/open-match/pkg/matchfunction"
    "open-match.dev/open-match/pkg/pb"
)

Also, you will have to update the main function to create the Open Match Query service connection and make the basicMatchFunction

main.go (Replace)

func main() {
    log.Println("Starting Edgegap's Match Function!")

    // Create Open Match Query service connection
    conn, err := grpc.Dial(
        openMatchQueryService, grpc.WithInsecure(),
    )

    if err != nil {
        log.Fatalf("Error while creating gRPC connection, err: %v", err.Error())
    }

    queryServiceClient := pb.NewQueryServiceClient(conn)

    // Creating basicMatchFunction
    basicMatchFunction := basicMatchFunction{
        queryServiceClient: queryServiceClient,
    }

    server := grpc.NewServer()

    pb.RegisterMatchFunctionServer(server, &basicMatchFunction) // IMPORTANT Register MatchFunction

    ln, err := net.Listen("tcp", fmt.Sprintf(":%d", matchFunctionServePort))

    if err != nil {
        log.Fatalf("TCP net listener initialization failed for port %v, got %s", 50502, err.Error())
    }

    log.Printf("TCP net listener initialized for port %v", matchFunctionServePort)
    err = server.Serve(ln)
    if err != nil {
        log.Fatalf("gRPC serve failed, got %s", err.Error())
    }
}

It will be hard to test this service in a standalone context. We will see it in action when all the services (Front end, Director, and Match Function) will be ready.

Now, we will create a file named Models.cs. This file will contain all the models used for HTTP calls.

Models.cs (Override All)

using Microsoft.AspNetCore.Http;
using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json.Serialization;
using System.Threading;
using System.Threading.Tasks;

namespace match_function
{
    // Based On OpenMatchRunRequest in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct OpenMatchRunRequest
    {
        [JsonPropertyName("profile")]
        public OpenMatchMatchProfile Profile { get; set; }
    }

    // Based On OpenMatchMatchProfile in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct OpenMatchMatchProfile
    {
        [JsonPropertyName("name")]
        public string Name { get; set; }
        [JsonPropertyName("pools")]
        public OpenMatchPool[] Pools { get; set; }
    }

    // Based On OpenMatchPool in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct OpenMatchPool
    {
        [JsonPropertyName("name")]
        public string Name { get; set; }
        [JsonPropertyName("tag_present_filters")]
        public TagPresentFilter[] TagPresentFilters { get; set; }
    }

    // Based On TagPresentFilter in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct TagPresentFilter
    {
        [JsonPropertyName("tag")]
        public string Tag { get; set; }
    }

    // Based On OpenMatchQueryTicketsRequest in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=Query
    public struct OpenMatchQueryTicketsRequest
    {
        [JsonPropertyName("pool")]
        public OpenMatchPool Pool { get; set; }
    }

    // Based On Stream result in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct OpenMatchStreamResult<T>
    {
        [JsonPropertyName("result")]
        public T Result { get; set; }
    }

    // Based On Stream result in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=Query
    public struct OpenMatchQueryTicketsResponse
    {
        [JsonPropertyName("tickets")]
        public OpenMatchTicket[] Tickets { get; set; }
    }

    // Based On OpenMatchTicket in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct OpenMatchTicket
    {
        [JsonPropertyName("id")]
        public string Id { get; set; }
        [JsonPropertyName("search_fields")]
        public OpenMatchSearchFields SearchFields { get; set; }
        [JsonPropertyName("extensions")]
        public Dictionary<string, ProtobufAny> Extensions { get; set; }
    }

    // Based On OpenMatchSearchFields in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=Query
    public struct OpenMatchSearchFields
    {
        [JsonPropertyName("tags")]
        public string[] Tags { get; set; }
    }

    // Based On ProtobufAny in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct ProtobufAny
    {
        [JsonPropertyName("@type")]
        public string TypeUrl { get; set; }
        [JsonPropertyName("value")]
        public byte[] Value { get; set; }
    }

    // Based On OpenMatchMatch in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct OpenMatchMatch
    {
        [JsonPropertyName("match_id")]
        public string MatchId { get; set; }
        [JsonPropertyName("match_profile")]
        public string MatchProfile { get; set; }
        [JsonPropertyName("match_function")]
        public string MatchFunction { get; set; }
        [JsonPropertyName("tickets")]
        public OpenMatchTicket[] Tickets { get; set; }
    }

    // Based On OpenMatchRunResponse in https://open-match.dev/site/swaggerui/index.html?urls.primaryName=MatchFunction
    public struct OpenMatchRunResponse
    {
        [JsonPropertyName("proposal")]
        public OpenMatchMatch Proposal { get; set; }
    } 
}

Let's update our class MatchFunction. We will add the logic that communicate with Open Match core. The class should look like this.

Core.cs (Replace)

public static class MatchFunction
{
    public static async Task Handle(HttpContext context, ILogger logger)
    {
        context.Request.ContentType = "application/json";
        OpenMatchRunRequest body = await context.Request.ReadFromJsonAsync<OpenMatchRunRequest>();

        logger.LogInformation($"Generating proposals for profile {body.Profile.Name}");

        IDictionary<string, IList<OpenMatchTicket>> poolTickets = await GetPoolTickets(body.Profile.Pools);
        IEnumerable<OpenMatchMatch> proposals = MakeMatches(body.Profile, poolTickets);

        logger.LogInformation("Streaming proposals to Open Match");
        foreach (OpenMatchMatch proposal in proposals)
        {
            var responseChunk = new OpenMatchStreamResult<OpenMatchRunResponse>
            {
                Result = new OpenMatchRunResponse
                {
                    Proposal = proposal
                }
            };
            await JsonSerializer.SerializeAsync(context.Response.Body, responseChunk);
            await context.Response.Body.FlushAsync();

            logger.LogInformation($"Streaming proposal {proposal.MatchId} to Open Match");
        }
    }

    private static async Task<IDictionary<string, IList<OpenMatchTicket>>> GetPoolTickets(IList<OpenMatchPool> pools)
    {
        IDictionary<string, IList<OpenMatchTicket>> result = new Dictionary<string, IList<OpenMatchTicket>>();

        foreach (OpenMatchPool pool in pools)
        {
            try
            {
                // Making a request to Open Match Front End. In an production environment, we recommend using a generated SDK
                // from Open Match's OpenAPI specification.
                // https://open-match.dev/site/swaggerui/index.html?urls.primaryName=Query
                HttpClient client = new HttpClient();

                OpenMatchQueryTicketsRequest body = new OpenMatchQueryTicketsRequest
                {
                    Pool = pool
                };

                // Sending the request to Open Match Query
                HttpResponseMessage response = await client.PostAsJsonAsync(
                    $"http://{Constant.OpenMatchQueryService}/v1/queryservice/tickets:query",
                    body
                );

                string stringBody = await response.Content.ReadAsStringAsync();
                IEnumerable<string> results = stringBody.Trim().Split('\n').Where(s => s is not null && s.Trim() != "");

                if (response.StatusCode != System.Net.HttpStatusCode.OK)
                {
                    throw new Exception($"Resquest Error {(int)response.StatusCode} - {stringBody}");
                }

                List<OpenMatchTicket> tickets = new();

                // Extracting propsals from response
                foreach (string rawJSON in results)
                {
                    var matchResult = JsonSerializer.Deserialize<OpenMatchStreamResult<OpenMatchQueryTicketsResponse>>(rawJSON);
                    tickets.AddRange(matchResult.Result.Tickets);
                }

                result.Add(pool.Name, tickets);
            }
            catch (Exception ex)
            {
                throw new Exception("TODO", ex);
            }
        }

        return result;
    }

    private static IEnumerable<OpenMatchMatch> MakeMatches(OpenMatchMatchProfile profile, IDictionary<string, IList<OpenMatchTicket>> poolTickets)
    {
        int ticketsPerPoolPerMatch = 2;
        int count = 0;

        while (true)
        {
            bool insufficientTickets = false;
            List<OpenMatchTicket> matchTickets = new();

            foreach (string poolName in poolTickets.Keys)
            {
                IList<OpenMatchTicket> tickets = poolTickets[poolName];
                if (tickets.Count < ticketsPerPoolPerMatch)
                {
                    // This pool is completely drained out. Stop creating matches.
                    insufficientTickets = true;
                    break;
                }

                // Remove the Tickets from this pool and add them to the match proposal.
                matchTickets.AddRange(tickets.Take(ticketsPerPoolPerMatch));
                poolTickets[poolName] = tickets.Skip(ticketsPerPoolPerMatch).ToArray();
            }

            if (insufficientTickets)
            {
                break;
            }

            yield return new OpenMatchMatch
            {
                MatchId = $"profile-{profile.Name}-time-{DateTime.UtcNow.ToString("o")}-{count}",
                MatchProfile = profile.Name,
                MatchFunction = Constant.MatchName,
                Tickets = matchTickets.ToArray(),
            };

            count++;
        }
    }
}

Containerize your service#

Go
C# (HTTP)

Containerization is powerful. You can learn more about it on Edgegap's documentation or Docker. Our container, we will use golang:1.16 for its base image.

Create a file named Dockerfile and write this inside.

FROM golang:1.16

COPY . /go/src/app
WORKDIR /go/src/app

RUN go get -d -v /go/src/app
RUN go install -v /go/src/app

WORKDIR /go/bin 

CMD ["matchfunction"]

You can now build your image using.

docker build -t edgegap-om-tuto-match-function:tuto .

You can run it using this command, but without all the other services, it will not work.

docker run -it --name om-tuto-match-function edgegap-om-tuto-match-function:tuto .

Conclusion#

You now have a basic Open Match Match Function service that can be called by Open Match Core using gRPC protocol. This is not production-ready. However, you should be able to grasp the basics of Open Match Match Function. You also created a Docker image that can be used later.