Advanced reservation requests

When reserving a payload, a list of payload selectors can be set to control which payloads can get reserved.

Each payload selector can

• specify a list of labels which need to exist on the payload to be reserved
• specify a payload state to filter for only payloads of that state. Can be either Ready (default) or Reserved. Reserved can be used to find a payload that's already reserved, e.g. for back-filling.

Only one payload will get reserved in any request, even when multiple may match the selectors.

Selectors will be considered in order. If no payloads are found that match one selector, the next selector in the list is tried next. If none of the selectors match a payload, a 412 Precondition Failed is returned.

By default, when no payload selectors are set in the request, any of the Ready payloads in the allocation can be reserved.

Example:

With the following selectors, a Ready payload with label map: a will be reserved (if available). If no payload exists with that label, the reservation falls back to the second selector, which in this case matches any Ready payload:

{
  "selectors": [
    {
      "match_labels": {
        "map": "a"
      }
    },
    {
      "match_labels": []
    }
  ]
}

Back-filling example:

The below selectors will first attempt to return an already reserved payload that needs back-filling (i.e. a payload that has set its needs-backfill label set to true), and falls back to reserving a Ready payload if there's no payload that requires back-filling.

In the same request, it also sets the needs-backfill label to false, to ensure this payload will only get returned in one reservation request. The payload can at a later point re-enable the backfill label if it needs more players using the Payload Local API SetLabelV0 method.

{
  "selectors": [
    {
      "match_labels": {
        "needs-backfill": "true"
      },
      "payload_state": "Reserved"
    },
    {
      "payload_state": "Ready"
    }
  ],
  "payload_metadata": {
    "labels": {
      "needs-backfill": "false"
    }
  }
}