Add entity retrieval methods and update EntitiesManager for improved querying

src/FederationServer/Classes/Enums/Method.php

@@ -8,6 +8,9 @@
     use FederationServer\Methods\Attachments\UploadAttachment;
     use FederationServer\Methods\Audit\ListAuditLogs;
     use FederationServer\Methods\Audit\ViewAuditEntry;
+    use FederationServer\Methods\Entities\GetEntity;
+    use FederationServer\Methods\Entities\ListEntities;
+    use FederationServer\Methods\Entities\QueryEntity;
     use FederationServer\Methods\Operators\CreateOperator;
     use FederationServer\Methods\Operators\DeleteOperator;
     use FederationServer\Methods\Operators\DisableOperator;
@@ -37,7 +40,9 @@
         case MANAGE_BLACKLIST_PERMISSION;
         case MANAGE_CLIENT_PERMISSION;
 
+        case GET_ENTITY;
         case LIST_ENTITIES;
+        case QUERY_ENTITY;
         case PUSH_ENTITY;
 
         case UPLOAD_ATTACHMENT;
@@ -74,6 +79,12 @@
                 case self::LIST_ENTITIES:
                     ListEntities::handleRequest();
                     break;
+                case self::QUERY_ENTITY:
+                    QueryEntity::handleRequest();
+                    break;
+                case self::GET_ENTITY:
+                    GetEntity::handleRequest();
+                    break;
                 case self::PUSH_ENTITY:
                     PushEntity::handleRequest();
                     break;
@@ -134,6 +145,8 @@
 
                 $path === '/entities' && $requestMethod === 'GET' => Method::LIST_ENTITIES,
                 $path === '/entities' && $requestMethod === 'POST' => Method::PUSH_ENTITY,
+                preg_match('#^/entities/([a-fA-F0-9\-]{36,})$#', $path) && $requestMethod === 'GET' => Method::GET_ENTITY,
+                $path === '/entities/query' && $requestMethod === 'POST' => Method::QUERY_ENTITY,
 
                 $path === '/operators' && $requestMethod === 'GET' => Method::LIST_OPERATORS,
                 $path === '/operators' && $requestMethod === 'POST' => Method::CREATE_OPERATOR,

src/FederationServer/Classes/Managers/EntitiesManager.php

@@ -51,30 +51,44 @@
          * Retrieves an entity by its ID and domain.
          *
          * @param string $id The ID of the entity.
-         * @param string $domain The domain of the entity.
+         * @param string|null $domain The domain of the entity.
          * @return EntityRecord|null The EntityRecord object if found, null otherwise.
-         * @throws InvalidArgumentException If the ID or domain is not provided or is invalid.
          * @throws DatabaseOperationException If there is an error preparing or executing the SQL statement.
          */
-        public static function getEntityByDomain(string $id, string $domain): ?EntityRecord
+        public static function getEntity(string $id, ?string $domain): ?EntityRecord
         {
-            if(strlen($id) < 1 || strlen($domain) < 1)
+            if(strlen($id) < 1)
             {
                 throw new InvalidArgumentException("Entity ID and domain must be provided.");
             }
 
+            if(!is_null($domain) && !filter_var($domain, FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME))
+            {
+                throw new InvalidArgumentException("Invalid domain format.");
+            }
+
             try
             {
-                $stmt = DatabaseConnection::getConnection()->prepare("SELECT * FROM entities WHERE id = :id AND domain = :domain");
-                $stmt->bindParam(':id', $id);
-                $stmt->bindParam(':domain', $domain);
-                $stmt->execute();
+                if(is_null($domain))
+                {
+                    $stmt = DatabaseConnection::getConnection()->prepare("SELECT * FROM entities WHERE id = :id");
+                    $stmt->bindParam(':id', $id);
+                }
+                else
+                {
+                    $stmt = DatabaseConnection::getConnection()->prepare("SELECT * FROM entities WHERE id = :id AND domain = :domain");
+                    $stmt->bindParam(':id', $id);
+                    $stmt->bindParam(':domain', $domain);
+                }
 
+                $stmt->execute();
                 $data = $stmt->fetch(PDO::FETCH_ASSOC);
+
                 if($data)
                 {
                     return new EntityRecord($data);
                 }
+
                 return null;
             }
             catch (PDOException $e)

src/FederationServer/Methods/Entities/GetEntity.php

@@ -0,0 +1,44 @@
+<?php
+
+    namespace FederationServer\Methods\Entities;
+
+    use FederationServer\Classes\Managers\EntitiesManager;
+    use FederationServer\Classes\Managers\OperatorManager;
+    use FederationServer\Classes\RequestHandler;
+    use FederationServer\Classes\Validate;
+    use FederationServer\Exceptions\DatabaseOperationException;
+    use FederationServer\Exceptions\RequestException;
+    use FederationServer\FederationServer;
+
+    class GetEntity extends RequestHandler
+    {
+        /**
+         * @inheritDoc
+         */
+        public static function handleRequest(): void
+        {
+            if(!preg_match('#^/entities/([a-fA-F0-9\-]{36,})$#', FederationServer::getPath(), $matches))
+            {
+                throw new RequestException('Bad Request: Entity UUID is required', 400);
+            }
+
+            $entityUuid = $matches[1];
+            if(!$entityUuid || !Validate::uuid($entityUuid))
+            {
+                throw new RequestException('Bad Request: Entity UUID is required', 400);
+            }
+
+
+            try
+            {
+                $entityRecord = EntitiesManager::getEntityByUuid($entityUuid);
+            }
+            catch (DatabaseOperationException $e)
+            {
+                throw new RequestException('Internal Server Error: Unable to retrieve entity', 500, $e);
+            }
+
+            self::successResponse($entityRecord->toArray());
+        }
+    }
+

src/FederationServer/Methods/Entities/ListEntities.php

@@ -0,0 +1,44 @@
+<?php
+
+    namespace FederationServer\Methods\Entities;
+
+    use FederationServer\Classes\Managers\EntitiesManager;
+    use FederationServer\Classes\RequestHandler;
+    use FederationServer\Exceptions\DatabaseOperationException;
+    use FederationServer\Exceptions\RequestException;
+    use FederationServer\FederationServer;
+
+    class ListEntities extends RequestHandler
+    {
+        /**
+         * @inheritDoc
+         */
+        public static function handleRequest(): void
+        {
+            $limit = (int) (FederationServer::getParameter('limit') ?? 100);
+            $page = (int) (FederationServer::getParameter('page') ?? 1);
+
+            if($limit < 1)
+            {
+                $limit = 100;
+            }
+
+            if($page < 1)
+            {
+                $page = 1;
+            }
+
+            try
+            {
+                $operators = EntitiesManager::getEntities($limit, $page);
+            }
+            catch (DatabaseOperationException $e)
+            {
+                throw new RequestException('Internal Server Error: Unable to retrieve operators', 500, $e);
+            }
+
+            $result = array_map(fn($op) => $op->toArray(), $operators);
+            self::successResponse($result);
+        }
+    }
+

src/FederationServer/Methods/Entities/QueryEntity.php

@@ -0,0 +1,44 @@
+<?php
+
+    namespace FederationServer\Methods\Entities;
+
+    use FederationServer\Classes\Managers\EntitiesManager;
+    use FederationServer\Classes\Managers\OperatorManager;
+    use FederationServer\Classes\RequestHandler;
+    use FederationServer\Exceptions\DatabaseOperationException;
+    use FederationServer\Exceptions\RequestException;
+    use FederationServer\FederationServer;
+
+    class QueryEntity extends RequestHandler
+    {
+        /**
+         * @inheritDoc
+         */
+        public static function handleRequest(): void
+        {
+            $id = FederationServer::getParameter('id');
+            $domain = FederationServer::getParameter('domain') ?? null;
+
+            if(!$id)
+            {
+                throw new RequestException('Bad Request: Entity ID is required', 400);
+            }
+
+            if(!is_null($domain) && !filter_var($domain, FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME))
+            {
+                throw new RequestException('Bad Request: Invalid domain format', 400);
+            }
+
+            try
+            {
+                $entitiy = EntitiesManager::getEntity($id, $domain);
+            }
+            catch (DatabaseOperationException $e)
+            {
+                throw new RequestException('Internal Server Error: Unable to retrieve entity', 500, $e);
+            }
+
+            self::successResponse($entitiy->toArray());
+        }
+    }
+