Snowflakes

Um snowflake é um identificador de 64 bits para um recurso do Decoding Chat, como um usuário, servidor, canal, mensagem, cargo ou anexo. É o tipo escrito como snowflake em todas as tabelas de transmissão desta referência, e a API HTTP, a API de administração e o Gateway compartilham esse mesmo espaço de identificadores.

Um snowflake é único dentro da implantação que o emitiu. O valor permanece estável, e o Decoding Chat não o reutiliza depois que o recurso é excluído. Implantações distintas podem emitir o mesmo valor numérico, então o cliente DEVE associar cada snowflake à sua implantação.

Nunca interprete um snowflake como número JSON

Valores de snowflake ultrapassam a faixa de inteiros exatos de um double JSON, então lê-lo como número pode alterá-lo silenciosamente. O cliente DEVE converter a string em um inteiro de 64 bits e DEVE comparar snowflakes como inteiros, porque strings decimais de comprimentos diferentes não se ordenam corretamente como texto.

Formato

Um snowflake empacota um timestamp, um ID de worker e uma sequência em 64 bits. Os campos de worker e sequência distinguem identificadores emitidos no mesmo milissegundo. O bit 63 é sempre zero, então um snowflake emitido cabe em um inteiro de 64 bits com sinal.

Campo	Bits	Descrição
Timestamp1	62 a 22	A quantidade de milissegundos desde 2015-01-01T00:00:00.000Z
ID do worker	21 a 12	O identificador sem sinal do worker alocador, de 0 até 1023
Sequência2	11 a 0	A sequência sem sinal por worker, de 0 até 4095

¹ O timestamp registra o instante em que o identificador foi emitido, que pode ocorrer pouco antes de o recurso existir

² Um valor de sequência maior indica um identificador posterior apenas quando ambos vêm do mesmo worker no mesmo milissegundo

A época é 1420070400000 milissegundos após a época Unix. Toda instância do Decoding Chat usa esse mesmo valor. Os 22 bits menos significativos expõem detalhes do alocador, então o cliente NÃO DEVE usá-los para roteamento nem para semântica de recurso.

Trate o timestamp embutido como um horário aproximado de emissão, não como prova de que o recurso já existe.

Extraindo um timestamp

Para obter o horário de criação em milissegundos Unix, desloque o snowflake 22 bits para a direita e some a época.

timestamp_ms = (snowflake >> 22) + 1420070400000

A expressão inversa produz o menor snowflake possível para um timestamp Unix em milissegundos. É útil como limite de paginação.

snowflake = (timestamp_ms - 1420070400000) << 22

A faixa representável vai de 2015-01-01T00:00:00.000Z até 2084-09-06T15:47:35.551Z.

Representação na transmissão

O Decoding Chat emite um snowflake como string decimal sem sinal em todo corpo JSON, parâmetro de caminho, parâmetro de query string e payload do Gateway. Um valor emitido contém apenas dígitos ASCII. O tráfego de entrada é mais permissivo, e RECOMENDA-SE que o cliente envie sempre a forma emitida.

Entrada aceita

Superfície	Entrada aceita
Requisição HTTP1	0, ou um dígito diferente de zero seguido de outros dígitos, enviado como string JSON ou como inteiro JSON
Comando do Gateway2	Um dígito não zero seguido de outros dígitos, como string de dígitos ASCII ou inteiro JSON positivo

¹ O Decoding Chat remove espaços no início e no fim antes de ler o texto. Nesse texto, um zero à esquerda, um sinal, um ponto decimal e qualquer outro caractere não numérico são rejeitados com o código de validação INVALID_SNOWFLAKE_FORMAT, e um valor bem formado acima de 9223372036854775807 é rejeitado com SNOWFLAKE_OUT_OF_RANGE

² O Gateway rejeita 0, zero à esquerda, valor com sinal, inteiro negativo e valor acima de 9223372036854775807

Os dois códigos de validação HTTP são códigos de elemento dentro de uma resposta 400 INVALID_FORM_BODY. Cada comando do Gateway indica o que sua própria rejeição provoca, desde descartar o campo até abandonar o comando inteiro.

Um snowflake enviado como número JSON mantém o valor exato em qualquer tamanho. Um número JSON fracionário é uma falha comum de tipo e reporta INVALID_FORMAT. O Decoding Chat lê a forma exponencial como o número que ela representa, e um valor acima de 9007199254740991 reporta INVALID_SNOWFLAKE_FORMAT. Parâmetros de caminho e de query string sempre chegam como texto.

0 é o início do tempo dos snowflakes

Um cursor de paginação HTTP aceita 0. Um parâmetro de caminho ou campo HTTP que identifica um recurso real também aceita 0, e a requisição então recebe o resultado normal de recurso não encontrado.

Paginação

Um endpoint de coleção que pagina sobre um recurso ordenado por snowflake aceita um cursor como before, after ou around. O endpoint define quais cursores aceita, se são mutuamente exclusivos, a ordem do resultado e como limit é aplicado.

Cursor	Seleciona
before	Identificadores menores que o valor do cursor, excluindo-o
after	Identificadores maiores que o valor do cursor, excluindo-o
around	Uma janela centrada no valor do cursor, incluindo-o

Listar mensagens do canal aceita around como parâmetro de query string, e Listar mensagens de vários canais o aceita em cada entrada do corpo da requisição. Nenhuma outra operação o aceita.

O tipo de um cursor before ou after depende da operação. Listar mensagens fixadas pagina pelo horário de fixação, então seu before é um timestamp ISO 8601. Listar entradas da lista de bloqueio pagina pelo valor da entrada. Seu after é o valor armazenado da última entrada da página anterior. Cada operação indica o tipo dos próprios cursores.

Como o timestamp ocupa os bits mais significativos, a ordem numérica dos snowflakes é a ordem de criação na resolução de milissegundos.

Um cursor é um limite numérico

Um cursor não precisa identificar um recurso, então um snowflake derivado de um timestamp pode delimitar um intervalo de tempo sem um parâmetro de timestamp dedicado.