Add elasticgraph-protobuf schema artifacts

CODEBASE_OVERVIEW.md

@@ -195,13 +195,14 @@ graph LR;
     click opensearch-ruby href "https://rubygems.org/gems/opensearch-ruby" "Open on RubyGems.org" _blank;
 ```
 
-### Extensions (6 gems)
+### Extensions (7 gems)
 
 These libraries extend ElasticGraph to provide optional but commonly needed functionality.
 
 * [elasticgraph-apollo](elasticgraph-apollo/README.md): Transforms an ElasticGraph project into an Apollo subgraph.
 * [elasticgraph-health_check](elasticgraph-health_check/README.md): Provides a health check for high availability ElasticGraph deployments.
 * [elasticgraph-json_ingestion](elasticgraph-json_ingestion/README.md): Pluggable JSON Schema ingestion serializer for ElasticGraph.
+* [elasticgraph-protobuf](elasticgraph-protobuf/README.md): Generates Protocol Buffers schema artifacts from ElasticGraph schemas.
 * [elasticgraph-query_interceptor](elasticgraph-query_interceptor/README.md): Intercepts ElasticGraph datastore queries.
 * [elasticgraph-query_registry](elasticgraph-query_registry/README.md): Provides a source-controlled query registry for ElasticGraph applications.
 * [elasticgraph-warehouse](elasticgraph-warehouse/README.md): Extends ElasticGraph to support ingestion into a data warehouse.
@@ -221,6 +222,7 @@ graph LR;
     elasticgraph-health_check["eg-health_check"];
     elasticgraph-datastore_core["eg-datastore_core"];
     elasticgraph-json_ingestion["eg-json_ingestion"];
+    elasticgraph-protobuf["eg-protobuf"];
     elasticgraph-query_interceptor["eg-query_interceptor"];
     elasticgraph-schema_artifacts["eg-schema_artifacts"];
     elasticgraph-query_registry["eg-query_registry"];
@@ -234,6 +236,7 @@ graph LR;
     elasticgraph-health_check --> elasticgraph-graphql;
     elasticgraph-health_check --> elasticgraph-support;
     elasticgraph-json_ingestion --> elasticgraph-support;
+    elasticgraph-protobuf --> elasticgraph-support;
     elasticgraph-query_interceptor --> elasticgraph-graphql;
     elasticgraph-query_interceptor --> elasticgraph-schema_artifacts;
     elasticgraph-query_registry --> elasticgraph-graphql;
@@ -249,6 +252,7 @@ graph LR;
     class elasticgraph-health_check targetGemStyle;
     class elasticgraph-datastore_core otherEgGemStyle;
     class elasticgraph-json_ingestion targetGemStyle;
+    class elasticgraph-protobuf targetGemStyle;
     class elasticgraph-query_interceptor targetGemStyle;
     class elasticgraph-schema_artifacts otherEgGemStyle;
     class elasticgraph-query_registry targetGemStyle;

Gemfile.lock

@@ -163,6 +163,12 @@ PATH
       faraday-retry (~> 2.4)
       opensearch-ruby (~> 3.4)
 
+PATH
+  remote: elasticgraph-protobuf
+  specs:
+    elasticgraph-protobuf (1.1.1.pre)
+      elasticgraph-support (= 1.1.1.pre)
+
 PATH
   remote: elasticgraph-query_interceptor
   specs:
@@ -707,6 +713,7 @@ DEPENDENCIES
   elasticgraph-lambda_support (= 1.1.1.pre)!
   elasticgraph-local (= 1.1.1.pre)!
   elasticgraph-opensearch (= 1.1.1.pre)!
+  elasticgraph-protobuf (= 1.1.1.pre)!
   elasticgraph-query_interceptor (= 1.1.1.pre)!
   elasticgraph-query_registry (= 1.1.1.pre)!
   elasticgraph-rack (= 1.1.1.pre)!
@@ -799,6 +806,7 @@ CHECKSUMS
   elasticgraph-lambda_support (1.1.1.pre)
   elasticgraph-local (1.1.1.pre)
   elasticgraph-opensearch (1.1.1.pre)
+  elasticgraph-protobuf (1.1.1.pre)
   elasticgraph-query_interceptor (1.1.1.pre)
   elasticgraph-query_registry (1.1.1.pre)
   elasticgraph-rack (1.1.1.pre)

config/docker_demo/Dockerfile

@@ -19,6 +19,7 @@ COPY elasticgraph-indexer elasticgraph-indexer/
 COPY elasticgraph-json_ingestion elasticgraph-json_ingestion/
 COPY elasticgraph-local elasticgraph-local/
 COPY elasticgraph-opensearch elasticgraph-opensearch/
+COPY elasticgraph-protobuf elasticgraph-protobuf/
 COPY elasticgraph-query_registry elasticgraph-query_registry/
 COPY elasticgraph-rack elasticgraph-rack/
 COPY elasticgraph-schema_artifacts elasticgraph-schema_artifacts/

elasticgraph-protobuf/.rspec

@@ -0,0 +1 @@
+../spec_support/subdir_dot_rspec

elasticgraph-protobuf/.yardopts

@@ -0,0 +1 @@
+../config/site/yardopts

elasticgraph-protobuf/Gemfile

@@ -0,0 +1 @@
+../Gemfile

elasticgraph-protobuf/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 - 2026 Block, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

elasticgraph-protobuf/README.md

@@ -0,0 +1,162 @@
+# ElasticGraph::Protobuf
+
+An ElasticGraph extension that generates Protocol Buffers (`proto3`) schema artifacts from ElasticGraph schemas.
+
+## Dependency Diagram
+
+```mermaid
+graph LR;
+    classDef targetGemStyle fill:#FADBD8,stroke:#EC7063,color:#000,stroke-width:2px;
+    classDef otherEgGemStyle fill:#A9DFBF,stroke:#2ECC71,color:#000;
+    classDef externalGemStyle fill:#E0EFFF,stroke:#70A1D7,color:#2980B9;
+    elasticgraph-protobuf["elasticgraph-protobuf"];
+    class elasticgraph-protobuf targetGemStyle;
+    elasticgraph-support["elasticgraph-support"];
+    elasticgraph-protobuf --> elasticgraph-support;
+    class elasticgraph-support otherEgGemStyle;
+```
+
+## Usage
+
+First, add `elasticgraph-protobuf` to your `Gemfile`, alongside the other ElasticGraph gems:
+
+```diff
+diff --git a/Gemfile b/Gemfile
+index 4a5ef1e..5c16c2b 100644
+--- a/Gemfile
++++ b/Gemfile
+@@ -8,6 +8,7 @@ gem "elasticgraph-query_registry", *elasticgraph_details
+
+ # Can be elasticgraph-elasticsearch or elasticgraph-opensearch based on the datastore you want to use.
+ gem "elasticgraph-opensearch", *elasticgraph_details
++gem "elasticgraph-protobuf", *elasticgraph_details
+
+ gem "httpx", "~> 1.3"
+
+```
+
+Next, update your `Rakefile` so that `ElasticGraph::Protobuf::SchemaDefinition::APIExtension` is
+included in the schema-definition extension modules:
+
+```diff
+diff --git a/Rakefile b/Rakefile
+index 2943335..26633c3 100644
+--- a/Rakefile
++++ b/Rakefile
+@@ -1,5 +1,6 @@
+ project_root = File.expand_path(__dir__)
+
++require "elastic_graph/protobuf/schema_definition/api_extension"
+ require "elastic_graph/local/rake_tasks"
+ require "elastic_graph/query_registry/rake_tasks"
+ require "rspec/core/rake_task"
+@@ -12,6 +13,8 @@ ElasticGraph::Local::RakeTasks.new(
+   local_config_yaml: settings_file,
+   path_to_schema: "#{project_root}/config/schema.rb"
+ ) do |tasks|
++  tasks.schema_definition_extension_modules << ElasticGraph::Protobuf::SchemaDefinition::APIExtension
++
+   # Set this to true once you're beyond the prototyping stage.
+   tasks.enforce_json_schema_version = false
+
+```
+
+Then opt into proto generation from your schema definition:
+
+```ruby
+# in config/schema/protobuf.rb
+
+ElasticGraph.define_schema do |schema|
+  schema.proto_schema_artifacts package_name: "myapp.events.v1"
+end
+```
+
+After running `bundle exec rake schema_artifacts:dump`, ElasticGraph will generate:
+
+- `schema.proto`
+- `proto_field_numbers.yaml`
+
+## Schema Definition Options
+
+### Custom Scalar Types
+
+Built-in ElasticGraph scalar types are automatically mapped to proto scalar types.
+For custom scalar types, the generator infers proto scalar types from `json_schema type:` when it is one
+of `string`, `boolean`, `number`, or `integer`. You can override inference with `proto_field`:
+
+```ruby
+# in config/schema/money.rb
+
+ElasticGraph.define_schema do |schema|
+  schema.scalar_type "Money" do |t|
+    t.mapping type: "long"
+    t.json_schema type: "integer"
+    t.proto_field type: "int64"
+  end
+end
+```
+
+### Sourcing Enum Values From Existing Protobuf Mappings
+
+If your project already maintains GraphQL-to-proto enum mappings (for example in tests),
+you can reuse them for proto schema generation:
+
+```ruby
+# in config/schema/proto_enum_mappings.rb
+
+ElasticGraph.define_schema do |schema|
+  schema.proto_enum_mappings(
+    SalesEg::ProtoEnumMappings::PROTO_ENUMS_BY_GRAPHQL_ENUM
+  ) if defined?(SalesEg::ProtoEnumMappings)
+end
+```
+
+When a mapping exists for an enum, `elasticgraph-protobuf` uses the mapped proto enum(s)
+as the source of enum values (respecting `exclusions`, `expected_extras`, and `name_transform`).
+
+### Stable Field Numbers
+
+`schema_artifacts:dump` automatically reads and writes `proto_field_numbers.yaml`
+in the schema artifacts directory. Existing numbers stay fixed even if field order
+changes, and new fields get the next available numbers.
+
+`schema.proto` always uses the public GraphQL field names. When a field uses a
+different `name_in_index`, the sidecar YAML stores that override privately:
+
+```yaml
+messages:
+  Widget:
+    fields:
+      id: 1
+      display_name:
+        field_number: 2
+        name_in_index: displayName
+```
+
+If a field is renamed with `field.renamed_from`, `elasticgraph-protobuf` reuses the
+existing field number under the new public field name.
+
+## Type Mappings
+
+The generated `schema.proto` uses these built-in scalar mappings:
+
+| ElasticGraph Type | Protobuf Type |
+|-------------------|------------|
+| `Boolean`         | `bool`     |
+| `Cursor`          | `string`   |
+| `Date`            | `string`   |
+| `DateTime`        | `string`   |
+| `Float`           | `double`   |
+| `ID`              | `string`   |
+| `Int`             | `int32`    |
+| `JsonSafeLong`    | `int64`    |
+| `LocalTime`       | `string`   |
+| `LongString`      | `int64`    |
+| `String`          | `string`   |
+| `TimeZone`        | `string`   |
+| `Untyped`         | `string`   |
+
+Additionally:
+- List types become `repeated` fields.
+- Nested list types generate wrapper messages so the output remains valid `proto3`.
+- Enum types generate `enum` definitions whose values are prefixed with the enum type name in `UPPER_SNAKE_CASE`, including a zero-valued `*_UNSPECIFIED` entry.

elasticgraph-protobuf/elasticgraph-protobuf.gemspec

@@ -0,0 +1,40 @@
+# Copyright 2024 - 2026 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require_relative "../elasticgraph-support/lib/elastic_graph/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "elasticgraph-protobuf"
+  spec.version = ElasticGraph::VERSION
+  spec.authors = ["Josh Wilson", "Myron Marston", "Block Engineering"]
+  spec.email = ["[email protected]"]
+  spec.homepage = "https://block.github.io/elasticgraph/"
+  spec.license = "MIT"
+  spec.summary = "Generates Protocol Buffers schema artifacts from ElasticGraph schemas."
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/block/elasticgraph/issues",
+    "changelog_uri" => "https://github.com/block/elasticgraph/releases/tag/v#{ElasticGraph::VERSION}",
+    "documentation_uri" => "https://block.github.io/elasticgraph/api-docs/v#{ElasticGraph::VERSION}/",
+    "homepage_uri" => "https://block.github.io/elasticgraph/",
+    "source_code_uri" => "https://github.com/block/elasticgraph/tree/v#{ElasticGraph::VERSION}/#{spec.name}",
+    "gem_category" => "extension"
+  }
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features|sig)/|\.(?:git|travis|circleci)|appveyor)})
+    end - [".rspec", "Gemfile", ".yardopts"]
+  end
+
+  spec.required_ruby_version = [">= 3.4", "< 4.1"]
+
+  spec.add_dependency "elasticgraph-support", ElasticGraph::VERSION
+
+  spec.add_development_dependency "elasticgraph-schema_definition", ElasticGraph::VERSION
+end

elasticgraph-protobuf/lib/elastic_graph/protobuf.rb

@@ -0,0 +1,18 @@
+# Copyright 2024 - 2026 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+module ElasticGraph
+  # Namespace for Protocol Buffers schema artifact generation extensions.
+  module Protobuf
+    # The name of the generated Protocol Buffers schema file.
+    PROTO_SCHEMA_FILE = "schema.proto"
+
+    # The name of the generated proto field-number mapping file.
+    PROTO_FIELD_NUMBERS_FILE = "proto_field_numbers.yaml"
+  end
+end