mirror of
https://github.com/CorentinTh/it-tools.git
synced 2026-10-24 23:01:12 +00:00
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.
This commit is contained in:
a0666660
parent
026383ffba
commit
a29f3e60c4
3 changed files with 160 additions and 42 deletions
|
|
@ -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);
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
};
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
|||
</td>
|
||||
<td>{{ decoded.isoDate }}</td>
|
||||
</tr>
|
||||
<tr v-if="platformKey !== 'twitter'">
|
||||
<tr v-for="field in decoded.fields" :key="field.label">
|
||||
<td class="labels">
|
||||
Datacenter id:
|
||||
{{ field.label }}:
|
||||
</td>
|
||||
<td>{{ decoded.datacenterId }}</td>
|
||||
</tr>
|
||||
<tr v-if="platformKey !== 'twitter'">
|
||||
<td class="labels">
|
||||
Worker id:
|
||||
</td>
|
||||
<td>{{ decoded.workerId }}</td>
|
||||
<td>{{ field.value }}</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="labels">
|
||||
|
|
@ -91,7 +85,7 @@ const epochOptions = SNOWFLAKE_PLATFORMS.map(p => ({ label: p.label, value: p.ke
|
|||
</tbody>
|
||||
</n-table>
|
||||
<div mt-2 text-xs op-60>
|
||||
Epoch: {{ effectiveEpoch }} ms · layout: 41-bit timestamp / 5-bit datacenter / 5-bit worker / 12-bit sequence
|
||||
Epoch: {{ effectiveEpoch }} ms · layout: {{ decoded.layoutLabel }}
|
||||
</div>
|
||||
</c-card>
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue