com.utilities.websockets 1.0.0-preview.1 (#1)

Documentation~/README.md

@@ -0,0 +1,149 @@
+# com.utilities.websockets
+
+[![Discord](https://img.shields.io/discord/855294214065487932.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/xQgMW9ufN4) [![openupm](https://img.shields.io/npm/v/com.utilities.websockets?label=openupm&registry_uri=https://package.openupm.com)](https://openupm.com/packages/com.utilities.websockets/) [![openupm](https://img.shields.io/badge/dynamic/json?color=brightgreen&label=downloads&query=%24.downloads&suffix=%2Fmonth&url=https%3A%2F%2Fpackage.openupm.com%2Fdownloads%2Fpoint%2Flast-month%2Fcom.utilities.websockets)](https://openupm.com/packages/com.utilities.websockets/)
+
+A simple websocket package for the [Unity](https://unity.com/) Game Engine.
+
+## Installing
+
+Requires Unity 2021.3 LTS or higher.
+
+The recommended installation method is though the unity package manager and [OpenUPM](https://openupm.com/packages/com.utilities.websockets).
+
+### Via Unity Package Manager and OpenUPM
+
+- Open your Unity project settings
+- Select the `Package Manager`
+![scoped-registries](images/package-manager-scopes.png)
+- Add the OpenUPM package registry:
+  - Name: `OpenUPM`
+  - URL: `https://package.openupm.com`
+  - Scope(s):
+    - `com.utilities`
+- Open the Unity Package Manager window
+- Change the Registry from Unity to `My Registries`
+- Add the `Utilities.Websockets` package
+
+### Via Unity Package Manager and Git url
+
+- Open your Unity Package Manager
+- Add package from git url: `https://github.com/RageAgainstThePixel/com.utilities.websockets.git#upm`
+  > Note: this repo has dependencies on other repositories! You are responsible for adding these on your own.
+  - [com.utilities.async](https://github.com/RageAgainstThePixel/com.utilities.async)
+
+---
+
+## Documentation
+
+### Table Of Contents
+
+- [Connect to a Server](#connect-to-a-server)
+- [Handling Events](#handling-events)
+  - [OnOpen](#onopen)
+  - [OnMessage](#onmessage)
+  - [OnError](#onerror)
+  - [OnClose](#onclose)
+- [Sending Messages](#sending-messages)
+  - [Text](#sending-text)
+  - [Binary](#sending-binary)
+- [Disconnect from a Server](#disconnect-from-a-server)
+
+### Connect to a Server
+
+To setup a new connection, create a new instance of WebSocket and subscribe to event callbacks, and call `Connect` or `ConnectAsync` methods.
+
+> Note: WebSocket implements `IDisposable` and should be properly disposed after use!
+
+```csharp
+var address = "wss://echo.websocket.events";
+using var socket = new WebSocket(address);
+socket.OnOpen += () => Debug.Log($"Connection Established @ {address}");
+socket.OnMessage += (dataFrame) => {
+    switch (dataFrame.Type)
+    {
+        case OpCode.Text:
+            AddLog($"<- Received: {dataFrame.Text}");
+            break;
+        case OpCode.Binary:
+            AddLog($"<- Received: {dataFrame.Data.Length} Bytes");
+            break;
+    }
+};
+socket.OnError += (exception) => Debug.LogException(exception);
+socket.OnClose += (code, reason) => Debug.Log($"Connection Closed: {code} {reason}");
+socket.Connect();
+```
+
+### Handling Events
+
+You can subscribe to the `OnOpen`, `OnMessage`, `OnError`, and `OnClose` events to handle respective situations:
+
+#### OnOpen
+
+Event triggered when the WebSocket connection has been established.
+
+```csharp
+socket.OnOpen += () => Debug.Log("Connection Established!");
+```
+
+#### OnMessage
+
+Event triggered when the WebSocket receives a message. The callback contains a data frame, which can be either text or binary.
+
+```csharp
+socket.OnMessage += (dataFrame) => {
+    switch (dataFrame.Type)
+    {
+        case OpCode.Text:
+            AddLog($"<- Received: {dataFrame.Text}");
+            break;
+        case OpCode.Binary:
+            AddLog($"<- Received: {dataFrame.Data.Length} Bytes");
+            break;
+    }
+};
+```
+
+#### OnError
+
+Event triggered when the WebSocket raises an error. The callback contains an exception which can be handled, re-thrown, or logged.
+
+```csharp
+socket.OnError += (exception) => Debug.LogException(exception);
+```
+
+#### OnClose
+
+Event triggered when the WebSocket connection has been closed. The callback contains the close code and reason.
+
+```csharp
+socket.OnClose += (code, reason) => Debug.Log($"Connection Closed: {code} {reason}");
+```
+
+### Sending Messages
+
+#### Sending Text
+
+Perfect for sending json payloads and other text messages.
+
+```csharp
+await socket.SendAsync("{\"message\":\"Hello World!\"}");
+```
+
+#### Sending Binary
+
+Perfect for sending binary data and files.
+
+```csharp
+var bytes = System.Text.Encoding.UTF8.GetBytes("Hello World!");
+await socket.SendAsync(bytes);
+```
+
+### Disconnect from a Server
+
+To disconnect from the server, use `Close` or `CloseAsync` methods and dispose of the WebSocket.
+
+```csharp
+socket.Close();
+socket.Dispose();
+```

Editor/AssemblyInfo.cs

@@ -0,0 +1 @@
+// Licensed under the MIT License. See LICENSE in the project root for license information.

Editor/Utilities.Websockets.Editor.asmdef

@@ -0,0 +1,18 @@
+{
+    "name": "Utilities.WebSockets.Editor",
+    "rootNamespace": "Utilities.WebSockets.Editor",
+    "references": [
+        "Utilities.WebSockets"
+    ],
+    "includePlatforms": [
+        "Editor"
+    ],
+    "excludePlatforms": [],
+    "allowUnsafeCode": false,
+    "overrideReferences": false,
+    "precompiledReferences": [],
+    "autoReferenced": true,
+    "defineConstraints": [],
+    "versionDefines": [],
+    "noEngineReferences": false
+}

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 RageAgainstThePixel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Runtime/AssemblyInfo.cs

@@ -0,0 +1 @@
+// Licensed under the MIT License. See LICENSE in the project root for license information.

Runtime/CloseStatusCode.cs

@@ -0,0 +1,80 @@
+// Licensed under the MIT License. See LICENSE in the project root for license information.
+
+namespace Utilities.WebSockets
+{
+    /// <summary>
+    /// When closing an established connection (e.g., when sending a Close frame, after the opening handshake has completed),
+    /// an endpoint MAY indicate a reason for closure.
+    /// </summary>
+    /// <remarks>
+    /// The values of this enumeration are defined in <see href="http://tools.ietf.org/html/rfc6455#section-7.4"/>.<para/>
+    /// </remarks>
+    public enum CloseStatusCode : ushort
+    {
+        /// <summary>
+        /// Indicates a normal closure, meaning that the purpose for which the connection was established has been fulfilled.
+        /// </summary>
+        Normal = 1000,
+        /// <summary>
+        /// Indicates that an endpoint is "going away", such as a server going down or a browser having navigated away from a page.
+        /// </summary>
+        GoingAway = 1001,
+        /// <summary>
+        /// Indicates that an endpoint is terminating the connection due to a protocol error.
+        /// </summary>
+        ProtocolError = 1002,
+        /// <summary>
+        /// Indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept
+        /// (e.g., an endpoint that understands only text data MAY send this if it receives a binary message).
+        /// </summary>
+        UnsupportedData = 1003,
+        /// <summary>
+        /// Reserved and MUST NOT be set as a status code in a Close control frame by an endpoint.<para/>
+        /// The specific meaning might be defined in the future.
+        /// </summary>
+        Reserved = 1004,
+        /// <summary>
+        /// Reserved and MUST NOT be set as a status code in a Close control frame by an endpoint.<para/>
+        /// It is designated for use in applications expecting a status code to indicate that no status code was actually present.
+        /// </summary>
+        NoStatus = 1005,
+        /// <summary>
+        /// Reserved and MUST NOT be set as a status code in a Close control frame by an endpoint.<para/>
+        /// It is designated for use in applications expecting a status code to indicate that the connection was closed abnormally,
+        /// e.g., without sending or receiving a Close control frame.
+        /// </summary>
+        AbnormalClosure = 1006,
+        /// <summary>
+        /// Indicates that an endpoint is terminating the connection because it has received data within a message
+        /// that was not consistent with the type of the message.
+        /// </summary>
+        InvalidPayloadData = 1007,
+        /// <summary>
+        /// Indicates that an endpoint is terminating the connection because it received a message that violates its policy.
+        /// This is a generic status code that can be returned when there is no other more suitable status code (e.g., 1003 or 1009)
+        /// or if there is a need to hide specific details about the policy.
+        /// </summary>
+        PolicyViolation = 1008,
+        /// <summary>
+        /// Indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process.
+        /// </summary>
+        TooBigToProcess = 1009,
+        /// <summary>
+        /// Indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate
+        /// one or more extension, but the server didn't return them in the response message of the WebSocket handshake.
+        /// The list of extensions that are needed SHOULD appear in the /reason/ part of the Close frame. Note that this status code
+        /// is not used by the server, because it can fail the WebSocket handshake instead.
+        /// </summary>
+        MandatoryExtension = 1010,
+        /// <summary>
+        /// Indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.
+        /// </summary>
+        ServerError = 1011,
+        /// <summary>
+        /// Reserved and MUST NOT be set as a status code in a Close control frame by an endpoint.<para/>
+        /// It is designated for use in applications expecting a status code to indicate that the connection was closed due to a failure to perform a TLS handshake
+        /// (e.g., the server certificate can't be verified).
+        /// </summary>
+        TlsHandshakeFailure = 1015
+    }
+}

Runtime/DataFrame.cs

@@ -0,0 +1,24 @@
+// Licensed under the MIT License. See LICENSE in the project root for license information.
+
+using System;
+
+namespace Utilities.WebSockets
+{
+    public class DataFrame
+    {
+        public OpCode Type { get; }
+
+        public ReadOnlyMemory<byte> Data { get; }
+
+        public string Text { get; }
+
+        public DataFrame(OpCode type, ReadOnlyMemory<byte> data)
+        {
+            Type = type;
+            Data = data;
+            Text = type == OpCode.Text
+                ? System.Text.Encoding.UTF8.GetString(data.Span)
+                : string.Empty;
+        }
+    }
+}