From 178e16627f2f8bd57d8cfd56f9ed80c85db081c7 Mon Sep 17 00:00:00 2001
From: netkas <netkas@nosial.net>
Date: Fri, 13 Sep 2024 13:50:50 -0400
Subject: [PATCH] Add new Enums to enhance error handling and session
 management

---
 src/Socialbox/Enums/ReservedUsernames.php     | 10 ++++
 .../Enums/SecondLevelAuthentication.php       |  8 +++
 src/Socialbox/Enums/SessionState.php          | 21 +++++++
 src/Socialbox/Enums/StandardError.php         | 46 +++++++++++++++
 src/Socialbox/Enums/StandardHeaders.php       | 59 +++++++++++++++++++
 src/Socialbox/Enums/StandardMethods.php       | 26 ++++++++
 src/Socialbox/Enums/StandardResponseCodes.php | 27 +++++++++
 7 files changed, 197 insertions(+)
 create mode 100644 src/Socialbox/Enums/ReservedUsernames.php
 create mode 100644 src/Socialbox/Enums/SecondLevelAuthentication.php
 create mode 100644 src/Socialbox/Enums/SessionState.php
 create mode 100644 src/Socialbox/Enums/StandardError.php
 create mode 100644 src/Socialbox/Enums/StandardHeaders.php
 create mode 100644 src/Socialbox/Enums/StandardMethods.php
 create mode 100644 src/Socialbox/Enums/StandardResponseCodes.php

diff --git a/src/Socialbox/Enums/ReservedUsernames.php b/src/Socialbox/Enums/ReservedUsernames.php
new file mode 100644
index 0000000..651d22b
--- /dev/null
+++ b/src/Socialbox/Enums/ReservedUsernames.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace Socialbox\Enums;
+
+enum ReservedUsernames : string
+{
+    case HOST = 'host';
+    case ANONYMOUS = 'anonymous';
+    case ADMIN = 'admin';
+}
\ No newline at end of file
diff --git a/src/Socialbox/Enums/SecondLevelAuthentication.php b/src/Socialbox/Enums/SecondLevelAuthentication.php
new file mode 100644
index 0000000..2d785e7
--- /dev/null
+++ b/src/Socialbox/Enums/SecondLevelAuthentication.php
@@ -0,0 +1,8 @@
+<?php
+
+namespace Socialbox\Enums;
+
+enum SecondLevelAuthentication : string
+{
+    case ONE_TIME_PASSWORD = 'OTP';
+}
\ No newline at end of file
diff --git a/src/Socialbox/Enums/SessionState.php b/src/Socialbox/Enums/SessionState.php
new file mode 100644
index 0000000..f277d2b
--- /dev/null
+++ b/src/Socialbox/Enums/SessionState.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace Socialbox\Enums;
+
+enum SessionState : string
+{
+    /**
+     * The session is currently active and usable
+     */
+    case ACTIVE = 'ACTIVE';
+
+    /**
+     * The session has expired and is no longer usable
+     */
+    case EXPIRED = 'EXPIRED';
+
+    /**
+     * The session was closed either by the client or the server and is no longer usable
+     */
+    case CLOSED = 'CLOSED';
+}
\ No newline at end of file
diff --git a/src/Socialbox/Enums/StandardError.php b/src/Socialbox/Enums/StandardError.php
new file mode 100644
index 0000000..f8e6174
--- /dev/null
+++ b/src/Socialbox/Enums/StandardError.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace Socialbox\Enums;
+
+enum StandardError : int
+{
+    // Fallback Codes
+    case UNKNOWN = -1;
+
+    // RPC Errors
+    case RPC_METHOD_NOT_FOUND = -1000;
+    case RPC_INVALID_ARGUMENTS = -1001;
+
+    // Server Errors
+    case INTERNAL_SERVER_ERROR = -2000;
+    case SERVER_UNAVAILABLE = -2001;
+
+    // Authentication/Cryptography Errors
+    case INVALID_PUBLIC_KEY = -3000;
+    case SESSION_NOT_FOUND = -3001;
+    case UNSUPPORTED_AUTHENTICATION_TYPE = -3002;
+
+    /**
+     * Returns the default generic message for the error
+     *
+     * @return string
+     */
+    public function getMessage(): string
+    {
+        return match ($this)
+        {
+            self::UNKNOWN => 'Unknown Error',
+
+            self::RPC_METHOD_NOT_FOUND => 'The request method was not found',
+            self::RPC_INVALID_ARGUMENTS => 'The request method contains one or more invalid arguments',
+
+            self::INTERNAL_SERVER_ERROR => 'Internal server error',
+            self::SERVER_UNAVAILABLE => 'Server temporarily unavailable',
+
+            self::INVALID_PUBLIC_KEY => 'The given public key is not valid',
+            self::SESSION_NOT_FOUND => 'The requested session UUID was not found',
+            self::UNSUPPORTED_AUTHENTICATION_TYPE => 'The requested authentication type is not supported by the server'
+        };
+
+    }
+}
\ No newline at end of file
diff --git a/src/Socialbox/Enums/StandardHeaders.php b/src/Socialbox/Enums/StandardHeaders.php
new file mode 100644
index 0000000..ec0b6fb
--- /dev/null
+++ b/src/Socialbox/Enums/StandardHeaders.php
@@ -0,0 +1,59 @@
+<?php
+
+namespace Socialbox\Enums;
+
+/**
+ * Enumeration of standard header names used in HTTP communication.
+ */
+enum StandardHeaders : string
+{
+    case CONTENT_TYPE = 'Content-Type';
+    case CLIENT_NAME = 'Client-Name';
+    case CLIENT_VERSION = 'Client-Version';
+    case SESSION_UUID = 'Session-UUID';
+    case FROM_PEER = 'From-Peer';
+    case SIGNATURE = 'Signature';
+
+    /**
+     * Determines if the current instance is required based on its type.
+     *
+     * @return bool Returns true if the instance is of type CONTENT_TYPE, CLIENT_VERSION, or CLIENT_NAME; otherwise, false.
+     */
+    public function isRequired(): bool
+    {
+        return match($this)
+        {
+            self::CONTENT_TYPE,
+            self::CLIENT_VERSION,
+            self::CLIENT_NAME
+                => true,
+
+            default => false,
+        };
+    }
+
+    /**
+     * Retrieves an array of required headers.
+     *
+     * @return array An array containing only the headers that are marked as required.
+     */
+    public static function getRequiredHeaders(): array
+    {
+        /** @var StandardHeaders $header */
+        return array_filter(StandardHeaders::toArray(), fn($header) => $header->isRequired());
+    }
+
+    /**
+     * @return array
+     */
+    public static function toArray(): array
+    {
+        $results = [];
+        foreach(StandardHeaders::values() as $header)
+        {
+            $results[$header->getValue()] = $header;
+        }
+
+        return $results;
+    }
+}
\ No newline at end of file
diff --git a/src/Socialbox/Enums/StandardMethods.php b/src/Socialbox/Enums/StandardMethods.php
new file mode 100644
index 0000000..456d2b7
--- /dev/null
+++ b/src/Socialbox/Enums/StandardMethods.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace Socialbox\Enums;
+
+use Socialbox\Classes\StandardMethods\CreateSession;
+use Socialbox\Classes\StandardMethods\Ping;
+use Socialbox\Interfaces\SerializableInterface;
+use Socialbox\Objects\ClientRequest;
+use Socialbox\Objects\RpcRequest;
+
+enum StandardMethods : string
+{
+    case PING = 'ping';
+    case CREATE_SESSION = 'create_session';
+
+    public function execute(ClientRequest $request, RpcRequest $rpcRequest): ?SerializableInterface
+    {
+        return match ($this)
+        {
+            self::PING => Ping::execute($request, $rpcRequest),
+            self::CREATE_SESSION => CreateSession::execute($request, $rpcRequest),
+
+            default => $rpcRequest->produceError(StandardError::RPC_METHOD_NOT_FOUND, sprintf('The method %s is not handled by the server', $this->value)),
+        };
+    }
+}
\ No newline at end of file
diff --git a/src/Socialbox/Enums/StandardResponseCodes.php b/src/Socialbox/Enums/StandardResponseCodes.php
new file mode 100644
index 0000000..a6c1769
--- /dev/null
+++ b/src/Socialbox/Enums/StandardResponseCodes.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace Socialbox\Enums;
+
+enum StandardResponseCodes : int
+{
+    /**
+     * The RPC Request was successful
+     */
+    case OK = 200;
+
+    /**
+     * The RPC Request was successful but no response was returned
+     */
+    case EMPTY = 204;
+
+    /**
+     * Bad RPC Request, fatal issue with how the client is producing the requests.
+     */
+    case BAD_REQUEST = 400;
+
+    /**
+     * Unexpected Internal Server error, general catch-all for anything RPC out outside related.
+     * Anything internal via an RPC request should return the RpcError with the error code -2000
+     */
+    case INTERNAL_SERVER_ERROR = 500;
+}
\ No newline at end of file