Roller ve izinler¶

İzin, bir üyeye sunucuda mesaj göndermek veya başka bir üyeyi yasaklamak gibi tek bir yetenek verir. Rol, bir izin kümesini işaretsiz 64 bitlik bir maske olarak tutar; bir kanalda saklanan izin geçersiz kılma ise bu kümeyi o kanal için ayarlar.

Bu sayfadaki rol yolları bir kullanıcı oturumu token'ını veya bir bot token'ını kabul eder. Sunucu rollerini listele ayrıca guilds kapsamlı bir OAuth2 erişim token'ını da kabul eder; diğer rol yolları geçerli bir erişim token'ını 403 ACCESS_DENIED ile yanıtlar. Sunucunun üyesi olmayan bir çağıran 403 FORBIDDEN alır. Rolleri değiştiren her yol, rol okunmadan önce kontrol edilen MANAGE_ROLES iznini gerektirir.

İzinler¶

TEBHOS'un tanımladığı her bit aşağıda yer alır.

19, 31–36, 38, 39, 41, 42, 44–50 ve 55–63 numaralı bitler atanmamıştır. Tanımlı tüm bitlerin birleşimi 33787032395841535 değeridir.

Yeni bir sunucunun @everyone rolü CREATE_INSTANT_INVITE, ADD_REACTIONS, STREAM, VIEW_CHANNEL, SEND_MESSAGES, EMBED_LINKS, ATTACH_FILES, READ_MESSAGE_HISTORY, USE_EXTERNAL_EMOJIS, CONNECT, SPEAK, USE_VAD, CHANGE_NICKNAME, USE_EXTERNAL_STICKERS ve VIEW_CHANNEL_MEMBERS ile başlar; bu 18014536052624961 değerine karşılık gelir.

TEBHOS tanımlamadığı bitleri atar. Bir rol veya geçersiz kılma yazımı yalnızca tanımlı bitleri tutar ve bir yanıt hiçbir zaman atanmamış bir bit içermez.

const Permissions = {
  VIEW_CHANNEL: 1n << 10n,
  SEND_MESSAGES: 1n << 11n,
  MANAGE_MESSAGES: 1n << 13n,
  ADMINISTRATOR: 1n << 3n,
};

function has(mask, flag) {
  const bits = BigInt(mask);
  return (bits & Permissions.ADMINISTRATOR) !== 0n || (bits & flag) === flag;
}

has("3072", Permissions.SEND_MESSAGES); // true

VIEW_CHANNEL = 1 << 10
SEND_MESSAGES = 1 << 11
ADMINISTRATOR = 1 << 3

def has(mask: str, flag: int) -> bool:
    bits = int(mask)
    return bool(bits & ADMINISTRATOR) or (bits & flag) == flag

has("3072", SEND_MESSAGES)  # True

Özellik kapısına tabi izin bitleri¶

VIEW_CHANNEL_MEMBERS, bir istemci özellik bildirimine bağlıdır. Bu biti anlayan bir istemci, bunu X-Tebhos-Features istek başlığında view_channel_members_permission değerini içeren virgülle ayrılmış bir liste olarak bildirir.

Sunucu rolünü değiştir isteğinde özelliği bildirmeyen bir istek, rolün kayıtlı VIEW_CHANNEL_MEMBERS değerini korur; dolayısıyla bu biti ne ayarlayabilir ne de temizleyebilir. Maskedeki diğer tüm bitler normal şekilde yazılır. Bu, biti onun varlığından haberi olmayan eski istemcilere karşı korur.

İzin hesaplama¶

TEBHOS bir üye için sunucuda ve isteğe bağlı olarak tek bir kanalda tek bir etkin maske hesaplar. Gateway aynı algoritmayı kullanır; böylece REST kontrolleri ile olay teslimi tutarlı olur.

1. Sunucu sahibi tanımlı tüm izinleri alır.
2. Üye olmayan bir kullanıcı boş bir maske alır.
3. Aksi hâlde temel, @everyone rolünün izinleri ile üyeye atanmış tüm rollerin izinlerinin birleşimidir.
4. Temel ADMINISTRATOR içeriyorsa üye tanımlı tüm izinleri alır ve hiçbir geçersiz kılma uygulanmaz.
5. Bir kanal belirtildiyse, o kanalın kendi izin geçersiz kılmaları şu sırayla uygulanır:
   1. @everyone rolü geçersiz kılması: reddedilen bitleri kaldırılır, ardından izin verilen bitleri eklenir.
   2. Üyenin sahip olduğu tüm rollerin geçersiz kılmaları, izin verilen bitlerin tek bir birleşimi ve reddedilen bitlerin tek bir birleşimi olarak toplanır ve tek adımda uygulanır (önce ret kaldırılır, ardından izin eklenir). Dolayısıyla üyenin bir rolündeki izin, başka bir rolündeki reddi yener.
   3. Üyenin kendi geçersiz kılması; önce ret, ardından izin.

Bir kanalın sonucu yalnızca o kanalın kendi geçersiz kılmalarına bağlıdır. Bir kategorinin geçersiz kılmaları kontrol anında devralınmaz; kanal kategoride oluşturulduğunda veya kategoriyle eşitlendiğinde kanala kopyalanır.

Bir kanal, kanal düzeyindeki maskesi VIEW_CHANNEL içerdiğinde üye tarafından görülebilir. Kanal kapsamlı bir istek, kanal mevcut değilse veya çağıranın bulunmadığı bir sunucuya aitse 404, çağıran üye olduğu hâlde VIEW_CHANNEL iznine ya da işlemin gerektirdiği belirli bite sahip değilse 403 döndürür.

Özel kanallar (DM'ler ve grup DM'ler) izin bitleri kullanmaz. Alıcıları, kanalın izin verdiği her şeyi yapabilir.

İletişim zaman aşımı¶

Zaman aşımı (bir sunucu üyesinde gelecekteki bir communication_disabled_until değeri), süresi dolana kadar üyenin sunucuda iletişim kurmasını engeller. Hesaplanan maskeyi değiştirmez: üye rollerinin verdiği tüm izinleri korur ve TEBHOS zaman aşımını ayrıca kontrol eder.

Zaman aşımı etkin olduğu sürece şu işlemler 403 FORBIDDEN ile başarısız olur:

• Mesaj gönderme
• Tepki ekleme
• Ek yükleme isteğinde bulunma
• Yazıyor göstergesini tetikleme
• Üyenin kendi takma adını değiştirme
• Bir ses kanalına katılma

Zaman aşımının özel kanallarda etkisi yoktur. İşlemleri maskeye göre gizleyen bir istemci communication_disabled_until değerini de geçerli zamanla karşılaştırmalıdır, çünkü zaman aşımındaki bir üyenin maskesi hâlâ SEND_MESSAGES içerir. Zaman aşımı uygulamak MODERATE_MEMBERS gerektirir.

Rol hiyerarşisi¶

Roller position değerine göre sıralanır; en yüksek konum ilk sıradadır. Aynı konuma sahip iki rol kimliğe göre sıralanır ve düşük kimlik önce gelir. Bir üyenin sırası, @everyone dışındaki en yüksek rolünün sırasıdır; hiç rolü olmayan bir üye tüm rollerin altında yer alır.

• Çağıran bir rolü yalnızca kendi en yüksek rolü o rolün kesinlikle üstündeyse yönetebilir. Sunucu sahibi tüm rolleri yönetir.
• Çağıran başka bir üye üzerinde (atma, yasaklama, zaman aşımı, takma ad, ses moderasyonu) yalnızca kendi sırası hedefin sırasının kesinlikle üstündeyse işlem yapabilir. Sahip herkes üzerinde işlem yapabilir, sahip üzerinde ise kimse işlem yapamaz.
• ADMINISTRATOR izin kontrollerini atlar, ancak hiyerarşiyi atlamaz.
• MANAGE_ROLES iznini yalnızca @everyone üzerinden alan bir çağıranın sıralı bir rolü yoktur; dolayısıyla hiçbir rolü yönetemez.

MANAGE_ROLES iznine sahip olup hedef rolün üstünde olmayan bir çağıran 403 FORBIDDEN alır.

Sunucu rolü nesnesi¶

@everyone rolünün adı @everyone'dır. Her üye için temel izinleri tanımlar. Silinemez, yeniden sıralanamaz veya ona ayrı gösterim konumu verilemez; adı, hoist ve mentionable değerleri değiştirilemez. Rengi ve izinleri değiştirilebilir.

{
  "id": "1489002177550843904",
  "name": "Moderator",
  "color": 3447003,
  "position": 4,
  "hoist_position": 1,
  "permissions": "1099511639046",
  "hoist": true,
  "mentionable": false,
  "unicode_emoji": null
}

İzin geçersiz kılma nesnesi¶

Bir kanal geçersiz kılmalarını permission_overwrites içinde saklar. Bunları ayarlayan ve silen işlemler Kanallar sayfasında belgelenmiştir.

Aynı bit tek bir geçersiz kılmada hem izin verilmiş hem reddedilmiş olamaz; böyle bir istek 400 BAD_REQUEST ile başarısız olur. Bitler kanal türüne göre filtrelenmez; bu nedenle bir geçersiz kılma, kanalının kullanmadığı bir izni belirtebilir.

{
  "id": "1489002177550843904",
  "type": 0,
  "allow": "0",
  "deny": "2048"
}

Rol konumu nesnesi¶

Rol ayrı gösterim konumu nesnesi¶

Sunucu rollerini listele¶

GET /guilds/{guild_id}/roles

Sunucudaki tüm sunucu rolü nesnelerini azalan position sırasıyla döndürür. Çağıran sunucunun üyesi olmalıdır; herhangi bir izin gerekmez.

guilds kapsamlı bir OAuth2 erişim token'ını da kabul eder; bu kapsamı olmayan bir token 403 MISSING_OAUTH_SCOPE alır.

Hız sınırı: guild:role:list, hesap ve sunucu başına 10 saniyede 60.

curl https://tebhos.com/api/v1/guilds/1489002177550843904/roles \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN"

Sunucu rolü oluştur¶

POST /guilds/{guild_id}/roles

Bir rol oluşturur ve yeni sunucu rolü nesnesini döndürür. MANAGE_ROLES gerektirir. Yeni rol, @everyone rolünün hemen üstünde, 1 konumuna yerleştirilir. Bir sunucuda en fazla 250 rol olabilir; daha fazlasını oluşturmak 400 BAD_REQUEST döndürür.

Hız sınırı: guild:role:create, hesap ve sunucu başına 60 saniyede 10.

Gateway sunucuya GUILD_ROLE_CREATE gönderir.

curl -X POST https://tebhos.com/api/v1/guilds/1489002177550843904/roles \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Helpers", "color": 3447003, "permissions": "8192"}'

Sunucu rolünü değiştir¶

PATCH /guilds/{guild_id}/roles/{role_id}

Bir rolü günceller ve güncellenmiş sunucu rolü nesnesini döndürür. MANAGE_ROLES ve rolün üstünde bir sıra gerektirir. Mevcut olmayan bir rol 404 NOT_FOUND döndürür.

Hız sınırı: guild:role:update, hesap ve sunucu başına 10 saniyede 20.

@everyone için name, hoist, hoist_position ve mentionable yok sayılır. Gateway GUILD_ROLE_UPDATE gönderir.

Sunucu rolü konumlarını değiştir¶

PATCH /guilds/{guild_id}/roles

Rolleri yeniden sıralar. Gövde, rol konumu nesnelerinden oluşan bir JSON dizisidir. MANAGE_ROLES gerektirir. Gövdesiz 204 döndürür.

Hız sınırı: guild:role:positions, hesap ve sunucu başına 10 saniyede 20.

Sahip olmayan biri yalnızca kendi en yüksek rolünün altındaki rolleri taşıyabilir ve bu roller yalnızca kendi aralarında yer değiştirir; çağıranın yönetemediği roller yerinde kalır. Değişiklikten sonra konumlar, @everyone üstündeki roller 1'den rol sayısına kadar gidecek şekilde yeniden numaralandırılır.

Gateway tüm rollerle birlikte GUILD_ROLE_UPDATE_BULK gönderir.

curl -X PATCH https://tebhos.com/api/v1/guilds/1489002177550843904/roles \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": "1489002177550843905", "position": 3}, {"id": "1489002177550843906", "position": 2}]'

Rol ayrı gösterim konumlarını değiştir¶

PATCH /guilds/{guild_id}/roles/hoist-positions

Ayrı gösterilen rollerin üye listesindeki sırasını ayarlar. Gövde, rol ayrı gösterim konumu nesnelerinden oluşan bir JSON dizisidir. MANAGE_ROLES gerektirir ve sahip olmayan biri dizideki her rolün üstünde olmalıdır. 204 döndürür.

Hız sınırı: guild:role:hoist_positions, hesap ve sunucu başına 10 saniyede 20.

@everyone rolünü veya bilinmeyen bir rolü belirten bir girdi 400 BAD_REQUEST; çağıranın yönetemediği bir rol ise 403 FORBIDDEN döndürür. Tüm girdiler geçerli olmadıkça hiçbir şey yazılmaz. Gateway GUILD_ROLE_UPDATE_BULK gönderir.

Rol ayrı gösterim konumlarını sıfırla¶

DELETE /guilds/{guild_id}/roles/hoist-positions

Tüm rollerde hoist_position değerini temizler; böylece ayrı gösterilen roller yeniden position değerine göre sıralanır. MANAGE_ROLES gerektirir. 204 döndürür.

Hız sınırı: guild:role:hoist_positions_reset, hesap ve sunucu başına 60 saniyede 10.

Sunucu rolünü sil¶

DELETE /guilds/{guild_id}/roles/{role_id}

Bir rolü siler ve onu taşıyan tüm üyelerden kaldırır. MANAGE_ROLES ve rolün üstünde bir sıra gerektirir. 204 döndürür.

Hız sınırı: guild:role:delete, hesap ve sunucu başına 60 saniyede 10.

Mevcut olmayan bir rol ve @everyone rolü 404 NOT_FOUND döndürür. Silme işlemi denetim kaydına yazılır.

Rol atama¶

Bir üyeye rol eklemek ve kaldırmak için PUT ve DELETE /guilds/{guild_id}/members/{user_id}/roles/{role_id} kullanılır; bunlar Sunucu üyeleri sayfasında belgelenmiştir. Her ikisi de MANAGE_ROLES ve rolün üstünde bir sıra gerektirir.