feat: publish RBS and RBI types with Gem

.github/workflows/ci.yml

@@ -63,6 +63,12 @@ jobs:
         with:
           go-version: stable
 
+      - name: Install protoc-gen-rbi
+        shell: bash
+        run: |
+          go install "github.com/coinbase/protoc-gen-rbi@$(tr -d '\n' < .protoc-gen-rbi-version)"
+          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
+
       - name: Install protoc
         uses: arduino/setup-protoc@c65c819552d16ad3c9b72d9dfd5ba5237b9c906b # v3
         with:
@@ -104,6 +110,35 @@ jobs:
 
         run: bundle exec rake TESTOPTS="--verbose"
 
+      - name: Test Ruby with Sorbet runtime assertions
+        if: ${{ matrix.os == 'ubuntu-latest' }}
+        working-directory: ./temporalio
+        # Timeout just in case there's a hanging part in rake
+        timeout-minutes: 10
+        # Set env vars for cloud tests. If secrets aren't present, tests will be skipped.
+        env:
+          # For mTLS tests
+          TEMPORAL_CLOUD_MTLS_TEST_TARGET_HOST: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }}.tmprl.cloud:7233
+          TEMPORAL_CLOUD_MTLS_TEST_NAMESPACE: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }}
+          TEMPORAL_CLOUD_MTLS_TEST_CLIENT_CERT: ${{ secrets.TEMPORAL_CLIENT_CERT }}
+          TEMPORAL_CLOUD_MTLS_TEST_CLIENT_KEY: ${{ secrets.TEMPORAL_CLIENT_KEY }}
+
+          # For API key tests
+          TEMPORAL_CLOUD_API_KEY_TEST_TARGET_HOST: us-east-1.aws.api.temporal.io:7233
+          TEMPORAL_CLOUD_API_KEY_TEST_NAMESPACE: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }}
+          TEMPORAL_CLOUD_API_KEY_TEST_API_KEY: ${{ secrets.TEMPORAL_CLIENT_CLOUD_API_KEY }}
+
+          # For cloud ops tests
+          TEMPORAL_CLOUD_OPS_TEST_TARGET_HOST: saas-api.tmprl.cloud:443
+          TEMPORAL_CLOUD_OPS_TEST_NAMESPACE: ${{ vars.TEMPORAL_CLIENT_NAMESPACE }}
+          TEMPORAL_CLOUD_OPS_TEST_API_KEY: ${{ secrets.TEMPORAL_CLIENT_CLOUD_API_KEY }}
+          TEMPORAL_CLOUD_OPS_TEST_API_VERSION: 2024-05-13-00
+
+          # Enable Sorbet runtime type checking to verify RBI accuracy.
+          TEMPORAL_SORBET_RUNTIME_CHECK: "1"
+
+        run: bundle exec rake test TESTOPTS="--verbose"
+
       - name: Deploy docs
         # Only deploy on main merge, not in PRs
         if: ${{ github.ref == 'refs/heads/main' && matrix.docsTarget }}

.protoc-gen-rbi-version

@@ -0,0 +1 @@
+v0.1.1

README.md

@@ -1469,6 +1469,20 @@ Now can run `steep`:
 
     bundle exec rake steep
 
+### Type Signatures (Experimental)
+
+The SDK ships two sets of type signatures:
+
+* **RBS**: Maintained throughout development of the SDK, but only recently made public.
+* **RBI**: Sorbet types maintained in parallel with the RBS signatures.
+
+We leverage `protoc` and the `protoc-gen-rbi` plugin to generate RBS and RBI types for all of our Protobuf messages and services.
+
+The RBI signatures are validated at runtime by running the test suite with `TEMPORAL_SORBET_RUNTIME_CHECK=1`, which applies every RBI
+signature to the real implementation at runtime via `SigApplicator`.
+
+This is yet another reason to ensure any changes you make have test coverage.
+
 ### Proto Generation
 
 Run:
@@ -1477,3 +1491,9 @@ Run:
 
 `proto:generate` now requires `protoc >= 34.0` because we generate RBS alongside the generated Ruby
 protobuf files.
+
+We use `protoc-gen-rbi` to generated protobuf RBI.
+
+It can be installed via `go install`:
+
+    go install github.com/coinbase/protoc-gen-rbi@$(cat ../.protoc-gen-rbi-version)

temporalio/Gemfile

@@ -21,10 +21,12 @@ group :development do
   gem 'opentelemetry-sdk'
   gem 'rake'
   gem 'rake-compiler'
+  gem 'rbi'
   gem 'rbs', '~> 3.10'
   gem 'rb_sys', '~> 0.9'
   gem 'rdoc'
   gem 'rubocop'
+  gem 'sorbet-runtime'
   gem 'sqlite3'
   gem 'steep', '~> 1.10'
   gem 'yard'

temporalio/extra/payload_visitor_gen.rb

@@ -190,6 +190,72 @@ def google_protobuf_any: (untyped value) -> void
     TEXT
   end
 
+  # Generate file Sorbet signature.
+  #
+  # @return [String] File signature.
+  def gen_rbi_code
+    method_defs = payload_methods.filter_map do |_, method_hash|
+      next if method_hash[:fields].empty?
+
+      <<~TEXT
+        sig { params(value: Object).void }
+        def #{method_name_from_desc(method_hash[:desc])}(value); end
+      TEXT
+    end.sort
+
+    <<~TEXT
+      # typed: true
+
+      # Generated code.  DO NOT EDIT!
+
+      class Temporalio::Api::PayloadVisitor
+        extend T::Sig
+
+        sig do
+          params(
+            on_enter: T.nilable(T.proc.params(value: Object).returns(Object)),
+            on_exit: T.nilable(T.proc.params(value: Object).returns(Object)),
+            skip_search_attributes: T::Boolean,
+            traverse_any: T::Boolean,
+            block: T.proc.params(value: Object).returns(Object)
+          ).void
+        end
+        def initialize(
+          on_enter: T.unsafe(nil),
+          on_exit: T.unsafe(nil),
+          skip_search_attributes: T.unsafe(false),
+          traverse_any: T.unsafe(false),
+          &block
+        ); end
+
+        sig { params(value: Object).returns(NilClass) }
+        def run(value); end
+
+        sig { params(value: Object).void }
+        def _run_activation(value); end
+
+        sig { params(value: Object).void }
+        def _run_activation_completion(value); end
+
+        private
+
+        sig { params(name: String).returns(String) }
+        def method_name_from_proto_name(name); end
+
+        sig { params(value: Object).returns(Object) }
+        def api_common_v1_payload(value); end
+
+        sig { params(value: Object).returns(Object) }
+        def api_common_v1_payload_repeated(value); end
+
+        sig { params(value: Object).void }
+        def google_protobuf_any(value); end
+
+      #{method_defs.join("\n").gsub("\n", "\n  ")}
+      end
+    TEXT
+  end
+
   private
 
   def payload_methods