cloudflare-tunnel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c80792cd4e7e48be6c97df5edf07c554d6285394607f70926e4e2a0d019572c7
+  data.tar.gz: b0bd9ffc636ec2029a83234d8172d5c8fba76ac20ba8b4e53b42e56c5df4b831
+SHA512:
+  metadata.gz: d91a8ac77dd2452910e816080413197b61c4d4b1a6353aa7a75dc9f2e2270ed4f24c14e17163aa00b11b999555ea2df0a535de36891d9b3004bf52c0dfb46c40
+  data.tar.gz: 6150c30d7d44ab48f3ecfe78fc2e9d192ebd4e41da51b4c31f7c77622a2f5465849923753d110c39fdcca0bee337e6a6722f218c4431e3c6be97e0be8832ca8b

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+## [0.1.0] - 2026-11-04
+
+### Added
+
+- Rails configuration generator and explicit development tunnel tasks.
+- Quiet offline retries, configurable cloudflared log levels and separate logs.
+- Installation guidance without automatic executable installation.
+- Connector readiness and signed local/public application diagnostics.
+- Secure temporary tokens, per-app locking and bounded child shutdown.
+- Local quality checks and tag-triggered GitHub Actions publishing.
+
+### Changed
+
+- Release preparation runs from main, checks for duplicate tags, runs local
+  checks, commits version and changelog updates, and pushes the branch and tag.
+- The first release can use the existing version and changelog without a version
+  bump or empty commit. Publishing runs in GitHub Actions after the tag is pushed.
+
+### Fixed
+
+- Use a shared credentials action with an explicit RubyGems owner for trusted
+  publishing of both first and subsequent releases.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Paulo Fidalgo and Ethos Link
+
+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,160 @@
+# Cloudflare Tunnel
+
+Run a remotely-managed Cloudflare tunnel alongside a Rails development server.
+Offline startup and connection loss stay quiet and do not stop the server or
+jobs. The gem supervises an existing `cloudflared` executable; it never installs,
+downloads or updates it, creates a tunnel, or changes DNS.
+
+Requires Ruby 4.0+, Rails 8.1 and a POSIX host (Linux or macOS).
+MIT licensed; maintained by [Ethos Link](https://www.ethos-link.com).
+This is an independent integration.
+
+## Rails setup
+
+Add to the development group:
+
+```ruby
+group :development do
+  gem "cloudflare-tunnel", "~> 0.1"
+end
+```
+
+```sh
+bundle install
+bin/rails generate cloudflare_tunnel:install \
+  --hostname=devel.example.com --port=3000 --metrics-port=20241
+```
+
+The generator creates `config/initializers/cloudflare_tunnel.rb` and adds
+`tunnel: bin/rails cloudflare_tunnel:start` to `Procfile.dev`.
+
+Install the executable yourself using [Cloudflare's instructions](https://developers.cloudflare.com/tunnel/downloads/).
+When missing, the start task prints that link once and stays idle so Foreman
+keeps other services running. The check task reports it and exits with failure.
+
+In Cloudflare, configure a remotely-managed tunnel's published application
+hostname to use `http://localhost:3000` (match your Rails port). Store its
+connector token with `bin/rails credentials:edit`:
+
+```yaml
+cloudflare:
+  tunnel:
+    token: YOUR_TUNNEL_TOKEN
+```
+
+`TUNNEL_TOKEN` overrides credentials. Tokens use temporary files with mode `0600`,
+stay out of command arguments and diagnostics, and are removed on normal exit,
+INT and TERM. A forced OS kill cannot run cleanup; remove abandoned
+`cloudflare-tunnel-*.token` files from your OS temporary directory if needed.
+
+```sh
+bin/dev
+# In a second terminal, after Rails and the tunnel are running:
+bin/rails cloudflare_tunnel:check
+```
+
+Adding the gem or booting Rails never starts a tunnel. Only the explicit start
+task does. Tasks refuse to run outside development. The diagnostic middleware
+is installed only in development. The generated initializer guards against the
+gem being excluded from other Bundler groups.
+
+## Configuration
+
+```ruby
+if Rails.env.development?
+  Cloudflare::Tunnel.configure do |config|
+    config.hostname = "devel.example.com"
+    config.origin = "http://localhost:#{ENV.fetch('PORT', '3000')}"
+    config.metrics_port = 20241
+    config.log_level = :error
+    config.log_path = "log/cloudflare-tunnel.log"
+    config.retry_interval = 30
+  end
+end
+```
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `hostname` | required | Bare public hostname configured in Cloudflare |
+| `origin` | `http://localhost:$PORT` (`3000` otherwise) | Expected Rails origin; change Cloudflare's origin setting separately |
+| `metrics_port` | `20241` | Readiness/metrics port bound to `127.0.0.1`; choose a distinct port for every concurrent app |
+| `log_level` | `:error` | Native cloudflared level: `:debug`, `:info`, `:warn`, `:error`, `:fatal` |
+| `log_path` | `log/cloudflare-tunnel.log` | Append connector output here, relative to Rails root; `nil` discards it |
+| `retry_interval` | `30` | Seconds before restarting an exited connector |
+| `shutdown_timeout` | `5` | Seconds after TERM before killing a stuck child |
+| `check_timeout` | `5` | HTTP connection/read/write timeouts, per diagnostic request |
+| `executable` | `cloudflared` | Name on PATH or an explicit filesystem path |
+| `enabled` | true | False when `TUNNEL` is `0`, `false`, `off` or `no`; configurable explicitly |
+| `token` | lazy Rails credentials / `TUNNEL_TOKEN` | String or callable; keep real tokens out of initializers |
+
+The connector handles its own reconnections. If it exits, the supervisor retries
+after `retry_interval`, without recurring terminal messages. Disabled tunnels,
+missing credentials and invalid configurations print one actionable message and
+stay idle. Fix configuration and restart. The check fails for those states.
+
+Use `TUNNEL=0 bin/dev` to disable the connector. Use your local Rails URL offline.
+OAuth callbacks and provider requests still need internet. Turnstile behavior
+remains application-owned.
+
+The native log level filters cloudflared messages. Connector output stays out of
+Rails logs and recurring Foreman output. Set `log_path = nil` to discard it.
+Ignore `log/` and `tmp/` in Git; appended logs need normal local cleanup. Debug
+logs may include request details; enable that level only while diagnosing.
+
+A per-app file lock prevents two gem-managed connectors in the same working
+directory. Stop older Docker or system-service connectors for that tunnel
+yourself. Other working directories can still run replicas and receive traffic.
+
+## Diagnostics
+
+`bin/rails cloudflare_tunnel:check` returns `0` only when all checks pass:
+
+1. Configuration, executable availability and token presence.
+2. The local Rails origin returns a fresh signed probe response.
+3. The connector's `/ready` endpoint reports an active Cloudflare connection.
+4. HTTPS on the public hostname returns the expected response from this app.
+
+The development-only `/.well-known/cloudflare-tunnel?nonce=…` probe uses an HMAC
+with a purpose-specific key derived from Rails' secret key base and returns
+`Cache-Control: no-store`. It creates no records and exposes no credentials.
+Fresh nonces prevent stale cached health pages passing the check. The signature
+identifies the application's key, not a particular machine sharing that key.
+The configured metrics port must belong to this connector.
+
+Failures identify the layer and return `1`, including offline failures. The check
+does not start a connector or change configuration. Redirects, Access login pages
+and incorrect origins/app keys fail. Executable availability alone does not
+validate the token; the running connector and end-to-end checks establish that.
+Authentication errors remain in the separate connector log. No Cloudflare
+management API token is required.
+
+References: [run parameters](https://developers.cloudflare.com/tunnel/reference/run-parameters/)
+and [readiness example](https://developers.cloudflare.com/tunnel/guides/kubernetes/).
+
+## Development
+
+Run `bin/setup` to install development dependencies, then `bin/ci` to run
+Minitest, Standard Ruby, the gem build and changelog generation. Tests control
+connector executables and HTTP boundaries; they need no Cloudflare account or
+internet once dependencies are installed.
+
+Use `bundle exec rake -T` to list available tasks. See the
+[changelog](CHANGELOG.md) for version history.
+
+## More from Ethos Link
+
+Cloudflare Tunnel is maintained by [Ethos Link](https://www.ethos-link.com),
+the software company behind Reviato and Nuntio. We build business products and
+share open-source software.
+
+- [Reviato — customer feedback and review analytics](https://www.reviato.com):
+  Collect private guest feedback and explore recurring themes in public reviews.
+  Hotels, restaurants and other local businesses can read the original customer
+  comments, track feedback and decide what needs attention.
+- [Nuntio — social media scheduling and publishing](https://www.nuntiohq.com):
+  Prepare social posts ahead of time, adapt captions and media for each channel,
+  and bring drafts, team review, scheduling and publishing outcomes into one
+  workspace.
+
+Explore [Ethos Link's products](https://www.ethos-link.com/products) and
+[open-source projects](https://www.ethos-link.com/opensource).

data/lib/cloudflare/tasks/tunnel.rake

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+namespace :cloudflare_tunnel do
+  desc "Run the optional development tunnel with quiet offline retries"
+  task start: :environment do
+    abort "cloudflare_tunnel:start is only available in development" unless Rails.env.development?
+    Cloudflare::Tunnel::Runner.new(Cloudflare::Tunnel.configuration).run
+  end
+
+  desc "Check configuration, connector, local origin and public app identity"
+  task check: :environment do
+    abort "cloudflare_tunnel:check is only available in development" unless Rails.env.development?
+    exit(Cloudflare::Tunnel::Check.new(Cloudflare::Tunnel.configuration).run ? 0 : 1)
+  end
+end

data/lib/cloudflare/tunnel/check.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "securerandom"
+
+module Cloudflare
+  module Tunnel
+    class Check
+      NETWORK_ERRORS = [SocketError, SystemCallError, Timeout::Error, IOError, OpenSSL::SSL::SSLError].freeze
+
+      def initialize(configuration, output: $stdout)
+        @configuration = configuration
+        @output = output
+      end
+
+      def run
+        issues = @configuration.errors
+        issues << "tunnel is disabled" unless @configuration.enabled
+        issues << "cloudflared not found. Install it yourself: #{INSTALL_URL}" unless @configuration.executable_path
+        issues << "token missing; set cloudflare.tunnel.token in Rails credentials" if @configuration.token_value.empty?
+        if issues.any?
+          issues.each { |issue| @output.puts("FAIL: #{issue}") }
+          return false
+        end
+
+        nonce = SecureRandom.hex(32)
+        expected = Probe.signature(@configuration.probe_secret.call, nonce)
+        local = verify("local origin", "#{@configuration.origin.to_s.chomp("/")}#{Probe::PATH}?nonce=#{nonce}", expected)
+        connector = verify("Cloudflare connection", "http://127.0.0.1:#{@configuration.metrics_port}/ready")
+        public_app = verify("public hostname", "https://#{@configuration.hostname}#{Probe::PATH}?nonce=#{nonce}", expected)
+        @output.puts("Origin must be #{@configuration.origin} in Cloudflare's published application settings.") unless local && connector && public_app
+        local && connector && public_app
+      end
+
+      private
+
+      def verify(label, url, expected = nil)
+        uri = URI(url)
+        # Ignore proxy environment variables for loopback diagnostics.
+        http = Net::HTTP.new(uri.hostname, uri.port, (uri.hostname == @configuration.hostname) ? :ENV : nil)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = http.read_timeout = http.write_timeout = @configuration.check_timeout
+        http.max_retries = 0
+        response = http.get(uri.request_uri, {"Cache-Control" => "no-cache"})
+        if response.code == "200" && (!expected || response.body == expected)
+          @output.puts("OK: #{label}")
+          true
+        else
+          @output.puts("FAIL: #{label} (HTTP #{response.code}; expected #{expected ? "this Rails application" : "an active connector"}). Check DNS, Cloudflare Access, origin and #{@configuration.log_path || "logging configuration"}.")
+          false
+        end
+      rescue *NETWORK_ERRORS => error
+        @output.puts("FAIL: #{label} (#{error.class}); network or service unavailable")
+        false
+      end
+    end
+  end
+end

data/lib/cloudflare/tunnel/configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Cloudflare
+  module Tunnel
+    class Configuration
+      LOG_LEVELS = %w[debug info warn error fatal].freeze
+      attr_accessor :enabled, :executable, :token, :hostname, :origin, :metrics_port,
+        :log_level, :log_path, :retry_interval, :shutdown_timeout, :check_timeout,
+        :root, :probe_secret
+
+      def initialize
+        @enabled = !%w[0 false off no].include?(ENV.fetch("TUNNEL", "1").downcase)
+        @executable = "cloudflared"
+        @root = Dir.pwd
+        @origin = "http://localhost:#{ENV.fetch("PORT", "3000")}"
+        @metrics_port = 20241
+        @log_level = :error
+        @log_path = "log/cloudflare-tunnel.log"
+        @retry_interval = 30
+        @shutdown_timeout = 5
+        @check_timeout = 5
+      end
+
+      def token_value
+        (token.respond_to?(:call) ? token.call : token).to_s.strip
+      end
+
+      def executable_path
+        paths = executable.to_s.include?(File::SEPARATOR) ? [File.expand_path(executable, root)] :
+          ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |directory| File.join(directory, executable) }
+        paths.find { |path| File.file?(path) && File.executable?(path) }
+      end
+
+      def path(value)
+        File.expand_path(value, root)
+      end
+
+      def errors
+        messages = []
+        messages << "hostname must be a bare public hostname" unless hostname.to_s.match?(/\A[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?\z/i)
+        uri = URI.parse(origin.to_s)
+        unless uri.is_a?(URI::HTTP) && %w[localhost 127.0.0.1 ::1].include?(uri.hostname) &&
+            uri.userinfo.nil? && [nil, "", "/"].include?(uri.path) && uri.query.nil? && uri.fragment.nil?
+          messages << "origin must be an HTTP(S) loopback URL without a path or credentials"
+        end
+        messages << "metrics_port must be between 1 and 65535" unless metrics_port.is_a?(Integer) && (1..65535).cover?(metrics_port)
+        messages << "log_level must be one of #{LOG_LEVELS.join(", ")}" unless LOG_LEVELS.include?(log_level.to_s)
+        %i[retry_interval shutdown_timeout check_timeout].each do |name|
+          value = case name
+          when :retry_interval then retry_interval
+          when :shutdown_timeout then shutdown_timeout
+          when :check_timeout then check_timeout
+          end
+          messages << "#{name} must be a positive finite number" unless value.is_a?(Numeric) && value.finite? && value.positive?
+        end
+        messages
+      rescue URI::InvalidURIError
+        messages << "origin must be a valid loopback URL"
+      end
+    end
+  end
+end

data/lib/cloudflare/tunnel/probe.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "rack/request"
+
+module Cloudflare
+  module Tunnel
+    class Probe
+      PATH = "/.well-known/cloudflare-tunnel"
+
+      def self.signature(secret, nonce)
+        OpenSSL::HMAC.hexdigest("SHA256", secret, nonce)
+      end
+
+      def initialize(app, secret:)
+        @app = app
+        @secret = secret
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        return @app.call(env) unless request.path_info == PATH
+
+        nonce = request.GET["nonce"].to_s
+        if request.get? && nonce.match?(/\A[0-9a-f]{64}\z/)
+          [200, {"content-type" => "text/plain", "cache-control" => "no-store"}, [self.class.signature(@secret.call, nonce)]]
+        else
+          [400, {"content-type" => "text/plain", "cache-control" => "no-store"}, ["Invalid probe"]]
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/tunnel/railtie.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module Tunnel
+    class Railtie < Rails::Railtie
+      initializer "cloudflare_tunnel.defaults", before: :load_config_initializers do |app|
+        Cloudflare::Tunnel.configure do |config|
+          config.root = app.root
+          config.token = -> { ENV["TUNNEL_TOKEN"] || app.credentials.dig(:cloudflare, :tunnel, :token) }
+          config.probe_secret = -> { app.key_generator.generate_key("cloudflare-tunnel/probe", 32) }
+        end
+      end
+
+      initializer "cloudflare_tunnel.probe", after: :load_config_initializers do |app|
+        if Rails.env.development?
+          app.middleware.use Probe, secret: Cloudflare::Tunnel.configuration.probe_secret
+        end
+      end
+
+      rake_tasks do
+        load File.expand_path("../tasks/tunnel.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/cloudflare/tunnel/runner.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tempfile"
+
+module Cloudflare
+  module Tunnel
+    class Runner
+      def initialize(configuration, output: $stdout)
+        @configuration = configuration
+        @output = output
+        @stopping = false
+      end
+
+      def run
+        @reader, @writer = IO.pipe
+        previous = %w[INT TERM].to_h { |signal| [signal, Signal.trap(signal) { stop }] }
+        if (reason = unavailable)
+          @output.puts("[tunnel] #{reason}")
+          pause
+        else
+          FileUtils.mkdir_p(@configuration.path("tmp/pids"))
+          File.open(@configuration.path("tmp/pids/cloudflare-tunnel.lock"), File::RDWR | File::CREAT, 0o600) do |lock|
+            if lock.flock(File::LOCK_EX | File::LOCK_NB)
+              supervise
+            else
+              @output.puts("[tunnel] already running for this application; skipping")
+              pause
+            end
+          end
+        end
+      ensure
+        terminate
+        previous&.each { |signal, handler| Signal.trap(signal, handler) }
+        @reader&.close
+        @writer&.close
+      end
+
+      private
+
+      def unavailable
+        if !@configuration.enabled
+          "disabled"
+        elsif !@configuration.executable_path
+          "cloudflared not found. Install it yourself: #{INSTALL_URL}"
+        elsif @configuration.errors.any?
+          "invalid configuration: #{@configuration.errors.join("; ")}"
+        elsif @configuration.token_value.empty?
+          "token missing; set cloudflare.tunnel.token in Rails credentials"
+        end
+      end
+
+      def supervise
+        log_path = @configuration.log_path && @configuration.path(@configuration.log_path)
+        FileUtils.mkdir_p(File.dirname(log_path)) if log_path
+        File.open(log_path || File::NULL, "a", 0o600) do |log|
+          Tempfile.create(["cloudflare-tunnel-", ".token"]) do |token|
+            token.write(@configuration.token_value)
+            token.flush
+            @output.puts("[tunnel] #{@configuration.hostname} -> #{@configuration.origin}; diagnostics: #{log_path || "disabled"}")
+            until @stopping
+              @pid = Process.spawn({"TUNNEL_TOKEN" => nil, "TUNNEL_TOKEN_FILE" => nil,
+                "TUNNEL_LOGFILE" => nil, "TUNNEL_LOGDIRECTORY" => nil},
+                @configuration.executable_path, "tunnel", "--no-autoupdate",
+                "--loglevel", @configuration.log_level.to_s,
+                "--metrics", "127.0.0.1:#{@configuration.metrics_port}",
+                "--grace-period", "2s", "run", "--token-file", token.path,
+                out: log, err: log)
+              @waiter = Process.detach(@pid)
+              pause(1) until @stopping || @waiter.join(0)
+              terminate
+              pause(@configuration.retry_interval) unless @stopping
+            end
+          ensure
+            terminate
+          end
+        end
+      end
+
+      def stop
+        @stopping = true
+        @writer.write_nonblock(".", exception: false)
+      end
+
+      def pause(timeout = nil)
+        IO.select([@reader], nil, nil, timeout) unless @stopping
+      end
+
+      def terminate
+        return unless @waiter
+
+        unless @waiter.join(0)
+          Process.kill("TERM", @pid)
+          unless @waiter.join(@configuration.shutdown_timeout)
+            Process.kill("KILL", @pid)
+            @waiter.join
+          end
+        end
+      rescue Errno::ESRCH
+        @waiter.join
+      ensure
+        @waiter = @pid = nil
+      end
+    end
+  end
+end

data/lib/cloudflare/tunnel/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module Tunnel
+    VERSION = "0.1.0"
+  end
+end

data/lib/cloudflare/tunnel.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "tunnel/version"
+require_relative "tunnel/configuration"
+require_relative "tunnel/runner"
+require_relative "tunnel/probe"
+require_relative "tunnel/check"
+
+module Cloudflare
+  module Tunnel
+    INSTALL_URL = "https://developers.cloudflare.com/tunnel/downloads/"
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.configure
+      yield configuration
+    end
+  end
+end
+
+require_relative "tunnel/railtie" if defined?(Rails::Railtie)

data/lib/cloudflare-tunnel.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "cloudflare/tunnel"

data/lib/generators/cloudflare_tunnel/install_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Cloudflare
+  module Tunnel
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        namespace "cloudflare_tunnel:install"
+        source_root File.expand_path("templates", __dir__)
+        desc "Configure a remotely-managed development tunnel; never installs cloudflared"
+        class_option :hostname, type: :string, required: true, desc: "Public development hostname"
+        class_option :port, type: :numeric, default: 3000, desc: "Local Rails port"
+        class_option :metrics_port, type: :numeric, default: 20241, desc: "Unique loopback connector metrics port"
+
+        def create_configuration
+          template "initializer.rb.tt", "config/initializers/cloudflare_tunnel.rb"
+        end
+
+        def configure_procfile
+          entry = "tunnel: bin/rails cloudflare_tunnel:start\n"
+          if File.exist?(File.join(destination_root, "Procfile.dev"))
+            content = File.read(File.join(destination_root, "Procfile.dev"))
+            if content.match?(/^tunnel:\s+bin\/tunnel\s*$/)
+              gsub_file "Procfile.dev", /^tunnel:\s+bin\/tunnel[^\n]*\n?/, entry
+            elsif content.match?(/^tunnel:/)
+              say "Existing tunnel entry retained; use: #{entry.strip}"
+            else
+              append_to_file "Procfile.dev", "\n#{entry}"
+            end
+          else
+            create_file "Procfile.dev", entry
+          end
+        end
+
+        def instructions
+          say "Set cloudflare.tunnel.token with bin/rails credentials:edit."
+          say "In Cloudflare, route #{options[:hostname]} to http://localhost:#{options[:port]}."
+          say "Install cloudflared yourself if needed: #{Cloudflare::Tunnel::INSTALL_URL}"
+          say "Start bin/dev, then run bin/rails cloudflare_tunnel:check."
+        end
+      end
+    end
+  end
+end

data/lib/generators/cloudflare_tunnel/templates/initializer.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+if Rails.env.development?
+  Cloudflare::Tunnel.configure do |config|
+    config.hostname = <%= options[:hostname].inspect %>
+    config.origin = "http://localhost:#{ENV.fetch("PORT", <%= options[:port].to_s.inspect %>)}"
+    config.metrics_port = <%= options[:metrics_port] %>
+    config.log_level = :error
+    config.log_path = "log/cloudflare-tunnel.log" # nil discards connector output
+    config.retry_interval = 30
+    # config.executable = "/path/to/cloudflared"
+    # config.enabled = false # TUNNEL=0 also disables the default configuration
+    # Token defaults to TUNNEL_TOKEN or credentials.dig(:cloudflare, :tunnel, :token).
+  end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: cloudflare-tunnel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paulo Fidalgo
+- Ethos Link
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+description: Supervise host-installed cloudflared with Rails configuration, quiet
+  retries, secure token handling, and end-to-end diagnostics.
+email:
+- devel@ethos-link.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/cloudflare-tunnel.rb
+- lib/cloudflare/tasks/tunnel.rake
+- lib/cloudflare/tunnel.rb
+- lib/cloudflare/tunnel/check.rb
+- lib/cloudflare/tunnel/configuration.rb
+- lib/cloudflare/tunnel/probe.rb
+- lib/cloudflare/tunnel/railtie.rb
+- lib/cloudflare/tunnel/runner.rb
+- lib/cloudflare/tunnel/version.rb
+- lib/generators/cloudflare_tunnel/install_generator.rb
+- lib/generators/cloudflare_tunnel/templates/initializer.rb.tt
+homepage: https://github.com/ethos-link/cloudflare-tunnel
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ethos-link/cloudflare-tunnel
+  source_code_uri: https://github.com/ethos-link/cloudflare-tunnel
+  changelog_uri: https://github.com/ethos-link/cloudflare-tunnel/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ethos-link/cloudflare-tunnel/issues
+  documentation_uri: https://github.com/ethos-link/cloudflare-tunnel/blob/main/README.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Quiet, offline-tolerant Cloudflare tunnels for Rails development
+test_files: []