WebSockets¶

WebSockets maken tweerichtingscommunicatie tussen een client en server mogelijk. In tegenstelling tot HTTP, dat een verzoek en antwoord patroon heeft, kunnen WebSocket peers een willekeurig aantal berichten in beide richtingen sturen. Vapor's WebSocket API maakt het mogelijk om zowel clients als servers te maken die berichten asynchroon afhandelen.

Server¶

WebSocket endpoints kunnen worden toegevoegd aan uw bestaande Vapor applicatie met behulp van de Routing API. Gebruik de webSocket methode zoals u get of post zou gebruiken.

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

WebSocket routes kunnen worden gegroepeerd en worden beschermd door middleware zoals normale routes.

Naast het accepteren van het inkomende HTTP verzoek, accepteren WebSocket handlers ook de nieuw opgezette WebSocket verbinding. Zie hieronder voor meer informatie over het gebruik van deze WebSocket voor het verzenden en lezen van berichten.

Client¶

Om verbinding te maken met een WebSocket eindpunt op afstand, gebruik WebSocket.connect.

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

De connect methode retourneert een future die wordt afgesloten als de verbinding tot stand is gebracht. Eenmaal verbonden zal de meegeleverde closure aangeroepen worden met de zojuist verbonden WebSocket. Zie hieronder voor meer informatie over het gebruik van deze WebSocket om berichten te versturen en te lezen.

Berichten¶

De WebSocket klasse heeft methoden voor het zenden en ontvangen van berichten en voor het luisteren naar gebeurtenissen zoals sluiting. WebSockets kunnen gegevens verzenden via twee protocollen: tekst en binair. Tekst berichten worden geïnterpreteerd als UTF-8 strings, terwijl binaire gegevens worden geïnterpreteerd als een array van bytes.

Versturen¶

Berichten kunnen worden verzonden met de WebSocket send methode.

ws.send("Hello, world")

Het doorgeven van een String aan deze methode resulteert in het versturen van een tekst bericht. Binaire berichten kunnen worden verzonden door een [UInt8] door te geven.

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

Het verzenden van berichten is asynchroon. Je kunt een EventLoopPromise meegeven aan de send method om een bericht te krijgen wanneer het bericht klaar is met verzenden of wanneer het verzenden mislukt is.

let promise = eventLoop.makePromise(of: Void.self)
ws.send(..., promise: promise)
promise.futureResult.whenComplete { result in
    // Is gelukt of niet gelukt om te verzenden.
}

Als u async/await gebruikt kunt u "wachten" op het resultaat

// TODO Check this actually works
let result = try await ws.send(...)

Ontvangen¶

Inkomende berichten worden afgehandeld via de onText en onBinary callbacks.

ws.onText { ws, text in
    // String ontvangen door deze WebSocket.
    print(text)
}

ws.onBinary { ws, binary in
    // [UInt8] ontvangen door deze WebSocket.
    print(binary)
}

De WebSocket zelf wordt als eerste parameter aan deze callbacks meegegeven om referentie cycli te voorkomen. Gebruik deze referentie om actie te ondernemen op de WebSocket na ontvangst van data. Bijvoorbeeld om een antwoord te sturen:

// Echo's van ontvangen berichten.
ws.onText { ws, text in
    ws.send(text)
}

Afsluiten¶

Om een WebSocket af te sluiten, roep de close methode op.

ws.close()

Deze methode retourneert een future die voltooid zal worden als de WebSocket gesloten is. Net als send, mag je ook een promise doorgeven aan deze methode.

ws.close(promise: nil)

Of "wacht" erop als je async/await gebruikt:

try await ws.close()

Om een melding te krijgen wanneer de peer de verbinding sluit, gebruik onClose. Deze future wordt uitgevoerd wanneer ofwel de client ofwel de server de WebSocket sluit.

ws.onClose.whenComplete { result in
    // Geslaagd of mislukt om te sluiten.
}

De closeCode eigenschap wordt ingesteld wanneer de WebSocket sluit. Dit kan gebruikt worden om te bepalen waarom de peer de verbinding heeft gesloten.

Ping / Pong¶

Ping en pong berichten worden automatisch verzonden door de client en server om WebSocket verbindingen in leven te houden. Je applicatie kan luisteren naar deze events door gebruik te maken van de onPing en onPong callbacks.

ws.onPing { ws in 
    // Ping is ontvangen.
}

ws.onPong { ws in
    // Pong werd ontvangen.
}