feat: add support for run task results callback

[karvounis-form3]

Description

This PR aims to address the missing support for Run Tasks Integration API. I have already raised an issue #862 about this.
It introduces the following:

• RunTaskRequest struct which can be used to objectify the request you get from a TFC/E run task
• RunTasksCallback interface which can be used to update the run task with status and messages
  • TaskResultsCallbackOptions defines the attributes required in order to perform the update

Testing plan

Unfortunately, it is not easy to test the Update function because you first need a running server which listens for incoming TFC/E requests. Then, you need a workspace run which is configured to use that run task endpoint.

External links

https://github.com/hashicorp/terraform-run-task-scaffolding-go this HashiCorp repo contains part of the code that can be found here.

[sebasslash]

Awesome, thanks for submitting this PR & sorry for the delay in reviewing. Some things to chew on in the meantime ⬇️

[sebasslash]

Would like to understand this more, along with the IsEndpointValidation check. Is the intent to ensure r.RunID is a valid run external ID (in the format of RunTaskRegistrationRunID)? As I read it, IsEndpointValidation will only return true if r.RunID == "run-xxxxxxxxxxxx" which should never be the case.

If we do want to ensure that it's in proper external ID format, use the helper validStringID()

[karvounis-form3]

When you create a run task, you are asked to provide an Endpoint URL. TFE sends a payload to it to make sure that it is a valid endpoint (have not found any relevant docs on this).

I got that function from the same function that is used by HashiCorp in the scaffolding repo. There, the IsEndpointValidation function checks against the token of the TFE request payload which will be test-token only when you first create the run task.

This is the payload from the above TFE request:

{
  "access_token": "test-token",
  "capabilities": {
    "outcomes": true
  },
  "configuration_version_download_url": ".../api/v2/configuration-versions/cv-xxxxxxxxxxxxxxxx/download",
  "configuration_version_id": "cv-xxxxxxxxxxxxxxxx",
  "is_speculative": false,
  "organization_name": "test-org",
  "payload_version": 1,
  "plan_json_api_url": ".../api/v2/runs/plan-xxxxxxxxxxxxxxxx/plan/json-output",
  "run_app_url": ".../app/test-org/test-workspace/runs/run-xxxxxxxxxxxxxxxx",
  "run_created_at": "2021-01-01T00:00:00.000Z",
  "run_created_by": "test-user",
  "run_id": "run-xxxxxxxxxxxxxxxx",
  "run_message": "Test run message",
  "stage": "test",
  "task_result_callback_url": ".../api/v2/task-results/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/callback",
  "task_result_enforcement_level": "test",
  "task_result_id": "taskrs-xxxxxxxxxxxxxxxx",
  "vcs_branch": null,
  "vcs_commit_url": null,
  "vcs_pull_request_url": null,
  "vcs_repo_url": null,
  "workspace_app_url": "...",
  "workspace_id": "ws-xxxxxxxxxxxxxxxx",
  "workspace_name": "test-workspace",
  "workspace_working_directory": ""
}

I can change the boolean check to check the token instead of the run ID as shown in the hashicorp/terraform-run-task-scaffolding-go repo.

[karvounis-form3]

I changed the validation to using the test token that TFC/E sends to register the endpoint as a run task. Let me know what you think

[sebasslash]

So the implementation look great ✅ However I do think we ought to add some unit tests around this behavior, particularly ensuring that things are being serialized correctly (TaskResultTag gives me some pause given mix-&-matching of json/jsonapi struct tags).

Writing a true integration test would not be plausible here, as it would require the test function to expose a publicly available server.

What sort of unit tests might be possible here?

• Test for validation errors, scenarios that would result in ErrInvalidTaskResultsCallbackStatus, ErrInvalidCallbackURL, ErrInvalidAccessToken and ErrInvalidTaskResultsCallbackType.
• Ensure the Authorization header is set to the correct token provided in the request sent from TFC. In the test function, you can spin up an httptest.Server, define an endpoint that validates the header is the correct token, and set that endpoint URL to TaskResultCallbackURL in a mocked RunTaskRequest.
• Ensure TaskResultTag is serialized correctly.

Last thing, make sure you define the server in helper_test.go. An example signature can be:

func runTaskCallbackMockServer(t *testing.T) *httptest.Server {}

Once you've added tests, make sure to run them locally and add the test output to the PR description. CI won't fire given this is a fork's branch, so once everything is a-ok I will rebase this PR onto a local branch to trigger CI.

[sebasslash]

Move these above the Update() call for visibility. The style ordering for a file is:

1. Interface definition
2. Struct definitions
3. Receiver method implementations.