outpunch-ruby 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d1ce909def454c1c033202a6e4fcd56da57df62aa9136ff8b8ca83e0a994d35
+  data.tar.gz: 93b88087d3fc832fc2ee33e9f209464f36700245961127f02e47ee64669c7236
+SHA512:
+  metadata.gz: 623853f37971fe05a61db5b342ff8ac2ea017b62fc0b4b0010c195951138b80f357782c86812d6c0cd4ac4c38c33f121f0dd4f1c4f52af4a88d84604afc820cf
+  data.tar.gz: 12886aaeb116eba5419f7090203e820cc392cc51e64936651e9a16496f15d3a526e02fa9ce10485d23b877ae2f9b7f2fd059aa24492515062768f988e35b2fa8

data/ext/outpunch/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "outpunch"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+name = "outpunch"
+crate-type = ["cdylib"]
+
+[dependencies]
+outpunch-client = { version = "0.5.0" }
+magnus = { version = "0.8" }
+rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
+tokio = { version = "1.50.0", features = ["full"] }
+outpunch_core = { version = "0.5.0", package = "outpunch" }
+
+[build-dependencies]
+rb-sys-build = "0.9"

data/ext/outpunch/extconf.rb

@@ -0,0 +1,4 @@
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("outpunch/outpunch")

data/ext/outpunch/src/gvl.rs

@@ -0,0 +1,67 @@
+use std::ffi::c_void;
+use std::panic::{self, AssertUnwindSafe};
+use std::sync::Arc;
+
+use magnus::{Error, Ruby};
+use tokio::sync::Notify;
+
+struct Call<F, R> {
+    func: Option<F>,
+    result: Option<std::thread::Result<R>>,
+}
+
+unsafe extern "C" fn call<F: FnOnce() -> R, R>(data: *mut c_void) -> *mut c_void {
+    let call = unsafe { &mut *(data as *mut Call<F, R>) };
+    if let Some(func) = call.func.take() {
+        call.result = Some(panic::catch_unwind(AssertUnwindSafe(func)));
+    }
+    std::ptr::null_mut()
+}
+
+fn trampoline<F: FnOnce() -> R, R>(
+    _: &Call<F, R>,
+) -> unsafe extern "C" fn(*mut c_void) -> *mut c_void {
+    call::<F, R>
+}
+
+unsafe extern "C" fn unblock(data: *mut c_void) {
+    let cancel = unsafe { &*(data as *const Notify) };
+    cancel.notify_one();
+}
+
+/// Run `func` with the GVL released. `func` receives a `Notify` that fires when Ruby
+/// interrupts the thread (Thread#kill, Thread#raise, Timeout); it returns `None` when
+/// it stopped early because of that.
+///
+/// Returns `Ok(None)` when the call was cancelled and Ruby had no exception pending.
+pub fn without_gvl<F, R>(ruby: &Ruby, func: F) -> Result<Option<R>, Error>
+where
+    F: FnOnce(Arc<Notify>) -> Option<R>,
+{
+    let cancel = Arc::new(Notify::new());
+    let mut state = Call {
+        func: Some({
+            let cancel = cancel.clone();
+            move || func(cancel)
+        }),
+        result: None,
+    };
+
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl2(
+            Some(trampoline(&state)),
+            &mut state as *mut _ as *mut c_void,
+            Some(unblock),
+            Arc::as_ptr(&cancel) as *mut c_void,
+        );
+    }
+
+    match state.result {
+        Some(Ok(Some(value))) => Ok(Some(value)),
+        Some(Ok(None)) | None => {
+            ruby.thread_check_ints()?;
+            Ok(None)
+        }
+        Some(Err(payload)) => panic::resume_unwind(payload),
+    }
+}

data/ext/outpunch/src/lib.rs

@@ -0,0 +1,168 @@
+use std::sync::Mutex;
+use std::time::Duration;
+
+use magnus::{Error, Ruby, function, method, prelude::*, wrap};
+
+mod gvl;
+mod server;
+
+struct ClientConfigInner {
+    server_url: String,
+    secret: String,
+    service: String,
+    forward_to: String,
+    reconnect_delay: f64,
+    request_timeout: f64,
+}
+
+#[wrap(class = "Outpunch::ClientConfig", free_immediately, size)]
+pub struct ClientConfig(Mutex<ClientConfigInner>);
+
+impl ClientConfig {
+    fn new(
+        server_url: String,
+        secret: String,
+        service: String,
+        forward_to: Option<String>,
+        reconnect_delay: Option<f64>,
+        request_timeout: Option<f64>,
+    ) -> Self {
+        Self(Mutex::new(ClientConfigInner {
+            server_url,
+            secret,
+            service,
+            forward_to: forward_to.unwrap_or_else(|| "http://localhost:8080".into()),
+            reconnect_delay: reconnect_delay.unwrap_or(5.0),
+            request_timeout: request_timeout.unwrap_or(25.0),
+        }))
+    }
+
+    fn to_rust(&self) -> outpunch_client::ClientConfig {
+        let inner = self.0.lock().unwrap();
+        outpunch_client::ClientConfig {
+            server_url: inner.server_url.clone(),
+            secret: inner.secret.clone(),
+            service: inner.service.clone(),
+            forward_to: inner.forward_to.clone(),
+            reconnect_delay: Duration::from_secs_f64(inner.reconnect_delay),
+            request_timeout: Duration::from_secs_f64(inner.request_timeout),
+        }
+    }
+
+    fn server_url(&self) -> String {
+        self.0.lock().unwrap().server_url.clone()
+    }
+
+    fn set_server_url(&self, v: String) {
+        self.0.lock().unwrap().server_url = v;
+    }
+
+    fn secret(&self) -> String {
+        self.0.lock().unwrap().secret.clone()
+    }
+
+    fn set_secret(&self, v: String) {
+        self.0.lock().unwrap().secret = v;
+    }
+
+    fn service(&self) -> String {
+        self.0.lock().unwrap().service.clone()
+    }
+
+    fn set_service(&self, v: String) {
+        self.0.lock().unwrap().service = v;
+    }
+
+    fn forward_to(&self) -> String {
+        self.0.lock().unwrap().forward_to.clone()
+    }
+
+    fn set_forward_to(&self, v: String) {
+        self.0.lock().unwrap().forward_to = v;
+    }
+
+    fn reconnect_delay(&self) -> f64 {
+        self.0.lock().unwrap().reconnect_delay
+    }
+
+    fn set_reconnect_delay(&self, v: f64) {
+        self.0.lock().unwrap().reconnect_delay = v;
+    }
+
+    fn request_timeout(&self) -> f64 {
+        self.0.lock().unwrap().request_timeout
+    }
+
+    fn set_request_timeout(&self, v: f64) {
+        self.0.lock().unwrap().request_timeout = v;
+    }
+
+    fn inspect(&self) -> String {
+        let inner = self.0.lock().unwrap();
+        format!(
+            "#<Outpunch::ClientConfig server_url={:?} service={:?} forward_to={:?}>",
+            inner.server_url, inner.service, inner.forward_to
+        )
+    }
+}
+
+fn run(_ruby: &Ruby, config: &ClientConfig) -> Result<(), Error> {
+    let rust_config = config.to_rust();
+    tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap()
+        .block_on(outpunch_client::run(&rust_config));
+    Ok(())
+}
+
+fn run_connection(ruby: &Ruby, config: &ClientConfig) -> Result<(), Error> {
+    let rust_config = config.to_rust();
+    let result = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap()
+        .block_on(outpunch_client::run_connection(&rust_config));
+    result.map_err(|e: Box<dyn std::error::Error + Send + Sync>| {
+        Error::new(ruby.exception_runtime_error(), e.to_string())
+    })
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("Outpunch")?;
+
+    let config_class = module.define_class("ClientConfig", ruby.class_object())?;
+    config_class.define_singleton_method("new", function!(ClientConfig::new, 6))?;
+    config_class.define_method("server_url", method!(ClientConfig::server_url, 0))?;
+    config_class.define_method("server_url=", method!(ClientConfig::set_server_url, 1))?;
+    config_class.define_method("secret", method!(ClientConfig::secret, 0))?;
+    config_class.define_method("secret=", method!(ClientConfig::set_secret, 1))?;
+    config_class.define_method("service", method!(ClientConfig::service, 0))?;
+    config_class.define_method("service=", method!(ClientConfig::set_service, 1))?;
+    config_class.define_method("forward_to", method!(ClientConfig::forward_to, 0))?;
+    config_class.define_method("forward_to=", method!(ClientConfig::set_forward_to, 1))?;
+    config_class.define_method("reconnect_delay", method!(ClientConfig::reconnect_delay, 0))?;
+    config_class.define_method(
+        "reconnect_delay=",
+        method!(ClientConfig::set_reconnect_delay, 1),
+    )?;
+    config_class.define_method("request_timeout", method!(ClientConfig::request_timeout, 0))?;
+    config_class.define_method(
+        "request_timeout=",
+        method!(ClientConfig::set_request_timeout, 1),
+    )?;
+    config_class.define_method("inspect", method!(ClientConfig::inspect, 0))?;
+    config_class.define_method("to_s", method!(ClientConfig::inspect, 0))?;
+
+    module.define_module_function("run", function!(run, 1))?;
+    module.define_module_function("run_connection", function!(run_connection, 1))?;
+
+    server::init(ruby, &module)?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "lib_tests.rs"]
+mod tests;

data/ext/outpunch/src/lib_tests.rs

@@ -0,0 +1,36 @@
+use super::ClientConfig;
+
+#[test]
+fn client_config_defaults() {
+    let config = ClientConfig::new(
+        "wss://example.com/ws".into(),
+        "secret".into(),
+        "my-service".into(),
+        None,
+        None,
+        None,
+    );
+    let rust = config.to_rust();
+    assert_eq!(rust.forward_to, "http://localhost:8080");
+    assert_eq!(rust.reconnect_delay.as_secs_f64(), 5.0);
+    assert_eq!(rust.request_timeout.as_secs_f64(), 25.0);
+}
+
+#[test]
+fn client_config_custom_values() {
+    let config = ClientConfig::new(
+        "wss://example.com/ws".into(),
+        "mysecret".into(),
+        "stormsnap".into(),
+        Some("http://localhost:8081".into()),
+        Some(10.0),
+        Some(30.0),
+    );
+    let rust = config.to_rust();
+    assert_eq!(rust.server_url, "wss://example.com/ws");
+    assert_eq!(rust.secret, "mysecret");
+    assert_eq!(rust.service, "stormsnap");
+    assert_eq!(rust.forward_to, "http://localhost:8081");
+    assert_eq!(rust.reconnect_delay.as_secs_f64(), 10.0);
+    assert_eq!(rust.request_timeout.as_secs_f64(), 30.0);
+}

data/ext/outpunch/src/server.rs

@@ -0,0 +1,241 @@
+use std::collections::HashMap;
+use std::sync::OnceLock;
+use std::time::Duration;
+
+use magnus::{Error, ExceptionClass, RHash, RModule, RString, Ruby, prelude::*, wrap};
+use outpunch_core::protocol::{IncomingRequest, TunnelResponse};
+use outpunch_core::server::{
+    Connection as CoreConnection, OutpunchServer, ServerConfig, TunnelError,
+};
+use tokio::runtime::Runtime;
+use tokio::sync::{Mutex, mpsc};
+
+use crate::gvl::without_gvl;
+
+fn runtime() -> &'static Runtime {
+    static RUNTIME: OnceLock<Runtime> = OnceLock::new();
+    RUNTIME.get_or_init(|| {
+        tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .thread_name("outpunch")
+            .build()
+            .expect("failed to start outpunch runtime")
+    })
+}
+
+fn outpunch_error(ruby: &Ruby, name: &str) -> Result<ExceptionClass, Error> {
+    ruby.class_object()
+        .const_get::<_, RModule>("Outpunch")?
+        .const_get(name)
+}
+
+#[wrap(class = "Outpunch::Server", free_immediately, size)]
+pub struct Server {
+    inner: OutpunchServer,
+}
+
+impl Server {
+    fn new(secret: String, timeout: f64, max_body_size: Option<usize>) -> Self {
+        let defaults = ServerConfig::default();
+        Self {
+            inner: OutpunchServer::new(ServerConfig {
+                secret,
+                timeout: Duration::from_secs_f64(timeout),
+                max_body_size: max_body_size.unwrap_or(defaults.max_body_size),
+                ..defaults
+            }),
+        }
+    }
+
+    fn create_connection(&self) -> Connection {
+        let inner = self.inner.create_connection();
+        let (tx, rx) = mpsc::unbounded_channel();
+        inner.on_message(move |msg| {
+            let _ = tx.send(msg);
+        });
+        Connection {
+            inner,
+            outgoing: Mutex::new(rx),
+        }
+    }
+
+    fn is_connected(ruby: &Ruby, rb_self: &Self, service: String) -> Result<bool, Error> {
+        loop {
+            let server = rb_self.inner.clone();
+            let service = service.clone();
+            let result = without_gvl(ruby, move |cancel| {
+                runtime().block_on(async {
+                    tokio::select! {
+                        connected = server.is_connected(&service) => Some(connected),
+                        _ = cancel.notified() => None,
+                    }
+                })
+            })?;
+            if let Some(connected) = result {
+                return Ok(connected);
+            }
+        }
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    fn handle_request(
+        ruby: &Ruby,
+        rb_self: &Self,
+        service: String,
+        method: String,
+        path: String,
+        query: HashMap<String, String>,
+        headers: HashMap<String, String>,
+        body: Option<RString>,
+    ) -> Result<RHash, Error> {
+        // SAFETY: the slice is copied before the GVL is released.
+        let body = body
+            .map(|b| String::from_utf8_lossy(unsafe { b.as_slice() }).into_owned())
+            .filter(|b| !b.is_empty());
+        let incoming = IncomingRequest {
+            service: service.clone(),
+            method,
+            path,
+            query,
+            headers,
+            body,
+        };
+
+        let server = rb_self.inner.clone();
+        let result = without_gvl(ruby, move |cancel| {
+            runtime().block_on(async {
+                tokio::select! {
+                    result = server.try_handle_request(incoming) => Some(result),
+                    _ = cancel.notified() => None,
+                }
+            })
+        })?;
+
+        match result {
+            None => Err(Error::new(
+                ruby.exception_runtime_error(),
+                "tunnel request interrupted",
+            )),
+            Some(Ok(response)) => response_hash(ruby, response),
+            Some(Err(TunnelError::NotConnected)) => Err(Error::new(
+                outpunch_error(ruby, "NotConnectedError")?,
+                format!("Service '{service}' not connected"),
+            )),
+            Some(Err(TunnelError::Timeout)) => Err(Error::new(
+                outpunch_error(ruby, "TunnelTimeoutError")?,
+                format!("Tunnel timeout for service '{service}'"),
+            )),
+            Some(Err(err)) => Err(Error::new(
+                outpunch_error(ruby, "TunnelError")?,
+                err.to_string(),
+            )),
+        }
+    }
+}
+
+fn response_hash(ruby: &Ruby, response: TunnelResponse) -> Result<RHash, Error> {
+    let hash = ruby.hash_new();
+    hash.aset("request_id", response.request_id)?;
+    hash.aset("status", response.status)?;
+    hash.aset("headers", response.headers)?;
+    hash.aset("body", response.body)?;
+    hash.aset("body_encoding", response.body_encoding)?;
+    Ok(hash)
+}
+
+#[wrap(class = "Outpunch::Connection", free_immediately, size)]
+pub struct Connection {
+    inner: CoreConnection,
+    outgoing: Mutex<mpsc::UnboundedReceiver<String>>,
+}
+
+impl Connection {
+    /// Feed one WebSocket text message from the tunnel client into the core.
+    fn push_message(ruby: &Ruby, rb_self: &Self, text: String) -> Result<(), Error> {
+        let inner = rb_self.inner.clone();
+        without_gvl(ruby, move |cancel| {
+            runtime().block_on(async {
+                tokio::select! {
+                    _ = inner.push_message(text) => Some(()),
+                    _ = cancel.notified() => None,
+                }
+            })
+        })?;
+        Ok(())
+    }
+
+    /// Block until the core has a message for the tunnel client. Returns nil once the
+    /// connection has ended.
+    fn next_outgoing(ruby: &Ruby, rb_self: &Self) -> Result<Option<String>, Error> {
+        loop {
+            let result = without_gvl(ruby, |cancel| {
+                runtime().block_on(async {
+                    let mut outgoing = rb_self.outgoing.lock().await;
+                    tokio::select! {
+                        msg = outgoing.recv() => Some(msg),
+                        _ = cancel.notified() => None,
+                    }
+                })
+            })?;
+            if let Some(msg) = result {
+                return Ok(msg);
+            }
+        }
+    }
+
+    fn close(&self) {
+        self.inner.close();
+    }
+
+    /// Run the connection lifecycle (auth, relay, cleanup). Blocks until the
+    /// connection ends; an interrupt closes the connection.
+    fn run(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        let inner = rb_self.inner.clone();
+        without_gvl(ruby, move |cancel| {
+            runtime().block_on(async {
+                let run = inner.run();
+                tokio::pin!(run);
+                tokio::select! {
+                    _ = &mut run => {}
+                    _ = cancel.notified() => {
+                        inner.close();
+                        run.await;
+                    }
+                }
+                Some(())
+            })
+        })?;
+        Ok(())
+    }
+}
+
+pub fn init(ruby: &Ruby, module: &RModule) -> Result<(), Error> {
+    ruby.require("timeout")?;
+    let timeout_error: ExceptionClass = ruby
+        .class_object()
+        .const_get::<_, RModule>("Timeout")?
+        .const_get("Error")?;
+    module.define_error("NotConnectedError", ruby.exception_runtime_error())?;
+    module.define_error("TunnelError", ruby.exception_runtime_error())?;
+    module.define_error("TunnelTimeoutError", timeout_error)?;
+
+    let server = module.define_class("Server", ruby.class_object())?;
+    server.define_singleton_method("new", magnus::function!(Server::new, 3))?;
+    server.define_method(
+        "create_connection",
+        magnus::method!(Server::create_connection, 0),
+    )?;
+    server.define_method("connected?", magnus::method!(Server::is_connected, 1))?;
+    server.define_method("handle_request", magnus::method!(Server::handle_request, 6))?;
+
+    let connection = module.define_class("Connection", ruby.class_object())?;
+    connection.define_method("push_message", magnus::method!(Connection::push_message, 1))?;
+    connection.define_method(
+        "next_outgoing",
+        magnus::method!(Connection::next_outgoing, 0),
+    )?;
+    connection.define_method("close", magnus::method!(Connection::close, 0))?;
+    connection.define_method("run", magnus::method!(Connection::run, 0))?;
+
+    Ok(())
+}

data/lib/outpunch-ruby.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "outpunch"

data/lib/outpunch.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "outpunch/outpunch"

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: outpunch-ruby
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- TechyCorp
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  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: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description:
+email:
+executables: []
+extensions:
+- ext/outpunch/extconf.rb
+extra_rdoc_files: []
+files:
+- ext/outpunch/Cargo.toml
+- ext/outpunch/extconf.rb
+- ext/outpunch/src/gvl.rs
+- ext/outpunch/src/lib.rs
+- ext/outpunch/src/lib_tests.rs
+- ext/outpunch/src/server.rs
+- lib/outpunch-ruby.rb
+- lib/outpunch.rb
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby bindings for the outpunch tunnel client
+test_files: []