{"id":29572688,"url":"https://github.com/accelbyte/session-dsm-grpc-plugin-gamelift-go","last_synced_at":"2025-07-19T05:10:53.593Z","repository":{"id":295005666,"uuid":"950057908","full_name":"AccelByte/session-dsm-grpc-plugin-gamelift-go","owner":"AccelByte","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-23T04:04:59.000Z","size":50,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-23T05:29:34.051Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AccelByte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-17T15:06:28.000Z","updated_at":"2025-05-23T04:05:03.000Z","dependencies_parsed_at":"2025-05-23T05:30:02.311Z","dependency_job_id":"227b8bf2-21f1-44cd-b481-57bac33ab387","html_url":"https://github.com/AccelByte/session-dsm-grpc-plugin-gamelift-go","commit_stats":null,"previous_names":["accelbyte/session-dsm-grpc-plugin-gamelift-go"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AccelByte/session-dsm-grpc-plugin-gamelift-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fsession-dsm-grpc-plugin-gamelift-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fsession-dsm-grpc-plugin-gamelift-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fsession-dsm-grpc-plugin-gamelift-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fsession-dsm-grpc-plugin-gamelift-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AccelByte","download_url":"https://codeload.github.com/AccelByte/session-dsm-grpc-plugin-gamelift-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Fsession-dsm-grpc-plugin-gamelift-go/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265892512,"owners_count":23845034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-19T05:10:52.978Z","updated_at":"2025-07-19T05:10:53.571Z","avatar_url":"https://github.com/AccelByte.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Session DSM Extend Override for Amazon GameLift Servers\n\n**AccelByte Gaming Services** (AGS) features can be customized using **Extend** services, which are backend gRPC servers that can be written by developers to customize AGS functionality. The **Session DSM Extend Override** is a service used to request servers to back AccelByte Game Sessions. Developers can customize the Session DSM to support other hosting providers including, Amazon GameLift Servers.\n\n## Overview\n\nThe Session DSM has three overridable functions: `CreateGameSession`, `CreateGameSessionAsync`, and `TerminateGameSession`. In this project, these functions are implemented to manage servers through Amazon GameLift Servers using [the official AWS SDK for Go v2](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2).\n\n- `CreateGameSession` creates a Amazon GameLift Game Session using the AWS SDK function `CreateGameSession` and immediately returns server connection details on success. This is the default behavior of the Session DSM, and is useful for testing or for games that may not require the power and flexibility of Amazon GameLift Queues\n- `CreateGameSessionAsync` starts a Amazon GameLift session queue placement using the AWS SDK function `StartGameSessionPlacement`. This is used when running the Session DSM in **asynchronous mode**, and is used to leverage Amazon GameLift Queues.\n- `TerminateGameSession` will terminate an existing Amazon GameLift Game Session using the AWS SDK function `TerminateGameSession`. This is used for sessions that are created by both `CreateGameSession` and `CreateGameSessionAsync`.\n\n### Synchronous vs Asynchronous Mode\n\nThere are two distinct methods that can be used to request servers from Amazon GameLift Servers, referred to as **synchronous mode** and **asynchronous mode**. This toggle is handled in the Session DSM, and can be set for specific AccelByte Session Templates as needed.\n\n**Synchronous mode** is simpler to implement, and is best used for early testing and development workflows. This method also gives developers explicit control over what fleets are used when a session is created.\n\nThe following sequence diagram depicts the normal flow when operating the Session DSM in synchronous mode. This is the default behavior, and the flow used by the quickstart guide.\n\n```mermaid\nsequenceDiagram\n\tbox black AccelByte\n\t\tparticipant AGS\n\t\tparticipant Session DSM\n\tend\n\tbox black Amazon\n\t\tparticipant GameLift\n\t\tparticipant Dedicated Server\n\tend\n\n\tNote over AGS: Match is created\n\t\n\tAGS -\u003e\u003e +Session DSM: CreateGameSession (Extend Override gRPC)\n\n\tSession DSM -\u003e\u003e +GameLift: CreateGameSession (Amazon GameLift Servers SDK)\n\tGameLift -\u003e\u003e -Session DSM: Server connection info\n\n\tGameLift -\u003e\u003e Dedicated Server: OnStartGameSession\n\t\n\tSession DSM -\u003e\u003e -AGS:\tServer connection info\n\t\n\tNote over AGS: Server connection info for \u003cbr\u003e the match is sent to client\n```\n\n**Asynchronous mode** allows developers to utilize Amazon GameLift Server Queues for session placement, which allows placing sessions to optimize by latency, cost, and location. Using Queues offers an easy and efficient way to process high volumes of session placement requests across multiple regions. This mode is recommended for production workloads.\n\nWhen using asynchronous mode and a session placement succeeds, the flow is similar to the synchronous flow, but the dedicated server makes the call to AccelByte through UpdateDSInformation to provide connection details and update the server status to \"AVAILABLE\".\n\n```mermaid\nsequenceDiagram\n\tbox black AccelByte\n\t\tparticipant AGS\n\t\tparticipant Session DSM\n\tend\n\tbox black Amazon\n\t\tparticipant GameLift\n\t\tparticipant Dedicated Server\n\tend\n\n\tNote over AGS: Match is created\n\t\n\tAGS -\u003e\u003e +Session DSM: CreateGameSessionAsync (Extend Override gRPC)\n\n\tSession DSM -\u003e\u003e +GameLift: StartGameSessionPlacement (Amazon GameLift Servers SDK)\n\n\tGameLift -\u003e\u003e -Session DSM: OK\n\t\n\tSession DSM -\u003e\u003e -AGS:\tOK\n\t\n\tNote over GameLift: Queue placement succeeds\n\t\n\tGameLift -\u003e\u003e Dedicated Server: OnStartGameSession\n\t\n\tDedicated Server -\u003e\u003e AGS: UpdateDSInformation (status = \"AVAILABLE\")\n\t\n\tNote over AGS: Server connection info for \u003cbr\u003e the match is sent to client\n```\n\n## Environment Variables\n\nSeveral environment variables are required when running the Session DSM. The following is a list of all environment variables and example values.\n\n- `AB_BASE_URL`: the full name of the AccelByte URL for your organization and namespace\n    - e.g. `\u003corganization\u003e-\u003cnamespace\u003e.prod.gamingservices.accelbyte.io`\n- `AB_CLIENT_ID` and `AB_CLIENT_SECRET`: the ID and secret of the AccelByte IAM Client for the CLI\n    - If you are coming from the QUICKSTART guide, these should match the `ByteWars-AMSCLI` client ID and secret\n\t- If you are running the Session DSM locally, these should match the Session DSM credentials, not the CLI credentials\n- `AWS_REGION`: the primary AWS region used to create Amazon GameLift resources \n    - e.g. `us-west-2`\n- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`: Amazon IAM credentials used by the Session DSM to manage Amazon GameLift sessions\n    - If you are coming from the QUICKSTART guide, these can be retrieved from Terraform\n- `AWS_LOCATION_OVERRIDE`:\n    - Only required when running the Session DSM in **synchronous mode**. This specifies the region that contains the Alias defined in `AWS_ALIAS_ID_OVERRIDE`\n    - When using Amazon GameLift Servers Anywhere, this value should match the custom location of your Anywhere fleet, e.g. `custom-location-1`\n\t- Otherwise, this should be the home region for your Amazon GameLift resources, e.g. `us-west-2`\n- `AWS_ALIAS_ID_OVERRIDE`: When using the Session DSM in **synchronous mode**, this value determines the fleet alias to use when creating a fleet using the AWS SDK `CreateGameSession` function\n    - e.g. `fleet-8959a83a-b6ca-469c-9b84-394dedc64a6f`\n- `AWS_QUEUE_ARN_OVERRIDE`: When using the Session DSM in **asynchronous mode**, this value determines the queue that should be used when placing the session. The queue will find an appropriate fleet/alias for the game session\n    - e.g. `arn:aws:gamelift:us-west-2:0123456789:gamesessionqueue/example-queue-name`\n\n## Quickstart\n\n### Creating, Uploading, and Deploying the Session DSM\n\nAccelByte provides a command-line utility that can be used to create, upload, and manage Extend apps. For more information, refer to the the official AccelByte documentation: [Get started with session Dedicated Server customization](https://docs.accelbyte.io/gaming-services/services/extend/override/getting-started-with-session-customization-server-dsm/#upload-the-extend-app).\n\nA helper script using the `extend-helper-cli` is located in the Session DSM repo that will create, configure, build, upload and deploy the Session DSM. Modify and run the script in `scripts/create_session_dsm.sh` to create and configure the Session DSM.\n\nYou will need to fill the environment variables at the top of the helper script before running.\n\nOnce the Session DSM is created and configured, a new AccelByte IAM Client will be created. You will need to add one additional permission to this client to support game session termination. In the AccelByte Admin Portal, navigate to `Game Setup` → `Games and Apps` → `IAM Clients` and edit the `extend-bytewars-session-dsm` IAM client. Add `Game Session` READ permissions (`NAMESPACE:{namespace}:SESSION:GAME [READ]`).\n\n### Running the Session DSM Locally\n\nYou may wish to run the Session DSM locally to quickly iterate and test changes. A docker-compose file is provided to quickly spin up a local server for testing. It is recommended to run using Linux, macOS, or WSL2 on Windows.\n\nYou will need [docker](https://www.docker.com/get-started/) installed (engine version 24.0.5 or later) to continue.\n\nYou will need to expose a port to AccelByte so that it can make requests to your locally running server. It is recommended to use [ngrok](https://ngrok.com/), though you may choose to use [pinggy](https://pinggy.io/) or another local tunnel service to expose the TCP port to the internet.\n\nThe following instructions assume that you are using Ngrok. You may refer to [ngrok documentation](https://ngrok.com/docs/getting-started/) for a quick start.\n\n1. Create a `.env` file. A template file is provided in `.env.template` that can be used as a base.\n    - Note that the `AB_CLIENT_ID` and `AB_CLIENT_SECRET` values should match the IAM Client for the **Session DSM**, and not the **CLI**.\n2. Run `docker compose up --build` to build and run the server locally.\n3. In another terminal window, expose the TCP port 6565 to the internet. If using ngrok, you can run `ngrok tcp 6565`\n    - Make a note of the forwarding URL (e.g. `0.tcp.ngrok.io:12345`)\n4. In the AccelByte Admin Portal, navigate to `Multiplayer` → `Matchmaking` → `Session Configuration`, and select the Session Template you wish to use. In the `Server` section, select `Custom URL` and provide your TCP forwarding URL. Save your changes.\n5. You can now matchmake normally. Any matchmaking pools backed by the modified session template will use your locally running Session DSM.\n\n## Additional Resources\n\nThis repository is based on the standard AccelByte Session DSM template: [AccelByte/session-dsm-grpc-plugin-go](https://github.com/AccelByte/session-dsm-grpc-plugin-go).\n\nThe IaC (Infrastructure as Code) repo to help you deploy AWS components needed to integrate with production-ready GameLift async queue system is here: [AccelByte/session-dsm-gamelift-iac](https://github.com/AccelByte/session-dsm-gamelift-iac).\n\nFor more information about the Extend system and the Session DSM extension, refer to the following resources:\n\n- [Getting Started with Session Dedicated Server Customization](https://docs.accelbyte.io/gaming-services/services/extend/override/getting-started-with-session-customization-server-dsm/)\n- [Introduction to External Dedicated Game Server Management with Session Override](https://docs.accelbyte.io/gaming-services/services/extend/override/session-dsm-function/)\n\nThe following functions in the AWS Golang SDK are used in this implementation of the Session DSM:\n\n- [aws-sdk-go-v2 - CreateGameSession](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/gamelift#Client.CreateGameSession)\n- [aws-sdk-go-v2 - StartGameSessionPlacement](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/gamelift#Client.StartGameSessionPlacement)\n- [aws-sdk-go-v2 - TerminateGameSession](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/gamelift#Client.TerminateGameSession)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Fsession-dsm-grpc-plugin-gamelift-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faccelbyte%2Fsession-dsm-grpc-plugin-gamelift-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Fsession-dsm-grpc-plugin-gamelift-go/lists"}