# 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>