From 6a59d690a63f2ade8048a83e42af833fc146665a Mon Sep 17 00:00:00 2001 From: kemurayama <7068107+kemurayama@users.noreply.github.com> Date: Thu, 18 Jan 2024 12:21:20 +0900 Subject: [PATCH] Release 1.8 into main (#305) * Release 1.8.0-rc.1 (#301) * Latest autogen docs for 1.8 * Release v1.8.0-rc.1 * Bump versions for 1.8.0-rc.1, fix typos from issue/297 * Release 1.8 (#303) * Latest autogen docs for 1.8 * Release v1.8.0-rc.1 * Bump versions for 1.8.0-rc.1, fix typos from issue/297 * remove rc from release 1.8 --------- Co-authored-by: Joseph Holley --- Makefile | 2 +- cloudbuild.yaml | 2 +- site/config.toml | 4 +- site/content/en/docs/Installation/helm.md | 15 +- site/content/en/docs/Installation/yaml.md | 18 +- site/content/en/docs/Reference/api.md | 1198 +++++++++++++++++++++ site/static/swaggerui/config.json | 14 +- 7 files changed, 1221 insertions(+), 32 deletions(-) diff --git a/Makefile b/Makefile index 5a72a3d7..96b22c82 100644 --- a/Makefile +++ b/Makefile @@ -24,7 +24,7 @@ # If you want information on how to edit this file checkout, # http://makefiletutorial.com/ -BASE_VERSION = 1.7.0 +BASE_VERSION = 1.8.0 SHORT_SHA = $(shell git rev-parse --short=7 HEAD | tr -d [:punct:]) VERSION_SUFFIX = $(SHORT_SHA) BRANCH_NAME = $(shell git rev-parse --abbrev-ref HEAD | tr -d [:punct:]) diff --git a/cloudbuild.yaml b/cloudbuild.yaml index f5deefcf..989f6cf8 100644 --- a/cloudbuild.yaml +++ b/cloudbuild.yaml @@ -113,7 +113,7 @@ steps: path: '/go' substitutions: - _OM_VERSION: "1.7.0" + _OM_VERSION: "1.8.0" _GCB_POST_SUBMIT: "0" _GCB_LATEST_VERSION: "undefined" logsBucket: 'gs://open-match-site-build-logs/' diff --git a/site/config.toml b/site/config.toml index 2e226493..5c5395e3 100644 --- a/site/config.toml +++ b/site/config.toml @@ -74,7 +74,7 @@ github_docs_repo = "https://github.com/googleforgames/open-match-docs" gcs_engine_id = "008748710159674449076:sqoelpnrdoe" release_branch = "main" -release_version = "1.7.0" +release_version = "1.8.0" slack_link = "https://join.slack.com/t/open-match/shared_invite/enQtNDM1NjcxNTY4MTgzLTM5ZWQxNjc1YWI3MzJmN2RiMWJmYWI0ZjFiNzNkZmNkMWQ3YWU5OGVkNzA5Yzc4OGVkOGU5MTc0OTA5ZTA5NDU" # Enable syntax highlighting and copy buttons on code blocks with Prism @@ -126,4 +126,4 @@ expiryDate = ["expiryDate"] [markup] [markup.goldmark] [markup.goldmark.renderer] - unsafe = true \ No newline at end of file + unsafe = true diff --git a/site/content/en/docs/Installation/helm.md b/site/content/en/docs/Installation/helm.md index 54621d1e..e9420ea7 100644 --- a/site/content/en/docs/Installation/helm.md +++ b/site/content/en/docs/Installation/helm.md @@ -8,8 +8,8 @@ description: > ## Prerequisites -- [Helm](https://docs.helm.sh/helm/) package manager 3.0.0+ -- [Kubernetes](https://kubernetes.io) cluster, tested on Kubernetes version 1.13+ +- [Helm](https://docs.helm.sh/helm/) package manager, tested on version 3.12.3+ +- [Kubernetes](https://kubernetes.io) cluster, tested on Kubernetes version 1.27+ ## Install the Open Match helm chart @@ -91,11 +91,10 @@ Specify each parameter using the `--set key=value[,key=value]` argument to `helm ```bash helm install --name open-match --namespace open-match open-match/open-match \ - --set open-match-telemetry.enabled=true \ - --set open-match-telemetry.jaeger.enabled=true + --set open-match-telemetry.enabled=true ``` -The above command sets the namespace where Open Match is deployed to `open-match`. Additionally turn on the telemetry exporters and deploy Jaeger along with Open Match core services. +The above command sets the namespace where Open Match is deployed to `open-match`, and turns on the telemetry exporters along with installing Open Match core services. The following tables lists the configurable parameters of the Open Match chart and their default values. @@ -114,7 +113,6 @@ The following tables lists the configurable parameters of the Open Match chart a | `open-match-core.proposalCollectionInterval` | Length of time after match function has started before it will be canceled. | `20s` | | `open-match-core.pendingReleaseTimeout` | Defines the time before a ticket returns to the pool after it was fetched. | `1m` | | `open-match-core.assignedDeleteTimeout` | Time after a ticket has been assigned before it is automatically deleted. | `10m` | -| `open-match-core.queryPageSize` | Maximum number of tickets to return on a single QueryTicketsResponse. | `10000` | | `open-match-core.backfillLockTimeout` | Defines the time of keeping a lock on a single backfill. | `1m` | | `open-match-override.enabled` | Turn on/off the installation of `om-override-configmap` | `false` | | `open-match-telemetry.enabled` | Turn on/off the installation of Open Match telemetry services | `false` | @@ -127,10 +125,6 @@ The following tables lists the configurable parameters of the Open Match chart a | `global.tls.rootca.mountPath` | The VolumeMount path for TLS CA | `/app/secrets/tls/rootca` | | `global.logging.rpc.enabled` | Turn on/off RPC payload logging for all Open Match core services | `false` | | `global.telemetry.zpages.enabled` | Turn on/off Open Match zPages instrument. | `true` | -| `global.telemetry.jaeger.enabled` | Turn on/off Open Match Jaeger exporter. Also install Jaeger if `open-match-telemetry.enabled` is set to true | `false` | -| `global.telemetry.jaeger.samplerFraction` | Configure a sampler that samples a given fraction of traces | `1` | -| `global.telemetry.jaeger.agentEndpoint` | AgentEndpoint instructs exporter to send spans to jaeger-agent at this address | `open-match-jaeger-agent:6831` | -| `global.telemetry.jaeger.collectorEndpoint` | CollectorEndpoint is the full url to the Jaeger HTTP Thrift collector | `open-match-jaeger-collector:14268/api/traces` | | `global.telemetry.prometheus.enabled` | Turn on/off Open Match Prometheus exporter. Also install Prometheus if `open-match-telemetry.enabled` is set to true | `false` | | `global.telemetry.prometheus.endpoint` | Bind the Prometheus exporters to the specified endpoint handler, also configures the `prometheus.io/path` k8s scraping annotations | `/metrics` | | `global.telemetry.prometheus.serviceDiscovery` | If Prometheus is enabled and `serviceDiscover: true`, add the Prometheus scraping annotations to each Pod of the Open Match core services | `true` | @@ -139,7 +133,6 @@ The following tables lists the configurable parameters of the Open Match chart a | `global.telemetry.grafana.enabled` | Turn on/off Open Match Grafana exporter. Also install Grafana if `open-match-telemetry.enabled` is set to true | `false` | | `global.telemetry.reportingPeriod` | Overrides the reporting periods of Open Match telemetry exporters | `1m` | | `open-match-telemetry.grafana` | Inherits the values from [Grafana helm chart](https://github.com/helm/charts/tree/master/stable/grafana) | | -| `open-match-telemetry.jaeger` | Inherits the values from [Jaeger helm chart](https://github.com/helm/charts/tree/master/incubator/jaeger) | | | `open-match-telemetry.prometheus` | Inherits the values from [Prometheus helm chart](https://github.com/helm/charts/tree/master/stable/prometheus) | | | `redis` | Inherits the values from the [Bitnami Redis Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/redis) | | diff --git a/site/content/en/docs/Installation/yaml.md b/site/content/en/docs/Installation/yaml.md index 0ec4d267..fcaa0c74 100644 --- a/site/content/en/docs/Installation/yaml.md +++ b/site/content/en/docs/Installation/yaml.md @@ -8,7 +8,7 @@ description: > ## Prerequisites -- [Kubernetes](https://kubernetes.io) cluster, tested on Kubernetes version 1.13+ +- [Kubernetes](https://kubernetes.io) cluster, tested on Kubernetes version 1.27+ ## Install Core Open Match @@ -18,7 +18,6 @@ The `01-open-match-core.yaml` contains: * Core Open Match service deployments. * A Redis deployment as Open Match's state storage system. -* ServiceAccounts, Roles, and RoleBindings to define Open Match deployments' IAMs. * HorizontalAutoScalars to auto-scale Open Match based on pods' average CPU utilization. Here is the command to install the Open Match core in your cluster: @@ -40,18 +39,18 @@ kubectl get -n open-match pod ``` Output: -NAME READY STATUS RESTARTS AGE -om-backend-76d8d76c96-fmhmn 0/1 ContainerCreating 0 3m53s -om-frontend-57fc9f6b66-86hxj 0/1 ContainerCreating 0 3m53s -om-query-799d8549d4-5qpgx 0/1 ContainerCreating 0 3m53s -om-swaggerui-867d79b885-m9q6x 0/1 ContainerCreating 0 3m54s -om-synchronizer-7f48f84dfd-j8swx 0/1 ContainerCreating 0 3m54s +NAME READY STATUS RESTARTS AGE +open-match-backend-76d8d76c96-fmhmn 0/1 ContainerCreating 0 3m53s +open-match-frontend-57fc9f6b66-86hxj 0/1 ContainerCreating 0 3m53s +open-match-query-799d8549d4-5qpgx 0/1 ContainerCreating 0 3m53s +open-match-swaggerui-867d79b885-m9q6x 0/1 ContainerCreating 0 3m54s +open-match-synchronizer-7f48f84dfd-j8swx 0/1 ContainerCreating 0 3m54s ``` {{% alert title="Note" color="info" %}} Open Match needs to be customized to run as a Matchmaker. This custom configuration is provided to the Open Match components via a ConfigMap -(om-configmap-override). +(open-match-configmap-override). Thus, starting the core service pods will remain in ContainerCreating until this config map is available. {{% /alert %}} @@ -75,7 +74,6 @@ kubectl apply --namespace open-match \ To delete Open Match and the corresponding sample components from this cluster, simply run: ```bash -kubectl delete psp,clusterrole,clusterrolebinding --selector=release=open-match kubectl delete namespace open-match ``` diff --git a/site/content/en/docs/Reference/api.md b/site/content/en/docs/Reference/api.md index 050a260b..1ec3263e 100644 --- a/site/content/en/docs/Reference/api.md +++ b/site/content/en/docs/Reference/api.md @@ -1161,6 +1161,1204 @@ still subject to possible change or removal. + + +### QueryService +The QueryService service implements helper APIs for Match Function to query Tickets from state storage. + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| QueryTickets | [QueryTicketsRequest](#openmatch-QueryTicketsRequest) | [QueryTicketsResponse](#openmatch-QueryTicketsResponse) stream | QueryTickets gets a list of Tickets that match all Filters of the input Pool. - If the Pool contains no Filters, QueryTickets will return all Tickets in the state storage. QueryTickets pages the Tickets by `queryPageSize` and stream back responses. - queryPageSize is default to 1000 if not set, and has a minimum of 10 and maximum of 10000. | +| QueryTicketIds | [QueryTicketIdsRequest](#openmatch-QueryTicketIdsRequest) | [QueryTicketIdsResponse](#openmatch-QueryTicketIdsResponse) stream | QueryTicketIds gets the list of TicketIDs that meet all the filtering criteria requested by the pool. - If the Pool contains no Filters, QueryTicketIds will return all TicketIDs in the state storage. QueryTicketIds pages the TicketIDs by `queryPageSize` and stream back responses. - queryPageSize is default to 1000 if not set, and has a minimum of 10 and maximum of 10000. | +| QueryBackfills | [QueryBackfillsRequest](#openmatch-QueryBackfillsRequest) | [QueryBackfillsResponse](#openmatch-QueryBackfillsResponse) stream | QueryBackfills gets a list of Backfills. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. | + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | +| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | +| double | | double | double | float | float64 | double | float | Float | +| float | | float | float | float | float32 | float | float | Float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | +| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) | + +--- +title: "Open Match API References" +linkTitle: "Open Match API References" +weight: 2 +description: + This document provides API references for Open Match services. +--- +# Protocol Documentation + + +## Table of Contents + +- [api/backend.proto](#api_backend-proto) + - [AssignTicketsRequest](#openmatch-AssignTicketsRequest) + - [AssignTicketsResponse](#openmatch-AssignTicketsResponse) + - [AssignmentFailure](#openmatch-AssignmentFailure) + - [AssignmentGroup](#openmatch-AssignmentGroup) + - [FetchMatchesRequest](#openmatch-FetchMatchesRequest) + - [FetchMatchesResponse](#openmatch-FetchMatchesResponse) + - [FunctionConfig](#openmatch-FunctionConfig) + - [ReleaseAllTicketsRequest](#openmatch-ReleaseAllTicketsRequest) + - [ReleaseAllTicketsResponse](#openmatch-ReleaseAllTicketsResponse) + - [ReleaseTicketsRequest](#openmatch-ReleaseTicketsRequest) + - [ReleaseTicketsResponse](#openmatch-ReleaseTicketsResponse) + + - [AssignmentFailure.Cause](#openmatch-AssignmentFailure-Cause) + - [FunctionConfig.Type](#openmatch-FunctionConfig-Type) + + - [BackendService](#openmatch-BackendService) + +- [api/evaluator.proto](#api_evaluator-proto) + - [EvaluateRequest](#openmatch-EvaluateRequest) + - [EvaluateResponse](#openmatch-EvaluateResponse) + + - [Evaluator](#openmatch-Evaluator) + +- [api/extensions.proto](#api_extensions-proto) + - [DefaultEvaluationCriteria](#openmatch-DefaultEvaluationCriteria) + +- [api/frontend.proto](#api_frontend-proto) + - [AcknowledgeBackfillRequest](#openmatch-AcknowledgeBackfillRequest) + - [AcknowledgeBackfillResponse](#openmatch-AcknowledgeBackfillResponse) + - [CreateBackfillRequest](#openmatch-CreateBackfillRequest) + - [CreateTicketRequest](#openmatch-CreateTicketRequest) + - [DeleteBackfillRequest](#openmatch-DeleteBackfillRequest) + - [DeleteTicketRequest](#openmatch-DeleteTicketRequest) + - [GetBackfillRequest](#openmatch-GetBackfillRequest) + - [GetTicketRequest](#openmatch-GetTicketRequest) + - [UpdateBackfillRequest](#openmatch-UpdateBackfillRequest) + - [WatchAssignmentsRequest](#openmatch-WatchAssignmentsRequest) + - [WatchAssignmentsResponse](#openmatch-WatchAssignmentsResponse) + + - [FrontendService](#openmatch-FrontendService) + +- [api/matchfunction.proto](#api_matchfunction-proto) + - [RunRequest](#openmatch-RunRequest) + - [RunResponse](#openmatch-RunResponse) + + - [MatchFunction](#openmatch-MatchFunction) + +- [api/messages.proto](#api_messages-proto) + - [Assignment](#openmatch-Assignment) + - [Assignment.ExtensionsEntry](#openmatch-Assignment-ExtensionsEntry) + - [Backfill](#openmatch-Backfill) + - [Backfill.ExtensionsEntry](#openmatch-Backfill-ExtensionsEntry) + - [Backfill.PersistentFieldEntry](#openmatch-Backfill-PersistentFieldEntry) + - [DoubleRangeFilter](#openmatch-DoubleRangeFilter) + - [Match](#openmatch-Match) + - [Match.ExtensionsEntry](#openmatch-Match-ExtensionsEntry) + - [MatchProfile](#openmatch-MatchProfile) + - [MatchProfile.ExtensionsEntry](#openmatch-MatchProfile-ExtensionsEntry) + - [Pool](#openmatch-Pool) + - [SearchFields](#openmatch-SearchFields) + - [SearchFields.DoubleArgsEntry](#openmatch-SearchFields-DoubleArgsEntry) + - [SearchFields.StringArgsEntry](#openmatch-SearchFields-StringArgsEntry) + - [StringEqualsFilter](#openmatch-StringEqualsFilter) + - [TagPresentFilter](#openmatch-TagPresentFilter) + - [Ticket](#openmatch-Ticket) + - [Ticket.ExtensionsEntry](#openmatch-Ticket-ExtensionsEntry) + - [Ticket.PersistentFieldEntry](#openmatch-Ticket-PersistentFieldEntry) + + - [DoubleRangeFilter.Exclude](#openmatch-DoubleRangeFilter-Exclude) + +- [api/query.proto](#api_query-proto) + - [QueryBackfillsRequest](#openmatch-QueryBackfillsRequest) + - [QueryBackfillsResponse](#openmatch-QueryBackfillsResponse) + - [QueryTicketIdsRequest](#openmatch-QueryTicketIdsRequest) + - [QueryTicketIdsResponse](#openmatch-QueryTicketIdsResponse) + - [QueryTicketsRequest](#openmatch-QueryTicketsRequest) + - [QueryTicketsResponse](#openmatch-QueryTicketsResponse) + + - [QueryService](#openmatch-QueryService) + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## api/backend.proto + + + + + +### AssignTicketsRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| assignments | [AssignmentGroup](#openmatch-AssignmentGroup) | repeated | Assignments is a list of assignment groups that contain assignment and the Tickets to which they should be applied. | + + + + + + + + +### AssignTicketsResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| failures | [AssignmentFailure](#openmatch-AssignmentFailure) | repeated | Failures is a list of all the Tickets that failed assignment along with the cause of failure. | + + + + + + + + +### AssignmentFailure +AssignmentFailure contains the id of the Ticket that failed the Assignment and the failure status. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ticket_id | [string](#string) | | | +| cause | [AssignmentFailure.Cause](#openmatch-AssignmentFailure-Cause) | | | + + + + + + + + +### AssignmentGroup +AssignmentGroup contains an Assignment and the Tickets to which it should be applied. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ticket_ids | [string](#string) | repeated | TicketIds is a list of strings representing Open Match generated Ids which apply to an Assignment. | +| assignment | [Assignment](#openmatch-Assignment) | | An Assignment specifies game connection related information to be associated with the TicketIds. | + + + + + + + + +### FetchMatchesRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| config | [FunctionConfig](#openmatch-FunctionConfig) | | A configuration for the MatchFunction server of this FetchMatches call. | +| profile | [MatchProfile](#openmatch-MatchProfile) | | A MatchProfile that will be sent to the MatchFunction server of this FetchMatches call. | + + + + + + + + +### FetchMatchesResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| match | [Match](#openmatch-Match) | | A Match generated by the user-defined MMF with the specified MatchProfiles. A valid Match response will contain at least one ticket. | + + + + + + + + +### FunctionConfig +FunctionConfig specifies a MMF address and client type for Backend to establish connections with the MMF + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| host | [string](#string) | | | +| port | [int32](#int32) | | | +| type | [FunctionConfig.Type](#openmatch-FunctionConfig-Type) | | | + + + + + + + + +### ReleaseAllTicketsRequest + + + + + + + + + +### ReleaseAllTicketsResponse + + + + + + + + + +### ReleaseTicketsRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ticket_ids | [string](#string) | repeated | TicketIds is a list of string representing Open Match generated Ids to be re-enabled for MMF querying because they are no longer awaiting assignment from a previous match result | + + + + + + + + +### ReleaseTicketsResponse + + + + + + + + + + + +### AssignmentFailure.Cause + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| UNKNOWN | 0 | | +| TICKET_NOT_FOUND | 1 | | + + + + + +### FunctionConfig.Type + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| GRPC | 0 | | +| REST | 1 | | + + + + + + + + + +### BackendService +The BackendService implements APIs to generate matches and handle ticket assignments. + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| FetchMatches | [FetchMatchesRequest](#openmatch-FetchMatchesRequest) | [FetchMatchesResponse](#openmatch-FetchMatchesResponse) stream | FetchMatches triggers a MatchFunction with the specified MatchProfile and returns a set of matches generated by the Match Making Function, and accepted by the evaluator. Tickets in matches returned by FetchMatches are moved from active to pending, and will not be returned by query. | +| AssignTickets | [AssignTicketsRequest](#openmatch-AssignTicketsRequest) | [AssignTicketsResponse](#openmatch-AssignTicketsResponse) | AssignTickets overwrites the Assignment field of the input TicketIds. | +| ReleaseTickets | [ReleaseTicketsRequest](#openmatch-ReleaseTicketsRequest) | [ReleaseTicketsResponse](#openmatch-ReleaseTicketsResponse) | ReleaseTickets moves tickets from the pending state, to the active state. This enables them to be returned by query, and find different matches. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. | +| ReleaseAllTickets | [ReleaseAllTicketsRequest](#openmatch-ReleaseAllTicketsRequest) | [ReleaseAllTicketsResponse](#openmatch-ReleaseAllTicketsResponse) | ReleaseAllTickets moves all tickets from the pending state, to the active state. This enables them to be returned by query, and find different matches. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. | + + + + + + +

Top

+ +## api/evaluator.proto + + + + + +### EvaluateRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| match | [Match](#openmatch-Match) | | A Matches proposed by the Match Function representing a candidate of the final results. | + + + + + + + + +### EvaluateResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| match_id | [string](#string) | | A Match ID representing a shortlisted match returned by the evaluator as the final result. | + + + + + + + + + + + + + + +### Evaluator +The Evaluator service implements APIs used to evaluate and shortlist matches proposed by MMFs. + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Evaluate | [EvaluateRequest](#openmatch-EvaluateRequest) stream | [EvaluateResponse](#openmatch-EvaluateResponse) stream | Evaluate evaluates a list of proposed matches based on quality, collision status, and etc, then shortlist the matches and returns the final results. | + + + + + + +

Top

+ +## api/extensions.proto + + + + + +### DefaultEvaluationCriteria +A DefaultEvaluationCriteria is used for a match's evaluation_input when using +the default evaluator. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| score | [double](#double) | | | + + + + + + + + + + + + + + + + +

Top

+ +## api/frontend.proto + + + + + +### AcknowledgeBackfillRequest +BETA FEATURE WARNING: This Request message is not finalized and still subject +to possible change or removal. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| backfill_id | [string](#string) | | An existing ID of Backfill to acknowledge. | +| assignment | [Assignment](#openmatch-Assignment) | | An updated Assignment of the requested Backfill. | + + + + + + + + +### 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 | + + + + + + + + +### CreateBackfillRequest +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) | | An empty Backfill object. | + + + + + + + + +### CreateTicketRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ticket | [Ticket](#openmatch-Ticket) | | A Ticket object with SearchFields defined. | + + + + + + + + +### DeleteBackfillRequest +BETA FEATURE WARNING: This Request message is not finalized and still subject +to possible change or removal. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| backfill_id | [string](#string) | | An existing ID of Backfill to delete. | + + + + + + + + +### DeleteTicketRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ticket_id | [string](#string) | | A TicketId of a generated Ticket to be deleted. | + + + + + + + + +### GetBackfillRequest +BETA FEATURE WARNING: This Request message is not finalized and still subject +to possible change or removal. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| backfill_id | [string](#string) | | An existing ID of Backfill to retrieve. | + + + + + + + + +### GetTicketRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ticket_id | [string](#string) | | A TicketId of a generated Ticket. | + + + + + + + + +### UpdateBackfillRequest +UpdateBackfillRequest - update searchFields, extensions and set assignment. + +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) | | A Backfill object with ID set and fields to update. | + + + + + + + + +### WatchAssignmentsRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ticket_id | [string](#string) | | A TicketId of a generated Ticket to get updates on. | + + + + + + + + +### WatchAssignmentsResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| assignment | [Assignment](#openmatch-Assignment) | | An updated Assignment of the requested Ticket. | + + + + + + + + + + + + + + +### FrontendService +The FrontendService implements APIs to manage and query status of a Tickets. + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| CreateTicket | [CreateTicketRequest](#openmatch-CreateTicketRequest) | [Ticket](#openmatch-Ticket) | CreateTicket assigns an unique TicketId to the input Ticket and record it in state storage. A ticket is considered as ready for matchmaking once it is created. - If a TicketId exists in a Ticket request, an auto-generated TicketId will override this field. - If SearchFields exist in a Ticket, CreateTicket will also index these fields such that one can query the ticket with query.QueryTickets function. | +| 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) | [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. | +| UpdateBackfill | [UpdateBackfillRequest](#openmatch-UpdateBackfillRequest) | [Backfill](#openmatch-Backfill) | UpdateBackfill updates search_fields and extensions for the backfill with the provided id. 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. | + + + + + + +

Top

+ +## api/matchfunction.proto + + + + + +### RunRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| profile | [MatchProfile](#openmatch-MatchProfile) | | A MatchProfile defines constraints of Tickets in a Match and shapes the Match proposed by the MatchFunction. | + + + + + + + + +### RunResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| proposal | [Match](#openmatch-Match) | | A Proposal represents a Match candidate that satifies the constraints defined in the input Profile. A valid Proposal response will contain at least one ticket. | + + + + + + + + + + + + + + +### MatchFunction +The MatchFunction service implements APIs to run user-defined matchmaking logics. + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Run | [RunRequest](#openmatch-RunRequest) | [RunResponse](#openmatch-RunResponse) stream | DO NOT CALL THIS FUNCTION MANUALLY. USE backend.FetchMatches INSTEAD. Run pulls Tickets that satisfy Profile constraints from QueryService, runs matchmaking logic against them, then constructs and streams back match candidates to the Backend service. | + + + + + + +

Top

+ +## api/messages.proto + + + + + +### Assignment +An Assignment represents a game server assignment associated with a Ticket. +Open Match does not require or inspect any fields on assignment. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| connection | [string](#string) | | Connection information for this Assignment. | +| extensions | [Assignment.ExtensionsEntry](#openmatch-Assignment-ExtensionsEntry) | repeated | Customized information not inspected by Open Match, to be used by the match making function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems. | + + + + + + + + +### Assignment.ExtensionsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [google.protobuf.Any](#google-protobuf-Any) | | | + + + + + + + + +### Backfill +Represents a backfill entity which is used to fill partially full matches. + +BETA FEATURE WARNING: This call and the associated Request and Response +messages are not finalized and still subject to possible change or removal. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | Id represents an auto-generated Id issued by Open Match. | +| search_fields | [SearchFields](#openmatch-SearchFields) | | Search fields are the fields which Open Match is aware of, and can be used when specifying filters. | +| extensions | [Backfill.ExtensionsEntry](#openmatch-Backfill-ExtensionsEntry) | repeated | Customized information not inspected by Open Match, to be used by the Match Function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems. | +| persistent_field | [Backfill.PersistentFieldEntry](#openmatch-Backfill-PersistentFieldEntry) | repeated | Customized information not inspected by Open Match, to be kept persistent throughout the life-cycle of a backfill. Optional, depending on the requirements of the connected systems. | +| create_time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Create time is the time the Ticket was created. It is populated by Open Match at the time of Ticket creation. | +| generation | [int64](#int64) | | Generation gets incremented on GameServers update operations. Prevents the MMF from overriding a newer version from the game server. Do NOT read or write to this field, it is for internal tracking, and changing the value will cause bugs. | + + + + + + + + +### Backfill.ExtensionsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [google.protobuf.Any](#google-protobuf-Any) | | | + + + + + + + + +### Backfill.PersistentFieldEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [google.protobuf.Any](#google-protobuf-Any) | | | + + + + + + + + +### DoubleRangeFilter +Filters numerical values to only those within a range. + double_arg: "foo" + max: 10 + min: 5 +matches: + {"foo": 5} + {"foo": 7.5} + {"foo": 10} +does not match: + {"foo": 4} + {"foo": 10.01} + {"foo": "7.5"} + {} + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| double_arg | [string](#string) | | Name of the ticket's search_fields.double_args this Filter operates on. | +| max | [double](#double) | | Maximum value. | +| min | [double](#double) | | Minimum value. | +| exclude | [DoubleRangeFilter.Exclude](#openmatch-DoubleRangeFilter-Exclude) | | Defines the bounds to apply when filtering tickets by their search_fields.double_args value. BETA FEATURE WARNING: This field and the associated values are not finalized and still subject to possible change or removal. | + + + + + + + + +### Match +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 FetchMatches call. +When a match is returned by the FetchMatches call, it should contain at least +one ticket to be considered as valid. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| match_id | [string](#string) | | A Match ID that should be passed through the stack for tracing. | +| match_profile | [string](#string) | | Name of the match profile that generated this Match. | +| match_function | [string](#string) | | Name of the match function that generated this Match. | +| tickets | [Ticket](#openmatch-Ticket) | repeated | Tickets belonging to this match. | +| extensions | [Match.ExtensionsEntry](#openmatch-Match-ExtensionsEntry) | repeated | Customized information not inspected by Open Match, to be used by the match making function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems. | +| backfill | [Backfill](#openmatch-Backfill) | | Backfill request which contains additional information to the match and contains an association to a GameServer. BETA FEATURE WARNING: This field is not finalized and still subject to possible change or removal. | +| allocate_gameserver | [bool](#bool) | | AllocateGameServer signalise Director that Backfill is new and it should allocate a GameServer, this Backfill would be assigned. BETA FEATURE WARNING: This field is not finalized and still subject to possible change or removal. | + + + + + + + + +### Match.ExtensionsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [google.protobuf.Any](#google-protobuf-Any) | | | + + + + + + + + +### MatchProfile +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. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | Name of this match profile. | +| pools | [Pool](#openmatch-Pool) | repeated | Set of pools to be queried when generating a match for this MatchProfile. | +| extensions | [MatchProfile.ExtensionsEntry](#openmatch-MatchProfile-ExtensionsEntry) | repeated | Customized information not inspected by Open Match, to be used by the match making function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems. | + + + + + + + + +### MatchProfile.ExtensionsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [google.protobuf.Any](#google-protobuf-Any) | | | + + + + + + + + +### Pool +Pool specfies a set of criteria that are used to select a subset of Tickets +that meet all the criteria. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | A developer-chosen human-readable name for this Pool. | +| double_range_filters | [DoubleRangeFilter](#openmatch-DoubleRangeFilter) | repeated | Set of Filters indicating the filtering criteria. Selected tickets must match every Filter. | +| string_equals_filters | [StringEqualsFilter](#openmatch-StringEqualsFilter) | repeated | | +| tag_present_filters | [TagPresentFilter](#openmatch-TagPresentFilter) | repeated | | +| created_before | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | If specified, only Tickets created before the specified time are selected. | +| created_after | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | If specified, only Tickets created after the specified time are selected. | + + + + + + + + +### SearchFields +Search fields are the fields which Open Match is aware of, and can be used +when specifying filters. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| double_args | [SearchFields.DoubleArgsEntry](#openmatch-SearchFields-DoubleArgsEntry) | repeated | Float arguments. Filterable on ranges. | +| string_args | [SearchFields.StringArgsEntry](#openmatch-SearchFields-StringArgsEntry) | repeated | String arguments. Filterable on equality. | +| tags | [string](#string) | repeated | Filterable on presence or absence of given value. | + + + + + + + + +### SearchFields.DoubleArgsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [double](#double) | | | + + + + + + + + +### SearchFields.StringArgsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | + + + + + + + + +### StringEqualsFilter +Filters strings exactly equaling a value. + string_arg: "foo" + value: "bar" +matches: + {"foo": "bar"} +does not match: + {"foo": "baz"} + {"bar": "foo"} + {} + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| string_arg | [string](#string) | | Name of the ticket's search_fields.string_args this Filter operates on. | +| value | [string](#string) | | | + + + + + + + + +### TagPresentFilter +Filters to the tag being present on the search_fields. + tag: "foo" +matches: + ["foo"] + ["bar","foo"] +does not match: + ["bar"] + [] + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| tag | [string](#string) | | | + + + + + + + + +### Ticket +A Ticket is a basic matchmaking entity in Open Match. A Ticket may represent +an individual 'Player', a 'Group' of players, or any other concepts unique to +your use case. Open Match will not interpret what the Ticket represents but +just treat it as a matchmaking unit with a set of SearchFields. Open Match +stores the Ticket in state storage and enables an Assignment to be set on the +Ticket. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | Id represents an auto-generated Id issued by Open Match. | +| assignment | [Assignment](#openmatch-Assignment) | | An Assignment represents a game server assignment associated with a Ticket, or whatever finalized matched state means for your use case. Open Match does not require or inspect any fields on Assignment. | +| search_fields | [SearchFields](#openmatch-SearchFields) | | Search fields are the fields which Open Match is aware of, and can be used when specifying filters. | +| extensions | [Ticket.ExtensionsEntry](#openmatch-Ticket-ExtensionsEntry) | repeated | Customized information not inspected by Open Match, to be used by the match making function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems. | +| persistent_field | [Ticket.PersistentFieldEntry](#openmatch-Ticket-PersistentFieldEntry) | repeated | Customized information not inspected by Open Match, to be kept persistent throughout the life-cycle of a ticket. Optional, depending on the requirements of the connected systems. | +| create_time | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | Create time is the time the Ticket was created. It is populated by Open Match at the time of Ticket creation. | + + + + + + + + +### Ticket.ExtensionsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [google.protobuf.Any](#google-protobuf-Any) | | | + + + + + + + + +### Ticket.PersistentFieldEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [google.protobuf.Any](#google-protobuf-Any) | | | + + + + + + + + + + +### DoubleRangeFilter.Exclude + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| NONE | 0 | No bounds should be excluded when evaluating the filter, i.e.: MIN <= x <= MAX | +| MIN | 1 | Only the minimum bound should be excluded when evaluating the filter, i.e.: MIN < x <= MAX | +| MAX | 2 | Only the maximum bound should be excluded when evaluating the filter, i.e.: MIN <= x < MAX | +| BOTH | 3 | Both bounds should be excluded when evaluating the filter, i.e.: MIN < x < MAX | + + + + + + + + + + + +

Top

+ +## api/query.proto + + + + + +### QueryBackfillsRequest +BETA FEATURE WARNING: This Request messages are not finalized and +still subject to possible change or removal. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| pool | [Pool](#openmatch-Pool) | | The Pool representing the set of Filters to be queried. | + + + + + + + + +### QueryBackfillsResponse +BETA FEATURE WARNING: This Request messages are not finalized and +still subject to possible change or removal. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| backfills | [Backfill](#openmatch-Backfill) | repeated | Backfills that meet all the filtering criteria requested by the pool. | + + + + + + + + +### QueryTicketIdsRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| pool | [Pool](#openmatch-Pool) | | The Pool representing the set of Filters to be queried. | + + + + + + + + +### QueryTicketIdsResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ids | [string](#string) | repeated | TicketIDs that meet all the filtering criteria requested by the pool. | + + + + + + + + +### QueryTicketsRequest + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| pool | [Pool](#openmatch-Pool) | | The Pool representing the set of Filters to be queried. | + + + + + + + + +### QueryTicketsResponse + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| tickets | [Ticket](#openmatch-Ticket) | repeated | Tickets that meet all the filtering criteria requested by the pool. | + + + + + + + + + + + + ### QueryService diff --git a/site/static/swaggerui/config.json b/site/static/swaggerui/config.json index 175b8578..781394c0 100644 --- a/site/static/swaggerui/config.json +++ b/site/static/swaggerui/config.json @@ -1,10 +1,10 @@ { "urls": [ - {"name": "Frontend", "url": "https://open-match.dev/api/v1.7.0/frontend.swagger.json"}, - {"name": "Backend", "url": "https://open-match.dev/api/v1.7.0/backend.swagger.json"}, - {"name": "Query", "url": "https://open-match.dev/api/v1.7.0/query.swagger.json"}, - {"name": "MatchFunction", "url": "https://open-match.dev/api/v1.7.0/matchfunction.swagger.json"}, - {"name": "Synchronizer", "url": "https://open-match.dev/api/v1.7.0/synchronizer.swagger.json"}, - {"name": "Evaluator", "url": "https://open-match.dev/api/v1.7.0/evaluator.swagger.json"} + {"name": "Frontend", "url": "https://open-match.dev/api/v1.8.0/frontend.swagger.json"}, + {"name": "Backend", "url": "https://open-match.dev/api/v1.8.0/backend.swagger.json"}, + {"name": "Query", "url": "https://open-match.dev/api/v1.8.0/query.swagger.json"}, + {"name": "MatchFunction", "url": "https://open-match.dev/api/v1.8.0/matchfunction.swagger.json"}, + {"name": "Synchronizer", "url": "https://open-match.dev/api/v1.8.0/synchronizer.swagger.json"}, + {"name": "Evaluator", "url": "https://open-match.dev/api/v1.8.0/evaluator.swagger.json"} ] -} \ No newline at end of file +}