frpc-ruby 0.70.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ddb7670b1112087e9f2e56e98977ada1bea3f9c741a1bdc4e97f1afc4c059732
+  data.tar.gz: 24fea9e84d86352b559985b4259d79ff16ad5ddc84b09ef96299bc3e26765c26
+SHA512:
+  metadata.gz: 90ff336c66197c8209324d7d4ca4cc9ccb7813f549dba81a1a01e565a69652eb15ae7c15b3cd2974989a63c0cc9ab43b5d911b50f283310062f8e7e631581623
+  data.tar.gz: cf281245d1f5a85f0e2503b265b8cbab978d7aa47510f543fbe622029ad7274bf0ab7af3ac7256ea895fdb58c1179cbc39ff0ab0f1b10b72cbcb9d66b5574dd7

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.70.1
+
+- First release. Vendors frp 0.70.1 (`CGO_ENABLED=0` upstream builds) as one
+  platform gem per target, with a `ruby`-platform gem for everything else.
+- `Frpc::Ruby.executable` resolution: explicit path, `FRPC_INSTALL_DIR` /
+  `FRPC_PATH`, vendored binary, then `PATH`.
+- `Frpc::Client` spawns and supervises frpc; `Frpc::Admin` wraps the admin API
+  (`/healthz`, `/api/status`, `/api/config`, `/api/reload`, `/api/stop`, and the
+  frp >= 0.68 store CRUD endpoints).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Kidd
+
+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.

data/README.md

@@ -0,0 +1,169 @@
+# frpc-ruby
+
+The [frp](https://github.com/fatedier/frp) client as a Ruby gem: the upstream
+`frpc` binary for your platform, plus a small wrapper that runs it and drives
+its admin HTTP API from Ruby.
+
+Packaged the way [`tailwindcss-ruby`](https://github.com/flavorjones/tailwindcss-ruby)
+is — one platform gem per target, each carrying the matching binary from the
+official frp release, and a plain `ruby` gem that carries none.
+
+## Install
+
+```ruby
+gem "frpc-ruby"
+```
+
+Bundler only fetches platform gems for platforms in your lockfile, so add the
+ones you deploy to:
+
+```sh
+bundle lock --add-platform x86_64-linux aarch64-linux arm64-darwin
+```
+
+`BUNDLE_FORCE_RUBY_PLATFORM=true` selects the binary-less gem — don't set it
+unless you're supplying `frpc` yourself.
+
+## Use
+
+The wrapper talks to frpc over its admin API, so the config must enable it:
+
+```toml
+serverAddr = "example.com"
+serverPort = 7000
+
+webServer.addr = "127.0.0.1"
+webServer.port = 7400
+webServer.user = "admin"
+webServer.password = "hunter2"
+
+[[proxies]]
+name = "ssh"
+type = "tcp"
+localPort = 22
+remotePort = 6000
+```
+
+`Client` reads `webServer.*` out of that file, so it needs nothing but a path:
+
+```ruby
+require "frpc"
+
+client = Frpc::Client.new("frpc.toml")
+
+client.status              # => {"tcp" => [{"name" => "ssh", "status" => "running", ...}]}
+client.proxy("ssh")        # => that one proxy's hash, or nil
+client.config              # => the config file as frpc currently sees it
+client.reload(new_toml)    # PUT /api/config, then GET /api/reload — no restart
+client.stop                # POST /api/stop, then reap; TERM/KILL if it hangs
+```
+
+`Client.run` guarantees the child is stopped, even on an exception:
+
+```ruby
+Frpc::Client.run("frpc.toml") { |client| pp client.status }
+```
+
+To talk to an frpc you didn't spawn — a systemd unit, another container — skip
+`Client` and use `Admin` directly:
+
+```ruby
+admin = Frpc::Admin.new(host: "127.0.0.1", port: 7400, user: "admin", password: "hunter2")
+admin.wait_until_healthy
+admin.status
+admin.reload
+```
+
+Reloading takes a moment to settle: frpc diffs the new config against the
+running proxies and creates, updates, or removes them asynchronously.
+
+### Just the binary
+
+```ruby
+Frpc::Ruby.executable   # => "/…/gems/frpc-ruby-0.70.1-x86_64-linux/exe/x86_64-linux/frpc"
+```
+
+The gem also installs an `frpc` shim on your `PATH`, so `bundle exec frpc -c frpc.toml`
+works, as does `frps`-style usage of any subcommand — the shim `exec`s the real
+binary with your arguments untouched.
+
+Resolution order:
+
+1. `Frpc::Ruby.executable(exe_path: "…")`
+2. `FRPC_INSTALL_DIR` (a directory) or `FRPC_PATH` (a file)
+3. the binary vendored in this gem
+4. `frpc` on `PATH`
+
+That's the escape hatch for unsupported architectures: install frpc yourself,
+set `FRPC_INSTALL_DIR`, and the `ruby`-platform gem works fine.
+
+## Platforms
+
+| gem platform | frp release target |
+| --- | --- |
+| `x86_64-linux` | `linux_amd64` |
+| `aarch64-linux` | `linux_arm64` |
+| `arm-linux` | `linux_arm` |
+| `arm64-darwin` | `darwin_arm64` |
+| `x86_64-darwin` | `darwin_amd64` |
+| `x64-mingw-ucrt` | `windows_amd64` |
+| `aarch64-mingw-ucrt` | `windows_arm64` |
+
+Upstream builds every non-darwin target with `CGO_ENABLED=0`, so one Linux
+binary per arch covers glibc and musl alike — no separate `-gnu`/`-musl` gems.
+
+## Why a subprocess and not cgo
+
+You can wrap `client.Service` in a `-buildmode=c-shared` object and load it with
+FFI, but a process that has loaded the Go runtime can't `fork` and keep using Go
+in the child ([golang/go#15538](https://github.com/golang/go/issues/15538)),
+which is a live hazard under Puma cluster mode, Unicorn, Resque and Spring. It
+also can't be `dlclose`d ([golang/go#11100](https://github.com/golang/go/issues/11100)),
+and it re-breaks whenever frp changes its internal API.
+
+A subprocess has a better failure mode: frpc crashing kills frpc, not your VM.
+The cgo route only pays off if you need the tunnel's data path inside the Ruby
+process — a custom `HandleWorkConnCb` or `ConnectorCreator` — which has no HTTP
+equivalent.
+
+## Development
+
+```sh
+direnv allow          # or: nix develop
+bin/test              # unit tests — a fake frpc, no network
+bin/smoke             # real frps + frpc, real bytes through a real tunnel
+rake vendor:all       # download + verify + unpack every platform's frpc
+rake gem:all          # build pkg/*.gem for every platform, plus the ruby gem
+```
+
+## Releasing
+
+Versions mirror upstream: gem `0.70.1` vendors frp `0.70.1`. A wrapper-only fix
+appends a fourth segment (`0.70.1.1`), which RubyGems orders after `0.70.1` and
+before `0.70.2`.
+
+```sh
+bin/sync-upstream            # latest frp release: bumps VERSION, pins checksums
+bin/sync-upstream 0.71.0     # or a specific one
+bin/increment-version        # wrapper-only bump instead: 0.70.1 -> 0.70.1.1
+
+bin/smoke                    # prove the new binary tunnels before shipping it
+git commit -am "frp 0.71.0" && git push     # CI builds the platform gems
+bin/release-gem              # push them to RubyGems, then tag
+```
+
+`bin/release-gem` builds the ruby-platform gem locally, downloads the platform
+gems from the latest successful `build-gems.yml` run, refuses to continue if any
+platform is missing or if CI built a different version, and tolerates gems that
+are already published so a half-finished release can be re-run.
+
+CI is what builds the shipped binaries, on purpose: it fetches them from GitHub
+Releases and verifies each against the committed `checksums/v<version>.txt`, so
+what ships never depends on the state of somebody's `vendor/` directory. Without
+that pin the Rakefile warns and falls back to the checksum file published
+alongside the release, which only catches transport corruption.
+
+## License
+
+MIT for this wrapper. The vendored `frpc` binary is
+[Apache-2.0](https://github.com/fatedier/frp/blob/dev/LICENSE), © the frp authors.

data/exe/frpc

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# RubyGems requires gemspec executables to be Ruby scripts, so the binary
+# itself cannot be the $PATH entry. This shim resolves and exec's it, keeping
+# the process (and therefore signals and exit status) intact.
+
+require "frpc/ruby"
+
+begin
+  exec(Frpc::Ruby.executable, *ARGV)
+rescue Frpc::Ruby::ExecutableNotFoundError, Frpc::Ruby::UnsupportedPlatformError => e
+  warn e.message
+  exit 1
+end

data/lib/frpc/admin.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Frpc
+  # Thin wrapper over the frpc admin HTTP API (`webServer.*` in frpc.toml).
+  #
+  #   webServer.addr = "127.0.0.1"
+  #   webServer.port = 7400
+  #   webServer.user = "admin"
+  #   webServer.password = "hunter2"
+  #
+  # Endpoints, as registered by client/admin_api.go:
+  #   GET  /healthz            (no auth)
+  #   GET  /api/status         per-proxy state
+  #   GET  /api/config         current config file contents
+  #   PUT  /api/config         overwrite the config file
+  #   GET  /api/reload         re-read the config file, diff, apply
+  #   POST /api/stop           graceful shutdown
+  #   GET/POST/PUT/DELETE /api/store/proxies*, /api/store/visitors*  (frp >= 0.68)
+  class Admin
+    class Error < StandardError; end
+
+    # Raised when frpc answers, but not with success.
+    class ResponseError < Error
+      attr_reader :code, :body
+
+      def initialize(method, path, code, body)
+        @code = code
+        @body = body
+        super("frpc #{method} #{path} failed: #{code} #{body}")
+      end
+    end
+
+    attr_reader :host, :port, :user
+
+    def initialize(host: "127.0.0.1", port: 7400, user: nil, password: nil, open_timeout: 2, read_timeout: 10)
+      @host = host
+      @port = Integer(port)
+      @user = user
+      @password = password
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # true once the admin server is listening. Never raises — this is the
+    # readiness probe, so a connection refused is an expected answer.
+    def healthy?
+      request(Net::HTTP::Get.new("/healthz"), auth: false)
+      true
+    rescue Error
+      false
+    end
+
+    # Blocks until healthy?, then returns self. Raises after the deadline.
+    def wait_until_healthy(timeout: 10, interval: 0.1)
+      deadline = monotonic_now + timeout
+      loop do
+        return self if healthy?
+        raise Error, "frpc admin server never came up on #{host}:#{port}" if monotonic_now >= deadline
+
+        sleep interval
+      end
+    end
+
+    # Per-proxy state: name, type, status ("running" / "start error" / ...),
+    # err, local_addr, plugin, remote_addr. Keyed by proxy type.
+    def status
+      get("/api/status")
+    end
+
+    # The config file frpc was started with, as a string.
+    def config
+      get("/api/config")
+    end
+
+    # Overwrite the config file on the frpc host. Does NOT apply it — call
+    # reload afterwards, which is what `frpc reload -c ...` does internally.
+    def config=(toml)
+      put("/api/config", toml)
+    end
+
+    # Re-read the config file and create/update/delete proxies to match.
+    # Optionally writes new_toml first.
+    def reload(new_toml = nil)
+      self.config = new_toml if new_toml
+      get("/api/reload")
+    end
+
+    # Graceful shutdown. The HTTP response comes back before the process exits.
+    def stop
+      post("/api/stop")
+    end
+
+    # --- store API (frp >= 0.68), only meaningful with a store source configured
+
+    def store_proxies
+      get("/api/store/proxies")
+    end
+
+    def store_visitors
+      get("/api/store/visitors")
+    end
+
+    def put_store_proxy(name, config)
+      put("/api/store/proxies/#{escape(name)}", JSON.generate(config), content_type: "application/json")
+    end
+
+    def delete_store_proxy(name)
+      delete("/api/store/proxies/#{escape(name)}")
+    end
+
+    def put_store_visitor(name, config)
+      put("/api/store/visitors/#{escape(name)}", JSON.generate(config), content_type: "application/json")
+    end
+
+    def delete_store_visitor(name)
+      delete("/api/store/visitors/#{escape(name)}")
+    end
+
+    # --- verbs
+
+    def get(path)
+      request(Net::HTTP::Get.new(path))
+    end
+
+    def post(path, body = nil, content_type: nil)
+      request(build(Net::HTTP::Post, path, body, content_type))
+    end
+
+    def put(path, body = nil, content_type: nil)
+      request(build(Net::HTTP::Put, path, body, content_type))
+    end
+
+    def delete(path)
+      request(Net::HTTP::Delete.new(path))
+    end
+
+    private
+
+    def build(klass, path, body, content_type)
+      req = klass.new(path)
+      req.body = body if body
+      req["Content-Type"] = content_type if content_type
+      req
+    end
+
+    def escape(segment)
+      URI.encode_www_form_component(segment.to_s)
+    end
+
+    # Returns parsed JSON when the response is JSON, the raw body when it is
+    # not (GET /api/config hands back TOML), and nil for empty bodies.
+    def request(req, auth: true)
+      req.basic_auth(@user, @password) if auth && @user
+
+      response = http.request(req)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise ResponseError.new(req.method, req.path, response.code, response.body.to_s)
+      end
+
+      decode(response)
+    rescue SystemCallError, Net::OpenTimeout, Net::ReadTimeout, IOError, EOFError => e
+      raise Error, "frpc #{req.method} #{req.path} failed: #{e.class}: #{e.message}"
+    end
+
+    def decode(response)
+      body = response.body.to_s
+      return nil if body.empty?
+      return body unless response["Content-Type"].to_s.include?("json")
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def http
+      Net::HTTP.new(host, port).tap do |client|
+        client.open_timeout = @open_timeout
+        client.read_timeout = @read_timeout
+      end
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/frpc/client.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "frpc/admin"
+require "frpc/ruby"
+
+module Frpc
+  # Runs frpc as a child process and controls it over its admin API.
+  #
+  #   client = Frpc::Client.new("frpc.toml", user: "admin", password: "hunter2")
+  #   client.status
+  #   client.reload(File.read("frpc2.toml"))
+  #   client.stop
+  #
+  # Or scoped, which always stops the child:
+  #
+  #   Frpc::Client.run("frpc.toml") { |c| pp c.status }
+  #
+  # The config file must enable the admin server, otherwise there is nothing to
+  # talk to and #start raises:
+  #
+  #   webServer.addr = "127.0.0.1"
+  #   webServer.port = 7400
+  class Client
+    class Error < StandardError; end
+
+    DEFAULT_ADMIN = { host: "127.0.0.1", port: 7400 }.freeze
+
+    attr_reader :config_path, :admin, :pid
+
+    def self.run(config_path, **kwargs)
+      client = new(config_path, **kwargs)
+      begin
+        yield client
+      ensure
+        client.stop
+      end
+    end
+
+    # host/port/user/password default to whatever webServer.* the config file
+    # declares, falling back to 127.0.0.1:7400. Pass them explicitly to skip
+    # that sniffing entirely.
+    def initialize(config_path,
+                   executable: nil,
+                   host: nil, port: nil, user: nil, password: nil,
+                   env: {}, log_to: nil, timeout: 10, start: true)
+      @config_path = File.expand_path(config_path)
+      raise Error, "no such frpc config file: #{@config_path}" unless File.exist?(@config_path)
+
+      @executable = Frpc::Ruby.executable(exe_path: executable)
+      @env = env
+      @log_to = log_to
+      @timeout = timeout
+
+      settings = web_server_settings
+      @admin = Admin.new(
+        host: host || settings[:addr] || DEFAULT_ADMIN[:host],
+        port: port || settings[:port] || DEFAULT_ADMIN[:port],
+        user: user || settings[:user],
+        password: password || settings[:password],
+      )
+
+      self.start if start
+    end
+
+    def start
+      raise Error, "frpc is already running (pid #{@pid})" if running?
+
+      @pid = Process.spawn(@env, @executable, "-c", @config_path, **spawn_options)
+      wait_for_admin
+      self
+    end
+
+    def running?
+      return false unless @pid
+
+      Process.waitpid(@pid, Process::WNOHANG).nil?
+    rescue Errno::ECHILD, Errno::ESRCH
+      false
+    end
+
+    def status = admin.status
+    def config = admin.config
+    def reload(new_toml = nil) = admin.reload(new_toml)
+
+    # Per-proxy hash for `name`, or nil when frpc does not know that proxy.
+    def proxy(name)
+      status.to_h.each_value do |proxies|
+        found = Array(proxies).find { |p| p["name"] == name.to_s }
+        return found if found
+      end
+      nil
+    end
+
+    # Asks frpc to shut down gracefully, then reaps the child. Falls back to
+    # TERM and finally KILL if it does not exit within `timeout`.
+    def stop(timeout: @timeout)
+      return unless @pid
+
+      begin
+        admin.stop
+      rescue Admin::Error
+        # Admin server already gone or never came up — signals below still apply.
+      end
+
+      reap(timeout: timeout) || terminate(timeout: timeout)
+      @pid = nil
+    end
+
+    private
+
+    def spawn_options
+      options = { pgroup: true }
+      if @log_to
+        options[:out] = @log_to
+        options[:err] = [:child, :out]
+      end
+      options
+    end
+
+    def wait_for_admin
+      deadline = now + @timeout
+      loop do
+        return if admin.healthy?
+
+        unless running?
+          raise Error, "frpc exited immediately; check its logs and #{@config_path}"
+        end
+        if now >= deadline
+          stop
+          raise Error, <<~MSG
+            frpc started (pid #{@pid}) but its admin API never answered on
+            #{admin.host}:#{admin.port} within #{@timeout}s. Does #{@config_path}
+            set webServer.addr and webServer.port?
+          MSG
+        end
+
+        sleep 0.05
+      end
+    end
+
+    # true once the child has been reaped, false on timeout.
+    def reap(timeout:)
+      deadline = now + timeout
+      loop do
+        return true unless running?
+        return false if now >= deadline
+
+        sleep 0.05
+      end
+    end
+
+    def terminate(timeout:)
+      signal("TERM")
+      return true if reap(timeout: timeout)
+
+      signal("KILL")
+      reap(timeout: timeout)
+    end
+
+    def signal(name)
+      Process.kill(name, @pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Best-effort scan of the config for webServer settings, supporting both
+    # the dotted form (webServer.port = 7400) and the table form
+    # ([webServer] / port = 7400). Anything explicitly passed to #initialize
+    # wins over this, so a parse miss is never fatal.
+    def web_server_settings
+      settings = {}
+      in_table = false
+
+      File.foreach(@config_path) do |line|
+        line = line.sub(/(?<!\\)#.*/, "").strip
+        next if line.empty?
+
+        if (table = line[/\A\[+\s*([^\]]+?)\s*\]+\z/, 1])
+          in_table = table.casecmp?("webServer")
+          next
+        end
+
+        key, value = line.split("=", 2)
+        next unless value
+
+        key = key.strip
+        dotted = key.sub!(/\AwebServer\./i, "") # nil when the prefix was absent
+        next unless dotted || in_table
+
+        assign(settings, key, value.strip)
+      end
+
+      settings
+    rescue SystemCallError
+      {}
+    end
+
+    def assign(settings, key, value)
+      value = value[1..-2] if value.start_with?('"') && value.end_with?('"')
+
+      case key.downcase
+      when "addr" then settings[:addr] = value
+      when "port" then settings[:port] = Integer(value, exception: false)
+      when "user" then settings[:user] = value
+      when "password" then settings[:password] = value
+      end
+    end
+  end
+end

data/lib/frpc/ruby/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Frpc
+  module Ruby
+    # Mirrors the upstream frp release we vendor. If the wrapper itself needs a
+    # release without an upstream bump, append a fourth segment ("0.70.1.1") —
+    # UPSTREAM_VERSION drops it again when building download URLs.
+    VERSION = "0.70.1"
+
+    UPSTREAM_VERSION = VERSION.split(".").first(3).join(".")
+  end
+end

data/lib/frpc/ruby.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "frpc/ruby/version"
+
+module Frpc
+  # Locates the `frpc` executable this gem should run.
+  #
+  # The gem ships as one platform gem per supported target, each carrying the
+  # matching CGO_ENABLED=0 binary from the upstream frp release under
+  # exe/<gem-platform>/. The plain "ruby" platform gem carries no binary at all;
+  # on an unsupported architecture the user installs frpc themselves and points
+  # FRPC_INSTALL_DIR at it.
+  module Ruby
+    # gem platform => upstream frp release target suffix
+    PLATFORMS = {
+      "arm64-darwin"    => "darwin_arm64",
+      "x86_64-darwin"   => "darwin_amd64",
+      "aarch64-linux"   => "linux_arm64",
+      "arm-linux"       => "linux_arm",
+      "x86_64-linux"    => "linux_amd64",
+      "x64-mingw-ucrt"  => "windows_amd64",
+      "x64-mingw32"     => "windows_amd64",
+      "aarch64-mingw-ucrt" => "windows_arm64",
+    }.freeze
+
+    # Platforms we actually publish a gem for. x64-mingw32 resolves at runtime
+    # (old rubies report that platform string) but shares the ucrt gem's binary,
+    # so it is not built separately.
+    PACKAGED_PLATFORMS = PLATFORMS.keys - ["x64-mingw32"]
+
+    class UnsupportedPlatformError < StandardError; end
+    class ExecutableNotFoundError < StandardError; end
+
+    class << self
+      # Resolution order, first hit wins:
+      #   1. an explicit exe_path: argument
+      #   2. FRPC_INSTALL_DIR / FRPC_PATH (a directory or a full path)
+      #   3. the binary vendored into this gem for the current platform
+      #   4. frpc on PATH
+      def executable(exe_path: nil)
+        override = exe_path || ENV["FRPC_INSTALL_DIR"] || ENV["FRPC_PATH"]
+        return resolve_override(override) unless override.nil? || override.empty?
+
+        return vendored_executable if vendored_executable
+        return path_executable if path_executable
+
+        raise ExecutableNotFoundError, <<~MSG
+          Cannot find the frpc executable for platform #{platform}.
+
+          This usually means the platform gem for #{platform} was not installed.
+          Bundler only locks the platforms it has seen, so try:
+
+              bundle lock --add-platform #{platform}
+
+          If #{platform} is not a platform frpc-ruby ships a binary for, install
+          frpc yourself from https://github.com/fatedier/frp/releases and set
+          FRPC_INSTALL_DIR to the directory containing it (or FRPC_PATH to the
+          executable itself).
+        MSG
+      end
+
+      # e.g. "x86_64-linux", "arm64-darwin"
+      def platform
+        @platform ||= [:cpu, :os].map { |part| Gem::Platform.local.public_send(part) }.join("-")
+      end
+
+      # The upstream release target for the running platform, e.g. "linux_amd64".
+      def upstream_target(gem_platform = platform)
+        PLATFORMS.fetch(gem_platform) do
+          raise UnsupportedPlatformError, "frpc-ruby has no upstream frp build for #{gem_platform}"
+        end
+      end
+
+      def exe_name
+        Gem.win_platform? ? "frpc.exe" : "frpc"
+      end
+
+      # Path the packaging task writes to, and the path executable/2 reads back.
+      def vendored_path(gem_platform = platform, name = exe_name)
+        File.expand_path(File.join(__dir__, "..", "..", "exe", gem_platform, name))
+      end
+
+      def vendored_executable
+        candidate = vendored_path
+        candidate if File.exist?(candidate)
+      end
+
+      def path_executable
+        ENV.fetch("PATH", "")
+           .split(File::PATH_SEPARATOR)
+           .reject(&:empty?)
+           .map { |dir| File.join(dir, exe_name) }
+           .find { |file| File.executable?(file) && !File.directory?(file) }
+      end
+
+      private
+
+      def resolve_override(path)
+        expanded  = File.expand_path(path)
+        candidate = File.directory?(expanded) ? File.join(expanded, exe_name) : expanded
+
+        unless File.exist?(candidate)
+          raise ExecutableNotFoundError,
+                "frpc executable override points at #{candidate}, which does not exist"
+        end
+
+        candidate
+      end
+    end
+  end
+end

data/lib/frpc.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "frpc/ruby"
+require "frpc/admin"
+require "frpc/client"
+
+# frpc-ruby ships the upstream frp client binary in a platform gem and drives it
+# over its admin HTTP API.
+#
+#   require "frpc"
+#   Frpc::Ruby.executable   # => path to the vendored frpc
+#   Frpc::Client.run("frpc.toml") { |c| pp c.status }
+module Frpc
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: frpc-ruby
+version: !ruby/object:Gem::Version
+  version: 0.70.1
+platform: ruby
+authors:
+- Nathan Kidd
+bindir: exe
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  Ships the upstream frpc binary for your platform and drives it from Ruby:
+  spawn the client, read per-proxy status, push a new config and reload it,
+  and shut it down gracefully — all over frpc's admin HTTP API.
+executables:
+- frpc
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/frpc
+- lib/frpc.rb
+- lib/frpc/admin.rb
+- lib/frpc/client.rb
+- lib/frpc/ruby.rb
+- lib/frpc/ruby/version.rb
+homepage: https://github.com/nathankidd/frpc-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/nathankidd/frpc-ruby
+  changelog_uri: https://github.com/nathankidd/frpc-ruby/blob/main/CHANGELOG.md
+  upstream_frp_uri: https://github.com/fatedier/frp/releases/tag/v0.70.1
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: The frp client (frpc) as a Ruby gem, with a wrapper for its admin API
+test_files: []