OpenCommunicate docs

How it works

A chat is one private GitHub repository. Every message is a file, written through GitHub's Git Data API; every client polls the branch and reads what changed.

One file per message

Two devices writing at once never touch the same path, so only the branch pointer can race, and a write that loses the race is rebuilt on the new head and retried. A message and its attachments land in one commit.

opencommunicate.json                     { protocol: 1, name, createdAt }
devices/<id>.json                        { id, nick, kind, login, joinedAt, notify?, quiet?, picture? }
auth/<id>.json                           salted PBKDF2-SHA256 hash of the account's password
channels/all/<message>.json              everyone
channels/dm-<a>-<b>/<message>.json       two accounts, ids sorted
channels/g-<slug>-<rand>/meta.json       { channel, name, members, admins, createdBy, createdAt }
channels/<channel>/files/<id>-<name>     attachments
branch "presence": presence/<id>.json    { id, lastSeen }
branch "receipts": receipts/<id>.json    { id, channels: { <channel>: { delivered?, read? } } }
branch "pins":     pins/<id>.json        { id, pins: [{ channel, id, at }] }

A message file is named <UTC time>-<sender id>-<random>.json, so names sort by time. Receipts, presence and pins live on branches of their own, so they never add history to the chat itself.

Sync

Clients poll the branch head with an ETag. While nothing moved GitHub answers 304, which costs nothing against the rate limit; when it moves, the client asks GitHub which files changed. The apps poll every 4 seconds while open, so messages arrive within about 5 seconds.

Accounts and rules

Everyone is nick#id, with a four-digit id picked at join. Group rules (who is admin, who may add members) and password checks are kept by the clients: there is no server, so anyone with write access to the repository could edit its files by hand. The privacy boundary is the repository.

Limits

  • GitHub keeps every file in history, so large attachments make the repository grow. Files are capped at 50 MB.
  • Polling means seconds, not milliseconds.
  • Messages sit in the private repository as plain JSON; there is no end-to-end encryption yet.

The full format, field by field: docs/PROTOCOL.md.

Nasıl çalışır

Bir sohbet, tek bir özel GitHub reposudur. Her mesaj GitHub'ın Git Data API'siyle yazılan bir dosyadır; her istemci dalı yoklar ve değişeni okur.

Mesaj başına bir dosya

Aynı anda yazan iki cihaz asla aynı dosyaya dokunmaz; yalnızca dal işaretçisi için yarışabilirler, yarışı kaybeden yazma yeni uç üzerinde yeniden kurulup tekrar denenir. Bir mesaj ve ekleri tek bir commit'te gider.

opencommunicate.json                     { protocol: 1, name, createdAt }
devices/<id>.json                        { id, nick, kind, login, joinedAt, notify?, quiet?, picture? }
auth/<id>.json                           salted PBKDF2-SHA256 hash of the account's password
channels/all/<message>.json              everyone
channels/dm-<a>-<b>/<message>.json       two accounts, ids sorted
channels/g-<slug>-<rand>/meta.json       { channel, name, members, admins, createdBy, createdAt }
channels/<channel>/files/<id>-<name>     attachments
branch "presence": presence/<id>.json    { id, lastSeen }
branch "receipts": receipts/<id>.json    { id, channels: { <channel>: { delivered?, read? } } }
branch "pins":     pins/<id>.json        { id, pins: [{ channel, id, at }] }

Mesaj dosyasının adı <UTC zaman>-<gönderen id>-<rastgele>.json biçimindedir, böylece adlar zamana göre sıralanır. Okundu bilgisi, çevrimiçi durumu ve sabitlemeler kendi dallarında durur; sohbetin geçmişine ekleme yapmazlar.

Eşitleme

İstemciler dalın ucunu ETag ile yoklar. Hiçbir şey değişmediyse GitHub 304 döner ve bu, istek sınırından bir şey yemez; uç değişince istemci GitHub'a hangi dosyaların değiştiğini sorar. Uygulamalar açıkken 4 saniyede bir yoklar, mesajlar yaklaşık 5 saniye içinde gelir.

Hesaplar ve kurallar

Herkes katılırken seçilen dört haneli bir kimlikle nick#id'dir. Grup kuralları (kim yönetici, kim üye ekleyebilir) ve şifre kontrolleri istemcilerde uygulanır: sunucu olmadığı için repoya yazma izni olan biri dosyaları elle değiştirebilir. Gizlilik sınırı repodur.

Sınırlar

  • GitHub her dosyayı geçmişte sonsuza kadar tutar, büyük ekler repoyu büyütür. Dosyalar en fazla 50 MB.
  • Yoklama milisaniye değil saniye demektir.
  • Mesajlar özel repoda düz JSON olarak durur; uçtan uca şifreleme henüz yok.

Alan alan tam biçim: docs/PROTOCOL.md (İngilizce).