Snowflake IDs

O CSGOFlip usa Snowflake IDs ao invés de UUIDs ou auto-increment para identificadores únicos.

O que são Snowflake IDs?

Snowflake IDs são identificadores de 64 bits criados pelo Twitter para geração distribuída de IDs únicos. Eles combinam timestamp, identificador de máquina e sequência.

Estrutura do Snowflake ID

 64 bits total
┌───────────────────────────────────────────────────────────────────┐
│  1 bit  │      41 bits       │   10 bits    │     12 bits         │
│  unused │     timestamp      │   worker ID  │     sequence        │
└───────────────────────────────────────────────────────────────────┘

- 1 bit:   Sempre 0 (para garantir número positivo)
- 41 bits: Milissegundos desde epoch customizado (~69 anos)
- 10 bits: ID do worker/máquina (0-1023)
- 12 bits: Sequência dentro do mesmo ms (0-4095)

Por que Snowflake e não UUID?

Comparativo

Aspecto	Snowflake	UUID v4	Auto-increment
Tamanho	8 bytes (64 bits)	16 bytes (128 bits)	4-8 bytes
Ordenação	✅ Por tempo	❌ Aleatório	✅ Sequencial
Distribuído	✅ Sem coordenação	✅ Sem coordenação	❌ Sequência central
Performance de índice	✅ Excelente	❌ Fragmentado	✅ Excelente
Previsibilidade	⚠️ Timestamp visível	✅ Aleatório	❌ Sequencial
Colisões	✅ Impossível (com worker ID)	✅ Praticamente impossível	✅ Impossível

1. Performance de Índice B-Tree

UUIDs são aleatórios, causando fragmentação em índices B-Tree:

UUID v4 (aleatório):
Inserções: a1b2c3, f4e5d6, 123456, zyxwvu, ...
                ↓
B-Tree fragmentado (muitos page splits)

Snowflake (ordenado por tempo):
Inserções: 1001, 1002, 1003, 1004, ...
                ↓
B-Tree sequencial (inserções no final)

Resultado: Inserções com Snowflake são ~2-5x mais rápidas que UUID.

2. Ordenação Natural

-- Com Snowflake, ORDER BY id = ORDER BY created_at (aproximado)
SELECT * FROM transactions ORDER BY id DESC LIMIT 10;

-- Com UUID, precisa de índice separado em created_at
SELECT * FROM transactions ORDER BY created_at DESC LIMIT 10;

3. Menor Tamanho

Snowflake: 8 bytes
UUID:      16 bytes

Em uma tabela com 100M de registros:
- Snowflake: 800 MB para IDs
- UUID:      1.6 GB para IDs

+ índices secundários que referenciam IDs

4. Geração Distribuída

Múltiplos servidores podem gerar IDs sem coordenação:

Server 1 (worker_id = 1): 1001, 1002, 1003...
Server 2 (worker_id = 2): 2001, 2002, 2003...

Nunca colidem porque worker_id é diferente.

---

Implementação

SnowflakeService

// src/infrastructure/snowflake/snowflake.service.ts

@Injectable()
export class SnowflakeService {
  private sequence = 0n;
  private lastTimestamp = -1n;
  
  // Epoch customizado: 1 Jan 2024 00:00:00 UTC
  private readonly EPOCH = 1704067200000n;
  
  // Worker ID (configurável por ambiente)
  private readonly workerId: bigint;
  
  constructor() {
    const workerIdEnv = process.env.WORKER_ID || '1';
    this.workerId = BigInt(parseInt(workerIdEnv, 10) & 0x3FF); // 10 bits
  }

  generate(): bigint {
    let timestamp = BigInt(Date.now());

    // Se mesmo milissegundo, incrementa sequência
    if (timestamp === this.lastTimestamp) {
      this.sequence = (this.sequence + 1n) & 0xFFFn; // 12 bits max
      
      // Se sequência estourou, espera próximo ms
      if (this.sequence === 0n) {
        timestamp = this.waitNextMillis(timestamp);
      }
    } else {
      this.sequence = 0n;
    }

    this.lastTimestamp = timestamp;

    // Monta o ID:
    // | timestamp (41 bits) | worker (10 bits) | sequence (12 bits) |
    return (
      ((timestamp - this.EPOCH) << 22n) |
      (this.workerId << 12n) |
      this.sequence
    );
  }

  private waitNextMillis(currentTimestamp: bigint): bigint {
    let timestamp = BigInt(Date.now());
    while (timestamp <= currentTimestamp) {
      timestamp = BigInt(Date.now());
    }
    return timestamp;
  }

  // Extrai informações de um ID
  parse(id: bigint): SnowflakeInfo {
    const timestamp = (id >> 22n) + this.EPOCH;
    const workerId = (id >> 12n) & 0x3FFn;
    const sequence = id & 0xFFFn;

    return {
      timestamp: new Date(Number(timestamp)),
      workerId: Number(workerId),
      sequence: Number(sequence),
    };
  }
}

interface SnowflakeInfo {
  timestamp: Date;
  workerId: number;
  sequence: number;
}

Uso nos Repositórios

// src/infrastructure/database/repositories/user.repository.ts

@Injectable()
export class UserRepository implements IUserRepository {
  constructor(
    private readonly prisma: PrismaService,
    private readonly snowflake: SnowflakeService,
  ) {}

  async create(data: CreateUserData): Promise<User> {
    const id = this.snowflake.generate();
    
    return this.prisma.user.create({
      data: {
        id,
        ...data,
      },
    });
  }
}

Prisma Schema

model User {
  id          BigInt   @id // Não usa @default(autoincrement())
  steamId     String   @unique
  username    String
  // ...
}

model Transaction {
  id          BigInt   @id
  userId      BigInt
  // ...
}

model CaseOpening {
  id          BigInt   @id
  userId      BigInt
  caseId      BigInt
  // ...
}

---

TypeScript e BigInt

Serialização JSON

BigInt não serializa nativamente para JSON:

// ❌ Erro
JSON.stringify({ id: 123456789012345678n });
// TypeError: Do not know how to serialize a BigInt

// ✅ Solução: converter para string
JSON.stringify({ id: '123456789012345678' });

DTOs

// Request DTO - recebe string
export class GetUserDto {
  @IsString()
  id: string;
}

// Response DTO - envia string
export class UserResponseDto {
  id: string; // Convertido de BigInt
  username: string;
}

// Controller
@Get(':id')
async getUser(@Param('id') id: string): Promise<UserResponseDto> {
  const user = await this.getUserUseCase.execute(BigInt(id));
  
  return {
    id: user.id.toString(),
    username: user.username,
  };
}

Prisma e BigInt

Prisma retorna BigInt nativamente:

const user = await prisma.user.findUnique({ where: { id: 123n } });
console.log(typeof user.id); // 'bigint'

// Para queries com string
const user = await prisma.user.findUnique({
  where: { id: BigInt('123456789012345678') },
});

---

Capacidade

Com a estrutura de 64 bits:

Componente	Bits	Valores	Duração/Capacidade
Timestamp	41	2^41 ms	~69 anos
Worker ID	10	1024	1024 servidores
Sequence	12	4096	4096/ms por worker

Capacidade total: 4096 IDs/ms × 1024 workers = ~4.2 milhões IDs/segundo

---

Debug e Análise

Extrair Timestamp de um ID

// Útil para debug
const id = 123456789012345678n;
const info = snowflakeService.parse(id);

console.log(info);
// {
//   timestamp: 2024-06-15T10:30:45.123Z,
//   workerId: 1,
//   sequence: 42
// }

Query por Range de Tempo

Como IDs são ordenados por tempo, podemos filtrar por range:

// IDs gerados após uma data específica
const startOfDay = new Date('2024-06-15T00:00:00Z');
const minId = snowflakeService.generateForTimestamp(startOfDay);

const todaysTransactions = await prisma.transaction.findMany({
  where: { id: { gte: minId } },
});

---

Considerações de Segurança

Timestamp Visível

O timestamp está embutido no ID, então é possível saber quando um registro foi criado:

const id = 123456789012345678n;
const info = snowflakeService.parse(id);
console.log(info.timestamp); // Revela quando foi criado

Mitigação: Se isso for um problema de privacidade, use UUIDs ou encripte os IDs na camada de apresentação.

Sequência Previsível

Dentro do mesmo milissegundo, IDs são sequenciais. Isso geralmente não é um problema, mas considere se enumeração de IDs é uma preocupação.

---

Comparativo de Performance

Benchmark: Inserção de 1M registros

Tipo de ID	Tempo	Tamanho do Índice
Auto-increment	45s	32 MB
Snowflake	48s	32 MB
UUID v4	95s	64 MB

Benchmark: SELECT com JOIN

Tipo de ID	Tempo (cold)	Tempo (warm)
Snowflake	120ms	25ms
UUID v4	180ms	45ms

---

Arquivos Fonte Relacionados

Principais Arquivos

• src/infrastructure/snowflake/snowflake.service.ts - Gerador de IDs
• src/infrastructure/snowflake/snowflake.module.ts - Módulo NestJS
• prisma/schema.prisma - Schema com BigInt IDs