From a29f3e60c4b9a587e7bebb6fad697ac4d2b9725a Mon Sep 17 00:00:00 2001 From: a0666660 <69061030+a0666660@users.noreply.github.com> Date: Sat, 3 Oct 2026 23:07:18 +0800 Subject: [PATCH] fix(snowflake-id-decoder): decode per-platform bit layouts Differential probing against platform documentation surfaced three issues in the fixed Twitter-layout decoder: - Mastodon ids are 48 bits of ms timestamp plus a 16-bit sequence, not the Twitter 42/5/5/12 layout - every decoded timestamp was wrong - Instagram uses a 41-bit timestamp, 13-bit logical shard and 10-bit sequence, not 5/5/12 - shard and sequence widths were misread - Discord names the middle fields worker/process while Twitter calls the same positions datacenter/worker; the tool showed Twitter labels for Discord ids decodeSnowflake now takes the platform and decodes from its layout descriptor; the UI renders the platform field names and bit budget. Regression vectors: the Discord documented example, plus constructed Instagram and Mastodon ids. --- .../snowflake-id-decoder.models.test.ts | 61 +++++++-- .../snowflake-id-decoder.models.ts | 125 +++++++++++++++--- .../snowflake-id-decoder.vue | 16 +-- 3 files changed, 160 insertions(+), 42 deletions(-) diff --git a/src/tools/snowflake-id-decoder/snowflake-id-decoder.models.test.ts b/src/tools/snowflake-id-decoder/snowflake-id-decoder.models.test.ts index 12317c29..7488602c 100644 --- a/src/tools/snowflake-id-decoder/snowflake-id-decoder.models.test.ts +++ b/src/tools/snowflake-id-decoder/snowflake-id-decoder.models.test.ts @@ -1,40 +1,77 @@ import { describe, expect, it } from 'vitest'; -import { decodeSnowflake } from './snowflake-id-decoder.models'; +import { SNOWFLAKE_PLATFORMS, decodeSnowflake } from './snowflake-id-decoder.models'; + +function platform(key: string) { + const found = SNOWFLAKE_PLATFORMS.find(p => p.key === key); + if (!found) { + throw new Error(`unknown platform ${key}`); + } + return found; +} describe('snowflake-id-decoder', () => { it('decodes a Twitter snowflake against the Twitter epoch', () => { // 565419792856637440 was posted on 2015-02-09 - const decoded = decodeSnowflake('565419792856637440', 1288834974657); + const decoded = decodeSnowflake('565419792856637440', platform('twitter'), platform('twitter').epoch); expect(decoded.timestamp).toBe(1423641558265); expect(decoded.isoDate).toContain('2015-02-11'); }); - it('decodes a Discord id against the Discord epoch', () => { - // Discord docs example: id 175928847299117063 -> 2016-04-30T11:18:25.796Z - const decoded = decodeSnowflake('175928847299117063', 1420070400000); + it('decodes the Discord documented example with worker/process naming', () => { + // https://discord.com/developers/docs/reference#snowflakes-example-snowflake-decomposition + // 175928847299117063 -> 2016-04-30T11:18:25.796Z, worker 1, process 0, sequence 7 + const decoded = decodeSnowflake('175928847299117063', platform('discord'), platform('discord').epoch); expect(decoded.timestamp).toBe(1462015105796); expect(decoded.isoDate).toBe('2016-04-30 11:18:25 UTC'); - expect(decoded.datacenterId).toBe(1); - expect(decoded.workerId).toBe(0); + expect(decoded.fields.find(f => f.label === 'Worker id')?.value).toBe(1); + expect(decoded.fields.find(f => f.label === 'Process id')?.value).toBe(0); expect(decoded.sequence).toBe(7); }); + it('decodes Instagram shard/sequence with the 41/13/10 layout', () => { + const instagram = platform('instagram'); + const id = ((185779978279n << 23n) | (5n << 10n) | 100n).toString(); + const decoded = decodeSnowflake(id, instagram, instagram.epoch); + expect(decoded.timestamp).toBe(1500000000000); + expect(decoded.fields.find(f => f.label === 'Shard id')?.value).toBe(5); + expect(decoded.sequence).toBe(100); + }); + + it('decodes Mastodon ids with the 48/16 layout', () => { + const id = ((1700000000000n << 16n) | 1234n).toString(); + const decoded = decodeSnowflake(id, platform('mastodon'), 0); + expect(decoded.timestamp).toBe(1700000000000); + expect(decoded.sequence).toBe(1234); + expect(decoded.fields).toHaveLength(0); + }); + it('rejects non-numeric input', () => { - expect(() => decodeSnowflake('abc', 0)).toThrow('positive integer'); - expect(() => decodeSnowflake('12 34', 0)).toThrow('positive integer'); - expect(() => decodeSnowflake('-5', 0)).toThrow('positive integer'); + const twitter = platform('twitter'); + expect(() => decodeSnowflake('abc', twitter, twitter.epoch)).toThrow('positive integer'); + expect(() => decodeSnowflake('12 34', twitter, twitter.epoch)).toThrow('positive integer'); + expect(() => decodeSnowflake('-5', twitter, twitter.epoch)).toThrow('positive integer'); }); it('handles very large ids beyond Number safe range', () => { // 2^63-1 must not lose precision - const decoded = decodeSnowflake('9223372036854775807', 0); + const decoded = decodeSnowflake('9223372036854775807', platform('twitter'), 0); expect(decoded.timestamp).toBe(Number(9223372036854775807n >> 22n)); }); it('extracts sequence bits', () => { // 0b1 << 22 | sequence 0b101010101010 const id = ((1n << 22n) | 0b101010101010n).toString(); - const decoded = decodeSnowflake(id, 0); + const decoded = decodeSnowflake(id, platform('twitter'), 0); expect(decoded.sequence).toBe(0b101010101010); }); + + it('custom epoch keeps the standard 64-bit layout', () => { + const custom = platform('custom'); + const id = ((1000n << 22n) | (3n << 17n) | (2n << 12n) | 7n).toString(); + const decoded = decodeSnowflake(id, custom, 5000); + expect(decoded.timestamp).toBe(6000); + expect(decoded.fields.find(f => f.label === 'Datacenter id')?.value).toBe(3); + expect(decoded.fields.find(f => f.label === 'Worker id')?.value).toBe(2); + expect(decoded.sequence).toBe(7); + }); }); diff --git a/src/tools/snowflake-id-decoder/snowflake-id-decoder.models.ts b/src/tools/snowflake-id-decoder/snowflake-id-decoder.models.ts index cb5f63a1..a6881540 100644 --- a/src/tools/snowflake-id-decoder/snowflake-id-decoder.models.ts +++ b/src/tools/snowflake-id-decoder/snowflake-id-decoder.models.ts @@ -1,26 +1,103 @@ +export interface SnowflakeFieldSpec { + label: string + bits: number +} + +export interface SnowflakeLayout { + /** Human-readable bit budget, shown under the results. */ + label: string + timestampBits: number + /** Middle fields in MSB→LSB order (between timestamp and sequence). */ + fields: SnowflakeFieldSpec[] + sequenceBits: number +} + +const STANDARD_64_BIT: SnowflakeLayout = { + label: '41-bit timestamp / 5-bit datacenter / 5-bit worker / 12-bit sequence', + timestampBits: 42, + fields: [ + { label: 'Datacenter id', bits: 5 }, + { label: 'Worker id', bits: 5 }, + ], + sequenceBits: 12, +}; + export interface SnowflakePlatform { key: string label: string epoch: number + layout: SnowflakeLayout } -/** Well-known Snowflake epochs. Twitter uses a custom 41-bit timestamp; the - * others use the standard 64-bit layout with a platform-specific epoch. */ +/** Well-known Snowflake variants. Twitter uses a custom 41-bit timestamp; + * Discord shares the Twitter bit layout but names the middle fields + * worker/process; Instagram shards with a 13-bit logical shard and a + * 10-bit sequence; Mastodon only packs 48 bits of ms timestamp plus a + * 16-bit sequence. */ export const SNOWFLAKE_PLATFORMS: SnowflakePlatform[] = [ - { key: 'twitter', label: 'Twitter / X', epoch: 1288834974657 }, - { key: 'discord', label: 'Discord', epoch: 1420070400000 }, - { key: 'instagram', label: 'Instagram', epoch: 1314220021721 }, - { key: 'mastodon', label: 'Mastodon', epoch: 0 }, - { key: 'custom', label: 'Custom epoch', epoch: 0 }, + { + key: 'twitter', + label: 'Twitter / X', + epoch: 1288834974657, + layout: STANDARD_64_BIT, + }, + { + key: 'discord', + label: 'Discord', + epoch: 1420070400000, + layout: { + label: '42-bit timestamp / 5-bit worker / 5-bit process / 12-bit sequence', + timestampBits: 42, + fields: [ + { label: 'Worker id', bits: 5 }, + { label: 'Process id', bits: 5 }, + ], + sequenceBits: 12, + }, + }, + { + key: 'instagram', + label: 'Instagram', + epoch: 1314220021721, + layout: { + label: '41-bit timestamp / 13-bit shard / 10-bit sequence', + timestampBits: 41, + fields: [ + { label: 'Shard id', bits: 13 }, + ], + sequenceBits: 10, + }, + }, + { + key: 'mastodon', + label: 'Mastodon', + epoch: 0, + layout: { + label: '48-bit timestamp / 16-bit sequence', + timestampBits: 48, + fields: [], + sequenceBits: 16, + }, + }, + { + key: 'custom', + label: 'Custom epoch', + epoch: 0, + layout: STANDARD_64_BIT, + }, ]; +export interface SnowflakeField { + label: string + value: number +} + export interface SnowflakeDecoded { /** Millisecond Unix timestamp encoded in the id. */ timestamp: number isoDate: string - /** Datacenter / worker / sequence when the platform uses the standard layout. */ - workerId: number - datacenterId: number + layoutLabel: string + fields: SnowflakeField[] sequence: number } @@ -32,21 +109,31 @@ function parseSnowflakeId(id: string): bigint { return BigInt(trimmed); } -/** Standard 64-bit Snowflake: 1 unused sign bit, 41-bit ms timestamp, - * 5-bit datacenter, 5-bit worker, 12-bit sequence. */ -export function decodeSnowflake(id: string, epoch: number): SnowflakeDecoded { +export function decodeSnowflake(id: string, platform: SnowflakePlatform, epoch: number): SnowflakeDecoded { const value = parseSnowflakeId(id); - const timestamp = Number((value >> 22n) & 0x1FFFFFFFFFFFFn) + epoch; - const datacenterId = Number((value >> 17n) & 0x1Fn); - const workerId = Number((value >> 12n) & 0x1Fn); - const sequence = Number(value & 0xFFFn); + const { layout } = platform; + + const middleBits = layout.fields.reduce((sum, field) => sum + field.bits, 0); + const timestampShift = BigInt(layout.sequenceBits + middleBits); + const timestampMask = (1n << BigInt(layout.timestampBits)) - 1n; + const timestamp = Number((value >> timestampShift) & timestampMask) + epoch; + + let cursor = timestampShift; + const fields = layout.fields.map((field) => { + cursor -= BigInt(field.bits); + const mask = (1n << BigInt(field.bits)) - 1n; + return { label: field.label, value: Number((value >> cursor) & mask) }; + }); + + const sequenceMask = (1n << BigInt(layout.sequenceBits)) - 1n; + const sequence = Number(value & sequenceMask); const date = new Date(timestamp); return { timestamp, isoDate: `${date.toISOString().replace('T', ' ').replace(/\..+/, '')} UTC`, - workerId, - datacenterId, + layoutLabel: layout.label, + fields, sequence, }; } diff --git a/src/tools/snowflake-id-decoder/snowflake-id-decoder.vue b/src/tools/snowflake-id-decoder/snowflake-id-decoder.vue index ef240629..2ed5d346 100644 --- a/src/tools/snowflake-id-decoder/snowflake-id-decoder.vue +++ b/src/tools/snowflake-id-decoder/snowflake-id-decoder.vue @@ -23,7 +23,7 @@ const validation = useValidation({ }); const decoded = computed(() => - withDefaultOnError(() => (id.value.trim() && validation.isValid ? decodeSnowflake(id.value, effectiveEpoch.value) : undefined), undefined), + withDefaultOnError(() => (id.value.trim() && validation.isValid ? decodeSnowflake(id.value, platform.value, effectiveEpoch.value) : undefined), undefined), ); const epochOptions = SNOWFLAKE_PLATFORMS.map(p => ({ label: p.label, value: p.key })); @@ -70,17 +70,11 @@ const epochOptions = SNOWFLAKE_PLATFORMS.map(p => ({ label: p.label, value: p.ke {{ decoded.isoDate }} - + - Datacenter id: + {{ field.label }}: - {{ decoded.datacenterId }} - - - - Worker id: - - {{ decoded.workerId }} + {{ field.value }} @@ -91,7 +85,7 @@ const epochOptions = SNOWFLAKE_PLATFORMS.map(p => ({ label: p.label, value: p.ke
- Epoch: {{ effectiveEpoch }} ms · layout: 41-bit timestamp / 5-bit datacenter / 5-bit worker / 12-bit sequence + Epoch: {{ effectiveEpoch }} ms · layout: {{ decoded.layoutLabel }}