hyperprobe-agent 1.2.27.pre.3-java

data/lib/hyperprobe.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+begin
+  require_relative 'hyperprobe/version'
+  require_relative 'hyperprobe/protos'
+  require_relative 'hyperprobe/core/logger'
+  require_relative 'hyperprobe/agent'
+  require_relative 'hyperprobe/lambda'
+  require_relative 'hyperprobe/railtie' if defined?(::Rails::Railtie)
+rescue SignalException, SystemExit
+  raise
+rescue Exception
+  # Missing native dependencies or a broken JVM transport disable only the SDK.
+  module HyperProbe
+    LOAD_FAILED = true
+  end
+end
+
+module HyperProbe
+  @instance = nil
+  @mutex = Mutex.new
+  @owner_pid = Process.pid
+
+  class << self
+    def logger(namespace = 'hyperprobe:agent')
+      Core::Logger.get_logger(namespace)
+    end
+    def start(options = {})
+      reset_after_fork
+      return nil if defined?(LOAD_FAILED) || @fork_disabled
+      return nil unless @mutex.try_lock
+      locked = true
+      begin
+        return @instance if @instance
+        @stop_requested = false
+
+        if ENV['HYPERPROBE_DISABLED']&.strip&.upcase == 'YES'
+          puts '[HyperProbe] Explicitly disabled via ENV["HYPERPROBE_DISABLED"].'
+          return nil
+        end
+
+        opts = (options || {}).dup
+        commit_sha = opts[:commit_sha] || opts[:commitSha] || opts['commit_sha'] || opts['commitSha'] || ENV['GIT_COMMIT'] || ENV['HYPERPROBE_COMMIT_SHA']
+        if commit_sha.nil? || commit_sha.to_s.strip.empty? || commit_sha.to_s.strip.downcase == 'unknown'
+          warn "\e[1m\e[33m⚠️  [HyperProbe] CRITICAL: Failed to start agent. A valid \"commit_sha\" is required via options or the GIT_COMMIT environment variable to ensure accurate source map resolution and prevent cross-deployment collisions.\e[0m"
+          return nil
+        end
+        opts[:commit_sha] = commit_sha
+
+        service_id = opts[:service_id] || opts[:serviceId] || opts['service_id'] || opts['serviceId'] || ENV['HYPERPROBE_SERVICE_ID']
+        if service_id.nil? || service_id.to_s.strip.empty?
+          warn "\e[1m\e[33m⚠️  [HyperProbe] CRITICAL: Failed to start agent. HYPERPROBE_SERVICE_ID is required.\e[0m"
+          return nil
+        end
+        if service_id && !UUID_REGEX.match?(service_id.to_s)
+          warn "\e[1m\e[33m⚠️  [HyperProbe] WARN: service_id is not a valid UUID, please check again.\e[0m"
+        end
+        opts[:service_id] = service_id
+
+        environment = opts[:environment] || opts['environment'] || ENV['HYPERPROBE_ENVIRONMENT']
+        if environment.nil? || environment.to_s.strip.empty?
+          warn "\e[1m\e[33m⚠️  [HyperProbe] CRITICAL: Failed to start agent. HYPERPROBE_ENVIRONMENT is required.\e[0m"
+          return nil
+        end
+        opts[:environment] = environment
+
+        broker_url = opts[:broker_url] || opts[:brokerUrl] || opts['broker_url'] || opts['brokerUrl'] || ENV['HYPERPROBE_BROKER_URL']
+        unless valid_broker_url?(broker_url)
+          warn "\e[1m\e[33m⚠️  [HyperProbe] CRITICAL: Failed to start agent. Invalid broker_url \"#{broker_url}\". It must be a valid URL (http:// or https://) or a raw gRPC target (e.g. localhost:60051), with no query parameters and no trailing slash.\e[0m"
+          return nil
+        end
+        opts[:broker_url] = broker_url
+
+        if defined?(JRUBY_VERSION) || (defined?(RUBY_PLATFORM) && RUBY_PLATFORM =~ /java/)
+          raw_jruby_ver = defined?(JRUBY_VERSION) ? JRUBY_VERSION.to_s : '0'
+          jruby_ver = Gem::Version.new(raw_jruby_ver)
+          if jruby_ver < Gem::Version.new('9.3.0.0')
+            warn "[HyperProbe] Unsupported JRuby version (#{raw_jruby_ver}); JRuby 9.3+ is required."
+            return nil
+          end
+
+          unless jruby_debug_enabled?
+            warn "\e[1m\e[31m❌ [HyperProbe] CRITICAL: Failed to start agent on JRuby. The '--debug' launch flag (or JRUBY_OPTS=\"--debug\") is required for JRuby to preserve line boundaries and local variables. Please add 'ENV JRUBY_OPTS=\"--debug\"' to your deployment environment or start with 'jruby --debug'.\e[0m"
+            return nil
+          end
+
+          unless jruby_scope_preservation_enabled?
+            warn '[HyperProbe] Agent disabled: compiled JRuby probes require -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass and -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass at process startup. These preserve locals with JIT enabled; benchmark their application-wide cost before deployment.'
+            return nil
+          end
+
+          begin
+            require 'java'
+            java_ver_str = java.lang.System.getProperty('java.specification.version') || '11'
+            java_major = java_ver_str.sub(/^1\./, '').to_i
+            if java_major.positive? && java_major < 11
+              warn "\e[1m\e[33m⚠️  [HyperProbe] Unsupported Java runtime (#{java_ver_str}). HyperProbe on JRuby requires Java 11+ for native HTTP/2 gRPC.\e[0m"
+              return nil
+            end
+          rescue LoadError, StandardError
+            # Pass through if on non-JVM or property read is restricted
+          end
+        else
+          ruby_ver = Gem::Version.new(RUBY_VERSION)
+          if ruby_ver < Gem::Version.new('3.0.0')
+            warn "\e[1m\e[33m⚠️  [HyperProbe] Unsupported Ruby version (#{RUBY_VERSION}). HyperProbe requires Ruby 3.0+ for targeted line hooks.\e[0m"
+            return nil
+          end
+        end
+
+        if opts.delete(:defer_start) || opts.delete(:deferStart)
+          @deferred_options = opts
+          return nil
+        end
+        @native_owner_pid = Process.pid
+        candidate = Agent.new(opts)
+        return nil if candidate.is_shutdown
+        if @stop_requested
+          candidate.shutdown
+          return nil
+        end
+        @instance = candidate
+        puts "[HyperProbe] Ruby agent successfully started (Version: #{VERSION}, ID: #{@instance.agent_id}, PID: #{@instance.owner_pid})."
+        @instance
+      ensure
+        @mutex.unlock if locked
+      end
+    rescue SignalException, SystemExit
+      candidate&.shutdown
+      raise
+    rescue Exception
+      nil
+    end
+
+    def shutdown
+      reset_after_fork
+      @stop_requested = true
+      unless @mutex.try_lock
+        defer_shutdown
+        return nil
+      end
+      begin
+        inst = @instance
+        @instance = nil
+      ensure
+        @mutex.unlock
+      end
+      return unless inst
+      inst.shutdown
+      puts '[HyperProbe] Ruby agent successfully shut down.'
+    rescue ThreadError
+      defer_shutdown
+      nil
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      nil
+    end
+
+    def instance
+      @instance
+    end
+
+    def after_fork
+      return unless Process.respond_to?(:fork) && !defined?(JRUBY_VERSION)
+
+      return @instance if @owner_pid == Process.pid
+      reset_after_fork
+      if @fork_disabled
+        warn '[HyperProbe] Inherited agent disabled. Use defer_start: true before preloading and after_fork in each worker.'
+        return nil
+      end
+      options = @deferred_options
+      @deferred_options = nil
+      start(options) if options
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      nil
+    end
+
+    def wrap_lambda(options = {}, &handler)
+      return handler if defined?(LOAD_FAILED)
+      Lambda.wrap(options, &handler)
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      handler
+    end
+
+    def stop_lambda
+      Lambda.stop if defined?(Lambda)
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      nil
+    end
+
+    def jruby_debug_enabled?
+      begin
+        require 'java'
+        return Java::OrgJruby::RubyInstanceConfig.FULL_TRACE_ENABLED == true
+      rescue StandardError, ScriptError, NameError
+      end
+
+      false
+    end
+
+    def jruby_scope_preservation_enabled?
+      require 'java'
+      required = 'AddCallProtocolInstructions,AddMissingInitsPass'
+      Java::OrgJrubyUtilCli::Options::IR_COMPILER_PASSES.load.to_s == required &&
+        Java::OrgJrubyUtilCli::Options::IR_JIT_PASSES.load.to_s == required
+    rescue StandardError, ScriptError
+      false
+    end
+
+    def valid_broker_url?(url)
+      return false if url.nil? || url.to_s.strip.empty?
+
+      raw = url.to_s.strip
+      if raw.start_with?('http://', 'https://')
+        begin
+          uri = URI.parse(raw)
+          return !raw.end_with?('/') && (uri.query.nil? || uri.query.empty?) && !uri.host.nil? && !uri.host.empty?
+        rescue URI::InvalidURIError
+          return false
+        end
+      end
+
+      # Raw gRPC target
+      !raw.include?('://') && !raw.include?('/') && !raw.include?('?')
+    end
+
+    private
+
+    def defer_shutdown
+      Thread.new do
+        inst = @mutex.synchronize do
+          current = @instance
+          @instance = nil
+          current
+        end
+        inst&.shutdown
+      rescue Exception
+        # Cleanup waits only on an agent worker, never on an application thread.
+        nil
+      end
+    end
+
+    def reset_after_fork
+      return if @owner_pid == Process.pid
+      @owner_pid = Process.pid
+      @mutex = Mutex.new
+      if @native_owner_pid
+        @fork_disabled = true
+        @instance&.after_fork
+        @instance = nil
+      end
+    end
+
+    def puts(message)
+      notice($stdout, message)
+    end
+
+    def warn(message)
+      notice($stderr, message)
+    end
+
+    def notice(stream, message)
+      if IO === stream
+        IO.instance_method(:write_nonblock).bind(stream).call("#{message}\n", exception: false)
+      elsif defined?(StringIO) && StringIO === stream
+        StringIO.instance_method(:write).bind(stream).call("#{message}\n")
+      end
+    rescue SignalException, SystemExit
+      raise
+    rescue Exception
+      nil
+    end
+  end
+end

data/transport/README.md

@@ -0,0 +1,98 @@
+# JRuby gRPC Transport
+
+Runtime baseline: MRI 3.0+ (tested 4.0.6), or JRuby 9.3+ on Java 11+ with the required
+launch profile below. The Java artifact requires Ruby >= 2.6 and has no
+`google-protobuf`, native `grpc`, or `ffi` runtime dependencies. MRI remains
+Ruby >= 3.0 with `google-protobuf` >= 3.25, < 5 and `grpc` >= 1.50, < 2.
+Choose a JDK supported by the selected JRuby.
+
+```sh
+jruby --debug \
+  -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass \
+  -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass app.rb
+```
+
+`--debug` alone does not preserve all warmed line events/bindings. SDK startup
+checks the effective Java field
+`Java::OrgJruby::RubyInstanceConfig.FULL_TRACE_ENABLED` (dot access in Ruby code), and
+`Java::OrgJrubyUtilCli::Options::IR_COMPILER_PASSES.load` plus
+`Java::OrgJrubyUtilCli::Options::IR_JIT_PASSES.load` against the exact lists above.
+It rejects unsafe profiles rather than changing process configuration. JIT stays
+enabled without method exclusions.
+
+`rake build` builds both `pkg/hyperprobe-agent-VERSION.gem` and
+`pkg/hyperprobe-agent-VERSION-java.gem`. It needs Maven and JDK 11+ at build time;
+Maven fetches the pinned dependencies then. `rake build:ruby` needs neither Java
+nor Maven. `rake transport:build` prepares a source checkout for JRuby tests.
+Generated JARs are ignored by Git and must be built before packaging Java.
+The release script builds/validates both artifacts and tests both interpreters;
+set `HYPERPROBE_JRUBY` if the JRuby executable is not named `jruby`.
+
+Release both artifacts at the same version. Do not build a generic Ruby gem on
+JRuby and assume its dependencies will change on installation. The gemspec's
+explicit `HYPERPROBE_GEM_PLATFORM=ruby|java` build target controls its immutable
+platform and dependency metadata; the default is always `ruby`. The source
+Gemfile selects the interpreter's development target. Direct Java `gem build`
+requires the previously built JAR. No Maven, jar-dependencies, native compiler,
+or network download is used when the installed Java gem loads or connects.
+
+The JAR contains grpc-java 1.84.0 (`grpc-netty-shaded` and `grpc-stub`), its
+transitive dependencies, and patched `com.google.protobuf:protobuf-java:3.25.9`
+core only. It does not bundle `protobuf-java-util` or Google's JRuby bridge.
+Maven Shade relocates gRPC, Netty, Guava and supporting classes under
+`co.hyperprobe.internal`; in particular, `com.google.protobuf` becomes
+`co.hyperprobe.internal.google.protobuf`. Service descriptors and Apache notices
+are merged. The supplemental [third-party notice](THIRD_PARTY_NOTICES.md)
+preserves protobuf's upstream BSD 3-Clause license and source credits.
+
+The transport bridge accepts protobuf bytes. For JRuby, an SDK-private Ruby
+message adapter delegates encoding/decoding to Java `DynamicMessage` using the
+generated descriptor of the existing SDK Ruby protocol schema. No generated
+Java message models or Google Ruby runtime API are introduced. It neither creates
+nor changes the host's `Google::Protobuf` module; a host application's separately
+loaded Google protobuf remains independent. MRI retains its existing generated
+Ruby protobuf path. The POM and Java bridge/codec sources ship in the Java gem
+so its bundled dependency versions can be audited and rebuilt.
+
+NIO sockets and JDK TLS/ALPN avoid platform-specific native binaries. HTTPS uses
+the JVM's normal trust store and hostname verification, never an insecure trust
+manager. Configure a private CA with the standard JVM trust-store options.
+Raw `host:port` and `http://host:port` use plaintext gRPC; HTTPS uses TLS. IPv6
+addresses in URLs must be bracketed. No HTTP/1.1 fallback is attempted.
+
+grpc-java handles fragmentation, flow control, compression and terminal status.
+Unary responses are accepted only after an OK terminal status. Inbound messages
+are limited to 4 MiB, matching gRPC's usual default. Calls carry a finite deadline
+including DNS, connect, TLS, request writes and response reads. The Ruby broker
+starts the budget before constructing the request; the Java bridge also bounds
+the caller's wait and cancels timed-out/interrupted calls. Shutdown cancels active
+RPCs and asynchronously releases its daemon event-loop thread without waiting
+for network peers. Errors propagate to the agent's fail-isolation boundary as
+Ruby StandardError (RPC status with numeric `code`) or LoadError (missing or
+incompatible bundled transport), never as an empty successful response.
+
+Interop specs launch a local MRI C-core gRPC server. Run:
+
+```sh
+rake transport:build
+ruby -S rspec spec/broker_transport_spec.rb spec/packaging_spec.rb
+HYPERPROBE_MRI_RUBY=/path/to/mri/ruby jruby --debug \
+  -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass \
+  -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass \
+  -S rspec spec/broker_transport_spec.rb spec/packaging_spec.rb
+```
+
+The MRI executable must have `grpc`, `google-protobuf` and `rspec` installed.
+The JRuby executable needs `rspec`, not the `google-protobuf` gem. Tests generate disposable
+local TLS certificates and a trust store; production trust configuration is not
+modified.
+
+Clean packaged Bundler installs have succeeded on JRuby 9.3 and 10.1 without
+forced installs or Google Ruby protobuf load-path overrides. JRuby 9.3 needs
+Ruby 2.6-compatible Bundler 2.4. Do not reuse a frozen Ruby 4 development
+lockfile on older runtimes without resolving for that runtime. The release
+script now supplies the complete required profile to its JRuby test invocation.
+
+`HYPERPROBE_TEST_LIB=/installed/gem/lib` runs the interop clients against an
+installed package rather than the source checkout. The test server remains the
+independent MRI C-core fixture.

data/transport/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,57 @@
+# Third-Party Notices
+
+The Java artifact bundles third-party libraries in
+`lib/hyperprobe/jars/hyperprobe-grpc.jar`. Its build inputs and pinned versions
+are recorded in `transport/pom.xml`; upstream license/notice resources are also
+carried in the shaded JAR. This supplemental notice preserves the protobuf
+copyright, conditions, and disclaimer for binary redistribution. It does not
+replace other bundled libraries' notices or change the SDK's own license.
+
+## Protocol Buffers Java Core 3.25.9
+
+- Component: `com.google.protobuf:protobuf-java:3.25.9` (core only, not
+  `protobuf-java-util` or Google's JRuby bridge).
+- Upstream project and source: <https://github.com/protocolbuffers/protobuf/tree/v25.9>.
+- Official license: <https://github.com/protocolbuffers/protobuf/blob/v25.9/LICENSE>.
+- Retrieved from <https://raw.githubusercontent.com/protocolbuffers/protobuf/v25.9/LICENSE>
+  on 2026-09-07; license text reproduced below verbatim.
+- License: BSD 3-Clause. This permits source and binary redistribution, including
+  modified versions, subject to the notice, disclaimer, and non-endorsement
+  conditions below. The SDK shades `com.google.protobuf` to
+  `co.hyperprobe.internal.google.protobuf`; upstream credit and license terms
+  remain applicable.
+
+```text
+Copyright 2008 Google Inc.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+    * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Code generated by the Protocol Buffer compiler is owned by the owner
+of the input file used when generating it.  This code is not
+standalone and requires a support library to be linked with it.  This
+support library is itself covered by the above license.
+```

data/transport/pom.xml

@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>co.hyperprobe</groupId>
+  <artifactId>hyperprobe-grpc</artifactId>
+  <version>1.0.0</version>
+  <properties>
+    <maven.compiler.release>11</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <project.build.outputTimestamp>2026-09-07T00:00:00Z</project.build.outputTimestamp>
+    <grpc.version>1.84.0</grpc.version>
+    <protobuf.version>3.25.9</protobuf.version>
+  </properties>
+  <dependencies>
+    <dependency>
+      <groupId>com.google.protobuf</groupId><artifactId>protobuf-java</artifactId><version>${protobuf.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>io.grpc</groupId><artifactId>grpc-netty-shaded</artifactId><version>${grpc.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>io.grpc</groupId><artifactId>grpc-stub</artifactId><version>${grpc.version}</version>
+    </dependency>
+  </dependencies>
+  <build>
+    <finalName>hyperprobe-grpc</finalName>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.14.1</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId><artifactId>maven-jar-plugin</artifactId><version>3.4.2</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId><artifactId>maven-shade-plugin</artifactId><version>3.6.1</version>
+        <executions>
+          <execution>
+            <phase>package</phase><goals><goal>shade</goal></goals>
+            <configuration>
+              <createDependencyReducedPom>false</createDependencyReducedPom>
+              <relocations>
+                <relocation><pattern>io.grpc</pattern><shadedPattern>co.hyperprobe.internal.grpc</shadedPattern></relocation>
+                <relocation><pattern>com.google</pattern><shadedPattern>co.hyperprobe.internal.google</shadedPattern></relocation>
+                <relocation><pattern>io.perfmark</pattern><shadedPattern>co.hyperprobe.internal.perfmark</shadedPattern></relocation>
+                <relocation><pattern>org.codehaus</pattern><shadedPattern>co.hyperprobe.internal.codehaus</shadedPattern></relocation>
+                <relocation><pattern>javax.annotation</pattern><shadedPattern>co.hyperprobe.internal.annotation</shadedPattern></relocation>
+                <relocation><pattern>org.jspecify</pattern><shadedPattern>co.hyperprobe.internal.jspecify</shadedPattern></relocation>
+              </relocations>
+              <filters>
+                <filter>
+                  <artifact>*:*</artifact>
+                  <excludes>
+                    <exclude>META-INF/*.SF</exclude><exclude>META-INF/*.RSA</exclude><exclude>META-INF/*.DSA</exclude>
+                    <exclude>META-INF/native/**</exclude><exclude>module-info.class</exclude>
+                    <exclude>META-INF/versions/**/module-info.class</exclude>
+                  </excludes>
+                </filter>
+              </filters>
+              <transformers>
+                <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+                <transformer implementation="org.apache.maven.plugins.shade.resource.ApacheLicenseResourceTransformer"/>
+                <transformer implementation="org.apache.maven.plugins.shade.resource.ApacheNoticeResourceTransformer"/>
+                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                  <manifestEntries>
+                    <Multi-Release>true</Multi-Release>
+                    <HyperProbe-Protobuf-Version>${protobuf.version}</HyperProbe-Protobuf-Version>
+                    <HyperProbe-Grpc-Version>${grpc.version}</HyperProbe-Grpc-Version>
+                  </manifestEntries>
+                </transformer>
+              </transformers>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>

data/transport/src/main/java/co/hyperprobe/transport/GrpcTransport.java

@@ -0,0 +1,118 @@
+package co.hyperprobe.transport;
+
+import com.google.common.util.concurrent.ListenableFuture;
+import io.grpc.CallOptions;
+import io.grpc.Channel;
+import io.grpc.ClientInterceptors;
+import io.grpc.Deadline;
+import io.grpc.ManagedChannel;
+import io.grpc.Metadata;
+import io.grpc.MethodDescriptor;
+import io.grpc.Status;
+import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
+import io.grpc.netty.shaded.io.grpc.netty.NettyChannelBuilder;
+import io.grpc.netty.shaded.io.netty.channel.nio.NioEventLoopGroup;
+import io.grpc.netty.shaded.io.netty.channel.socket.nio.NioSocketChannel;
+import io.grpc.netty.shaded.io.netty.handler.ssl.SslProvider;
+import io.grpc.netty.shaded.io.netty.handler.ssl.SslContextBuilder;
+import io.grpc.netty.shaded.io.netty.util.concurrent.DefaultThreadFactory;
+import io.grpc.stub.ClientCalls;
+import io.grpc.stub.MetadataUtils;
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+/** Byte-only boundary: protobuf encoding remains in Ruby, HTTP/2 belongs to grpc-java. */
+public final class GrpcTransport {
+    private static final MethodDescriptor.Marshaller<byte[]> BYTES = new MethodDescriptor.Marshaller<byte[]>() {
+        public InputStream stream(byte[] value) {
+            return new ByteArrayInputStream(value);
+        }
+
+        public byte[] parse(InputStream stream) {
+            try {
+                return stream.readAllBytes();
+            } catch (IOException e) {
+                throw Status.INTERNAL.withCause(e).asRuntimeException();
+            }
+        }
+    };
+
+    private final NioEventLoopGroup eventLoop;
+    private final ManagedChannel channel;
+    private final Channel authenticatedChannel;
+
+    public GrpcTransport(String host, int port, boolean secure, String serviceId, boolean keepAlive)
+            throws javax.net.ssl.SSLException {
+        eventLoop = new NioEventLoopGroup(1, new DefaultThreadFactory("hyperprobe-grpc", true));
+        try {
+            // Explicit NIO/JDK TLS avoids platform-specific native libraries in the gem.
+            NettyChannelBuilder builder = NettyChannelBuilder.forAddress(host, port)
+                    .eventLoopGroup(eventLoop).channelType(NioSocketChannel.class)
+                    .maxInboundMessageSize(4 * 1024 * 1024).disableRetry();
+            if (secure) {
+                builder.sslContext(GrpcSslContexts.configure(SslContextBuilder.forClient(), SslProvider.JDK).build());
+            } else {
+                builder.usePlaintext();
+            }
+            if (keepAlive) {
+                builder.keepAliveTime(60, TimeUnit.SECONDS).keepAliveTimeout(20, TimeUnit.SECONDS)
+                        .keepAliveWithoutCalls(true);
+            }
+            Metadata metadata = new Metadata();
+            metadata.put(Metadata.Key.of("x-hp-service-id", Metadata.ASCII_STRING_MARSHALLER), serviceId);
+            channel = builder.build();
+            authenticatedChannel = ClientInterceptors.intercept(channel,
+                    MetadataUtils.newAttachHeadersInterceptor(metadata));
+        } catch (RuntimeException | Error | javax.net.ssl.SSLException e) {
+            eventLoop.shutdownGracefully(0, 1, TimeUnit.SECONDS);
+            throw e;
+        }
+    }
+
+    public byte[] call(String method, byte[] request, long timeoutNanos) throws RpcException {
+        Deadline deadline = Deadline.after(timeoutNanos, TimeUnit.NANOSECONDS);
+        MethodDescriptor<byte[], byte[]> descriptor = MethodDescriptor.<byte[], byte[]>newBuilder()
+                .setType(MethodDescriptor.MethodType.UNARY).setFullMethodName(method)
+                .setRequestMarshaller(BYTES).setResponseMarshaller(BYTES).build();
+        ListenableFuture<byte[]> future = ClientCalls.futureUnaryCall(
+                authenticatedChannel.newCall(descriptor, CallOptions.DEFAULT.withDeadline(deadline)), request);
+        try {
+            // The caller is bounded even during DNS, connect, TLS, or a stalled peer.
+            // A unary future completes only after terminal grpc-status, not the first DATA frame.
+            return future.get(Math.max(0, deadline.timeRemaining(TimeUnit.NANOSECONDS)), TimeUnit.NANOSECONDS);
+        } catch (TimeoutException e) {
+            throw new RpcException(Status.DEADLINE_EXCEEDED);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new RpcException(Status.CANCELLED);
+        } catch (ExecutionException e) {
+            throw new RpcException(Status.fromThrowable(e.getCause()));
+        } finally {
+            if (!future.isDone()) {
+                future.cancel(true);
+            }
+        }
+    }
+
+    public void shutdown() {
+        channel.shutdownNow();
+        eventLoop.shutdownGracefully(0, 1, TimeUnit.SECONDS);
+    }
+
+    public static final class RpcException extends Exception {
+        private final int code;
+
+        RpcException(Status status) {
+            super(status.getCode() + ": " + status.getDescription());
+            code = status.getCode().value();
+        }
+
+        public int getCode() {
+            return code;
+        }
+    }
+}

data/transport/src/main/java/co/hyperprobe/transport/ProtoCodec.java

@@ -0,0 +1,43 @@
+package co.hyperprobe.transport;
+
+import com.google.protobuf.ByteString;
+import com.google.protobuf.CodedInputStream;
+import com.google.protobuf.DescriptorProtos.FileDescriptorProto;
+import com.google.protobuf.Descriptors;
+import com.google.protobuf.DynamicMessage;
+import java.io.IOException;
+
+/** SDK-private protobuf runtime. Maven relocates every protobuf type in this API. */
+public final class ProtoCodec {
+    public static final int MAX_BYTES = 4 * 1024 * 1024;
+    private final Descriptors.FileDescriptor file;
+
+    public ProtoCodec(byte[] descriptor) throws IOException, Descriptors.DescriptorValidationException {
+        file = Descriptors.FileDescriptor.buildFrom(
+                FileDescriptorProto.parseFrom(descriptor), new Descriptors.FileDescriptor[0]);
+    }
+
+    public Descriptors.FileDescriptor getFile() {
+        return file;
+    }
+
+    public DynamicMessage.Builder builder(Descriptors.Descriptor descriptor) {
+        return DynamicMessage.newBuilder(descriptor);
+    }
+
+    public ByteString bytes(byte[] value) {
+        return ByteString.copyFrom(value);
+    }
+
+    public DynamicMessage decode(Descriptors.Descriptor descriptor, byte[] bytes) throws IOException {
+        if (bytes.length > MAX_BYTES) {
+            throw new IllegalArgumentException("Protobuf payload exceeds 4 MiB");
+        }
+        CodedInputStream input = CodedInputStream.newInstance(bytes);
+        input.setSizeLimit(MAX_BYTES);
+        input.setRecursionLimit(64);
+        DynamicMessage message = DynamicMessage.parseFrom(descriptor, input);
+        input.checkLastTagWas(0);
+        return message;
+    }
+}