mmlogic.proto

syntax = 'proto3';
package api;
option go_package = "github.com/GoogleCloudPlatform/open-match/internal/pb";

// The protobuf messages sent in the gRPC calls are defined 'messages.proto'.
import 'api/protobuf-spec/messages.proto';

// The MMLogic API provides utility functions for common MMF functionality, such
// as retreiving profiles and players from state storage, writing results to state storage,
// and exposing metrics and statistics.
service MmLogic {
  // Profile and match object functions

  //  Send GetProfile a match object with the ID field populated, it will return a
  //  'filled' one.
  //  Note: filters are assumed to have been checked for validity by the
  //  backendapi  when accepting a profile
  rpc GetProfile(messages.MatchObject) returns (messages.MatchObject) {}

  // CreateProposal is called by MMFs that wish to write their results to
  // a proposed MatchObject, that can be sent out the Backend API once it has
  // been approved (by default, by the evaluator process).
  //  - adds all players in all Rosters to the proposed player ignore list
  //  - writes the proposed match to the provided key
  //  - adds that key to the list of proposals to be considered
  // INPUT: 
  //  * TO RETURN A MATCHOBJECT AFTER A SUCCESSFUL MMF RUN
  //    To create a match MatchObject message with these fields populated:
  //      - id, set to the value of the MMF_PROPOSAL_ID env var
  //      - properties
  //      - error.  You must explicitly set this to an empty string if your MMF
  //      - roster, with the playerIDs filled in the 'players' repeated field. 
  //      - [optional] pools, set to the output from the 'GetPlayerPools' call,
  //        will populate the pools with stats about how many players the filters
  //        matched and how long the filters took to run, which will be sent out
  //        the backend api along with your match results.
  //        was successful.
  //  * TO RETURN AN ERROR 
  //    To report a failure or error, send a MatchObject message with these
  //    these fields populated:
  //      - id, set to the value of the MMF_ERROR_ID env var. 
  //      - error, set to a string value describing the error your MMF encountered.
  //      - [optional] properties, anything you put here is returned to the
  //        backend along with your error.
  //      - [optional] rosters, anything you put here is returned to the
  //        backend along with your error.
  //      - [optional] pools, set to the output from the 'GetPlayerPools' call,
  //        will populate the pools with stats about how many players the filters
  //        matched and how long the filters took to run, which will be sent out
  //        the backend api along with your match results.
  // OUTPUT: a Result message with a boolean success value and an error string
  // if an error was encountered
  rpc CreateProposal(messages.MatchObject) returns (messages.Result) {}

  // Player listing and filtering functions
  //
  // RetrievePlayerPool gets the list of players that match every Filter in the
  // PlayerPool, .excluding players in any configured ignore lists.  It
  // combines the results, and returns the resulting player pool.
  rpc GetPlayerPool(messages.PlayerPool) returns (stream messages.PlayerPool) {}

  // Ignore List functions
  //
  // IlInput is an empty message reserved for future use.
  rpc GetAllIgnoredPlayers(messages.IlInput) returns (messages.Roster) {}
  // ListIgnoredPlayers retrieves players from the ignore list specified in the
  // config file under 'ignoreLists.proposed.name'.
  rpc ListIgnoredPlayers(messages.IlInput) returns (messages.Roster) {}

  // NYI
  // UpdateMetrics sends stats about the MMF run to export to a metrics aggregation tool 
  // like Prometheus or StackDriver.
  // rpc UpdateMetrics(messages.NYI) returns (messages.Results) {}
}