synced/open-match
1
0
Fork 0
mirror of https://github.com/googleforgames/open-match.git synced 2025-03-25 13:24:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial protos for Open Match 0.6 (#322)

Browse Source
This commit is contained in:
Saurabh Wagh
2019-04-29 16:39:49 -07:00
committed by GitHub
parent b9af86b829
commit 871abeee69
7 changed files with 368 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
api/LICENSE Normal file
View File

@ -0,0 +1,13 @@
Copyright 2018 Google LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

15
api/README.md
View File

@ -1,12 +1,11 @@
# Open Match APIs
## REST compatibility
Follow the guidelines at https://cloud.google.com/endpoints/docs/grpc/transcoding to keep the gRPC service definitions friendly to REST transcoding. An excerpt:
This directory contains the API specification files for Open Match. API documenation will be produced in a future version, although the protobuf files offer a concise description of the API calls available, along with arguments and return messages.
"Transcoding involves mapping HTTP/JSON requests and their parameters to gRPC methods and their parameters and return types (we'll look at exactly how you do this in the following sections). Because of this, while it's possible to map an HTTP/JSON request to any arbitrary API method, it's simplest and most intuitive to do so if the gRPC API itself is structured in a resource-oriented way, just like a traditional HTTP REST API. In other words, the API service should be designed so that it uses a small number of standard methods (corresponding to HTTP verbs like GET, PUT, and so on) that operate on the service's resources (and collections of resources, which are themselves a type of resource). These standard methods are List, Get, Create, Update, and Delete."
* [Protobuf .proto files for all APIs](./protobuf-spec/)
It is for these reasons we don't have gRPC calls that support bi-directional streaming in Open Match.
References:
## REST API Usage
Open Match gateway proxy transcodes any REST calls to its underlying gRPC service. Follow the [examples](https://cloud.google.com/endpoints/docs/grpc-service-config/reference/rpc/google.api#httprule) for further details.
* [gRPC](https://grpc.io/)
* [Language Guide (proto3)](https://developers.google.com/protocol-buffers/docs/proto3)
If you want to regenerate the golang gRPC modules (for local Open Match core component development, for example), the `protoc_go.sh` file in this directory may be of use to you!
<TODO: Add a sample REST API call>

78
api/backend.proto Normal file
View File

@ -0,0 +1,78 @@
// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = 'proto3';
package api;
option go_package = "internal/future/pb";
import 'api/messages.proto';
// Configuration for the Match Function to be triggered by Open Match to generate proposals.
message MatchFunctionConfig {
message GrpcFunctionProperties {
string host = 1;
int32 port = 2;
}
message RestFunctionProperties {
string host = 1;
int32 port = 2;
}
// A developer-chosen human-readable name for this Match Function.
string name = 1;
// Properties for the type of this function.
oneof function {
GrpcFunctionProperties grpc_function = 101;
RestFunctionProperties rest_function = 102;
}
}
message GetMatchesRequest{
// MatchFunction to be executed for the given list of MatchProfiles
MatchFunctionConfig function = 1;
// MatchProfiles for which this MatchFunction should be executed.
repeated messages.MatchProfile profile = 2;
}
message GetMatchesResponse{
// Result Match for the requested MatchProfile.
messages.Match match = 1;
}
message AssignTicketsRequest {
// List of Ticket ids for which the Assinment is to be made.
repeated string ticket_id = 1;
// Assignment to be associated with the Ticket ids.
messages.Assignment assignment = 2;
}
message AssignTicketsResponse {
}
// The service implementing the Backent API that is called to generate matches and make assignments for Tickets.
service Backend {
// GetMatches triggers execution of the specfied MatchFunction for each of the specified MatchProfiles.
// Each MatchFunction execution returns a set of proposals which are then evaluated to generate results.
// GetMatches method streams these results back to the caller.
rpc GetMatches(GetMatchesRequest) returns (stream GetMatchesResponse) {
}
// AssignTickets sets the specified Assignment on the Tickets for the Ticket ids passed.
rpc AssignTickets(AssignTicketsRequest) returns (AssignTicketsResponse) {
}
}

75
api/frontend.proto Normal file
View File

@ -0,0 +1,75 @@
// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = 'proto3';
package api;
option go_package = "internal/future/pb";
import 'api/messages.proto';
message CreateTicketRequest {
// Ticket object with the properties of the Ticket to be created.
messages.Ticket ticket = 1;
}
message CreateTicketsResponse {
// Ticket object for the created Ticket - with the ticket id populated.
messages.Ticket ticket = 1;
}
message DeleteTicketRequest {
// Ticket id of the Ticket to be deleted.
string ticket_id = 1;
}
message DeleteTicketResponse {
}
message GetTicketRequest {
// Ticket id of the Ticket to fetch.
string ticket_id = 1;
}
message GetTicketUpdatesRequest {
// Ticket id of the Ticket to get updates on.
string ticket_id = 1;
}
message GetTicketUpdatesResponse {
// The updated Ticket object.
messages.Assignment assignment = 1;
}
// The Frontend service enables creating Tickets for matchmaking and fetching the status of these Tickets.
service Frontend {
// CreateTicket will create a new ticket, assign a Ticket id to it and put the Ticket in state storage.
// It will then look through the 'properties' field for the attributes defined as indices the matchmakaking
// config. If the attributes exist and are valid integers, they will be indexed. Creating a ticket adds
// the Ticket to the pool of Tickets considered for matchmaking.
rpc CreateTicket(CreateTicketRequest) returns (CreateTicketsResponse) {
}
// DeleteTicket removes the Ticket from state storage and from corresponding configured indices. Deleting
// the ticket stops the ticket from being considered for future matchmaking requests.
rpc DeleteTicket(DeleteTicketRequest) returns (DeleteTicketResponse) {
}
// GetTicket fetches the ticket associated with the specified Ticket id.
rpc GetTicket(GetTicketRequest) returns (Ticket) {
}
// GetTicketUpdates streams matchmaking results from Open Match for the provided Ticket id.
rpc GetTicketUpdates(GetTicketUpdatesRequest) returns (stream GetTicketUpdatesResponse) {
}
}

36
api/matchfunction.proto Normal file
View File

@ -0,0 +1,36 @@
// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = 'proto3';
package api;
option go_package = "internal/future/pb";
import 'api/messages.proto';
message RunRequest {
// The MatchProfile that describes the Match that this MatchFunction needs to generate proposals for.
messages.MatchProfile profile = 1;
}
message RunResponse {
// The proposal generated by this MatchFunction Run.
messages.Match proposal = 1;
}
// This proto defines the API for running Match Functions as long-lived, 'serving' functions.
service MatchFunction {
// This is the function that is executed when by the Open Match backend to generate Match proposals.
rpc Run(RunRequest) returns (stream RunResponse) {
}
}

121
api/messages.proto Normal file
View File

@ -0,0 +1,121 @@
// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = 'proto3';
package api;
option go_package = "internal/future/pb";
// A Ticket is a basic matchmaking entity in Open Match. In order to enter matchmaking using Open Match, the client
// should generate a Ticket, passing in the properties to be associated with this Ticket. Open Match will generate an
// id for a Ticket during creation. A Ticket could be used to represent an individual 'Player' or a 'Group' of players.
// Open Match will not interpret what the Ticket represents but just treat it as a matchmaking unit with a set of
// properties. Open Match stores the Ticket in state storage and enables an Assignment to be associated with this Ticket.
message Ticket {
// The Ticket id generated by Open Match.
string id = 1;
// JSON string for properties associated with this Ticket. A subset of these properties will be indexed based
// on the indexing configuration.
string properties = 2;
// Assignment associated with the Ticket.
Assignment assignment = 3;
}
// An Assignment object represents the assignment associated with a Ticket.
message Assignment {
// Connection information for this Assignment.
string connection = 1;
// Other details to be sent to the players. (Optional)
// Open Match does not interpret these properties.
string properties = 2;
// Error when finding an Assignment for this Ticket.
string error = 3;
}
// A hard filter used to query a subset of Tickets meeting the filtering criteria.
message Filter {
// Name of the ticket attribute this Filter operates on.
string attribute = 1;
// Maximum value. Defaults to positive infinity (any value above minv).
double max = 2;
// Minimum value. Defaults to 0.
double min = 3;
}
message Pool {
// A developer-chosen human-readable name for this Pool.
string name = 1;
// Set of Filters indicating the filtering criteria. Selected players must match every Filter.
repeated Filter filter = 2;
}
// A Roster is a named collection of Ticket ids. It exists so that a Tickets associated with a Match can
// be labelled to belong to a team, sub-team etc. It can also be used to represent the current state of
// a Match in scenarios such as backfill, join-in-progress etc.
message Roster {
// A developer-chosen human-readable name for this Roster.
string name = 1;
// Tickets belonging to this Roster.
repeated string ticket_id = 2;
}
// A MatchProfile is Open Match's representation of a Match specification. It is used to indicate the criteria
// for selecting players for a match. A MatchProfile is the input to the API to get matches and is passed to
// the MatchFunction. It contains all the information required by the MatchFunction to generate match proposals.
message MatchProfile {
// Name of this match profile.
string name = 1;
// Set of properties associated with this MatchProfile. (Optional)
// Open Match does not interpret these properties but passes them through to the MatchFunction.
string properties = 2;
// Set of pools to be queried when generating a match for this MatchProfile.
// The pool names can be used in empty Rosters to specify composition of a match.
repeated Pool pool = 3;
// Set of Rosters for this match request. Could be empty Rosters used to indicate the composition of the
// generated Match or they could be partially pre-populated Ticket list to be used in scenarios such as
// backfill / join in progress.
repeated Roster roster = 4;
}
// A Match is used to represent a completed match object. It can be generated by a MatchFunction as a proposal
// or can be returned by OpenMatch as a result in response to the GetMatches call.
message Match{
// A Match ID that should be passed through the stack for tracing.
string match_id = 1;
// Name of the match profile that generated this Match.
string match_profile = 2;
// Name of the match function that generated this Match.
string match_function = 3;
// Tickets belonging to this match.
repeated Ticket ticket = 4;
// Set of Rosters that comprise this Match
repeated Roster roster = 5;
// Match properties for this Match. Open Match does not interpret this field.
string properties = 6;
}

38
api/mmlogic.proto Normal file
View File

@ -0,0 +1,38 @@
// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = 'proto3';
package api;
option go_package = "internal/future/pb";
import 'api/messages.proto';
message RetrievePoolRequest{
// The Pool representing the set of Filters to be queried.
messages.Pool pool = 1;
}
message RetrievePoolResponse{
// The Tickets that meet the Filter criteria requested by the Pool.
repeated messages.Ticket ticket = 1;
}
// The MMLogic API provides utility functions for common MMF functionality such as retreiving Tickets
// from state storage.
service MmLogic {
// RetrievePool gets the list of Tickets that match every Filter in the specified Pool.
rpc RetrievePool(RetrievePoolRequest) returns (stream RetrievePoolResponse) {
}
}