162 lines
5.1 KiB
Markdown
162 lines
5.1 KiB
Markdown
# MWSE — Micro Web Socket Engine
|
||
|
||
MWSE, kendisine bağlanan eşleri birbirleriyle eşleştirerek eşler arası veri
|
||
tünelleri oluşturan geniş ölçekli bir WebSocket mikroservis altyapısıdır.
|
||
|
||
Servis; cihazları senkronize etmek, odalar oluşturmak, sohbet ve görüntülü
|
||
görüşme yazılımları için gerçek zamanlı altyapı sağlamak amacıyla kullanılır.
|
||
Sunucu cihazları sanallaştırdığı için eşler birbirlerinin gerçek IP adresini veya
|
||
cihaz bilgisini bilmeden düşük gecikmeli, çift yönlü iletişim kurabilir.
|
||
|
||
## Durum (Go engine, v0.1.0 paritesi ✅)
|
||
|
||
Motor Node.js'ten **Go** ile yeniden yazıldı. Concurrency modeli goroutine +
|
||
`sync.RWMutex` + bağlantı başına tek-yazıcı (actor) deseni üzerine kuruludur;
|
||
Node.js'teki "leave-while-send" race condition ve EventPool promise takılması
|
||
(#33) giderildi.
|
||
|
||
| Özellik | Durum |
|
||
|---|---|
|
||
| WebSocket bağlantı yaşam döngüsü | ✅ |
|
||
| Oda oluşturma / katılma / çıkma | ✅ |
|
||
| Eşleme (pair) sistemi | ✅ |
|
||
| Paket tünelleme (pack/to, pack/room) | ✅ |
|
||
| Veri senkronizasyonu (data/sync, sync/pool) | ✅ |
|
||
| Bildirim + suit yanıtı (notify/send, notify/reply) | ✅ |
|
||
| 3. parti sunucu köprüsü (bridge) | ✅ |
|
||
| İkili çerçeveleme (binary framing) | ⏳ 2.5.0 |
|
||
| Studio (akış/WebRTC sunucusu) | ⏳ 2.0.0 |
|
||
|
||
## Kurulum ve çalıştırma
|
||
|
||
### Gereksinimler
|
||
|
||
- Go 1.22+
|
||
- (Opsiyonel) TypeScript — SDK derlemek için `npm run build`
|
||
|
||
### Sunucuyu başlat
|
||
|
||
```bash
|
||
# Bağımlılıklar
|
||
go mod tidy
|
||
|
||
# Çalıştır (varsayılan: 0.0.0.0:7707)
|
||
go run .
|
||
|
||
# Yapılandırma env değişkenleriyle:
|
||
MWSE_ADDR=:8080 \
|
||
MWSE_OUTBOUND_BUFFER=2048 \
|
||
MWSE_MAX_MESSAGE_SIZE=33554432 \
|
||
go run .
|
||
```
|
||
|
||
### Ortam değişkenleri
|
||
|
||
| Değişken | Varsayılan | Açıklama |
|
||
|---|---|---|
|
||
| `MWSE_ADDR` | `:7707` | Dinleme adresi |
|
||
| `MWSE_OUTBOUND_BUFFER` | `1024` | Bağlantı başına gönderim kuyruğu |
|
||
| `MWSE_MAX_MESSAGE_SIZE` | `16777216` | Maksimum gelen frame boyutu (bayt) |
|
||
| `MWSE_PING_INTERVAL` | `10s` | Heartbeat ping aralığı |
|
||
| `BRIDGE_APPROVE_URL` | — | Bağlantı onay URL'i (3. parti köprü) |
|
||
| `BRIDGE_TRIGGER_URL` | — | Suit yanıtı push URL'i |
|
||
| `BRIDGE_INBOX` | — | `1` ile inbox'ı etkinleştir |
|
||
|
||
### Testler
|
||
|
||
```bash
|
||
go test -race ./...
|
||
```
|
||
|
||
## Frontend SDK entegrasyonu
|
||
|
||
SDK, TypeScript ile yazılmış ve derlenmiş JavaScript olarak `/script`
|
||
endpoint'inden sunulur. Herhangi bir bundler gerekmez.
|
||
|
||
```html
|
||
<!-- Sunucu çalışırken -->
|
||
<script src="http://localhost:7707/script"></script>
|
||
|
||
<script>
|
||
const mwse = new MWSE({
|
||
endpoint: "ws://localhost:7707",
|
||
autoReconnect: true
|
||
});
|
||
|
||
mwse.on('scope', async () => {
|
||
console.log('Bağlandı:', mwse.me.socketId);
|
||
// Oda oluştur / katıl
|
||
const room = mwse.room({ name: 'genel', joinType: 'free', ifexistsJoin: true });
|
||
await room.createRoom();
|
||
room.on('message', (pack, peer) => console.log(peer.socketId, ':', pack));
|
||
room.send({ text: 'merhaba!' });
|
||
});
|
||
</script>
|
||
```
|
||
|
||
## Demo dosyaları
|
||
|
||
| Demo | Yol | Açıklama |
|
||
|---|---|---|
|
||
| Chat | `/demos/chat.html` | ~20 satır JS ile odalı sohbet |
|
||
| Sesli görüşme | `/demos/audio.html` | P2P WebRTC ses (eşler arası) |
|
||
| Video görüşme | `/demos/video.html` | P2P WebRTC video (kamera ızgara görünümü) |
|
||
|
||
## API kontrolü (/api)
|
||
|
||
API anahtarı al, sonra kullan:
|
||
|
||
```bash
|
||
# Anahtar al
|
||
KEY=$(curl -s -X POST localhost:7707/api/auth/key \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"domain":"myapp"}' | jq -r .key)
|
||
|
||
# Tüm odaları listele
|
||
curl -s localhost:7707/api/rooms | jq .
|
||
|
||
# Belirli bir istemciye mesaj gönder
|
||
curl -s -X POST localhost:7707/api/client/<id>/send \
|
||
-H "x-api-key: $KEY" \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"pack": {"hello": "world"}}'
|
||
|
||
# 3. parti köprü — inbox boşalt
|
||
curl -s -X POST localhost:7707/api/bridge/inbox \
|
||
-H "x-api-key: $KEY"
|
||
```
|
||
|
||
## Mimari
|
||
|
||
```
|
||
Client (WebSocket)
|
||
│
|
||
▼
|
||
ws.Hub (router + registry)
|
||
├─ services/auth.go Pairing, IP adresi, erişilebilirlik
|
||
├─ services/room.go Oda oluşturma / yönetimi
|
||
├─ services/datatransfer.go pack/to, request/to, response/to tünelleri
|
||
├─ services/notify.go Store-and-forward bildirim + suit yanıtı
|
||
├─ services/datastore.go Aktif senkronizasyon (CRUD broadcast)
|
||
│ Pasif senkronizasyon (hash-dedup merge pool)
|
||
├─ services/bridge.go 3. parti sunucu inbox (bridge/send)
|
||
└─ services/ippressure.go Sanal IP basıncı
|
||
|
||
httpserver
|
||
├─ GET/POST /api/* Kontrol düzlemi (API anahtarı, oda/istemci yönetimi)
|
||
├─ POST /api/bridge/inbox 3. parti sunucu inbox boşaltma
|
||
└─ /* (WebSocket değilse) SDK (script/index.js) + statik dosyalar
|
||
```
|
||
|
||
## Güvenlik
|
||
|
||
- Bağlı cihazların mesajları **sokete iletilmeden önce** kullanıcılar tarafından
|
||
manipüle edilebilir; MWSE bu doğrulamayı yapmaz. Hassas veriler için
|
||
uygulama katmanında imzalama/şifreleme ekleyin.
|
||
- 3. parti köprü (`BRIDGE_APPROVE_URL`) kullanılıyorsa bağlantı onayı uygulama
|
||
sunucusuna delege edilir (fail-closed: onay gelmezse bağlantı reddedilir).
|
||
|
||
## Geliştirici dökümanı
|
||
|
||
Tüm wiki sayfaları: <https://git.saqut.com/saqut/MWSE/wiki>
|