chore: naming improvements and docs

README-proxying.md

@@ -0,0 +1,67 @@
+<img src="https://docs.momentohq.com/img/logo.svg" alt="logo" width="400"/>
+
+# Using Momento With A Proxy
+
+Momento `SimpleCacheClient` connections can be proxied with relative ease. We'll provide an example here, using
+[HA Proxy](https://www.haproxy.com/) as a layer 4 proxy on localhost.
+
+## Configuring HA Proxy
+
+To configure HA Proxy you'll need two available local ports, one for the control plane and the other for the cache
+plane. You'll also need the hostnames of the actual control plane and cache plane servers that your account is
+configured to connect to. If you're using a JWT to authenticate with Momento, you can extract the hostnames for the
+control plane (cp) and cache plane (c) with the following shell command:
+
+```shell
+echo $MOMENTO_AUTH_TOKEN | awk -F . {'print $2}' | base64 -d
+```
+
+A sample configuration (using nonexistent server hostnames) is as follows:
+
+```text
+frontend control-plane-fe
+  bind localhost:4443
+  option tcplog
+  mode tcp
+  default_backend control-plane-be
+
+backend control-plane-be
+  mode tcp
+  server server1 control.some-control-cell-name.momentohq.com:443
+
+frontend cache-plane-fe
+  bind localhost:4444
+  option tcplog
+  mode tcp
+  default_backend cache-plane-fe
+
+backend cache-plane-fe
+  mode tcp
+  server server1 cache.some-cache-cell-name.momentohq.com:443
+```
+
+## Configuring the Momento Client
+
+Configuring the Momento client to use the proxy requires the same information, which is passed to the credential
+provider. Using the `EnvMomentoTokenProvider`, which reads the token from an environment variable:
+
+```php
+$authProvider = new EnvMomentoTokenProvider(
+    // name of the environment variable that contains our auth token
+    "MOMENTO_AUTH_TOKEN",
+    // host and port to connect to haproxy for the control plane
+    "localhost:4443",
+    // host and port to connect to haproxy for the cache plane
+    "localhost:4444",
+    // host and port to connect haproxy to Momento's control plane
+    "control.some-control-cell-name.momentohq.com:443",
+    // host and port to connect haproxy to Momento's cache plane
+    "cache.some-cache-cell-name.momentohq.com:443"
+);
+```
+
+This configuration instructs the client to connect through the proxy server, **overriding the target name used for SSL
+host name checking**.
+
+----------------------------------------------------------------------------------------
+For more info, visit our website at [https://gomomento.com](https://gomomento.com)!

src/Auth/EnvMomentoTokenProvider.php

@@ -12,17 +12,41 @@ class EnvMomentoTokenProvider implements ICredentialProvider
     private string $authToken;
     private string $controlEndpoint;
     private string $cacheEndpoint;
+    private ?string $trustedControlEndpointCertificateName = null;
+    private ?string $trustedCacheEndpointCertificateName = null;
 
-    public function __construct(string $envVariableName)
+    public function __construct(
+        string  $envVariableName,
+        ?string $controlEndpoint = null,
+        ?string $cacheEndpoint = null,
+        ?string $trustedControlEndpointCertificateName = null,
+        ?string $trustedCacheEndpointCertificateName = null
+    )
     {
         $authToken = getenv($envVariableName);
         if ($authToken === false || isNullOrEmpty($authToken)) {
             throw new InvalidArgumentError("Environment variable $envVariableName is empty or null.");
         }
-        $payload = AuthUtils::parseAuthToken($authToken);
         $this->authToken = $authToken;
-        $this->controlEndpoint = $payload->cp;
-        $this->cacheEndpoint = $payload->c;
+
+        $endpointArgs = [
+            $controlEndpoint, $cacheEndpoint, $trustedCacheEndpointCertificateName, $trustedControlEndpointCertificateName
+        ];
+        if ($this->anyAreDefined($endpointArgs)) {
+            if (!$this->allAreDefined($endpointArgs)) {
+                throw new InvalidArgumentError(
+                    "If any of controlEndpoint, cacheEndpoint, trustedCacheEndpointCertificateName, or " .
+                    "trustedControlEndpointCertificateName are provided, they must all be.");
+            }
+            $this->controlEndpoint = $controlEndpoint;
+            $this->cacheEndpoint = $cacheEndpoint;
+            $this->trustedControlEndpointCertificateName = $trustedControlEndpointCertificateName;
+            $this->trustedCacheEndpointCertificateName = $trustedCacheEndpointCertificateName;
+        } else {
+            $payload = AuthUtils::parseAuthToken($authToken);
+            $this->controlEndpoint = $payload->cp;
+            $this->cacheEndpoint = $payload->c;
+        }
     }
 
     public function getAuthToken(): string
@@ -40,13 +64,23 @@ public function getControlEndpoint(): string
         return $this->controlEndpoint;
     }
 
-    public function getControlProxyEndpoint(): string|null
+    public function getTrustedControlEndpointCertificateName(): string|null
+    {
+        return $this->trustedControlEndpointCertificateName;
+    }
+
+    public function getTrustedCacheEndpointCertificateName(): string|null
+    {
+        return $this->trustedCacheEndpointCertificateName;
+    }
+
+    private function anyAreDefined(array $input): bool
     {
-        return null;
+        return in_array(true, $input);
     }
 
-    public function getCacheProxyEndpoint(): string|null
+    private function allAreDefined(array $input): bool
     {
-        return null;
+        return !in_array(false, $input);
     }
 }

src/Auth/ICredentialProvider.php

@@ -11,7 +11,7 @@ public function getControlEndpoint(): string;
 
     public function getCacheEndpoint(): string;
 
-    public function getControlProxyEndpoint(): string|null;
+    public function getTrustedControlEndpointCertificateName(): string|null;
 
-    public function getCacheProxyEndpoint(): string|null;
+    public function getTrustedCacheEndpointCertificateName(): string|null;
 }

src/Cache/_ControlGrpcManager.php

@@ -19,10 +19,10 @@ class _ControlGrpcManager
 
     public function __construct(ICredentialProvider $authProvider)
     {
-        $endpoint = $authProvider->getControlProxyEndpoint() ?? $authProvider->getControlEndpoint();
+        $endpoint = $authProvider->getControlEndpoint();
         $channelArgs = ["credentials" => ChannelCredentials::createSsl()];
-        if ($authProvider->getControlProxyEndpoint()) {
-            $channelArgs["grpc.ssl_target_name_override"] = $authProvider->getControlEndpoint();
+        if ($authProvider->getTrustedControlEndpointCertificateName()) {
+            $channelArgs["grpc.ssl_target_name_override"] = $authProvider->getTrustedControlEndpointCertificateName();
         }
         $channel = new Channel($endpoint, $channelArgs);
         $interceptors = [

src/Cache/_DataGrpcManager.php

@@ -18,10 +18,10 @@ class _DataGrpcManager
 
     public function __construct(ICredentialProvider $authProvider)
     {
-        $endpoint = $authProvider->getCacheProxyEndpoint() ?? $authProvider->getCacheEndpoint();
+        $endpoint = $authProvider->getCacheEndpoint();
         $channelArgs = ["credentials" => ChannelCredentials::createSsl()];
-        if ($authProvider->getCacheProxyEndpoint()) {
-            $channelArgs["grpc.ssl_target_name_override"] = $authProvider->getCacheEndpoint();
+        if ($authProvider->getTrustedCacheEndpointCertificateName()) {
+            $channelArgs["grpc.ssl_target_name_override"] = $authProvider->getTrustedCacheEndpointCertificateName();
         }
         $channel = new Channel($endpoint, $channelArgs);
         $interceptors = [