Integrasi API generative AI, khususnya image generation (seperti Flux, Stable Diffusion, atau Midjourney API wrapper), memiliki latensi pemrosesan tinggi (3 hingga 30 detik) dan biaya komputasi GPU yang mahal per panggilan. Masalah umum muncul ketika AI agent atau client network gateway menerapkan kebijakan automatic retry saat menghadapi timeout HTTP transient. Tanpa penanganan idempotensi, request retry akan diproses sebagai tugas inferensi baru yang menduplikasi pengurangan kuota (double billing) dan membebani resource inference node.

Anatomi Masalah: AI Agent Retries dan Race Conditions

Saat AI agent atau client HTTP memanggil endpoint generasi visual, latensi pipeline model sering kali melampaui timeout lokal client (misalnya 5000 ms). Urutan kegagalan standar:

  1. Client mengirim request generate gambar. Backend mulai mengurangi kredit dan menjadwalkan GPU task.
  2. Koneksi terputus di level gateway sebelum inferensi selesai. Client menerima error 504 Gateway Timeout.
  3. Middleware AI agent secara otomatis mengirim request ulang dengan prompt dan seed yang persis sama.
  4. Backend yang naif memproses request kedua sebagai transaksi terpisah: kredit dipotong dua kali, dua inferensi identik dijalankan.

Solusi standar industri untuk masalah ini adalah mewajibkan header Idempotency-Key (UUID v4) dari client, dikombinasikan dengan fingerprint payload untuk mendeteksi perubahan parameter.

Arsitektur Idempotency State Machine

Mekanisme proteksi membutuhkan penyimpanan status sementara yang cepat dan atomic. Redis adalah pilihan optimal menggunakan pola state berikut:

  • Locking / Pending: Mengunci key dengan TTL terukur saat proses generate berjalan.
  • Completed: Menyimpan respons final (URL CDN gambar, token usage, metadata) selama rentang waktu tertentu (misal: 24 jam).
  • Conflict Handling: Mengembalikan error 409 Conflict jika key yang sama dikirim bersamaan dengan payload berbeda, atau jika eksekusi sebelumnya masih berstatus pending.
State Flow:
Request Masuk -> Cek Key di Redis
  |-- Tidak Ada -> Set atomic NX 'PENDING' -> Jalankan Inferensi GPU -> Simpan 'COMPLETED' (Hasil) -> Return 200
  |-- Ada (Status PENDING) -> Return 409 Conflict (Proses sedang berjalan)
  |-- Ada (Status COMPLETED) -> Verifikasi Fingerprint
        |-- Fingerprint Cocok -> Return Cached Response (HTTP 200) tanpa memotong saldo
        |-- Fingerprint Beda -> Return 422 / 409 Unprocessable Entity

Implementasi Idempotency Middleware

Berikut adalah implementasi middleware API menggunakan Node.js, Express, dan modul Redis standar (menggunakan command atomic SET NX EX).

import crypto from 'node:crypto';
import type { Request, Response, NextFunction } from 'express';
import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL || 'redis://localhost:6379');

interface IdempotencyRecord {
  status: 'PENDING' | 'COMPLETED';
  fingerprint: string;
  statusCode?: number;
  body?: any;
}

export function generatePayloadFingerprint(body: Record<string, any>): string {
  // Ambil hanya parameter penentu komputasi visual
  const normalized = {
    prompt: body.prompt?.trim(),
    negative_prompt: body.negative_prompt?.trim() || '',
    aspect_ratio: body.aspect_ratio || '1:1',
    seed: body.seed ?? null,
    model: body.model
  };
  return crypto.createHash('sha256').update(JSON.stringify(normalized)).digest('hex');
}

export async function idempotencyMiddleware(req: Request, res: Response, next: NextFunction) {
  const idempotencyKey = req.header('Idempotency-Key');
  if (!idempotencyKey) {
    return res.status(400).json({ error: 'Missing Idempotency-Key header' });
  }

  const redisKey = `idempotency:${idempotencyKey}`;
  const currentFingerprint = generatePayloadFingerprint(req.body);

  try {
    const existing = await redis.get(redisKey);

    if (existing) {
      const record: IdempotencyRecord = JSON.parse(existing);

      if (record.fingerprint !== currentFingerprint) {
        return res.status(409).json({
          error: 'Idempotency-Key reuse with altered payload parameters'
        });
      }

      if (record.status === 'PENDING') {
        return res.status(409).json({
          error: 'A request with this key is currently being processed'
        });
      }

      if (record.status === 'COMPLETED') {
        res.setHeader('X-Cache-Lookup', 'HIT-IDEMPOTENT');
        return res.status(record.statusCode || 200).json(record.body);
      }
    }

    // Set status PENDING dengan TTL 60 detik (atomic lock)
    const acquired = await redis.set(
      redisKey,
      JSON.stringify({ status: 'PENDING', fingerprint: currentFingerprint }),
      'EX', 60,
      'NX'
    );

    if (!acquired) {
      return res.status(409).json({ error: 'Concurrent request detected' });
    }

    // Intercept res.json untuk menyimpan output final
    const originalJson = res.json.bind(res);
    res.json = (body: any) => {
      if (res.statusCode >= 200 && res.statusCode < 300) {
        const completedRecord: IdempotencyRecord = {
          status: 'COMPLETED',
          fingerprint: currentFingerprint,
          statusCode: res.statusCode,
          body
        };
        // Simpan hasil selama 24 jam (86400 detik)
        redis.set(redisKey, JSON.stringify(completedRecord), 'EX', 86400).catch(console.error);
      } else {
        // Hapus lock jika pipeline gagal agar client bisa mencoba ulang
        redis.del(redisKey).catch(console.error);
      }
      return originalJson(body);
    };

    next();
  } catch (err) {
    next(err);
  }
}

Unit Testing Integrasi dan Edge Cases

Pengujian harus memverifikasi tiga skenario kritis: eksekusi pertama berhasil, eksekusi ulang menghasilkan data cache tanpa eksekusi worker GPU ganda, dan payload yang diubah memicu conflict error.

import { describe, it, expect, beforeEach } from 'vitest';
import request from 'supertest';
import express from 'express';
import { idempotencyMiddleware } from './middleware';
import { redis } from './redis';

const app = express();
app.use(express.json());

let billingDeductionCount = 0;

app.post('/v1/images/generations', idempotencyMiddleware, (req, res) => {
  billingDeductionCount += 1;
  return res.status(200).json({
    asset_url: 'https://cdn.example.com/outputs/img_123.webp',
    credits_deducted: 4
  });
});

describe('Image Gen Idempotency Integration', () => {
  beforeEach(async () => {
    await redis.flushall();
    billingDeductionCount = 0;
  });

  it('hanya memotong kuota satu kali untuk request berulang', async () => {
    const key = 'req_test_abc123';
    const payload = { prompt: 'cyberpunk warrior portrait', aspect_ratio: '16:9', seed: 42 };

    // Request pertama: Fresh execution
    const res1 = await request(app)
      .post('/v1/images/generations')
      .set('Idempotency-Key', key)
      .send(payload);

    expect(res1.status).toBe(200);
    expect(billingDeductionCount).toBe(1);

    // Request kedua (retry): Harus HIT cache
    const res2 = await request(app)
      .post('/v1/images/generations')
      .set('Idempotency-Key', key)
      .send(payload);

    expect(res2.status).toBe(200);
    expect(res2.headers['x-cache-lookup']).toBe('HIT-IDEMPOTENT');
    expect(res2.body.asset_url).toBe(res1.body.asset_url);
    expect(billingDeductionCount).toBe(1); // Kuota tidak terpotong lagi
  });

  it('mengembalikan 409 jika parameter diubah memakai key yang sama', async () => {
    const key = 'req_test_fixed';
    
    await request(app)
      .post('/v1/images/generations')
      .set('Idempotency-Key', key)
      .send({ prompt: 'cat wearing glasses' });

    const conflictRes = await request(app)
      .post('/v1/images/generations')
      .set('Idempotency-Key', key)
      .send({ prompt: 'dog wearing glasses' });

    expect(conflictRes.status).toBe(409);
    expect(conflictRes.body.error).toContain('altered payload parameters');
  });
});

Trade-offs: Redis vs PostgreSQL

Dalam skala produksi, pemilihan penyimpanan status idempotency bergantung pada konsistensi transaksi data keuangan:

  • Redis: Ideal untuk API berlatensi rendah dengan volume request tinggi. Operasi SET NX sangat cepat (<1 ms). Kelemahannya, jika Redis restart tanpa persistensi AOF yang ketat, data lock berpotensi hilang.
  • PostgreSQL (Tabel Idempotency): Tepat digunakan jika pemotongan saldo pengguna berada di DB relasional dalam blok BEGIN...COMMIT. Menggunakan constraint UNIQUE (idempotency_key, user_id) memberikan jaminan ACID mutlak, namun menambah beban I/O pada database utama.

Rekomendasi arsitektur: Gunakan Redis untuk menangani caching respons dan lock inferensi jangka pendek (TTL 60-120 detik), tetapi pastikan fungsi pemotongan balance internal tetap dilindungi atomic lock pada layer database akun pengguna.