Snowflake'ler¶

Snowflake, kullanıcı, sunucu, kanal, mesaj, rol, emoji veya ek gibi bir TEBHOS kaynağı için 64 bitlik bir tanımlayıcıdır (kimlik). Bu başvurudaki her alan tablosunda snowflake olarak yazılan türdür; HTTP API ve Gateway aynı tanımlayıcı alanını paylaşır.

Bir snowflake TEBHOS içinde benzersizdir. Değeri sabittir ve kaynak silindikten sonra yeniden kullanılmaz.

Bazı tanımlayıcılar snowflake değildir. Davet kodları, özel URL kodları, webhook token'ları ve yükleme anahtarları opak string'lerdir; her kaynak sayfası bunu ilgili yerde belirtir.

Biçim¶

Bir snowflake 64 bite bir zaman damgası, bir işçi kimliği ve bir sıra numarası sığdırır. İşçi ve sıra alanları, aynı milisaniyede verilen tanımlayıcıları birbirinden ayırır. 63. bit 2084 yılına kadar sıfır kalır; bu nedenle bugün verilen her snowflake işaretli 64 bitlik bir tamsayıya sığar.

Başlangıç anı (epoch), Unix başlangıcından 1420070400000 milisaniye sonradır. Alt 22 bit tanımlayıcının nasıl ayrıldığını açıklar. Bunları yönlendirme veya herhangi bir kaynak anlamı için kullanmayın.

Tanımlayıcılar ayrılmış bir üreteç hizmeti tarafından verilir; bu nedenle işçi başına tekdüze olarak artar. Gömülü zaman damgasını kaynağın var olduğunun kanıtı olarak değil, yaklaşık bir oluşturulma zamanı olarak değerlendirin.

Zaman damgasını çıkarma¶

Oluşturulma zamanını Unix milisaniyesi olarak elde etmek için snowflake'i 22 bit sağa kaydırın ve başlangıç anını ekleyin.

timestamp_ms = (snowflake >> 22) + 1420070400000

Tersi, bir Unix milisaniye zaman damgası için mümkün olan en küçük snowflake'i üretir. Sayfalama sınırı olarak kullanışlıdır.

snowflake = (timestamp_ms - 1420070400000) << 22

const TEBHOS_EPOCH = 1420070400000n;

function snowflakeToDate(id) {
  return new Date(Number((BigInt(id) >> 22n) + TEBHOS_EPOCH));
}

function dateToSnowflake(date) {
  return ((BigInt(date.getTime()) - TEBHOS_EPOCH) << 22n).toString();
}

snowflakeToDate("1489002177550843904");

from datetime import datetime, timezone

TEBHOS_EPOCH = 1420070400000

def snowflake_to_datetime(snowflake: str) -> datetime:
    ms = (int(snowflake) >> 22) + TEBHOS_EPOCH
    return datetime.fromtimestamp(ms / 1000, tz=timezone.utc)

def datetime_to_snowflake(dt: datetime) -> str:
    return str((int(dt.timestamp() * 1000) - TEBHOS_EPOCH) << 22)

Hat üzerindeki gösterim¶

TEBHOS, her JSON gövdesinde ve Gateway yükünde bir snowflake'i işaretsiz ondalık bir string olarak yayar; örneğin "id": "1489002177550843904". Yol parametreleri ve sorgu dizesi parametreleri her zaman metindir.

Snowflake'leri aynı şekilde gönderin:

• Bir yolda, GET /channels/1489002177550843904 örneğindeki gibi ondalık rakamları kullanın.
• Bir JSON gövdesinde veya sorgu dizesinde ondalık bir string gönderin.

64 bitlik bir tamsayı olarak ayrıştırılamayan bir yol veya gövde değeri, genellikle 400 BAD_REQUEST ile reddedilir. Görünür hiçbir kaynağı belirtmeyen, biçimi doğru bir kimlik, o kaynak için olağan bulunamadı sonucunu, genellikle 404 NOT_FOUND döndürür.

Sayfalama¶

Snowflake'e göre sıralanmış bir kaynak üzerinde sayfalama yapan bir koleksiyon, before, after veya around gibi bir imleç kabul eder. Her işlem hangi imleçleri desteklediğini, bunların birleştirilip birleştirilemeyeceğini, sonuç sırasını ve limit değerinin nasıl uygulandığını tanımlar.

Kanal mesajlarını listeleme üçünü de kabul eder. Mesajlar sayfasındaki toplu mesaj getirme işlemi bunları her girişte kabul eder. Bazı imleçler snowflake değildir: örneğin sabitlenmiş mesaj listesi sabitlenme zamanına göre sayfalanır. Her işlem kendi imleçlerinin türünü belirtir.

Zaman damgası yüksek bitleri kapladığından, snowflake'lerin sayısal sırası milisaniye çözünürlüğünde oluşturulma sırasıdır.