[norman-abramovitz]

Summary

CF v3 lifecycle operations (DELETE, scale, start/stop/restart) are async: CF responds 202 Accepted with an empty body and a Location header pointing at /v3/jobs/{jobGuid}. The current capi clients call HTTP and return only error, throwing the Location header (and therefore the job GUID) on the floor. Callers that need to poll for completion can't.

This PR retrofits 6+ resource clients to the existing (*Job, error) shape that OrganizationsClient.Delete and SpacesClient.Delete already use — no new pattern, just consistency.

The pattern (review once, applies to every commit)

The fix is identical at every callsite:

// Before
func (c *FooClient) Delete(ctx context.Context, guid string) error {
    _, err := c.httpClient.Delete(ctx, "/v3/foos/"+guid)
    if err != nil {
        return fmt.Errorf("deleting foo: %w", err)
    }
    return nil
}

// After
func (c *FooClient) Delete(ctx context.Context, guid string) (*capi.Job, error) {
    resp, err := c.httpClient.Delete(ctx, "/v3/foos/"+guid)
    if err != nil {
        return nil, fmt.Errorf("deleting foo: %w", err)
    }
    location := resp.Headers.Get("Location")
    if location == "" {
        return nil, fmt.Errorf("deleting foo: no Location header on async response")
    }
    jobGUID := location
    if idx := strings.LastIndex(location, "/"); idx >= 0 {
        jobGUID = location[idx+1:]
    }
    if jobGUID == "" {
        return nil, fmt.Errorf("deleting foo: malformed Location header %q", location)
    }
    return &capi.Job{Resource: capi.Resource{GUID: jobGUID}}, nil
}

Reviewing commit 1 (Apps.Delete) is sufficient context for commits 2–7 — the rest mechanically apply the same change to different resources. Each commit message confirms it.

Commits

#	Resource	Change
1	Apps.Delete	error → (*Job, error) from Location
2	Routes.Delete + ServiceCredentialBindings.Delete	Same. Previous impl json.Unmarshal'd the empty body into Job and silently produced Job{GUID:""} — callers polling the empty GUID got 404s. SCB is polymorphic: user-provided returns 204 (sync, nil job), managed returns 202+Location.
3	Apps.Start/Stop/Restart/Restage	error → (*Job, error)
4	Processes.Scale	error → (*Job, error)
5	Apps/Processes sync-complete fallback	Some older CFs (< ~3.190) return 200/204 with no Location for some endpoints. Treat that as a sync-complete and return (nil, nil) instead of a hard error on missing Location.
6	Remove fabricated Apps.Restage	The standalone Restage method didn't correspond to any CF v3 endpoint. CF v3 has no atomic restage — it's a composition of package lookup → build → set-droplet → stop → start. Removing the fabrication; callers should compose explicitly.
7	Roles.Delete	error → (*Job, error)

Verification

• CF v3 API spec — Location-header contract for delete action across /v3/apps/{guid}, /v3/routes/{guid}, /v3/service_credential_bindings/{guid}, /v3/roles/{guid}. All four documented to return 202 + Location → /v3/jobs/{jobGuid}.
• cloud_controller_ng source — destroy actions emit head :accepted, 'Location' => … directly.
• Validated end-to-end against a real CF 3.180 deployment.

Breaking changes

Yes — the public interfaces change signature (error → (*Job, error)). Existing callers that ignore async completion need to update their code:

// Before
err := client.Apps().Delete(ctx, guid)

// After (caller can ignore the job if they don't need it)
_, err := client.Apps().Delete(ctx, guid)

This is parallel to the way OrganizationsClient.Delete and SpacesClient.Delete already work — they return (*Job, error) today. Bringing the rest of v3 in line.

Tests

Each commit adds:

• A "happy path" test asserting the returned Job.GUID matches the Location-header GUID
• A "missing Location" regression that asserts an error rather than Job{GUID: ""}
• For the sync-fallback commit, a test exercising 200/204 with no Location

Full suite green.

Out of scope (separate PR)

A second PR (#3, feat-link-meta) adds an optional Meta map[string]interface{} field to capi.Link. Independent change; either PR can land first.

[wayneeseguin]

Great idea, thank you for this!