WebSocket¶

WebSocket è un protocollo di comunicazione bidirezionale usato per trasmettere messaggi tra client e server. A differenza di HTTP, che utilizza un pattern di richiesta-risposta, i WebSocket consentono di inviare un numero arbitrario di messaggi in entrambe le direzioni. L'API WebSocket di Vapor ti permette di creare sia client che server che gestiscono messaggi in modo asincrono.

Server¶

Gli endpoint WebSocket possono essere aggiunti alla tua applicazione Vapor esistente utilizzando l'API di routing. Usa il metodo webSocket come faresti con get o post.

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

Le route WebSocket possono essere raggruppate e protette da middleware come le normali route.

Oltre ad accettare la richiesta HTTP in ingresso, i gestori WebSocket accettano la connessione WebSocket appena stabilita. Vedi sotto per ulteriori informazioni sull'utilizzo di questo WebSocket per inviare e leggere messaggi.

Client¶

Per connetterti a un endpoint WebSocket remoto, usa WebSocket.connect.

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

Il metodo connect restituisce un future che si completa quando la connessione è stabilita. Una volta connesso, il blocco fornito verrà chiamato con il WebSocket appena connesso. Vedi sotto per ulteriori informazioni sull'utilizzo di questo WebSocket per inviare e leggere messaggi.

Messaggi¶

La classe WebSocket ha metodi per inviare e ricevere messaggi e per ascoltare eventi come la chiusura. I WebSocket possono trasmettere dati tramite due protocolli: testo e binario. I messaggi di testo sono interpretati come stringhe UTF-8 mentre i dati binari sono interpretati come un array di byte.

Invio¶

I messaggi possono essere inviati utilizzando il metodo send del WebSocket.

ws.send("Ciao, mondo")

Passare una String a questo metodo comporta l'invio di un messaggio di testo. I messaggi binari possono essere inviati passando un [UInt8].

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

L'invio di messaggi è asincrono. Puoi fornire una EventLoopPromise al metodo di invio per essere notificato quando il messaggio è stato inviato o non è stato possibile inviarlo.

let promise = eventLoop.makePromise(of: Void.self)
ws.send(..., promise: promise)
promise.futureResult.whenComplete { result in
    // Riuscito o non riuscito a inviare.
}

Se stai usando async/await puoi usare await per attendere il completamento dell'operazione asincrona.

try await ws.send(...)

Ricezione¶

I messaggi possono essere ricevuti utilizzando il metodo onText o onBinary del WebSocket.

ws.onText { ws, text in
    // Testo ricevuto.
    print(text)
}

ws.onBinary { ws, binary in
    // [UInt8] ricevuto.
    print(binary)
}

Il primo argomento del blocco di callback è il WebSocket stesso. Questo permette l'accesso al WebSocket all'interno del callback senza creazione di riferimenti circolari.

// Stampa il messagio ricevuto
ws.onText { ws, text in
    print(text)
}

Chiusura¶

Per chiudere il WebSocket, chiama il metodo close.

ws.close()

Questo metodo ritorna un future che si completa quando la connessione è stata chiusa. Come per l'invio di messaggi, puoi fornire una EventLoopPromise per essere notificato quando la connessione è stata chiusa.

ws.close(promise: nil)

Oppure puoi attendere la chiusura del WebSocket utilizzando await.

try await ws.close()

Per essere notificato quando il WebSocket è stato chiuso, dal server o dal client che sia, puoi ascoltare l'evento onClose.

ws.onClose.whenComplete { result in
    // WebSocket chiuso.
}

La proprietà closeCode del WebSocket contiene il codice di chiusura inviato dal peer, e può essere utilizzato per determinare il motivo per cui la connessione è stata chiusa.

Ping / Pong¶

Dei messaggi di ping e pong vengono inviati automaticamente dal client e dal server per mantenere attive le connessioni WebSocket. La tua applicazione può ascoltare questi eventi utilizzando i callback onPing e onPong.

ws.onPing { ws in 
    // Ping ricevuto.
}

ws.onPong { ws in
    // Pong ricevuto.
}