feat: scope credit grant idempotency key to customer

The credit grant idempotency key was unique per (namespace, key), so two
different customers in the same namespace could not reuse the same key
even though grant creation and key lookup are both customer-scoped.
Re-scope the partial unique index to (namespace, customer_id, key) and
document the scope on the API field. Loosening the constraint cannot
fail on existing data: any rows violating the new index would have
violated the old one.

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));