matchmaking-function-grpc-plugin-server-csharp

flowchart LR
   subgraph AccelByte Gaming Services
   CL[gRPC Client]
   end
   subgraph Extend Override App
   SV["gRPC Server"]
   end
   CL --- SV

Loading

AccelByte Gaming Services (AGS) features can be customized using Extend Override apps. An Extend Override app is basically a gRPC server which contains one or more custom functions which can be called by AGS instead of the default functions.

Overview

This repository provides a project template to create an Extend Override app for matchmaking function written in C#. It includes an example of how the custom functions can be implemented to match 2 players. It also includes the essential gRPC server authentication and authorization to ensure security. Additionally, it comes with built-in instrumentation for observability, ensuring that metrics, traces, and logs are available upon deployment.

You can clone this repository to begin developing your own Extend Override app for matchmaking function. Simply modify this project by implementing your own logic for the custom functions.

Prerequisites

1. Windows 11 WSL2 or Linux Ubuntu 22.04 or macOS 14+ with the following tools installed:

   a. Bash

   • On Windows WSL2 or Linux Ubuntu:

     bash --version
     
     GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
     ...
     

   • On macOS:

     bash --version
     
     GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
     ...
     

   b. Make

   • On Windows WSL2 or Linux Ubuntu:

     To install from the Ubuntu repository, run sudo apt update && sudo apt install make.

     make --version
     
     GNU Make 4.3
     ...
     

   • On macOS:

     make --version
     
     GNU Make 3.81
     ...
     

   c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)

   • On Linux Ubuntu:

     1. To install from the Ubuntu repository, run sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2.
     2. Add your user to the docker group: sudo usermod -aG docker $USER.
     3. Log out and log back in to allow the changes to take effect.

   • On Windows or macOS:

     Follow Docker's documentation on installing the Docker Desktop on Windows or macOS.

     docker version
     
     ...
     Server: Docker Desktop
        Engine:
        Version:          24.0.5
     ...
     

   d. .NET 8 SDK

   • On Linux Ubuntu:

     To install from the Ubuntu repository, run sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0.

   • On Windows or macOS:

     Follow the documentation for Windows or macOS.

     dotnet --version
     
     8.0.119
     

   e. Postman

   • Use the available binary from Postman.

   f. extend-helper-cli

   • Use the available binary from extend-helper-cli.

   g. Local tunnel service that has TCP forwarding capability, such as:

   • Ngrok

     Need registration for free tier. Please refer to ngrok documentation for a quick start.

   • Pinggy

     Free to try without registration. Please refer to pinggy documentation for a quick start.

   ❗ In macOS, you may use Homebrew to easily install some of the tools above.

2. Access to AccelByte Gaming Services environment.

   a. Base URL

   • For Shared Cloud tier e.g. https://spaceshooter.prod.gamingservices.accelbyte.io
   • For Private Cloud tier e.g. https://dev.accelbyte.io

   b. Create a Game Namespace if you don't have one yet. Keep the Namespace ID.

   c. Create an OAuth Client with confidential client type with the following permission. Keep the Client ID and Client Secret.

Setup

To be able to run this app, you will need to follow these setup steps.

1. Create a docker compose .env file by copying the content of .env.template file.

   ⚠️ The host OS environment variables have higher precedence compared to .env file variables: If the variables in .env file do not seem to take effect properly, check if there are host OS environment variables with the same name. See documentation about docker compose environment variables precedence for more details.

2. Fill in the required environment variables in .env file as shown below.

   AB_BASE_URL=https://test.accelbyte.io     # Base URL of AccelByte Gaming Services environment
   AB_CLIENT_ID='xxxxxxxxxx'                 # Client ID from the Prerequisites section
   AB_CLIENT_SECRET='xxxxxxxxxx'             # Client Secret from the Prerequisites section
   AB_NAMESPACE='xxxxxxxxxx'                 # Namespace ID from the Prerequisites section
   PLUGIN_GRPC_SERVER_AUTH_ENABLED=true      # Enable or disable access token validation
   

   ❗ In this app, PLUGIN_GRPC_SERVER_AUTH_ENABLED is true by default: If it is set to false, the gRPC server can be invoked without an AGS access token. This option is provided for development purpose only. It is recommended to enable gRPC server access token validation in production environment.

For more options, create src/AccelByte.PluginArch.Demo.Server/appsettings.Development.json and fill in the required configuration.

{
  "EnableAuthorization": true,                 // Enable or disable access token and permission check (env var: PLUGIN_GRPC_SERVER_AUTH_ENABLED)
  "RevocationListRefreshPeriod": 60,
  "AccelByte": {
    "BaseUrl": "https://test.accelbyte.io",     // Base URL (env var: AB_BASE_URL)
    "ClientId": "xxxxxxxxxx",                   // Client ID (env var: AB_CLIENT_ID)    
    "ClientSecret": "xxxxxxxxxx",               // Client Secret (env var: AB_CLIENT_SECRET)
    "AppName": "MMV2GRPCSERVICE",
    "TraceIdVersion": "1",
    "Namespace": "xxxxxxxxxx",                  // Namespace ID (env var: AB_NAMESPACE)
    "EnableTraceId": true,
    "EnableUserAgentInfo": true,
    "ResourceName": "MMV2GRPCSERVICE"
  }
}

⚠️ Environment variables will override related values in this file.

Building

To build this app, use the following command.

$ make build

The build output will be available in .output directory.

Running

To (build and) run this app in a container, use the following command.

$ docker compose up --build

Testing

Test in Local Development Environment

⚠️ To perform the following, make sure PLUGIN_GRPC_SERVER_AUTH_ENABLED is set to false: Otherwise, the gRPC request will be rejected by the gRPC server.

This app can be tested locally using Postman.

1. Run this app by using the command below.

   docker compose up --build

2. Open Postman, create a new gRPC request, and enter localhost:6565 as server URL.

   ⚠️ If you are running grpc-plugin-dependencies stack alongside this project as mentioned in Test Observability: Use localhost:10000 instead of localhost:6565. This way, the gRPC server will be called via Envoy service within grpc-plugin-dependencies stack instead of directly.

3. Continue by selecting MakeMatches grpc stream method and click Invoke button. This will start stream connection to thegRPC server.

4. Proceed by sending parameters first to specify number of players in a match by copying sample json below and click Send.

   {
       "parameters": {
           "rules": {
               "json": "{\"shipCountMin\":2, \"shipCountMax\":2}"
           }
       }
   }

5. Now we can send match ticket to start matchmaking by copying sample json below and replace it into Postman message then click Send.

   {
       "ticket": {
           "players": [
               {
                   "player_id": "playerA"
               }
           ]
       }
   }

6. You can do step 5 multiple times until the number of players is met and a match can be created. In this case, it is 2 players.

7. If successful, you will receive responses (down stream) in Postman that looks like the following.

   {
       "match": {
           "tickets": [],
           "teams": [
               {
                   "user_ids": [
                       "playerA",
                       "playerB"
                   ]
               }
           ],
           "region_preferences": [
               "us-east-2", 
               "us-west-2"
           ],
   
           "match_attributes": null
       }
   }

Test with AccelByte Gaming Services

To test the app, which runs locally with AGS, the gRPC server needs to be connected to the internet. To do this without requiring public IP, you can use local tunnel service.

1. Run this app by using command below.

   docker compose up --build

2. Expose gRPC server TCP port 6565 in local development environment to the internet. Simplest way to do this is by using local tunnel service provider.

   • Sign in to ngrok and get your authtoken from the ngrok dashboard and set it up in your local environment. And, to expose gRPC server use following command:

     ngrok tcp 6565

   • Or alternatively, you can use pinggy and use only ssh command line to setup simple tunnel. Then to expose gRPC server use following command:

     ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -R0:127.0.0.1:6565 [email protected]

   Please take note of the tunnel forwarding URL, e.g., http://0.tcp.ap.ngrok.io:xxxxx or tcp://xxxxx-xxx-xxx-xxx-xxx.a.free.pinggy.link:xxxxx.

   ❗ You may also use other local tunnel service and different method to expose the gRPC server port (TCP) to the internet.

   ⚠️ If you are running grpc-plugin-dependencies stack alongside this app as mentioned in Test Observability: Run the above command in grpc-plugin-dependencies directory instead of this app directory and change tunnel local port from 6565 to 10000. This way, the gRPC server will be called via Envoy service within grpc-plugin-dependencies stack instead of directly.

3. Create an OAuth Client with confidential client type with the following permissions. Keep the Client ID and Client Secret.

   • For AGS Private Cloud customers:
     • NAMESPACE:{namespace}:MATCHMAKING:RULES [CREATE,READ,UPDATE,DELETE]
     • NAMESPACE:{namespace}:MATCHMAKING:FUNCTIONS [CREATE,READ,UPDATE,DELETE]
     • NAMESPACE:{namespace}:MATCHMAKING:POOL [CREATE,READ,UPDATE,DELETE]
     • NAMESPACE:{namespace}:MATCHMAKING:TICKET [CREATE,READ,UPDATE,DELETE]
     • ADMIN:NAMESPACE:{namespace}:INFORMATION:USER:* [CREATE,READ,UPDATE,DELETE]
     • ADMIN:NAMESPACE:{namespace}:SESSION:CONFIGURATION:* [CREATE,READ,UPDATE,DELETE]
   • For AGS Shared Cloud customers:
     • Matchmaking -> Rule Sets (Create, Read, Update, Delete)
     • Matchmaking -> Match Functions (Create, Read, Update, Delete)
     • Matchmaking -> Match Pools (Create, Read, Update, Delete)
     • Matchmaking -> Match Tickets (Create, Read, Update, Delete)
     • IAM -> Users (Create, Read, Update, Delete)
     • Session -> Configuration Template (Create, Read, Update, Delete)

   ⚠️ Oauth Client created in this step is different from the one from Prerequisites section: It is required by Postman collection script in the next step to register the gRPC Server URL and also to create and delete test users.

4. Import the Postman collection into Postman to simulate the matchmaking flow. Follow the instructions in the Postman collection overview to set up the environment, using the Client ID and Client Secret from the previous step. Monitor the Extend app console log while the matchmaking flow is running. The gRPC server methods should be triggered when creating match tickets, and players should be grouped in pairs.

Test Observability

To be able to see the how the observability works in this app locally, there are few things that need be setup before performing tests.

1. Uncomment loki logging driver in docker-compose.yaml

    # logging:
    #   driver: loki
    #   options:
    #     loki-url: http://host.docker.internal:3100/loki/api/v1/push
    #     mode: non-blocking
    #     max-buffer-size: 4m
    #     loki-retries: "3"
   

   ⚠️ Make sure to install docker loki plugin beforehand: Otherwise, this project will not be able to run. This is required so that container logs can flow to the loki service within grpc-plugin-dependencies stack. Use this command to install docker loki plugin: docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions.

2. Clone and run grpc-plugin-dependencies stack alongside this project. After this, Grafana will be accessible at http://localhost:3000.

   git clone https://github.com/AccelByte/grpc-plugin-dependencies.git
   cd grpc-plugin-dependencies
   docker-compose up
   

   ❗ More information about grpc-plugin-dependencies is available here.

3. Perform testing. For example, by following Test in Local Development Environment or Test with AccelByte Gaming Services.

Deploying

After completing testing, the next step is to deploy your app to AccelByte Gaming Services.

1. Create an Extend Override app

   If you do not already have one, create a new Extend Override App.

   On the App Detail page, take note of the following values.

   • Namespace
   • App Name

   Under the Environment Configuration section, set the required secrets and/or variables.

   • Secrets
     • AB_CLIENT_ID
     • AB_CLIENT_SECRET

2. Build and Push the Container Image

   Use extend-helper-cli to build and upload the container image.

   extend-helper-cli image-upload --login --namespace <namespace> --app <app-name> --image-tag v0.0.1
   

   ⚠️ Run this command from your project directory. If you are in a different directory, add the --work-dir <project-dir> option to specify the correct path.

3. Deploy the Image

   On the App Detail page:

   • Click Image Version History
   • Select the image you just pushed
   • Click Deploy Image

Next Step

Proceed by modifying this Extend Override app template to implement your own custom logic. For more details, see here.