Gateway'e genel bakış¶

TEBHOS Gateway kalıcı bir WebSocket'tir. Hesap ve sunucu olaylarını gönderir ve sınırlı, küçük bir istemci komutu kümesini kabul eder. Diğer tüm okuma ve değiştirme işlemleri birer HTTP API işlemidir.

Bağlanma¶

İstemci soketi açar, Hello'yu bekler, Identify gönderir ve ardından bağlantı boyunca heartbeat gönderir.

1. Örnek keşif belgesinden endpoints.gateway değerini okuyun (genel örnekte wss://tebhos.com/ws) ve bu adrese ?v=1&encoding=json ile bir WebSocket açın.
2. İşlem kodu (opcode) 10 Hello yükünü okuyun ve içinden heartbeat_interval değerini alın.
3. Token ve properties ile işlem kodu 2 Identify gönderin.
4. Ready yükünü okuyun ve daha sonraki bir Resume için session_id değerini saklayın.
5. Her heartbeat_interval milisaniyede bir, son Dispatch sıra numarasıyla işlem kodu 1 Heartbeat gönderin.

{
  "op": 2,
  "d": {
    "token": "...",
    "properties": {
      "os": "Linux",
      "browser": "my-client",
      "device": "desktop"
    }
  }
}

Yalnızca token ve properties zorunludur. Ham kullanıcı oturum token'ını veya bot token'ını ({application_id}.{secret}) bir HTTP kimlik doğrulama öneki olmadan gönderin. Bot token'ındaki Bot öneki tolere edilir ve soyulur; Bearer edilmez. İsteğe bağlı alanlar için bkz. Identify. Hesap ve sunucu güncellemeleri, olay adı t içinde ve verisi d içinde olmak üzere Dispatch'ler olarak gelir.

const ws = new WebSocket("wss://tebhos.com/ws?v=1&encoding=json");
let seq = null;
let timer = null;

ws.onmessage = (frame) => {
  const payload = JSON.parse(frame.data);
  if (payload.s != null) seq = payload.s;

  switch (payload.op) {
    case 10: // Hello
      timer = setInterval(
        () => ws.send(JSON.stringify({ op: 1, d: seq })),
        payload.d.heartbeat_interval,
      );
      ws.send(JSON.stringify({
        op: 2,
        d: {
          token: process.env.TEBHOS_TOKEN,
          properties: { os: "linux", browser: "my-bot", device: "my-bot" },
        },
      }));
      break;
    case 1: // Server heartbeat request
      ws.send(JSON.stringify({ op: 1, d: seq }));
      break;
    case 0: // Dispatch
      console.log(payload.t, payload.d);
      break;
  }
};
ws.onclose = (event) => {
  clearInterval(timer);
  console.log("closed", event.code, event.reason);
};

import asyncio, json, os
import websockets

async def main():
    async with websockets.connect("wss://tebhos.com/ws?v=1&encoding=json") as ws:
        hello = json.loads(await ws.recv())
        interval = hello["d"]["heartbeat_interval"] / 1000
        seq = None

        async def heartbeat():
            while True:
                await asyncio.sleep(interval)
                await ws.send(json.dumps({"op": 1, "d": seq}))

        asyncio.create_task(heartbeat())
        await ws.send(json.dumps({
            "op": 2,
            "d": {
                "token": os.environ["TEBHOS_TOKEN"],
                "properties": {"os": "linux", "browser": "my-bot", "device": "my-bot"},
            },
        }))
        async for raw in ws:
            payload = json.loads(raw)
            if payload.get("s") is not None:
                seq = payload["s"]
            if payload["op"] == 1:
                await ws.send(json.dumps({"op": 1, "d": seq}))
            elif payload["op"] == 0:
                print(payload["t"])

asyncio.run(main())

Protokol sürümü¶

Tek Gateway sürümü 1 sürümüdür. v=1 bağlantı parametresi bu sürümü seçer. Gateway, başka her değer için ve değer hiç verilmediğinde, Hello göndermeden önce bağlantıyı 4012 koduyla ve Invalid API version nedeniyle kapatır.

Uç noktayı keşfetme¶

endpoints.gateway değerini örnek keşif belgesinden (GET https://tebhos.com/api/v1/.well-known/tebhos) okuyun. Bir bot bunun yerine GET /gateway/bot çağırabilir; bu uç aynı WebSocket URL'sini sabit bir önerilen shard sayısı ve sabit bir oturum başlatma sınırı nesnesiyle birlikte döndürür. Bu yol bot token'ı dışındaki her kimlik bilgisini 401 ile reddeder.

Bağlantı parametreleri¶

Bağlantı parametrelerini keşfedilen URL'nin sonuna ekleyin.

Bilinmeyen parametreler yok sayılır. Tanınmayan bir compress veya stream değeri sıkıştırmasız bağlantıyı seçer ve bağlantı açık kalır. İstemci, bağlantının sıkıştırılıp sıkıştırılmadığını aldığı çerçevenin türünden okumak ZORUNDADIR (MUST). Bir zstd-stream bağlantısında sunucunun her çerçevesi ikili (binary) çerçevedir.

TEBHOS web ve masaüstü istemcileri ?v=1&encoding=json&compress=zstd-stream&stream=1 ile bağlanır.

Gateway yükü¶

Her mantıksal mesaj Gateway yükünü kullanır.

Çözüldüğünde JSON nesnesi olmayan bir yük, bağlantıyı 4002 koduyla ve Decode failed nedeniyle kapatır. op içermeyen bir nesne 4002 ve Invalid payload nedeniyle kapatır. op içeren ama d içermeyen bir nesne 4001 ve Unknown opcode nedeniyle kapatır; bunun istisnası Identify ve Resume'dur, bunlar 4005 ile kapatır.

Dispatch, sunucudan istemciye giden bir olay yüküdür. Her canlı Dispatch oturum sıra numarasını bir artırır. Oturum 0 sıra numarasıyla başlar; bu yüzden Ready sıra numarası 1'dir.

Yeniden oynatılan bir Dispatch özgün sıra numarasını korur ve yeniden oynatılan bir dizide boşluklar olabilir; çünkü Guild Sync, Guild Member List Update ve Guild Members Chunk canlı olarak teslim edilir ve hiçbir zaman saklanmaz. Resumed geçerli sıra numarasını taşır ve onu artırmaz. Resumed'dan sonraki ilk canlı Dispatch, bu sıra numarasının bir fazlasına sahip olur. Sıra numarası tek bir Gateway oturumuna özgüdür ve oturumlar ya da shard'lar arasında anlam taşımaz.

Çerçeveleme¶

Gelen tek bir WebSocket mesajı, hat üzerinde 4.096 baytla sınırlıdır; sıkıştırılmış gelen bir mesaj ise açıldıktan sonra da ayrıca 4.096 baytla sınırlıdır. Bu sınırlardan birini aşan bir mesaj bağlantıyı 4002 koduyla ve Payload too large nedeniyle kapatır. Açılamayan gelen bir mesaj 4002 ve Decompression failed nedeniyle kapatır.

JSON yükleri UTF-8 nesnelerdir. Sıkıştırılmamış bir istemci yükü metin çerçevesinde, istemcinin anlaşılan zstd akışıyla sıkıştırdığı bir yük ise ikili çerçevede gönderilir.

Gateway gelen çerçevenin türünü incelemez. Gelen her mesajı bağlantının anlaştığı sıkıştırmayla çözer. İstemci her yükü anlaşılan biçimde göndermek ZORUNDADIR (MUST): sıkıştırmasız bir bağlantıda sıkıştırılmamış olarak, bir zstd-stream bağlantısında ise aynı sıkıştırma akışı üzerinden, sırasıyla.

JSON tamsayı gösterimi¶

Snowflake'ler ondalık dizelerdir. Tanımlayıcı sözleşmesi için bkz. Snowflake'ler. Sıra numaraları, sayılar, sürümler ve bit alanları JSON sayılarıdır.

Sıkıştırma¶

zstd-stream, her iki yönde de kesintisiz bir akıştır. İstemci, sunucunun her çerçevesini geliş sırasıyla aynı açıcıya vermek ve her istemci çerçevesini aynı sıkıştırıcıdan üretmek ZORUNDADIR (MUST). Tek bir WebSocket mesajı tam olarak bir Gateway yükü taşır.

zstd-stream anlaşan bir bağlantıda Hello zaten sıkıştırılmıştır; bu yüzden böyle bir bağlantının aldığı ilk çerçeve ikili çerçevedir. Sunucu zstd uygulamasını yükleyemezse, bağlantı bu ilk çerçeveyi göndermeye çalışırken 4002 koduyla ve Compression failed: zstd-stream nedeniyle kapanır.

Sinyalleşme durum makinesi¶

Bir bağlantı şu durumlardan geçer: Opening, Unauthenticated, Starting, Replaying ve Ready. Heartbeat her açık durumda kabul edilir; Closed ise o WebSocket için son durumdur.

Açılış (Opening)¶

Kimliği doğrulanmamış (Unauthenticated)¶

Başlatılıyor (Starting)¶

Yeniden oynatılıyor (Replaying)¶

Hazır (Ready)¶

Yeniden oynatılıyor veya Hazır (Replaying or Ready)¶

Herhangi bir açık durum¶

Kayıt dışındaki bir işlem kodu ve istemcinin gönderdiği bir sunucu işlem kodu, oturum bağlıysa 4001, bağlantı kimliği doğrulanmamışsa 4003 ile kapatır.

Hello ve oturum oluşturma¶

Sunucu, WebSocket'i kabul ederken işlem kodu 10 Hello gönderir.

{
  "op": 10,
  "d": {
    "heartbeat_interval": 41250
  }
}

Aralık milisaniye cinsindendir ve bağlantı için belirleyicidir.

İşlem kodu 2 Identify bir oturum oluşturur. Gateway token'ı TEBHOS API'ye karşı doğrular: kullanıcı oturum token'ı canlı bir giriş oturumuna ait olmalı, bot token'ı ise bir bot uygulamasıyla eşleşmelidir. Başarılı bir Identify, session_id değeri saklanan oturumu tanımlayan Ready gönderir. TEBHOS ayrı bir resume URL'si yayımlamaz; bu yüzden Resume, istemcinin keşfettiği aynı Gateway uç noktasına yeniden bağlanır.

Geçersiz bir token 4004 koduyla ve Invalid token nedeniyle kapatır. Zaten 100 canlı oturum tutan bir kullanıcı hesabı 4008 ve Too many sessions nedeniyle kapatır. Bot kimlik bilgisi bu üst sınıra tabi değildir. Hatalı biçimli bir shard çifti 4010 ve Invalid shard nedeniyle kapatır. Shard'ı 2.500'den fazla sunucuya çözümlenen bir bot oturumu 4011 ve Sharding required nedeniyle kapatır.

Heartbeat'ler¶

İşlem kodu 1, kimlik doğrulamadan önce ve sonra kabul edilir. Bir oturum yokken yükü yok sayılır ve sunucu yine de onaylar. Oturum oluştuktan sonra en son işlenen Dispatch sıra numarasını, henüz hiç Dispatch yoksa null gönderin.

{
  "op": 1,
  "d": 42
}

Sunucu, d içermeyen işlem kodu 11 Heartbeat ACK ile yanıt verir. Oturum bağlandıktan sonra ne null ne de tamsayı olan bir d, bağlantıyı 4007 koduyla ve Invalid sequence nedeniyle kapatır. Gateway sıra numarasını 5.000 ms içinde oturumla doğrulayamazsa bağlantı aynı kod ve nedenle kapanır.

Gateway heartbeat durumunu her 13.750 ms'de bir denetler. Son onaydan bu yana aralığın yüzde 90'ı geçtiğinde d: null ile işlem kodu 1 gönderir. Buna hemen kendi işlem kodu 1'inizle yanıt verin ve bildirilen aralıkta heartbeat göndermeye devam edin. Son tarihi kaçıran bir bağlantı 4009 koduyla ve Heartbeat timeout nedeniyle kapanır.

Sıra numarası içeren bir heartbeat, bu sıra numarasına eşit veya altındaki saklanan tüm Dispatch'leri yeniden oynatma arabelleğinden kalıcı olarak kırpar ve onu onaylanmış sıra numarası olarak kaydeder. İstemci yalnızca işlediği bir sıra numarasını göndermek ZORUNDADIR (MUST), çünkü daha düşük bir sıra numarasından yapılan sonraki bir Resume 4007 ile kapanır.

Oturumu sürdürme¶

İşlem kodu 6; özgün token'ı, Ready'deki session_id değerini ve son işlenen Dispatch sıra numarasını verir.

{
  "op": 6,
  "d": {
    "token": "...",
    "session_id": "6F1D0B7C9A2E4F83B5C1D9E7A4F20B13",
    "seq": 42
  }
}

Başarılı bir Resume, seq üzerindeki saklanan tüm Dispatch'leri sırasıyla yeniden oynatır ve Resumed ile biter.

Tüm alanlar zorunludur. Eksik bir alan, dize olmayan bir token veya session_id ya da tamsayı olmayan bir seq, bağlantıyı 4002 koduyla ve Invalid resume payload nedeniyle kapatır.

Gateway bağlantısı kopan bir oturumu 60.000 ms saklar. Kabul edilen bir seq, oturumun geçerli sıra numarasından büyük ve oturumun zaten onayladığı sıra numarasından küçük olamaz. Bu sınırlardan birinin dışındaki bir seq, 4007 koduyla ve Invalid sequence nedeniyle kapatır.

Bilinmeyen veya süresi dolmuş bir oturum d: false ile işlem kodu 9 gönderir ve soketi kimliği doğrulanmamış durumda bırakır. Belirtilen oturumun sahibi olmayan bir token 4004 ve Invalid token nedeniyle kapatır. Ulaşılamayan bir oturum 4000 ve Session unavailable nedeniyle kapatır. Bu hataların hiçbiri ayrıca saklanan bir oturumu yok etmez.

Başarılı bir Resume oturumun soketini değiştirir ve oturumun en son seçtiği durum (presence) bilgisini geri yükler. Soketi kopan bir oturum 5.000 ms sonra offline olarak yayımlanır; bu yüzden bundan sonra yapılan bir Resume geri yüklenen durumu yeniden yayımlar.

Resume'u yalnızca yeni bir sokette gönderin: zaten bir oturum bağlı olan bir soketteki Resume 4005 koduyla ve Already authenticated nedeniyle kapatır. Resume, kaynak IP'nin Identify bütçesini de paylaşır ve bütçeyi aşan bir Resume yanıt verilmeden atılır. Sürdürülen oturum hâlâ başka bir sokete bağlıysa, o soket işlem kodu 7 Reconnect alır ve ardından 4000 ile kapanır.

Yeniden bağlanma¶

İşlem kodu 7 Reconnect, istemciden yeni bir WebSocket açmasını ister. Gateway bunu düğüm oturumu boşalttığında, düğüm oturumu başka bir düğüme aktardığında ve başarılı bir Resume'un yerinden ettiği sokete gönderir.

{
  "op": 7
}

Ardından geçerli soket 4000 koduyla ve Session drain requested; reconnect to continue nedeniyle kapanır. Kapanıştan sonraki 60.000 ms içinde gönderilen bir Resume, Oturumu sürdürme bölümündeki sıra numarası sınırlarına bağlı olarak oturumu kurtarabilir.

Geçersiz oturum¶

d: false ile işlem kodu 9, belirtilen oturumun sürdürülemeyeceği anlamına gelir. Gateway bunu Resume bilinmeyen veya süresi dolmuş bir oturumu belirttiğinde ve canlı bir bağlantıya bağlı oturum süreci sona erdiğinde gönderir.

{
  "op": 9,
  "d": false
}

Soket kimliği doğrulanmamış duruma döner; böylece açık kalır ve yeniden Identify yapabilir. TEBHOS hiçbir zaman d: true göndermez.

Oturumlar¶

Oturum Identify ile oluşturulur ve Ready'deki, rastgele 32 karakterlik büyük harfli onaltılık bir dize olan session_id ile tanımlanır. Gateway üzerinde soketten bağımsız olarak yaşar: aktarım sona erdiğinde oturum 60.000 ms boyunca sürdürülebilir kalır. Bir kullanıcı hesabı aynı anda en fazla 100 canlı oturum tutabilir; Sessions Replace olayı ve Ready'deki sessions dizisi, hesabın canlı oturumlarını her birine bildirir.

HTTP API üzerinden bir giriş oturumunu iptal etmek ve bir botu sıfırlamak ya da silmek, eşleşen Gateway oturumlarını sonlandırır.

Sharding¶

İstemci, Identify'da shard değerini bir [shard_id, shard_count] çifti olarak VEREBİLİR (MAY). shard_id, shard_count değerinden küçük, negatif olmayan bir tamsayıdır; shard_count ise 1 ile 16.384 arasındadır. Verilmeyen veya null bir değer hiçbir sharding uygulamaz. Hatalı biçimli bir çift 4010 koduyla ve Invalid shard nedeniyle kapatır.

Bir sunucu, sunucunun snowflake'inin tamsayı değeri üzerinden hesaplanan (guild_id >> 22) % shard_count shard'ına aittir.

Identify sırasında Gateway, hesabın sunucu listesini shard'ın sahip olduğu sunuculara göre filtreler ve oturum yalnızca bunlara bağlanır. Filtrelenen küme aynı zamanda Ready guilds dizisidir. Bir bot oturumunda bu sunucuların her biri kullanılamaz sunucu olarak başlar ve Ready'den sonra her sunucu için bir Guild Create veya Guild Delete gelir. Ready, kabul edilen çifti shard olarak geri yansıtır.

Sunucu tavanına göre yalnızca bot oturumu denetlenir. Shard'ı 2.500'den fazla sunucuya sahip olan bir bot 4011 koduyla ve Sharding required nedeniyle kapatır. Çift vermeyen bir bot, sunucu listesinin tamamına göre denetlenir. Kullanıcı oturumu, sunucu sayısı ne olursa olsun yalnızca 100 oturum sınırıyla sınırlıdır.

TEBHOS'ta büyük bot kademesi, shard sayısı hizalama gereksinimi ve Identify eşzamanlılık kovaları yoktur. GET /gateway/bot sabit olarak tek shard önerir.

Intent'ler¶

TEBHOS'ta intents alanı, intent bitleri ve ayrıcalıklı intent onayı yoktur. Gateway, Identify'daki intents anahtarını yok sayar. İstemci trafiğini, Olay filtreleme bölümünde açıklandığı gibi Lazy Request abonelikleri ve Identify ignored_events listesiyle şekillendirir.

Sıralama¶

Dispatch sıralaması tek bir Gateway oturumu içinde geçerlidir. Shard'lar, HTTP yanıtları veya medya vekili işlemleri arasında toplam bir sıralama oluşturmaz.

Guild Create ve Guild Sync, belirttikleri sunucu için eksiksiz rolleri, kanalları, emojileri, çıkartmaları ve ses durumlarını taşır; istemci saklanan listelerini bunlarla değiştirir. O sunucu için diğer her Dispatch, saklanan bu durumun bir kısmını değiştirir.