Fix generator and add proxies/patches for backward compatibility (#204)

Signed-off-by: saimedhi <saimedhi@amazon.com>

util/ClientEndpoint.php

@@ -48,6 +48,12 @@ public function renderClass(): string
         $class = file_get_contents(self::CLIENT_CLASS_TEMPLATE);
         // use Namespace
         $useNamespace = '';
+
+        // The following namespaces do not have OpenSearch API specifications
+        $patchnamespaces = ['async_search', 'searchable_snapshots', 'ssl', 'sql', 'data_frame_transform_deprecated', 'monitoring'];
+        $this->namespace = array_unique(array_merge($this->namespace, $patchnamespaces));
+        sort($this->namespace);
+
         foreach ($this->namespace as $name) {
             if (empty($name)) {
                 continue;
@@ -89,6 +95,13 @@ public function renderClass(): string
         foreach ($this->endpoints as $endpoint) {
             $endpoints .= $this->renderEndpoint($endpoint);
         }
+        $proxyFolder = 'util/endpointproxies/';
+        if (is_dir($proxyFolder)) {
+            $proxyFiles = glob($proxyFolder . '/*.php');
+            foreach ($proxyFiles as $file) {
+                $endpoints .= require $file;
+            }
+        }
         $class = str_replace(':endpoints', $endpoints, $class);
 
         // Namespace functions

util/Endpoint.php

@@ -94,7 +94,7 @@ public function __construct(
         $this->content = $this->content[$this->apiName];
 
         $this->parts = $this->getPartsFromContent($this->content);
-        $this->requiredParts = $this->getRequiredParts($this->content);
+        $this->requiredParts = $this->getRequiredParts($this->content, $this->namespace);
     }
 
     public function getParts(): array
@@ -113,7 +113,7 @@ private function getPartsFromContent(array $content): array
         return $parts;
     }
 
-    private function getRequiredParts(array $content): array
+    private function getRequiredParts(array $content, string $namespace): array
     {
         $required = [];
         // Get the list of required parts
@@ -122,7 +122,8 @@ private function getRequiredParts(array $content): array
         }
         if (count($required) > 1) {
             return call_user_func_array('array_intersect', $required);
-        } elseif (count($required) === 1) {
+        }
+        if (empty($namespace) && !empty($required)) {
             return $required[0];
         }
         return $required;
@@ -158,18 +159,20 @@ public function renderClass(): string
                 : '\\' . $this->normalizeName($this->namespace),
             $class
         );
+        $class = isset($this->content['deprecation_message'])
+            ? str_replace(':deprecation-message', $this->content['deprecation_message'], $class)
+            : preg_replace('/\s*\/\*\*\s+\*\s+@deprecated :deprecation-message\s+\*\//', '', $class);
 
         // Set the HTTP method
         $action = $this->getMethod();
         if ($action === ['POST', 'PUT'] && $this->getClassName() !== 'Bulk') {
             $method = "'PUT'";
+        } elseif (!empty($this->content['body']) && ($action === ['GET', 'POST'] || $action === ['POST', 'GET'])) {
+            $method = 'isset($this->body) ? \'POST\' : \'GET\'';
+        } elseif ($this->getClassName() == "Refresh" || $this->getClassName() == "Flush") {
+            $method = "'POST'";
         } else {
-            if (!empty($this->content['body']) &&
-                ($action === ['GET', 'POST'] || $action === ['POST', 'GET'])) {
-                $method = 'isset($this->body) ? \'POST\' : \'GET\'';
-            } else {
-                $method = sprintf("'%s'", reset($action));
-            }
+            $method = sprintf("'%s'", reset($action));
         }
         $class = str_replace(':method', $method, $class);
 
@@ -210,7 +213,8 @@ public function renderClass(): string
         $EndpointName = $this->getClassName();
 
         if (!empty($this->namespace)) {
-            $filePath = $baseDir . "/src/OpenSearch/Endpoints/$this->namespace/$EndpointName.php";
+            $namespace = str_replace('_', '', ucwords($this->namespace, '_'));
+            $filePath = $baseDir . "/src/OpenSearch/Endpoints/$namespace/$EndpointName.php";
         } else {
             $filePath = $baseDir . "/src/OpenSearch/Endpoints/$EndpointName.php";
         }

util/EndpointProxies/createPointInTimeProxy.php

@@ -0,0 +1,13 @@
+<?php
+
+return <<<'EOD'
+
+/**
+ * Proxy function to createPointInTime() to prevent BC break. 
+ * This API will be removed in a future version. Use 'createPit' API instead.
+ */
+public function createPointInTime(array $params = [])
+{
+    return $this->createPit($params);
+}
+EOD;

util/EndpointProxies/deletePointInTimeProxy.php

@@ -0,0 +1,13 @@
+<?php
+
+return <<<'EOD'
+
+/**
+ * Proxy function to deletePointInTime() to prevent BC break. 
+ * This API will be removed in a future version. Use 'deletePit' API instead.
+ */
+public function deletePointInTime(array $params = [])
+{
+    return $this->deletePit($params);
+}
+EOD;

util/EndpointProxies/security/changePasswordProxy.php

@@ -0,0 +1,36 @@
+<?php
+
+return <<<'EOD'
+
+/**
+ * Changes the password for the current user.
+ *
+ * $params['pretty']      = (boolean) Whether to pretty format the returned JSON response.
+ * $params['human']       = (boolean) Whether to return human readable values for statistics.
+ * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors.
+ * $params['source']      = (string) The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
+ * $params['filter_path'] = (any) Comma-separated list of filters used to reduce the response.
+ * $params['current_password']   = (string) The current password
+ * $params['password']           = (string) New password
+ *
+ * @param array $params Associative array of parameters
+ * @return array
+ */
+public function changePassword(array $params = [])
+{
+    $body = $this->extractArgument($params, 'body');
+    if ($body ===null) {
+        $body =[
+            'current_password' => $this->extractArgument($params, 'current_password'),
+            'password' => $this->extractArgument($params, 'password'),
+        ];
+    }
+
+    $endpointBuilder = $this->endpoints;
+    $endpoint = $endpointBuilder('Security\ChangePassword');
+    $endpoint->setParams($params);
+    $endpoint->setBody($body);
+
+    return $this->performRequest($endpoint);
+}
+EOD;

util/EndpointProxies/security/createActionGroupProxy.php

@@ -0,0 +1,37 @@
+<?php
+
+return <<<'EOD'
+
+    /**
+     * Creates or replaces the specified action group.
+     *
+     * $params['action_group'] = (string) The name of the action group to create or replace. (Required)
+     * $params['allowed_actions']    = (array) list of allowed actions
+     * $params['pretty']       = (boolean) Whether to pretty format the returned JSON response.
+     * $params['human']        = (boolean) Whether to return human readable values for statistics.
+     * $params['error_trace']  = (boolean) Whether to include the stack trace of returned errors.
+     * $params['source']       = (string) The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
+     * $params['filter_path']  = (any) Comma-separated list of filters used to reduce the response.
+     *
+     * @param array $params Associative array of parameters
+     * @return array
+     */
+    public function createActionGroup(array $params = [])
+    {
+        $action_group = $this->extractArgument($params, 'action_group');
+        $body = $this->extractArgument($params, 'body');
+        if ($body ===null) {
+            $body =[
+                'allowed_actions' => $this->extractArgument($params, 'allowed_actions'),
+            ];
+        }
+
+        $endpointBuilder = $this->endpoints;
+        $endpoint = $endpointBuilder('Security\CreateActionGroup');
+        $endpoint->setParams($params);
+        $endpoint->setActionGroup($action_group);
+        $endpoint->setBody($body);
+
+        return $this->performRequest($endpoint);
+    }
+EOD;

util/EndpointProxies/security/createRoleMappingProxy.php

@@ -0,0 +1,41 @@
+<?php
+
+return <<<'EOD'
+
+/**
+ * Creates or replaces the specified role mapping.
+ *
+ * $params['role']        = (string)  (Required)
+ * $params['pretty']      = (boolean) Whether to pretty format the returned JSON response.
+ * $params['human']       = (boolean) Whether to return human readable values for statistics.
+ * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors.
+ * $params['source']      = (string) The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
+ * $params['filter_path'] = (any) Comma-separated list of filters used to reduce the response.
+ * $params['backend_roles']  = (array)
+ * $params['hosts']          = (array)
+ * $params['users']          = (array)
+ * 
+ * @param array $params Associative array of parameters
+ * @return array
+ */
+public function createRoleMapping(array $params = [])
+{
+    $role = $this->extractArgument($params, 'role');
+    $body = $this->extractArgument($params, 'body');
+    if ($body ===null) {
+        $body = array_filter([
+            'backend_roles' => $this->extractArgument($params, 'backend_roles'),
+            'hosts' => $this->extractArgument($params, 'hosts'),
+            'users' => $this->extractArgument($params, 'users'),
+        ]);
+    }
+
+    $endpointBuilder = $this->endpoints;
+    $endpoint = $endpointBuilder('Security\CreateRoleMapping');
+    $endpoint->setParams($params);
+    $endpoint->setRole($role);
+    $endpoint->setBody($body);
+
+    return $this->performRequest($endpoint);
+}
+EOD;

util/EndpointProxies/security/createRoleProxy.php

@@ -0,0 +1,41 @@
+<?php
+
+return <<<'EOD'
+
+/**
+ * Creates or replaces the specified role.
+ *
+ * $params['role']        = (string)  (Required)
+ * $params['pretty']      = (boolean) Whether to pretty format the returned JSON response.
+ * $params['human']       = (boolean) Whether to return human readable values for statistics.
+ * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors.
+ * $params['source']      = (string) The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
+ * $params['filter_path'] = (any) Comma-separated list of filters used to reduce the response.
+ * $params['cluster_permissions']  = (array)
+ * $params['index_permissions']    = (array)
+ * $params['tenant_permissions']   = (array)
+ * 
+ * @param array $params Associative array of parameters
+ * @return array
+ */
+public function createRole(array $params = [])
+{
+    $role = $this->extractArgument($params, 'role');
+    $body = $this->extractArgument($params, 'body');
+    if ($body ===null) {
+        $body = array_filter([
+            'cluster_permissions' => $this->extractArgument($params, 'cluster_permissions'),
+            'index_permissions' => $this->extractArgument($params, 'index_permissions'),
+            'tenant_permissions' => $this->extractArgument($params, 'tenant_permissions'),
+        ]);
+    }
+
+    $endpointBuilder = $this->endpoints;
+    $endpoint = $endpointBuilder('Security\CreateRole');
+    $endpoint->setParams($params);
+    $endpoint->setRole($role);
+    $endpoint->setBody($body);
+
+    return $this->performRequest($endpoint);
+}
+EOD;

util/EndpointProxies/security/createTenantProxy.php

@@ -0,0 +1,37 @@
+<?php
+
+return <<<'EOD'
+
+/**
+ * Creates or replaces the specified tenant.
+ *
+ * $params['tenant']      = (string) The name of the tenant to create
+ * $params['description'] = (string) Description of the tenant
+ * $params['pretty']      = (boolean) Whether to pretty format the returned JSON response.
+ * $params['human']       = (boolean) Whether to return human readable values for statistics.
+ * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors.
+ * $params['source']      = (string) The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
+ * $params['filter_path'] = (any) Comma-separated list of filters used to reduce the response.
+ *
+ * @param array $params Associative array of parameters
+ * @return array
+ */
+public function createTenant(array $params = [])
+{
+    $tenant = $this->extractArgument($params, 'tenant');
+    $body = $this->extractArgument($params, 'body');
+    if ($body ===null) {
+        $body = [
+            'description' => $this->extractArgument($params, 'description'),
+        ];
+    }
+
+    $endpointBuilder = $this->endpoints;
+    $endpoint = $endpointBuilder('Security\CreateTenant');
+    $endpoint->setParams($params);
+    $endpoint->setTenant($tenant);
+    $endpoint->setBody($body);
+
+    return $this->performRequest($endpoint);
+}
+EOD;

util/EndpointProxies/security/createUserProxy.php

@@ -0,0 +1,43 @@
+<?php
+
+return <<<'EOD'
+
+/**
+     * Creates or replaces the specified user.
+     *
+     * $params['username']    = (string)  (Required)
+     * $params['pretty']      = (boolean) Whether to pretty format the returned JSON response.
+     * $params['human']       = (boolean) Whether to return human readable values for statistics.
+     * $params['error_trace'] = (boolean) Whether to include the stack trace of returned errors.
+     * $params['source']      = (string) The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
+     * $params['filter_path'] = (any) Comma-separated list of filters used to reduce the response.
+     * $params['password']                   = (string)
+     * $params['opendistro_security_roles']  = (array)
+     * $params['backend_roles']              = (array)
+     * $params['attributes']                 = (array)
+     * 
+     * @param array $params Associative array of parameters
+     * @return array
+     */
+    public function createUser(array $params = [])
+    {
+        $username = $this->extractArgument($params, 'username');
+        $body = $this->extractArgument($params, 'body');
+        if ($body ===null) {
+            $body = array_filter([
+                'password' => $this->extractArgument($params, 'password'),
+                'opendistro_security_roles' => $this->extractArgument($params, 'opendistro_security_roles'),
+                'backend_roles' => $this->extractArgument($params, 'backend_roles'),
+                'attributes' => $this->extractArgument($params, 'attributes'),
+            ]);
+        }
+
+        $endpointBuilder = $this->endpoints;
+        $endpoint = $endpointBuilder('Security\CreateUser');
+        $endpoint->setParams($params);
+        $endpoint->setUsername($username);
+        $endpoint->setBody($body);
+
+        return $this->performRequest($endpoint);
+    }
+EOD;

util/EndpointProxies/security/deleteDistinguishedNamesProxy.php

@@ -0,0 +1,13 @@
+<?php
+
+return <<<'EOD'
+
+/**
+ * Proxy function to deleteDistinguishedNames() to prevent BC break.
+ * This API will be removed in a future version. Use 'deleteDistinguishedName' API instead.
+ */
+public function deleteDistinguishedNames(array $params = [])
+{
+    return $this->deleteDistinguishedName($params);
+}
+EOD;

util/EndpointProxies/security/getAccountProxy.php

@@ -0,0 +1,13 @@
+<?php
+
+return <<<'EOD'
+
+/**
+ * Proxy function to getAccount() to prevent BC break.
+ * This API will be removed in a future version. Use 'getAccountDetails' API instead.
+ */
+public function getAccount(array $params = [])
+{
+    return $this->getAccountDetails($params);
+}
+EOD;