feat: scope credit grant idempotency key to customer (#4716)

Author: tothandras

api/spec/packages/aip-client-javascript/src/models/types.ts

@@ -3429,8 +3429,9 @@ export interface CreateCreditGrantRequest {
   /**
    * Idempotency key for the credit grant creation request.
    *
-   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
-   * creating a duplicate grant, which makes create requests safe to retry.
+   * Unique per customer: reusing the same key for the same customer returns an HTTP
+   * 409 Conflict instead of creating a duplicate grant, which makes create requests
+   * safe to retry. The same key may be reused across different customers.
    */
   key?: string
 }
@@ -3493,8 +3494,9 @@ export interface CreditGrant {
   /**
    * Idempotency key for the credit grant creation request.
    *
-   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
-   * creating a duplicate grant, which makes create requests safe to retry.
+   * Unique per customer: reusing the same key for the same customer returns an HTTP
+   * 409 Conflict instead of creating a duplicate grant, which makes create requests
+   * safe to retry. The same key may be reused across different customers.
    */
   key?: string
   /**
@@ -5944,8 +5946,9 @@ export interface CreateCreditGrantRequestInput {
   /**
    * Idempotency key for the credit grant creation request.
    *
-   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
-   * creating a duplicate grant, which makes create requests safe to retry.
+   * Unique per customer: reusing the same key for the same customer returns an HTTP
+   * 409 Conflict instead of creating a duplicate grant, which makes create requests
+   * safe to retry. The same key may be reused across different customers.
    */
   key?: string
 }
@@ -6008,8 +6011,9 @@ export interface CreditGrantInput {
   /**
    * Idempotency key for the credit grant creation request.
    *
-   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
-   * creating a duplicate grant, which makes create requests safe to retry.
+   * Unique per customer: reusing the same key for the same customer returns an HTTP
+   * 409 Conflict instead of creating a duplicate grant, which makes create requests
+   * safe to retry. The same key may be reused across different customers.
    */
   key?: string
   /**

api/spec/packages/aip/src/customers/credits/grant.tsp

@@ -209,8 +209,9 @@ model CreditGrant {
   /**
    * Idempotency key for the credit grant creation request.
    *
-   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
-   * creating a duplicate grant, which makes create requests safe to retry.
+   * Unique per customer: reusing the same key for the same customer returns an HTTP
+   * 409 Conflict instead of creating a duplicate grant, which makes create requests
+   * safe to retry. The same key may be reused across different customers.
    */
   @visibility(Lifecycle.Read, Lifecycle.Create)
   key?: Shared.ExternalResourceKey;

api/v3/api.gen.go

@@ -5440,8 +5440,9 @@ components:
           description: |-
             Idempotency key for the credit grant creation request.
 
-            When provided, reusing the same key returns an HTTP 409 Conflict instead of
-            creating a duplicate grant, which makes create requests safe to retry.
+            Unique per customer: reusing the same key for the same customer returns an HTTP
+            409 Conflict instead of creating a duplicate grant, which makes create requests
+            safe to retry. The same key may be reused across different customers.
         expires_at:
           allOf:
             - $ref: '#/components/schemas/DateTime'
@@ -9432,8 +9433,9 @@ components:
           description: |-
             Idempotency key for the credit grant creation request.
 
-            When provided, reusing the same key returns an HTTP 409 Conflict instead of
-            creating a duplicate grant, which makes create requests safe to retry.
+            Unique per customer: reusing the same key for the same customer returns an HTTP
+            409 Conflict instead of creating a duplicate grant, which makes create requests
+            safe to retry. The same key may be reused across different customers.
       additionalProperties: false
       description: CreditGrant create request.
     CreateCreditGrantTaxConfig:

api/v3/client/models_customers.go

@@ -134,14 +134,18 @@ func TestV3CreateCreditGrantIdempotencyKey(t *testing.T) {
 		c.requireStatus(http.StatusCreated, err)
 	})
 
-	t.Run("the same key conflicts across different customers in a namespace", func(t *testing.T) {
+	t.Run("the same key is allowed across different customers", func(t *testing.T) {
 		key := ulid.Make().String()
 
-		_, err := c.Customers.Credits.Grants.Create(t.Context(), createCustomer("credit_grant_idem_cust_a"), grant(&key))
+		grantA, err := c.Customers.Credits.Grants.Create(t.Context(), createCustomer("credit_grant_idem_cust_a"), grant(&key))
 		c.requireStatus(http.StatusCreated, err)
+		require.NotNil(t, grantA)
 
-		_, err = c.Customers.Credits.Grants.Create(t.Context(), createCustomer("credit_grant_idem_cust_b"), grant(&key))
-		requireProblem(t, err, http.StatusConflict)
+		grantB, err := c.Customers.Credits.Grants.Create(t.Context(), createCustomer("credit_grant_idem_cust_b"), grant(&key))
+		c.requireStatus(http.StatusCreated, err)
+		require.NotNil(t, grantB)
+
+		require.NotEqual(t, grantA.ID, grantB.ID)
 	})
 
 	t.Run("an over-length key is rejected with 400", func(t *testing.T) {
@@ -331,8 +335,8 @@ func TestV3VoidCreditGrantPaymentAdjustmentNone(t *testing.T) {
 
 // TestV3CreditGrantKeyReadAndFilter verifies that the idempotency key is exposed
 // on the get/list read responses and that list credit grants can be filtered by
-// key. The key column carries a unique partial index per namespace, so an
-// equality filter targets at most one grant.
+// key. The key column carries a unique partial index per namespace and customer,
+// so a customer-scoped equality filter targets at most one grant.
 func TestV3CreditGrantKeyReadAndFilter(t *testing.T) {
 	c := newV3Client(t)
 	currency := v3sdk.BillingCurrencyCode("USD")

api/v3/openapi.yaml

@@ -125,10 +125,10 @@ func (ChargeCreditPurchase) Indexes() []ent.Index {
 	return []ent.Index{
 		index.Fields("tax_code_id").
 			StorageKey("chargecreditpurchases_tax_code_id"),
-		// Idempotency key, unique per namespace. Partial so it is enforced only while live:
-		// NULL means no idempotency requested, and a soft-deleted grant must not permanently
-		// reserve a key the caller may reuse.
-		index.Fields("namespace", "key").
+		// Idempotency key, unique per customer within a namespace. Partial so it is enforced
+		// only while live: NULL means no idempotency requested, and a soft-deleted grant must
+		// not permanently reserve a key the caller may reuse.
+		index.Fields("namespace", "customer_id", "key").
 			Annotations(
 				entsql.IndexWhere("key IS NOT NULL AND deleted_at IS NULL"),
 			).

e2e/customer_credits_v3_test.go

@@ -0,0 +1,4 @@
+-- reverse: create index "chargecreditpurchase_namespace_customer_id_key" to table: "charge_credit_purchases"
+DROP INDEX "chargecreditpurchase_namespace_customer_id_key";
+-- reverse: drop index "chargecreditpurchase_namespace_key" from table: "charge_credit_purchases"
+CREATE UNIQUE INDEX "chargecreditpurchase_namespace_key" ON "charge_credit_purchases" ("namespace", "key") WHERE ((key IS NOT NULL) AND (deleted_at IS NULL));

openmeter/ent/db/migrate/schema.go

@@ -0,0 +1,7 @@
+-- drop index "chargecreditpurchase_namespace_key" from table: "charge_credit_purchases"
+DROP INDEX "chargecreditpurchase_namespace_key";
+-- create index "chargecreditpurchase_namespace_customer_id_key" to table: "charge_credit_purchases"
+-- the old (namespace, key) unique index guarantees no (namespace, customer_id, key) duplicates exist,
+-- so widening the key scope cannot fail on existing data
+-- atlas:nolint MF101
+CREATE UNIQUE INDEX "chargecreditpurchase_namespace_customer_id_key" ON "charge_credit_purchases" ("namespace", "customer_id", "key") WHERE ((key IS NOT NULL) AND (deleted_at IS NULL));