search

aip-dev / google.aip.dev

API Improvement Proposals. https://aip.dev/
Other
1.1k stars 500 forks source link

Compute / Flatten / Lookup Effective Method #69

Open lukesneeringer opened 5 years ago

lukesneeringer commented 5 years ago

From @jgeewax:

We've had a few different teams have an idea of different customization applied in a hierarchy that is then flatted to be evaluated. We need a standard method that covers this use case so that we all do it the same.

Let's assume we have some sort of Config resource that can apply to any resource, as well as orgs, projects, and folders. We want a way of saying "What config applies to my GCE VM (my-instance)?"

First, what do we call the method? Options:

  • LookupEffectiveConfig
  • CalculateEffectiveConfig
  • ComputeEffectiveConfig
  • GetEffectiveConfig
  • FlattenConfig
  • ResolveEffectiveConfig

Second, we need to decide the order in which to apply the hierarchy ( at least for GCP).

I think this would be Org -> Folder -> Project -> Resource, right?

lukesneeringer commented 5 years ago

From another employee internally (I do not know the person, so not naming them publicly):

Which order to apply the hierarchy may need to be defined on a per-policy-type basis. It might be valuable to decouple the naming of the method from the evaluation rules.

lukesneeringer commented 5 years ago

From another employee internally:

My 2 cents on the overall question - for calls like this that are effectively gathering, filtering, and squashing data I think Lookup- or LookupEffective- are clearer than Calculate- or Compute- which imply that there will be some deeper change between the inputs and outputs. Resolve- makes me think either of conflicts (due to too many years working with source control) or ending something, bringing it to resolution.Flatten- is a possibility but I don't think it captures the essence of retrieving data from disparate sources as well as Lookup does nor do I find it as clear.

garrettjonesgoogle commented 5 years ago

Result of discussion with @lukesneeringer :

Given that:

we should use Get in the name. Using a different term feels like a distinction without a useful difference.

In order to have some kind of distinction of the use case, using Effective in the name makes sense.

Additionally, there are use cases for list support for effective values. For that, ListEffective is the best choice by analogy.

@lukesneeringer can confirm if this matches his understanding of our conversation.

If so, we should draft an AIP.

lukesneeringer commented 5 years ago

Yes, that matches my understanding.

EDIT: With the possible exception that I could see a case for using a different verb if it is expensive to figure out the value. (If it is going to take ten minutes and we bill you $5 to do it, ComputeEffective might be better. I have no idea if anyone will ever hit that in practice and the AIP could likely ignore the possibility.)