etunnel 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2fef3d0b4489dc6b413507a3df7b135535d6dcb108435a4549375fbb0a0519bf
+  data.tar.gz: d3bdb54234f9caefe126784dced3c7f2cd252b7a2f1526448bdeaf7e8d41f738
+SHA512:
+  metadata.gz: fa6516ba349f1e9562195489a218062ca6dc6f86cd5f89ba224f2677eff8d00d6ada789919b2118577f08546a6f828322e74e4c163569fa065a933c09ec5ad83
+  data.tar.gz: a8960d0a92e76922465837ea21ca05fa6d7faeecb0b1d191e98cde8376a47a18aed6075739cceab923b2aae74b7b14d149dfcc3229506cdc53c9dd9da947833b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 etunnel authors
+
+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,47 @@
+# etunnel for Ruby
+
+EventMachine/faye-websocket based.
+
+Zero registration: every SDK client speaks the same tiny wire protocol
+([PROTOCOL.md](../../PROTOCOL.md)) against any etunnel server
+(default `wss://t.ggcode.uk/tunnel`).
+
+## Install
+
+```
+gem install etunnel
+```
+
+Requires Ruby >= 2.7 (pulls in faye-websocket).
+
+## CLI
+
+```
+etunnel 3000
+```
+
+Prints `TUNNEL_URL: https://<subdomain>.t.ggcode.uk` — that URL now routes to
+your local service. Ctrl-C closes the tunnel.
+
+## Embed
+
+```ruby
+require 'etunnel'
+t = Etunnel.connect('wss://t.ggcode.uk/tunnel', 3000)
+puts t.url
+```
+
+## Environment variables
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `ETUNNEL_SERVER` | tunnel server WebSocket URL | `wss://t.ggcode.uk/tunnel` |
+| `ETUNNEL_LOCAL` | local port or `host:port` (or 1st CLI arg) | `3000` |
+| `ETUNNEL_TOKEN` | paid-plan API key (optional) | - |
+| `ETUNNEL_SUBDOMAIN` | custom subdomain (paid plans) | random |
+
+## License
+
+MIT — see [LICENSE](../../LICENSE). Buffer-based protocol client: request and
+response bodies are buffered per stream (fine for webhooks/dashboards/demos;
+use the [Go SDK](../../sdk) for streaming and WebSocket pass-through).

data/bin/etunnel

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "etunnel"
+
+Etunnel.main

data/lib/etunnel.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# etunnel SDK for Ruby (requires gem install faye-websocket).
+# Buffer-based protocol client (bodies buffered per stream; no WS upgrades).
+#
+#   gem install faye-websocket
+#   ruby etunnel.rb 3000
+#
+# Embed:
+#   require_relative 'etunnel'
+#   t = Etunnel.connect('wss://t.ggcode.uk/tunnel', 3000)
+#   puts t.url
+require 'json'
+require 'socket'
+require 'net/http'
+begin
+  require 'eventmachine'
+  require 'faye/websocket'
+rescue LoadError
+  warn 'etunnel: gem install faye-websocket'
+  exit 1
+end
+
+# faye-websocket needs a running EventMachine reactor.
+unless EventMachine.reactor_running?
+  Thread.new { EventMachine.run }
+  sleep 0.05 until EventMachine.reactor_running?
+end
+
+MAXP = 32_768
+HOP = %w[connection transfer-encoding keep-alive upgrade proxy-connection te trailer content-length host].freeze
+
+module Etunnel
+  def self.frame(kind, sid, payload)
+    [kind].pack('C') + [sid].pack('N') + [payload.bytesize].pack('N') + payload
+  end
+
+  def self.connect(server, local, token: nil, subdomain: nil)
+    local = "127.0.0.1:#{local}" unless local.to_s.include?(':')
+    ws = Faye::WebSocket::Client.new(server, ['etunnel-v1'])
+
+    queue = Queue.new
+    ws.on :message do |event|
+      data = event.data
+      if data.is_a?(String) && data.encoding == Encoding::UTF_8 && data.start_with?('{')
+        queue << [:text, data]
+      else
+        # binary frames arrive as ASCII-8BIT Strings (or Arrays)
+        bin = data.is_a?(Array) ? data.pack('C*') : data
+        queue << [:bin, bin]
+      end
+    end
+    ws.on :close do
+      queue << [:close, nil]
+    end
+
+    hello = { type: 'hello', proto: 1, client: 'etunnel-ruby/1.0' }
+    hello[:token] = token if token
+    hello[:subdomain] = subdomain if subdomain
+    ws.send(JSON.generate(hello))
+
+    url = nil
+    loop do
+      kind, payload = queue.pop
+      raise 'etunnel: connection closed' if kind == :close
+
+      next unless kind == :text
+
+      m = JSON.parse(payload)
+      if m['type'] == 'welcome'
+        url = m['url']
+        break
+      elsif m['type'] == 'error'
+        raise "etunnel: #{m['code']}: #{m['message']}"
+      end
+    end
+
+    streams = {}
+    closed = false
+
+    Thread.new do
+      loop do
+        kind, payload = queue.pop
+        break if kind == :close
+
+        if kind == :text
+          m = JSON.parse(payload)
+          case m['type']
+          when 'req'
+            streams[m['streamId']] = { req: m, body: +''.b }
+          when 'ping'
+            ws.send(JSON.generate({ type: 'pong', ts: m['ts'] || 0 }))
+          when 'bye'
+            closed = true
+            ws.close
+            break
+          end
+        else
+          next if payload.bytesize < 9
+
+          kind_b, sid, n = payload.unpack('C N N')
+          data = payload.byteslice(9, n)
+          st = streams[sid]
+          next unless st
+
+          case kind_b
+          when 0x01 then st[:body] << data
+          when 0x02
+            streams.delete(sid)
+            serve(ws, st[:req], st[:body], sid, local)
+          when 0x03 then streams.delete(sid)
+          end
+        end
+      end
+    end
+
+    tunnel = Object.new
+    tunnel.define_singleton_method(:url) { url }
+    tunnel.define_singleton_method(:close) do
+      ws.send(JSON.generate({ type: 'bye', reason: 'client closed' }))
+      ws.close
+    end
+    tunnel
+  end
+
+  def self.serve(ws, req, body, sid, local)
+    host, port = local.split(':')
+    method = req['method'] || 'GET'
+    path = req['path'] || '/'
+    headers = (req['headers'] || {}).reject { |k, _| HOP.include?(k.downcase) }
+
+    out = Thread.new do
+      begin
+        http = Net::HTTP.new(host, port.to_i)
+        http.open_timeout = 10
+        klass = Net::HTTP.const_get(method.capitalize)
+        r = klass.new(path, headers.to_h { |k, v| [k, Array(v).first] })
+        r.body = body unless method == 'GET' || method == 'HEAD'
+        resp = http.request(r)
+        [resp.code.to_i, resp.each_header.reject { |k, _| HOP.include?(k) }.to_h, resp.body || '']
+      rescue StandardError => e
+        [502, { 'Content-Type' => 'text/plain' }, "etunnel: local service error: #{e}\n"]
+      end
+    end.value
+
+    status, headers, payload = out
+    ws.send(JSON.generate({ type: 'res', streamId: sid, status: status,
+                            headers: headers.to_h { |k, v| [k, [v]] } }))
+    payload = payload.b
+    i = 0
+    while i < payload.bytesize
+      ws.send(frame(0x01, sid, payload.byteslice(i, MAXP)))
+      i += MAXP
+    end
+    ws.send(frame(0x02, sid, ''))
+  end
+end
+
+def Etunnel.main(argv = ARGV)
+  server = ENV['ETUNNEL_SERVER'] || 'wss://t.ggcode.uk/tunnel'
+  local = argv[0] || ENV['ETUNNEL_LOCAL'] || '3000'
+  begin
+    t = Etunnel.connect(server, local,
+                        token: ENV['ETUNNEL_TOKEN'], subdomain: ENV['ETUNNEL_SUBDOMAIN'])
+  rescue StandardError => e
+    warn "etunnel: #{e}"
+    exit 1
+  end
+  $stdout.sync = true
+  puts "TUNNEL_URL: #{t.url}"
+  trap(:INT) { t.close; exit 0 }
+  sleep 1 while true
+end
+Etunnel.main if $PROGRAM_NAME == __FILE__

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: etunnel
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- etunnel authors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faye-websocket
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+description: 'Expose a local service through an etunnel reverse-tunnel server with
+  one line of code. '
+executables:
+- etunnel
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/etunnel
+- lib/etunnel.rb
+homepage: https://github.com/ggcode/etunnel
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ggcode/etunnel
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: Expose a local service through an etunnel reverse-tunnel server with one
+  line of code
+test_files: []