Replace Service classes with Resolver pattern

Author: abnegate

src/Resolver.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Utopia\Proxy;
+
+use Utopia\Proxy\Resolver\Exception;
+use Utopia\Proxy\Resolver\Result;
+
+/**
+ * Backend Resolver Interface
+ *
+ * Platform-agnostic interface for resolving resource identifiers to backend endpoints.
+ * Implement this interface to integrate your platform with the proxy.
+ */
+interface Resolver
+{
+    /**
+     * Resolve a resource identifier to a backend endpoint
+     *
+     * @param  string  $resourceId  Protocol-specific identifier (database ID, hostname, etc.)
+     * @return Result Backend endpoint and metadata
+     *
+     * @throws Exception If resource not found or unavailable
+     */
+    public function resolve(string $resourceId): Result;
+
+    /**
+     * Called when a new connection is established
+     *
+     * @param  string  $resourceId  The resource identifier
+     * @param  array<string, mixed>  $metadata  Additional connection metadata
+     */
+    public function onConnect(string $resourceId, array $metadata = []): void;
+
+    /**
+     * Called when a connection is closed
+     *
+     * @param  string  $resourceId  The resource identifier
+     * @param  array<string, mixed>  $metadata  Additional disconnection metadata
+     */
+    public function onDisconnect(string $resourceId, array $metadata = []): void;
+
+    /**
+     * Track activity for a resource
+     *
+     * @param  string  $resourceId  The resource identifier
+     * @param  array<string, mixed>  $metadata  Activity metadata
+     */
+    public function trackActivity(string $resourceId, array $metadata = []): void;
+
+    /**
+     * Invalidate cached resolution data for a resource
+     *
+     * @param  string  $resourceId  The resource identifier
+     */
+    public function invalidateCache(string $resourceId): void;
+
+    /**
+     * Get resolver statistics
+     *
+     * @return array<string, mixed> Statistics data
+     */
+    public function getStats(): array;
+}

src/Resolver/Exception.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Utopia\Proxy\Resolver;
+
+/**
+ * Exception thrown during resolution
+ */
+class Exception extends \Exception
+{
+    public const NOT_FOUND = 404;
+
+    public const UNAVAILABLE = 503;
+
+    public const TIMEOUT = 504;
+
+    public const FORBIDDEN = 403;
+
+    public const INTERNAL = 500;
+
+    /**
+     * @param  array<string, mixed>  $context
+     */
+    public function __construct(
+        string $message,
+        int $code = self::INTERNAL,
+        public readonly array $context = []
+    ) {
+        parent::__construct($message, $code);
+    }
+}

src/Resolver/Result.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Utopia\Proxy\Resolver;
+
+/**
+ * Result of resource resolution
+ */
+class Result
+{
+    /**
+     * @param  string  $endpoint  Backend endpoint in format "host:port"
+     * @param  array<string, mixed>  $metadata  Optional metadata about the resolved backend
+     * @param  int|null  $timeout  Optional connection timeout override in seconds
+     */
+    public function __construct(
+        public readonly string $endpoint,
+        public readonly array $metadata = [],
+        public readonly ?int $timeout = null
+    ) {
+    }
+}