Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for backfill ticket response #229

Merged
merged 2 commits into from
Jun 9, 2021
Merged

Add documentation for backfill ticket response #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f977a1e
Add documentation for backfill ticket response
highlyunavailable Jun 4, 2021
5708043
Update site/content/en/docs/Reference/api.md
syntxerror Jun 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 14 additions & 17 deletions site/content/en/docs/Guides/Backfill/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,34 +19,31 @@ Some scenarios that could happen when playing multiplayer games include:

A Match Function example using Backfill can be found [here](https://github.com/googleforgames/open-match/blob/master/examples/functions/golang/backfill/mmf/matchfunction.go).

1. Player creates Ticket (`T1`).
1. Player 1 creates a Ticket (`T1`).
2. Director calls `Backend.FetchMatches` with a MatchProfile.
3. MMF runs `QueryBackfills` and `QueryTickets` using the MatchProfile. It returns `T1`.
4. MMF use `T1`, constructs a new Backfill (`B1`*) and returns a `Match` containing ticket `T1` and Backfill `B1`.
5. Director starts allocating GameServer with Backfill `B1` information.
6. Another player creates a Ticket (`T2`).
4. MMF constructs a new Backfill (`B1`) and returns a `Match` containing ticket `T1` and Backfill `B1`. The Backfill should be created with field `AllocateGameServer` set to `true`, so the game server orchestrator (e.g.: [Agones](https://agones.dev/site/)) knows it has to create a new Game Server. The Director handles making calls to create the Game Server.
5. Director starts allocating a Game Server with Backfill `B1` information.
6. Player 2 creates a Ticket (`T2`).
7. Director calls `Backend.FetchMatches`.
8. MMF runs `QueryBackfills` and `QueryTickets` using the MatchProfile. They return `B1` and `T2` accordingly.
9. MMF determines `B1` could be used because it has open slots available. `T2` and `B1` forms a new Match.
10. When GameServer allocating ends, it starts polling Open Match to acknowledge the backfill with `Frontend.AcknowledgeBackfill` by ID received in the Match (`B1.ID`) and in order to assign the address of the GameServer for `T1` and `T2`.

*: The Backfill should be created with field `AllocateGameServer` set to `true`, so GameServer orchestrator (e.g.: [Agones](https://agones.dev/site/)) knows it has to create a new GameServer.
9. MMF determines `B1` could be used based on data set on `B1` by the last run of the MMF (e.g. a number of open slots). `T2` and `B1` form a new Match.
10. When the Game Server has started, it begins polling Open Match to acknowledge the backfill with `Frontend.AcknowledgeBackfill` using the backfill's ID (`B1.ID`) and supplies connection information for the server, to be returned as the `Assignment` data of the tickets `T1` and `T2`. The Game Server also receives the ticket data of the tickets that were assigned so that any data supplied on the ticket (e.g. player IDs) may be used by the game server.

## Considerations

In order to use Backfill you need to customize your MMF and your Game Servers. BackfillId should be propagated to each Game Server during Game Server allocation. Which would be used later in `AcknowledgeBackfill` requests to define Backfill which is tied to this Game Server.
If Backfill is not being used, no changes are required since the Backfill API doesn't change
the behavior of the current Open Match API state.
In order to use Backfill you need to customize your MMF and your Game Servers. Backfill IDs should be propagated to each Game Server during Game Server allocation to be used in `AcknowledgeBackfill` requests to define Backfill which is tied to the Game Server.

If Backfill is not being used, no changes are required since the Backfill API doesn't change the behavior of the current Open Match API state.

### Acknowledging Backfills

AcknowledgeBackfill is a request, that acts as a periodic ping, made to Open Match Frontend to set the assignment on the tickets associated with this backfill.
GameServer receives current Backfill status as a response.
`AcknowledgeBackfill` is a request made to the Open Match Frontend that serves to notify Open Match that server still interested in the backfill, and to confirm the assignment of the tickets associated with this backfill in the same manner as `Backend.AssignTickets`. The Game Server receives the current Backfill status as well as a list of new tickets that were just acknowledged by the request as a response. The list is not idempotent, but can be appended to prior lists received from `AcknowledgeBackfill`.

GameServers would run `AcknowledgeBackfill` every N seconds, where N is, at most, `backfillTTL` represents 80% of pendingReleaseTimeout and this value MUST always be bigger than N (backfillTTL = 0.8 * pendingReleaseTimeout; N < backfillTTL, where N is AcknowledgeBackfill interval)
GameServers must run `AcknowledgeBackfill` within `backfillTTL` seconds after the Backfill is created and within `backfillTTL` of the last `AcknowledgeBackfill` call after that, where `backfillTTL` is 80% of the pendingReleaseTimeout configuration value.

### Cleaning up Backfills
**Note:** You must keep acknowledging a backfill until it is no longer needed, and if it expires the Backfill object must be recreated and the new ID communicated to the Game Server to begin the `AcknowledgeBackfill` process anew.

This process deletes expired Backfill objects from the state store. Backifll becomes expired if it is not acknowledged in `backfillTTL` period.
### Cleaning up Backfills

Note: you need to keep acknowledging a backfill and if it expires you need to recreate the Backfill object again.
This process deletes expired Backfill objects from the state store. Backfills become expired if they are not acknowledged in the `backfillTTL` period.
21 changes: 19 additions & 2 deletions site/content/en/docs/Reference/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ description:

- [api/frontend.proto](#api/frontend.proto)
- [AcknowledgeBackfillRequest](#openmatch.AcknowledgeBackfillRequest)
- [AcknowledgeBackfillResponse](#openmatch.AcknowledgeBackfillResponse)
- [CreateBackfillRequest](#openmatch.CreateBackfillRequest)
- [CreateTicketRequest](#openmatch.CreateTicketRequest)
- [DeleteBackfillRequest](#openmatch.DeleteBackfillRequest)
Expand Down Expand Up @@ -412,6 +413,23 @@ to possible change or removal.



<a name="openmatch.AcknowledgeBackfillResponse"></a>

### AcknowledgeBackfillResponse
BETA FEATURE WARNING: This Request message is not finalized and still subject
to possible change or removal.


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| backfill | [Backfill](#openmatch.Backfill) | | The Backfill that was acknowledged. |
| tickets | [Ticket](#openmatch.Ticket) | repeated | All of the Tickets that were successfully assigned |






<a name="openmatch.CreateBackfillRequest"></a>

### CreateBackfillRequest
Expand Down Expand Up @@ -570,7 +588,7 @@ The FrontendService implements APIs to manage and query status of a Tickets.
| DeleteTicket | [DeleteTicketRequest](#openmatch.DeleteTicketRequest) | [.google.protobuf.Empty](#google.protobuf.Empty) | DeleteTicket immediately stops Open Match from using the Ticket for matchmaking and removes the Ticket from state storage. The client should delete the Ticket when finished matchmaking with it. |
| GetTicket | [GetTicketRequest](#openmatch.GetTicketRequest) | [Ticket](#openmatch.Ticket) | GetTicket get the Ticket associated with the specified TicketId. |
| WatchAssignments | [WatchAssignmentsRequest](#openmatch.WatchAssignmentsRequest) | [WatchAssignmentsResponse](#openmatch.WatchAssignmentsResponse) stream | WatchAssignments stream back Assignment of the specified TicketId if it is updated. - If the Assignment is not updated, GetAssignment will retry using the configured backoff strategy. |
| AcknowledgeBackfill | [AcknowledgeBackfillRequest](#openmatch.AcknowledgeBackfillRequest) | [Backfill](#openmatch.Backfill) | AcknowledgeBackfill is used to notify OpenMatch about GameServer connection info This triggers an assignment process. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. |
| AcknowledgeBackfill | [AcknowledgeBackfillRequest](#openmatch.AcknowledgeBackfillRequest) | [AcknowledgeBackfillResponse](#openmatch.AcknowledgeBackfillResponse) | AcknowledgeBackfill is used to notify OpenMatch about GameServer connection info. This triggers an assignment process. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. |
| CreateBackfill | [CreateBackfillRequest](#openmatch.CreateBackfillRequest) | [Backfill](#openmatch.Backfill) | CreateBackfill creates a new Backfill object. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. |
| DeleteBackfill | [DeleteBackfillRequest](#openmatch.DeleteBackfillRequest) | [.google.protobuf.Empty](#google.protobuf.Empty) | DeleteBackfill receives a backfill ID and deletes its resource. Any tickets waiting for this backfill will be returned to the active pool, no longer pending. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. |
| GetBackfill | [GetBackfillRequest](#openmatch.GetBackfillRequest) | [Backfill](#openmatch.Backfill) | GetBackfill returns a backfill object by its ID. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. |
Expand Down Expand Up @@ -1141,4 +1159,3 @@ The QueryService service implements helper APIs for Match Function to query Tick
| <a name="bool" /> bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |