New: copy of the websockets.md file for reference

Author: TheHandyOwl

docs/advanced/websockets.es.md

@@ -0,0 +1,134 @@
+# WebSockets
+
+[WebSockets](https://en.wikipedia.org/wiki/WebSocket) allow for two-way communication between a client and server. Unlike HTTP, which has a request and response pattern, WebSocket peers can send an arbitrary number of messages in either direction. Vapor's WebSocket API allows you to create both clients and servers that handle messages asynchronously.
+
+## Server
+
+WebSocket endpoints can be added to your existing Vapor application using the Routing API. Use the `webSocket` method like you would use `get` or `post`. 
+
+```swift
+app.webSocket("echo") { req, ws in
+    // Connected WebSocket.
+    print(ws)
+}
+```
+
+WebSocket routes can be grouped and protected by middleware like normal routes. 
+
+In addition to accepting the incoming HTTP request, WebSocket handlers accept the newly established WebSocket connection. See below for more information on using this WebSocket to send and read messages.
+
+## Client
+
+To connect to a remote WebSocket endpoint, use `WebSocket.connect`. 
+
+```swift
+WebSocket.connect(to: "ws://echo.websocket.org", on: eventLoop) { ws in
+    // Connected WebSocket.
+    print(ws)
+}
+```
+
+The `connect` method returns a future that completes when the connection is established. Once connected, the supplied closure will be called with the newly connected WebSocket. See below for more information on using this WebSocket to send and read messages.
+
+## Messages
+
+The `WebSocket` class has methods for sending and receiving messages as well as listening for events like closure. WebSockets can transmit data via two protocols: text and binary. Text messages are interpreted as UTF-8 strings while binary data is interpreted as an array of bytes.
+
+### Sending
+
+Messages can be sent using the WebSocket's `send` method.
+
+```swift
+ws.send("Hello, world")
+```
+
+Passing a `String` to this method results in a text message being sent. Binary messages can be sent by passing a `[UInt8]`. 
+
+```swift
+ws.send([1, 2, 3])
+```
+
+Message sending is asynchronous. You can supply an `EventLoopPromise` to the send method to be notified when the message has finished sending or failed to send. 
+
+```swift
+let promise = eventLoop.makePromise(of: Void.self)
+ws.send(..., promise: promise)
+promise.futureResult.whenComplete { result in
+    // Succeeded or failed to send.
+}
+```
+
+If using `async`/`await` you can use `await` to wait for the asynchronous operation to complete
+
+```swift
+try await ws.send(...)
+```
+
+### Receiving
+
+Incoming messages are handled via the `onText` and `onBinary` callbacks.
+
+```swift
+ws.onText { ws, text in
+    // String received by this WebSocket.
+    print(text)
+}
+
+ws.onBinary { ws, binary in
+    // [UInt8] received by this WebSocket.
+    print(binary)
+}
+```
+
+The WebSocket itself is supplied as the first parameter to these callbacks to prevent reference cycles. Use this reference to take action on the WebSocket after receiving data. For example, to send a reply:
+
+```swift
+// Echoes received messages.
+ws.onText { ws, text in
+    ws.send(text)
+}
+```
+
+## Closing
+
+To close a WebSocket, call the `close` method. 
+
+```swift
+ws.close()
+```
+
+This method returns a future that will be completed when the WebSocket has closed. Like `send`, you may also pass a promise to this method.
+
+```swift
+ws.close(promise: nil)
+```
+
+Or `await` on it if using `async`/`await`:
+
+```swift
+try await ws.close()
+```
+
+To be notified when the peer closes the connection, use `onClose`. This future will be completed when either the client or server closes the WebSocket.
+
+```swift
+ws.onClose.whenComplete { result in
+    // Succeeded or failed to close.
+}
+```
+
+The `closeCode` property is set when the WebSocket closes. This can be used to determine why the peer closed the connection.
+
+## Ping / Pong
+
+Ping and pong messages are sent automatically by the client and server to keep WebSocket connections alive. Your application can listen for these events using the `onPing` and `onPong` callbacks.
+
+```swift
+ws.onPing { ws in 
+    // Ping was received.
+}
+
+ws.onPong { ws in
+    // Pong was received.
+}
+```