feat(gcp): current region methods

[prefanatic]

This PR implements methods to retrieve the region in which the current cloud instance is running. Structurally, these methods are analogous to projectId supporting methods, found within gcp/lib/src/gcp_project.dart

Usage of these new methods follow a similar pattern:

final computedRegion = await computeRegion();
print(computedRegion);
...
// Outputs: us-central1

final environmentRegion = regionFromEnvironment();
print(environmentRegion);
...
// Outputs: us-central1

Practically, these new methods are copy-pastes, substituting projectId with region. In my original proposal within #392, I perhaps erroneously utilized location rather than region. After combing through some GCP documentation, it looks like region is perhaps the more widely utilized term?

I am looking for additional feedback on the code documentation for these methods. Most of the documentation from gcp_project.dart was brought forward, with some subjective edits to represent instance & region vs. project Ids.

Regarding the metadata server, I linked to instance metadata to provide further documentation on what these instance endpoints provide, however, I was unable to find v1/instance/region within this public documentation. Is this particular endpoint not documented there for a reason?

I tried combing through search to find various environment variables that currently exist, that could represent the instance's region. I was only successful in finding two discretely populated variables. If there are more, I would like to add them in to add some redundancy in the same way the projectId is evaluated.

Finally, in regards to unit tests, I brought forward the same pattern used to test computeProjectId. This includes the TODO comment regarding stubs for the metadata server under test.

Closes #392

[kevmoo]

@prefanatic – it seems like CLOUDSDK_COMPUTE_REGION and FUNCTION_REGION

Do you just want some utilities to access metadata? Do you have a case where you want to overload the function region locally?

I don't want to over design this!

[prefanatic]

@prefanatic – it seems like CLOUDSDK_COMPUTE_REGION and FUNCTION_REGION

Do you just want some utilities to access metadata? Do you have a case where you want to overload the function region locally?

I don't want to over design this!

Typically my use case for running locally, not on GCP, revolves around ensuring my environment is set up appropriately with the environment variables these methods would be first looking for. I then just assume the metadata access "just works" when it's inside GCP.

In terms of "utilities to access metadata" and over designing in general - I suppose the answer lies in how easily mapped metadata endpoints are to this enhanced enum approach? I don't have sufficient context over what this service offers. We'd also assume in this case that many, or all, metadata endpoints have associated environment variables.