WebSockets#

تتيح WebSockets التواصل ثنائي الاتجاه بين العميل والخادم. على خلاف HTTP الذي يعتمد نمط الطلب والاستجابة، يمكن لأطراف WebSocket إرسال عدد عشوائي من الرسائل في أي من الاتجاهين. تتيح لك واجهة WebSocket في Vapor إنشاء كل من العملاء والخوادم التي تعالج الرسائل بشكل غير متزامن.

الخادم#

يمكن إضافة نقاط نهاية WebSocket إلى تطبيق Vapor الحالي باستخدام واجهة التوجيه (Routing API). استخدم الطريقة webSocket كما تستخدم get أو post.

app.webSocket("echo") { req, ws in
    // Connected WebSocket.
    print(ws)
}

يمكن تجميع مسارات WebSocket وحمايتها بالوسيطة مثل المسارات العادية.

بالإضافة إلى قبول طلب HTTP الوارد، تقبل معالجات WebSocket اتصال WebSocket الذي أُنشئ حديثًا. راجع أدناه لمزيد من المعلومات حول استخدام WebSocket هذا لإرسال الرسائل وقراءتها.

العميل#

للاتصال بنقطة نهاية WebSocket بعيدة، استخدم WebSocket.connect.

WebSocket.connect(to: "ws://echo.websocket.org", on: eventLoop) { ws in
    // Connected WebSocket.
    print(ws)
}

تُرجع الطريقة connect future يكتمل عند إنشاء الاتصال. بمجرد الاتصال، سيُستدعى الإغلاق (closure) المُقدَّم مع WebSocket المتصل حديثًا. راجع أدناه لمزيد من المعلومات حول استخدام WebSocket هذا لإرسال الرسائل وقراءتها.

الرسائل#

يحتوي الصنف WebSocket على طرق لإرسال الرسائل واستقبالها بالإضافة إلى الاستماع للأحداث مثل الإغلاق. يمكن لـ WebSockets نقل البيانات عبر بروتوكولين: نصّي (text) وثنائي (binary). تُفسَّر الرسائل النصية كسلاسل UTF-8، بينما تُفسَّر البيانات الثنائية كمصفوفة من البايتات.

الإرسال#

يمكن إرسال الرسائل باستخدام الطريقة send الخاصة بـ WebSocket.

ws.send("Hello, world")

يؤدي تمرير String إلى هذه الطريقة إلى إرسال رسالة نصية. يمكن إرسال الرسائل الثنائية بتمرير [UInt8].

ws.send([1, 2, 3])

إرسال الرسائل غير متزامن. يمكنك تزويد الطريقة send بـ EventLoopPromise لإخطارك عند انتهاء إرسال الرسالة أو فشلها.

let promise = eventLoop.makePromise(of: Void.self)
ws.send(..., promise: promise)
promise.futureResult.whenComplete { result in
    // Succeeded or failed to send.
}

إذا كنت تستخدم async/await يمكنك استخدام await لانتظار اكتمال العملية غير المتزامنة

try await ws.send(...)

الاستقبال#

تُعالَج الرسائل الواردة عبر ردّي النداء (callbacks) onText وonBinary.

ws.onText { ws, text in
    // String received by this WebSocket.
    print(text)
}

ws.onBinary { ws, binary in
    // [UInt8] received by this WebSocket.
    print(binary)
}

يُقدَّم WebSocket نفسه كأول مُعامِل لردود النداء هذه لمنع الدورات المرجعية (reference cycles). استخدم هذا المرجع لاتخاذ إجراء على WebSocket بعد استقبال البيانات. على سبيل المثال، لإرسال ردّ:

// Echoes received messages.
ws.onText { ws, text in
    ws.send(text)
}

الإغلاق#

لإغلاق WebSocket، استدعِ الطريقة close.

ws.close()

تُرجع هذه الطريقة future سيكتمل عندما يُغلَق WebSocket. مثل send، يمكنك أيضًا تمرير promise إلى هذه الطريقة.

ws.close(promise: nil)

أو استخدم await عليها إذا كنت تستخدم async/await:

try await ws.close()

لإخطارك عندما يُغلق الطرف الآخر الاتصال، استخدم onClose. سيكتمل هذا الـ future عندما يُغلق العميل أو الخادم WebSocket.

ws.onClose.whenComplete { result in
    // Succeeded or failed to close.
}

تُضبط الخاصية closeCode عند إغلاق WebSocket. يمكن استخدام ذلك لتحديد سبب إغلاق الطرف الآخر للاتصال.

Ping / Pong#

تُرسَل رسائل ping وpong تلقائيًا بواسطة العميل والخادم للحفاظ على اتصالات WebSocket حيّة. يمكن لتطبيقك الاستماع لهذه الأحداث باستخدام ردّي النداء onPing وonPong.

ws.onPing { ws in 
    // Ping was received.
}

ws.onPong { ws in
    // Pong was received.
}