Adds Ruby converter

.github/workflows/daily.yml

@@ -124,3 +124,26 @@ jobs:
       - name: Integration tests
         run: |
           npm run test:integration-javascript
+  integration-tests-ruby:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: 8.17
+      - name: Setup node.js
+        uses: actions/setup-node@v4
+      - name: Install
+        run: |
+          npm install
+      - name: Build
+        run: |
+          npm run build
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+      - name: Prepare for testing
+        run: |
+          npm run test:setup-ruby
+      - name: Integration tests
+        run: |
+          npm run test:integration-ruby

.github/workflows/weekly.yml

@@ -64,3 +64,26 @@ jobs:
       - name: Integration tests
         run: |
           npm run test:integration-javascript
+  integration-tests-ruby:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+      - name: Setup node.js
+        uses: actions/setup-node@v4
+      - name: Install
+        run: |
+          npm install
+      - name: Build
+        run: |
+          npm run build
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+      - name: Prepare for testing
+        run: |
+          npm run test:setup-ruby
+      - name: Integration tests
+        run: |
+          npm run test:integration-ruby

README.md

@@ -79,8 +79,8 @@ const { convertRequests, listFormats } = require("@elastic/request-converter");
 
 ## Available Formats
 
-At this time the converter supports `curl` and `python`. Work is currently in
-progress to add support for `javascript`, `ruby` and `php`.
+At this time the converter supports `curl`, `python`, `javascript` and `ruby`. Work is currently in
+progress to add support for `php`.
 
 ### curl
 
@@ -107,6 +107,18 @@ Supported options:
 | `complete` | `boolean` | no | If `true`, generate a complete script. If `false`, only generate the request code. The default is `false`. |
 | `elasticsearchUrl` | `string` | no | The Elasticsearch endpoint to use. The default is `http://localhost:9200`. |
 
+### ruby
+
+The Ruby exporter generates code for the Elasticsearch Ruby client.
+
+Supported options:
+
+| Option name | Type | Required | Description |
+| ----------- | ---- | -------- | ----------- |
+| `printResponse` | `boolean` | no | If `true`, add code to print the response. The default is `false`. |
+| `complete` | `boolean` | no | If `true`, generate a complete script. If `false`, only generate the request code. The default is `false`. |
+| `elasticsearchUrl` | `string` | no | The Elasticsearch endpoint to use. The default is `http://localhost:9200`. |
+
 ## Command-Line Interface
 
 For convenience, a CLI that wraps the `convertRequests` function is also available.

package.json

@@ -23,10 +23,12 @@
     "test:setup-curl": "node scripts/download-examples.mjs",
     "test:setup-python": "node scripts/download-examples.mjs && ./tests/integration/run-python.sh",
     "test:setup-javascript": "node scripts/download-examples.mjs && ./tests/integration/run-javascript.sh",
+    "test:setup-ruby": "node scripts/download-examples.mjs && ./tests/integration/run-ruby.sh",
     "test:integration": "jest tests/integration",
     "test:integration-curl": "./scripts/test-format.sh curl",
     "test:integration-python": "./scripts/test-format.sh python",
     "test:integration-javascript": "./scripts/test-format.sh javascript",
+    "test:integration-ruby": "./scripts/test-format.sh ruby",
     "test:example": "./scripts/test-example.sh",
     "fix": "npm run fix:lint && npm run fix:prettier",
     "fix:lint": "eslint src tests --fix --ignore-pattern tests/wasm/",

scripts/compile-templates.mjs

@@ -5,7 +5,7 @@ const sourceDir = (process.platform !== "win32")
   ? "src/exporters"
   : "src\\exporters";
 process.chdir(sourceDir);
-const cmd = "handlebars python.tpl javascript.tpl -f templates.js -c";
+const cmd = "handlebars python.tpl javascript.tpl ruby.tpl -f templates.js -c";
 exec(cmd, (error, stdout, stderr) => {
   if (error) {
     console.log(stdout);

src/convert.ts

@@ -4,6 +4,7 @@ import { parseRequests, ParsedRequest } from "./parse";
 import { PythonExporter } from "./exporters/python";
 import { CurlExporter } from "./exporters/curl";
 import { JavaScriptExporter } from "./exporters/javascript";
+import { RubyExporter } from "./exporters/ruby";
 import util from "util";
 
 const isBrowser = typeof window !== "undefined";
@@ -41,6 +42,7 @@ const EXPORTERS: Record<string, FormatExporter> = {
   python: new PythonExporter(),
   curl: new CurlExporter(),
   javascript: new JavaScriptExporter(),
+  ruby: new RubyExporter(),
 };
 
 /**

src/exporters/ruby.tpl

@@ -0,0 +1,57 @@
+{{#if complete}}
+require "elasticsearch"
+
+client = Elasticsearch::Client.new(
+  host: {{#if elasticsearchUrl}}"{{elasticsearchUrl}}"{{else}}ENV["ELASTICSEARCH_URL"]{{/if}},
+  api_key: ENV["ELASTIC_API_KEY"]
+)
+
+{{/if}}
+{{#each requests}}
+{{#supportedApi}}
+{{#hasArgs}}
+response{{#if @index}}{{@index}}{{/if}} = client.{{this.api}}(
+{{#if this.body}}
+  {{#each this.params}}
+  {{alias @key ../this.request.path}}: "{{{this}}}",
+  {{/each}}
+  {{#each this.query}}
+  {{alias @key ../this.request.query}}: {{{rubyprint this}}},
+  {{/each}}
+  body: {{{rubyprint this.body}}}
+{{else}}
+  {{#if this.query}}
+  {{#each this.params}}
+  {{alias @key ../this.request.path}}: "{{{this}}}",
+  {{/each}}
+  {{#each this.query}}
+  {{alias @key ../this.request.query}}: {{{rubyprint this}}}{{#unless @last}},{{/unless}}
+  {{/each}}
+  {{else}}
+  {{#each this.params}}
+  {{alias @key ../this.request.path}}: "{{{this}}}"{{#unless @last}},{{/unless}}
+  {{/each}}
+  {{/if}}
+{{/if}}
+)
+{{else}}
+response{{#if @index}}{{@index}}{{/if}} = client.{{this.api}}
+{{/hasArgs}}
+{{else}}
+response{{#if @index}}{{@index}}{{/if}} = client.perform_request(
+  "{{this.method}}",
+  "{{this.path}}",
+  {{#if this.query}}
+  params: {{{rubyprint this.query}}},
+  {{/if}}
+  {{#if this.body}}
+  headers: { "Content-Type": "application/json" },
+  body: {{{rubyprint this.body}}},
+  {{/if}}
+)
+{{/supportedApi}}
+{{#if ../printResponse}}
+print(resp{{#if @index}}{{@index}}{{/if}})
+{{/if}}
+
+{{/each}}

src/exporters/ruby.ts

@@ -0,0 +1,134 @@
+import { readFileSync } from "fs";
+import path from "path";
+import Handlebars from "handlebars";
+import { FormatExporter, ConvertOptions } from "../convert";
+import { ParsedRequest } from "../parse";
+import "./templates";
+
+// this regex should match the list of APIs that do not have specific handlers
+// in the Ruby client. APIs in this list are rendered with a perform_request()
+// call
+const UNSUPPORTED_APIS = new RegExp("^_internal.*$");
+
+const RUBYCONSTANTS: Record<string, string> = { null: "nil" };
+
+export class RubyExporter implements FormatExporter {
+  template: Handlebars.TemplateDelegate | undefined;
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async check(requests: ParsedRequest[]): Promise<boolean> {
+    // only return true if all requests are for Elasticsearch
+    return requests
+      .map((req) => req.service == "es")
+      .reduce((prev, curr) => prev && curr, true);
+  }
+
+  async convert(
+    requests: ParsedRequest[],
+    options: ConvertOptions,
+  ): Promise<string> {
+    if (!(await this.check(requests))) {
+      throw new Error("Cannot perform conversion");
+    }
+    return (await this.getTemplate())({ requests, ...options });
+  }
+
+  async getTemplate(): Promise<Handlebars.TemplateDelegate> {
+    if (!this.template) {
+      // custom data renderer for Ruby
+      Handlebars.registerHelper("rubyprint", (context) => {
+        const lines = JSON.stringify(context ?? null, null, 2).split(/\r?\n/);
+        for (let i = 1; i < lines.length; i++) {
+          lines[i] = "  " + lines[i];
+        }
+        if (lines.length > 1) {
+          let result = lines.join("\n");
+          for (const k of Object.keys(RUBYCONSTANTS)) {
+            result = result.replaceAll(`${k},\n`, `${RUBYCONSTANTS[k]},\n`);
+            result = result.replaceAll(`${k}\n`, `${RUBYCONSTANTS[k]}\n`);
+          }
+          return result;
+        } else if (RUBYCONSTANTS[lines[0]]) {
+          return RUBYCONSTANTS[lines[0]];
+        } else if (lines[0].startsWith('"') && lines[0].endsWith('"')) {
+          // special case: handle strings such as "null" as
+          // their native types
+          const s = lines[0].substring(1, lines[0].length - 1);
+          if (RUBYCONSTANTS[s]) {
+            return RUBYCONSTANTS[s];
+          } else {
+            return lines[0];
+          }
+        } else {
+          return lines[0];
+        }
+      });
+
+      // custom conditional for requests without any arguments
+      Handlebars.registerHelper(
+        "hasArgs",
+        function (this: ParsedRequest, options) {
+          if (
+            Object.keys(this.params ?? {}).length +
+              Object.keys(this.query ?? {}).length +
+              Object.keys(this.body ?? {}).length >
+            0
+          ) {
+            return options.fn(this);
+          } else {
+            return options.inverse(this);
+          }
+        },
+      );
+
+      // custom conditional to separate supported vs unsupported APIs
+      Handlebars.registerHelper(
+        "supportedApi",
+        function (this: ParsedRequest, options) {
+          if (!UNSUPPORTED_APIS.test(this.api as string) && this.request) {
+            return options.fn(this);
+          } else {
+            return options.inverse(this);
+          }
+        },
+      );
+
+      // attribute name renderer that considers aliases and code-specific names
+      // arguments:
+      //   name: the name of the attribute
+      //   props: the list of schema properties this attribute belongs to
+      // TODO: I don't think any of these are necessary in Ruby, but check for others
+      Handlebars.registerHelper("alias", (name, props) => {
+        const aliases: Record<string, string> = {
+          _meta: "meta",
+          _field_names: "field_names",
+          _routing: "routing",
+          _source: "source",
+          _source_excludes: "source_excludes",
+          _source_includes: "source_includes",
+        };
+        if (aliases[name]) {
+          return aliases[name];
+        }
+        if (props) {
+          for (const prop of props) {
+            if (prop.name == name && prop.codegenName != undefined) {
+              return prop.codegenName;
+            }
+          }
+        }
+        return name;
+      });
+
+      if (process.env.NODE_ENV !== "test") {
+        this.template = Handlebars.templates["ruby.tpl"];
+      } else {
+        // when running tests we read the templates directly, in case the
+        // compiled file is not up to date
+        const t = readFileSync(path.join(__dirname, "./ruby.tpl"), "utf-8");
+        this.template = Handlebars.compile(t);
+      }
+    }
+    return this.template;
+  }
+}

tests/integration/convert.test.ts

@@ -14,6 +14,7 @@ const TEST_FORMATS: Record<string, string> = {
   python: "py",
   javascript: "js",
   curl: "sh",
+  ruby: "rb",
 };
 
 interface Example {

tests/integration/run-ruby.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+set -eo pipefail
+set -x
+
+CLIENT_DIR=/tmp/ruby-client
+BRANCH=$(jq -r .version package.json | grep -Eo "^[0-9]+\.[0-9]+")
+
+if [ ! -d "$CLIENT_DIR" ]; then
+  echo "Installing from branch $BRANCH"
+  git clone -b "$BRANCH" --depth=1 "https://github.com/elastic/elasticsearch-ruby.git" "$CLIENT_DIR" ||
+    (echo "Branch $BRANCH not found. Cloning main branch." &&
+       git clone -b "main" --depth=1 "https://github.com/elastic/elasticsearch-ruby.git" "$CLIENT_DIR")
+  pushd "$CLIENT_DIR"
+  bundle install
+  bundle exec rake bundle:install
+  bundle exec rake automation:build_gems
+  gem install build/elasticsearch-api*
+  gem install build/elasticsearch*
+  popd
+fi
+
+if [[ "$1" != "" ]]; then
+  ruby $1
+fi