fix(teams): prevent duplicate slug allocation under concurrent creation

Replace non-deterministic random suffix generation with sequential
numeric candidates (my-team → my-team-1 → my-team-2, capped at 10).
Wrap team creation in a bounded retry loop (5 attempts) so P2002
constraint violations from concurrent inserts trigger re-allocation
rather than surfacing as a 409. The database-level @unique constraint
on Team.slug remains the authoritative guard; application logic now
recovers gracefully when it fires.

Adds slug utility tests (createSlug, generateUniqueSlug determinism
and bounds) and team route tests for retry-on-race-condition and
retry-exhaustion paths.

Closes #499

Author: Ridanshi

apps/backend/src/__tests__/slug.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { createSlug, generateUniqueSlug } from '../utils/slug';
+
+describe('createSlug', () => {
+  it('lowercases and trims input', () => {
+    expect(createSlug('  Hello World  ')).toBe('hello-world');
+  });
+
+  it('replaces spaces with hyphens', () => {
+    expect(createSlug('My Team Name')).toBe('my-team-name');
+  });
+
+  it('strips non-alphanumeric characters', () => {
+    expect(createSlug('DevCard @Core!')).toBe('devcard-core');
+  });
+
+  it('collapses multiple hyphens', () => {
+    expect(createSlug('a--b---c')).toBe('a-b-c');
+  });
+
+  it('removes leading and trailing hyphens', () => {
+    expect(createSlug('--team--')).toBe('team');
+  });
+});
+
+describe('generateUniqueSlug', () => {
+  it('returns base slug when it is available', async () => {
+    const slugExists = vi.fn().mockResolvedValue(false);
+    const result = await generateUniqueSlug('My Team', slugExists);
+    expect(result).toBe('my-team');
+    expect(slugExists).toHaveBeenCalledOnce();
+  });
+
+  it('returns sequential numeric suffix when base slug is taken', async () => {
+    const slugExists = vi.fn()
+      .mockResolvedValueOnce(true)  // my-team taken
+      .mockResolvedValueOnce(false); // my-team-1 free
+    const result = await generateUniqueSlug('My Team', slugExists);
+    expect(result).toBe('my-team-1');
+  });
+
+  it('increments suffix deterministically until a free slot is found', async () => {
+    const slugExists = vi.fn()
+      .mockResolvedValueOnce(true)  // my-team
+      .mockResolvedValueOnce(true)  // my-team-1
+      .mockResolvedValueOnce(true)  // my-team-2
+      .mockResolvedValueOnce(false); // my-team-3 free
+    const result = await generateUniqueSlug('My Team', slugExists);
+    expect(result).toBe('my-team-3');
+  });
+
+  it('throws when all 10 suffix candidates are taken', async () => {
+    const slugExists = vi.fn().mockResolvedValue(true);
+    await expect(generateUniqueSlug('My Team', slugExists)).rejects.toThrow(
+      'Unable to generate unique slug',
+    );
+    expect(slugExists).toHaveBeenCalledTimes(11); // base + 10 suffixes
+  });
+
+  it('produces consistent slugs across concurrent calls for different inputs', async () => {
+    const takenSlugs = new Set<string>();
+    const slugExists = vi.fn(async (slug: string) => takenSlugs.has(slug));
+
+    const [a, b] = await Promise.all([
+      generateUniqueSlug('Alpha Team', slugExists),
+      generateUniqueSlug('Beta Team', slugExists),
+    ]);
+
+    expect(a).toBe('alpha-team');
+    expect(b).toBe('beta-team');
+    expect(a).not.toBe(b);
+  });
+});

apps/backend/src/__tests__/team.test.ts

@@ -1,8 +1,12 @@
+import { Prisma, TeamRole } from '@prisma/client';
+import Fastify from 'fastify';
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import Fastify, { FastifyInstance } from 'fastify';
-import { PrismaClient, TeamRole } from '@prisma/client';
+
 import { teamRoutes } from '../routes/team';
 
+import type { PrismaClient } from '@prisma/client';
+import type { FastifyInstance } from 'fastify';
+
 // ─── Shared mock data ─────────────────────────────────────────────────────────
 
 const MOCK_OWNER_ID    = 'user-uuid-001';
@@ -92,7 +96,7 @@ const prismaMock = {
 
 // ─── App factory ──────────────────────────────────────────────────────────────
 
-let mockJwtVerify = vi.fn();
+const mockJwtVerify = vi.fn();
 
 async function buildApp(): Promise<FastifyInstance> {
   const app = Fastify({ logger: false });
@@ -118,7 +122,7 @@ async function createTeam(
   app: FastifyInstance,
   body: Record<string, unknown>,
   authenticated = true,
-) {
+): Promise<ReturnType<typeof app.inject>> {
   return app.inject({
     method: 'POST',
     url: '/',
@@ -220,6 +224,46 @@ describe('Teams API', () => {
       expect(res.statusCode).toBe(500);
       expect(res.json()).toMatchObject({ error: 'Failed to create team' });
     });
+
+    it('201 — retries and succeeds when first attempt loses slug race to concurrent request', async () => {
+      // First generateUniqueSlug: base slug appears available
+      prismaMock.team.findUnique.mockResolvedValueOnce(null);
+      // First $transaction: P2002 — another request inserted first
+      prismaMock.$transaction.mockRejectedValueOnce(
+        new Prisma.PrismaClientKnownRequestError('Unique constraint failed', { code: 'P2002', clientVersion: '0' }),
+      );
+      // Second generateUniqueSlug: base slug now taken, devcard-core-1 is free
+      prismaMock.team.findUnique.mockResolvedValueOnce(MOCK_TEAM); // devcard-core taken
+      prismaMock.team.findUnique.mockResolvedValueOnce(null);      // devcard-core-1 free
+      // Second $transaction: succeeds with suffix slug
+      prismaMock.$transaction.mockImplementationOnce(async (cb: any) => {
+        return cb({
+          team: { create: vi.fn().mockResolvedValue({ ...MOCK_TEAM, slug: 'devcard-core-1' }) },
+          teamMember: { create: vi.fn().mockResolvedValue({}) },
+        });
+      });
+
+      const res = await createTeam(app, validBody);
+
+      expect(res.statusCode).toBe(201);
+      expect(res.json().slug).toBe('devcard-core-1');
+    });
+
+    it('409 — exhausts all retry attempts when DB rejects every slug with P2002', async () => {
+      const p2002 = new Prisma.PrismaClientKnownRequestError(
+        'Unique constraint failed on the fields: (`slug`)',
+        { code: 'P2002', clientVersion: '0' },
+      );
+      // Slug always appears available at the application level
+      prismaMock.team.findUnique.mockResolvedValue(null);
+      // DB always rejects with P2002 (concurrent inserts won every race)
+      prismaMock.$transaction.mockRejectedValue(p2002);
+
+      const res = await createTeam(app, validBody);
+
+      expect(res.statusCode).toBe(409);
+      expect(prismaMock.$transaction).toHaveBeenCalledTimes(5);
+    });
   });
 
   // ── GET /:slug — public team profile ─────────────────────────────────────

apps/backend/src/routes/team.ts

@@ -24,14 +24,14 @@ type TeamProfile = {
   members: TeamMember[];
 }
 
-export async function teamRoutes(app:FastifyInstance){
+export async function teamRoutes(app: FastifyInstance): Promise<void> {
     app.post('/', async(request:FastifyRequest<{
         Body: {name: string, description? : string, avatarUrl?: string }
     }>, reply: FastifyReply) => {
         let decoded; 
         try {
             decoded = await request.jwtVerify() as any; 
-        } catch (error) {
+        } catch (_error) {
             return reply.status(401).send({error : 'Unauthorized'})
         }
 
@@ -42,55 +42,45 @@ export async function teamRoutes(app:FastifyInstance){
         }; 
         const {name , description , avatarUrl} = parsed.data; 
 
-        const finalSlug = await generateUniqueSlug(name, async(slug) => {
-            const existing = await app.prisma.team.findUnique({where: {slug }})
+        const MAX_CREATE_ATTEMPTS = 5;
 
-            return !!existing
-        })
+        for (let attempt = 0; attempt < MAX_CREATE_ATTEMPTS; attempt++) {
+          let finalSlug: string;
+          try {
+            finalSlug = await generateUniqueSlug(name, async (slug) => {
+              const existing = await app.prisma.team.findUnique({ where: { slug } });
+              return !!existing;
+            });
+          } catch {
+            return reply.status(409).send({ error: 'Unable to generate a unique team slug' });
+          }
 
-        try {
+          try {
             const team = await app.prisma.$transaction(async (tx) => {
-                const team = await tx.team.create({
-                    data: {
-                        name, 
-                        slug: finalSlug, 
-                        description, 
-                        avatarUrl, 
-                        ownerId: userId, 
-                    }
-                })
-    
-                await tx.teamMember.create({
-                    data: {
-                        teamId : team.id, 
-                        userId, 
-                        role: TeamRole.OWNER, 
-                        joinedAt: new Date(), 
-                    }
-                })
-                return team
-            })   
-            return reply.status(201).send(team)
-
-        }catch (error) {
+              const created = await tx.team.create({
+                data: { name, slug: finalSlug, description, avatarUrl, ownerId: userId },
+              });
+              await tx.teamMember.create({
+                data: { teamId: created.id, userId, role: TeamRole.OWNER, joinedAt: new Date() },
+              });
+              return created;
+            });
+            return reply.status(201).send(team);
+          } catch (error) {
             if (error instanceof Prisma.PrismaClientKnownRequestError) {
-                switch (error.code) {
-                case 'P2002':
-                    return reply.status(409).send({
-                    error: 'Team slug already exists'
-                    });
-
-                case 'P2003':
-                    return reply.status(400).send({
-                    error: 'Invalid organizer'
-                    });
-                }
+              if (error.code === 'P2002') {
+                continue;
+              }
+              if (error.code === 'P2003') {
+                return reply.status(400).send({ error: 'Invalid organizer' });
+              }
             }
             app.log.error('Failed to create a team');
-            return reply.status(500).send({
-                error: 'Failed to create team'
-            });
+            return reply.status(500).send({ error: 'Failed to create team' });
+          }
         }
+
+        return reply.status(409).send({ error: 'Unable to allocate a unique team slug' });
     })
 
     app.get('/:slug', async(request: FastifyRequest<{Params: {slug: string}}>, reply: FastifyReply) => {
@@ -164,7 +154,7 @@ export async function teamRoutes(app:FastifyInstance){
         let decoded; 
         try {
            decoded = await request.jwtVerify() as any;  
-        } catch (error) {
+        } catch (_error) {
             return reply.status(401).send({error : 'Unauthorized'})
         }
         const userId = decoded.id; 
@@ -231,7 +221,7 @@ export async function teamRoutes(app:FastifyInstance){
         let decoded; 
         try {
             decoded = await request.jwtVerify() as any
-        } catch (error) {
+        } catch (_error) {
             return reply.status(401).send({error : 'Unauthorized'})
         }
         const paramsSlug = request.params.slug 
@@ -299,7 +289,7 @@ export async function teamRoutes(app:FastifyInstance){
         let decoded; 
         try {
             decoded = await request.jwtVerify() as any
-        } catch (error) {
+        } catch (_error) {
             return reply.status(401).send({error : 'Unauthorized'})
         }
         const userId = decoded.id; 
@@ -347,7 +337,7 @@ export async function teamRoutes(app:FastifyInstance){
         let decoded; 
         try {
             decoded = await request.jwtVerify() as any
-        } catch (error) {
+        } catch (_error) {
             return reply.status(401).send({error : 'Unauthorized'})
         }
         const userId = decoded.id; 

apps/backend/src/utils/slug.ts

@@ -1,19 +1,27 @@
-export function createSlug(name:string){
-    return name.toLowerCase().trim().replace(/\s+/g, '-').replace(/[^a-z0-9-]+/g, '').replace(/-+/g, '-').replace(/^-+|-+$/g, '')
+export function createSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]+/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
 }
 
-export async function generateUniqueSlug(name: string, 
-    slugExists: (slug: string) => Promise<boolean> 
-){
-    const cleanSlug = createSlug(name)
-    let finalSlug = cleanSlug; 
-    while(true){
-        const exists = await slugExists(finalSlug)
+const MAX_SLUG_ATTEMPTS = 10;
 
-        if(!exists) break; 
+export async function generateUniqueSlug(
+  name: string,
+  slugExists: (slug: string) => Promise<boolean>,
+): Promise<string> {
+  const baseSlug = createSlug(name);
 
-        const randomSuffix  = Math.random().toString(36).substring(2,6); 
-        finalSlug = `${cleanSlug}-${randomSuffix}` 
-    }
-    return finalSlug; 
+  if (!(await slugExists(baseSlug))) { return baseSlug; }
+
+  for (let i = 1; i <= MAX_SLUG_ATTEMPTS; i++) {
+    const candidate = `${baseSlug}-${i}`;
+    if (!(await slugExists(candidate))) { return candidate; }
+  }
+
+  throw new Error(`Unable to generate unique slug for "${name}" after ${MAX_SLUG_ATTEMPTS} attempts`);
 }