feat: add support for get augmented

[schoren]

This PR adds support for augmented entities. This is a feature needed, for example, in transactions. We have 2 "representations" of transactions: the one used in files, which looks like this:

type: Transaction
spec:
  id: transactionID
  name: some feature
  description: do stuff in sequence
  steps:
    - testID_1
    - testID_2

it contains just the information needed to create/update the transaction, and just a test ID to reference the step tests.

We also have another representation used in the API, that looks like this: (redacted)

{
  "id": "_2yuIhL4g",
  "name": "01- Transaction",
  "version": 1,
  "steps": [
    {
      "id": "XK1UI2L4R",
      "name": "01- Pokeshop - List",
      "description": "Get a Pokemon",
      // the rest of the test
    },
    {
      "id": "K74lShYVR",
      "name": "02 - Pokeshop - Add",
      "description": "Add a Pokemon",
      // the rest of the test
    }
  ],
  "createdAt": "2023-04-06T14:30:19.354747Z",
  "summary": {
    "runs": 2,
    "lastRun": {
      "time": "2023-04-06T14:31:00.770013Z",
      "fails": 3
    }
  }
}

With this PR, we allow resources to define "base" fields and "augmented" fields. In this example, the transaction base fields would be:

• id
• name
• description
• testIDs

And then the augmented fields would be:

• tests
• createdAt
• summary

The "augmented" version is the sum of base and augmented fields.

The augmented version is requested by passing the X-Tracettest-Augmented: true header. It works on Get and List.

Since augmentation can be expensive in tems of DB querying, the ResourceManager allows resource handlers to specify methods to deal with augmented requests (GetAugmented and ListAugmented).

The resource struct can define the "augmented" fields just by making them optional. Like:

type Transaction struct{
  // this is a "base" fields, because it's not optional
  ID id.ID `mapstructure:"id"`

  // this field is augmented because it's optional (because omitempty is enabled
  Summary Summary `mapstructure:"summary,omitempty"`
}

Checklist

• tested locally
• added new dependencies
• updated the docs
• added a test

[xoscar]

My only concern about this is the usage of a header instead of a query parameter, is there anything specifically why we would prefer one instead of the other?

[schoren]

@xoscar My thinking is that this is a content modifier, so I think of it as content negotiation, like when requesting json vs yaml. I don't feel SUPER strong about using a header, but I think it keeps URLs clean and related to the data itself rather than the representation.

So, my thinking is: url query params: filters and other data modifiers; headers: content format negotiation.

Does that make sense?

[xoscar]

Makes sense, let's move forward with this