feat(client): Add support for impersonation. (#724)

A new 'impersonation' package provides a function which can be used to
construct a context.Context object containing a Fastly CID. If that
context is passed to any of go-fastly's API functions which generate
HTTP requests to the Fastly API endpoint, the contained CID will be
included in the request.

As noted in the package documentation, impersonation is only available
to Fastly employees, it is not usable by customers.

 All Submissions:

* [X] Have you followed the guidelines in our Contributing document?
* [X] Have you checked to ensure there aren't other open [Pull
Requests](https://github.com/fastly/go-fastly/pulls) for the same
update/change?

<!-- You can erase any parts of this template not applicable to your
Pull Request. -->

### New Feature Submissions:

* [X] Does your submission pass tests?

### Changes to Core Features:

* [X] Have you added an explanation of what your changes do and why
you'd like us to include them?
* [X] Have you written new tests for your core changes, as applicable?
* [X] Have you successfully run tests with your changes locally?

Author: kpfleming

CHANGELOG.md

@@ -8,6 +8,8 @@
 
 ### Enhancements:
 
+- feat(client): Add support for impersonation. [#724](https://github.com/fastly/go-fastly/pull/724)
+
 ### Bug fixes:
 
 ### Dependencies:
@@ -29,6 +31,7 @@
 - feat(ngwaf/v1/signals): moves signals up to the base level and adds support for account level signals ([#722](https://github.com/fastly/go-fastly/pull/722))
 
 ### Enhancements:
+
 - feat(ngwaf): add support for alerts ([#714](https://github.com/fastly/go-fastly/pull/714))
 - feat(ngwaf/v1/workspaces/thresholds): adds CRUD support for NGWAF Thresholds ([#713](https://github.com/fastly/go-fastly/pull/713))
 - feat(tls_custom_certificate): Add support for allow_untrusted_root attribute ([#596](https://github.com/fastly/go-fastly/pull/596))
@@ -38,6 +41,7 @@
 - fix(client): Implement new mechanism for serializing mutating requests. ([#715](https://github.com/fastly/go-fastly/pull/715))
 
 ### Dependencies:
+
 - build(deps): `golang.org/x/crypto` from 0.39.0 to 0.40.0 ([#720](https://github.com/fastly/go-fastly/pull/720))
 - build(deps): `golang.org/x/sys` from 0.33.0 to 0.34.0 ([#720](https://github.com/fastly/go-fastly/pull/720))
 

fastly/client.go

@@ -23,6 +23,8 @@ import (
 	"github.com/google/jsonapi"
 	"github.com/hashicorp/go-cleanhttp"
 	"github.com/mitchellh/mapstructure"
+
+	"github.com/fastly/go-fastly/v11/fastly/impersonation"
 )
 
 // APIKeyEnvVar is the name of the environment variable where the Fastly API
@@ -313,6 +315,10 @@ func (c *Client) DeleteJSONAPIBulk(ctx context.Context, p string, i any, ro Requ
 // Request makes an HTTP request against the HTTPClient using the given verb,
 // Path, and request options.
 func (c *Client) Request(ctx context.Context, verb, p string, ro RequestOptions) (*http.Response, error) {
+	if id, ok := impersonation.CustomerIDFromContext(ctx); ok {
+		ro.Params[impersonation.QueryParam] = id
+	}
+
 	req, err := c.RawRequest(ctx, verb, p, ro)
 	if err != nil {
 		return nil, err

fastly/client_test.go

@@ -6,6 +6,10 @@ import (
 	"net/url"
 	"strings"
 	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/fastly/go-fastly/v11/fastly/impersonation"
 )
 
 func TestClient_RawRequest(t *testing.T) {
@@ -55,3 +59,31 @@ func TestClient_RawRequest(t *testing.T) {
 		}
 	}
 }
+
+type impersonationRoundTripper struct {
+	rawQuery string
+}
+
+func (irt *impersonationRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	irt.rawQuery = req.URL.RawQuery
+	return &http.Response{StatusCode: http.StatusOK}, nil
+}
+
+func TestClient_Impersonation(t *testing.T) {
+	const testCustomerID = "1234ABCD"
+
+	require := require.New(t)
+	t.Parallel()
+
+	c, err := NewClient("nokey")
+	require.NoError(err)
+
+	irt := &impersonationRoundTripper{}
+	ro := CreateRequestOptions()
+	c.HTTPClient = &http.Client{Transport: irt}
+
+	_, err = c.Request(impersonation.NewContextForCustomerID(context.TODO(), testCustomerID), http.MethodGet, "/test", ro)
+	require.NoError(err)
+
+	require.Equal(impersonation.QueryParam+"="+testCustomerID, irt.rawQuery, "unexpected query parameter")
+}

fastly/impersonation/doc.go

@@ -0,0 +1,8 @@
+// Package impersonation provides a method for using a
+// [context.Context] object to provide a Fastly CID that will be used
+// for API requests made using the context. This method is used by
+// Fastlyans to issue API requests 'on behalf of' (impersonating) a
+// Fastly customer.
+//
+// Note: This impersonation mechanism is only usable by Fastly employees.
+package impersonation

fastly/impersonation/impersonation.go

@@ -0,0 +1,31 @@
+package impersonation
+
+import (
+	"context"
+)
+
+const QueryParam = "customer_id"
+
+type impersonationKey struct{}
+
+var key impersonationKey
+
+// NewContextForCustomerID returns a [context.Context] which contains
+// the customer ID specified in the id parameter.
+//
+// This [context.Context] should be passed to the various request
+// methods of [fastly.Client] so that those request methods can use
+// the included customer ID to impersonate the customer when the
+// request is made.
+func NewContextForCustomerID(ctx context.Context, id string) context.Context {
+	return context.WithValue(ctx, key, id)
+}
+
+// CustomerIDFromContext returns the customer ID contained within the
+// provided [context.Context]. If the provided [context.Context] does
+// not contain a customer ID, then `false` is returned along with an
+// empty string.
+func CustomerIDFromContext(ctx context.Context) (string, bool) {
+	id, ok := ctx.Value(key).(string)
+	return id, ok
+}

fastly/purge.go

@@ -5,6 +5,8 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+
+	"github.com/fastly/go-fastly/v11/fastly/impersonation"
 )
 
 // Purge is a response from a purge request.
@@ -44,6 +46,10 @@ func (c *Client) Purge(ctx context.Context, i *PurgeInput) (*Purge, error) {
 		return nil, err
 	}
 
+	if id, ok := impersonation.CustomerIDFromContext(ctx); ok {
+		requestOptions.Params[impersonation.QueryParam] = id
+	}
+
 	resp, err := c.Post(ctx, "purge/"+i.URL, requestOptions)
 	if err != nil {
 		return nil, err
@@ -99,6 +105,10 @@ func (c *Client) PurgeKey(ctx context.Context, i *PurgeKeyInput) (*Purge, error)
 	requestOptions := CreateRequestOptions()
 	requestOptions.Parallel = true
 
+	if id, ok := impersonation.CustomerIDFromContext(ctx); ok {
+		requestOptions.Params[impersonation.QueryParam] = id
+	}
+
 	req, err := c.RawRequest(ctx, http.MethodPost, path, requestOptions)
 	if err != nil {
 		return nil, err
@@ -145,6 +155,10 @@ func (c *Client) PurgeKeys(ctx context.Context, i *PurgeKeysInput) (map[string]s
 	requestOptions := CreateRequestOptions()
 	requestOptions.Parallel = true
 
+	if id, ok := impersonation.CustomerIDFromContext(ctx); ok {
+		requestOptions.Params[impersonation.QueryParam] = id
+	}
+
 	req, err := c.RawRequest(ctx, http.MethodPost, path, requestOptions)
 	if err != nil {
 		return nil, err
@@ -183,7 +197,12 @@ func (c *Client) PurgeAll(ctx context.Context, i *PurgeAllInput) (*Purge, error)
 
 	path := ToSafeURL("service", i.ServiceID, "purge_all")
 
-	req, err := c.RawRequest(ctx, http.MethodPost, path, CreateRequestOptions())
+	requestOptions := CreateRequestOptions()
+	if id, ok := impersonation.CustomerIDFromContext(ctx); ok {
+		requestOptions.Params[impersonation.QueryParam] = id
+	}
+
+	req, err := c.RawRequest(ctx, http.MethodPost, path, requestOptions)
 	if err != nil {
 		return nil, err
 	}

fastly/resource_locking.go

@@ -20,8 +20,8 @@ type ResourceLockManager struct {
 	locks map[string]weak.Pointer[sync.Mutex]
 }
 
-// NewResourceLockManager creates constructs a [ResourceLockManager]
-// with an empty map.
+// NewResourceLockManager constructs a [ResourceLockManager] with an
+// empty map.
 func NewResourceLockManager() *ResourceLockManager {
 	return &ResourceLockManager{
 		locks: make(map[string]weak.Pointer[sync.Mutex]),