Expose capability checks for YAML REST tests

[mosche]

This PR adds support to check capabilities both in the skip and requires section on YAML REST tests.

See here for an example:

"Capabilities API":

  - requires:
      capabilities:
        - method: GET
          path: /_capabilities
          parameters: [method, path, parameters, capabilities]
          capabilities: []
      reason: "capabilities api requires itself to be supported"

  - do:
      capabilities:
        method: GET
        path: /_capabilities
        parameters: method,path,parameters,capabilities
        error_trace: false

  - match: { supported: true }

[elasticsearchmachine]

Pinging @elastic/es-core-infra (Team:Core/Infra)

[mosche]

:rest-api-spec:validateRestSpec returns an error for capabilities.json, apparently I skipped over some required fields.

[thecoop]

I've added an unknown response to a capabilities query, indicating the cluster can't determine if something is supported or not - eg its a mixed-cluster and one of the nodes doesn't support _capabilities, or there's an error communicating with a node.

That does mean that the response can be either a string or a boolean - not great. The alternatives are:

• Return an HTTP error 503 if we get a failure from a node
• Use a tri-state value true false null
• Add an extra field indicating if the result can be computed properly "available": true, "supported": false. This might be a bit confusing.

We also need to consider what clients will do if a node temporarily goes unavailable, resulting in all capability queries returning null/unknown as it can't get a response off a node to check its capabilities.

[thecoop]

Decision - return null when some nodes are unresponsive. We should also return false if any nodes do not support _capabilities at all

[mosche]

Thanks @thecoop , the changes are looking good to me 💯
How do you want to proceed?

[thecoop]

I've changed this to use null for unknown, which gets all these tests passing. Making it return false when some nodes don't support capabilities (with tests) can be a separate PR.

[thecoop]

I'm happy with this, @mosche merge if you are