refactor(connectivity): private_link returns Value, should return TaskStateUpdate (14 methods + VPC/TGW deletes)

[joshrotenberg]

Summary

The entire private_link module returns Result<serde_json::Value> on 14 methods where the spec promises TaskStateUpdate. Additionally, vpc_peering and transit_gateway deletes return Value::Null (response body discarded) when the spec returns a Task. Cuts callers off from polling the resulting async operation.

Expected behavior

Every connectivity endpoint that the spec marks as task-returning (i.e. has a taskId in the response) should return the canonical TaskStateUpdate so callers can poll /tasks/{taskId} to completion.

Actual behavior

• src/connectivity/private_link.rs:325-625 — 14 typed methods (get_private_link, create_private_link, delete_private_link, update_private_link, add_principal, remove_principal, get_endpoint_script, disassociate_connections, plus the active-active variants and PSC service variants) all return Result<Value>.
• src/connectivity/transit_gateway.rs:189,325 — TGW deletes return Result<Value> and discard the body (Value::Null).
• src/connectivity/vpc_peering.rs — VPC peering deletes have the same shape.

The spec lists TaskStateUpdate as the response on each of these.

Impact

Callers cannot use the typed handlers to track async operations on connectivity. They must drop to client.get_raw("/tasks/{id}") themselves and reconstruct the polling loop. Inconsistent with the rest of the crate, which already returns TaskStateUpdate for similar mutating operations on databases/subscriptions.

Relevant code

• src/connectivity/private_link.rs:325-625 (14 methods)
• src/connectivity/transit_gateway.rs:189,325
• src/connectivity/vpc_peering.rs (delete handlers)

Suggested fix

Change the return type from Result<Value> to Result<TaskStateUpdate> (using the canonical type from #64). For deletes, send the delete_with_body request and deserialize the response.

This is best done after — or as part of — #64 so we don't migrate Value→Value-typed-as-TaskStateUpdate→canonical-TaskStateUpdate in two passes.

Acceptance criteria

• All 14 private_link methods return Result<TaskStateUpdate> (or the canonical type from refactor(types): consolidate shared task/tag/link models and normalize task status typing #64)
• VPC peering and TGW deletes return Result<TaskStateUpdate>, body is parsed (no more Value::Null)
• Mock tests assert each method round-trips a TaskStateUpdate
• If breaking-change, migration note in CHANGELOG

References

• Surfaced in 2026-05 review (axis A1 — coverage fidelity)
• Related: refactor(types): consolidate shared task/tag/link models and normalize task status typing #64 (canonical task types), fix(request): send request body when deleting AA subscription regions #59 (AA region delete body)

[joshrotenberg]

Investigation note — spec dependency identified, work paused

Started this and stopped on review. Findings:

1. Main's bundled OpenAPI spec does NOT contain any /private-link paths. Only /private-service-connect is in tests/fixtures/cloud_openapi.json on main. The 14 Result<Value> handlers on main are calling routes that aren't documented in this spec.

2. The refreshed spec on codex/refresh-pass (PR Refresh pass quick wins #71, DRAFT) does contain the routes, and it DOES document each as 202 Accepted returning TaskStateUpdate — confirming the original issue's premise.

3. The existing wiremock tests on main contradict the spec: they mount resource-shape responses (resourceId, status, shareName, principals, script) and assert on those fields via result["..."]. Either the tests were written speculatively without consulting the spec, or the live API actually returns those resource shapes today (and the refreshed spec is forward-looking).

Without a live cluster verification, ripping out the existing tests in favor of TaskStateUpdate mocks risks shipping wrong typing — we'd be picking a side without evidence.

Recommended path

Block this issue on one of:

• PR Refresh pass quick wins #71 lands first (or its spec refresh is cherry-picked), so we're working against the documented spec
• Live validation against a real Cloud account confirms whether GET/POST/DELETE /private-link/* actually return TaskStateUpdate or the resource shapes the current tests claim

Once one of those happens, the work is straightforward: 11 methods on main + 2 new methods that #71 adds, plus updating the 9 existing tests. Will pick this up after the dependency clears.