feat: add functionality for a proxy tunnel command (#1315)

Co-authored-by: taskbot <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

cmd/thv/app/proxy.go

@@ -171,6 +171,9 @@ func init() {
 	if err := proxyCmd.MarkFlagRequired("target-uri"); err != nil {
 		logger.Warnf("Warning: Failed to mark flag as required: %v", err)
 	}
+
+	// Attach the subcommand to the main proxy command
+	proxyCmd.AddCommand(proxyTunnelCmd)
 }
 
 func proxyCmdFunc(cmd *cobra.Command, args []string) error {

cmd/thv/app/proxy_tunnel.go

@@ -0,0 +1,128 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"os/signal"
+	"strings"
+	"syscall"
+
+	"github.com/spf13/cobra"
+
+	"github.com/stacklok/toolhive/pkg/logger"
+	"github.com/stacklok/toolhive/pkg/transport/types"
+	"github.com/stacklok/toolhive/pkg/workloads"
+)
+
+var (
+	tunnelProvider   string
+	providerArgsJSON string
+)
+
+var proxyTunnelCmd = &cobra.Command{
+	Use:   "tunnel [flags] TARGET SERVER_NAME",
+	Short: "Create a tunnel proxy for exposing internal endpoints",
+	Long: `Create a tunnel proxy for exposing internal endpoints.
+
+	TARGET may be either:
+  • a URL (http://..., https://...) -> used directly as the target URI
+  • a workload name                  -> resolved to its URL
+
+Examples:
+  thv proxy tunnel http://localhost:8080 my-server --tunnel-provider ngrok
+  thv proxy tunnel my-workload        my-server --tunnel-provider ngrok
+
+Flags:
+  --tunnel-provider string   The provider to use for the tunnel (e.g., "ngrok") - mandatory
+  --provider-args string     JSON object with provider-specific arguments (default "{}")
+`,
+	Args: cobra.ExactArgs(2),
+	RunE: proxyTunnelCmdFunc,
+}
+
+func init() {
+	proxyTunnelCmd.Flags().StringVar(&tunnelProvider, "tunnel-provider", "",
+		"The provider to use for the tunnel (e.g., 'ngrok') - mandatory")
+	proxyTunnelCmd.Flags().StringVar(&providerArgsJSON, "provider-args", "{}", "JSON object with provider-specific arguments")
+
+	// Mark tunnel-provider as required
+	if err := proxyTunnelCmd.MarkFlagRequired("tunnel-provider"); err != nil {
+		logger.Warnf("Warning: Failed to mark flag as required: %v", err)
+	}
+}
+
+func proxyTunnelCmdFunc(cmd *cobra.Command, args []string) error {
+	ctx, cancel := signal.NotifyContext(cmd.Context(), syscall.SIGINT, syscall.SIGTERM)
+	defer cancel()
+
+	targetArg := args[0] // URL or workload name
+	serverName := args[1]
+
+	// Validate provider
+	provider, ok := types.SupportedTunnelProviders[tunnelProvider]
+	if !ok {
+		return fmt.Errorf("invalid tunnel provider %q, supported providers: %v", tunnelProvider, types.GetSupportedProviderNames())
+	}
+
+	var rawArgs map[string]any
+	if err := json.Unmarshal([]byte(providerArgsJSON), &rawArgs); err != nil {
+		return fmt.Errorf("invalid --provider-args: %w", err)
+	}
+
+	// validate target uri
+	finalTargetURI, err := resolveTarget(ctx, targetArg)
+	if err != nil {
+		return err
+	}
+
+	// parse provider-specific configuration
+	if err := provider.ParseConfig(rawArgs); err != nil {
+		return fmt.Errorf("invalid provider config: %w", err)
+	}
+
+	// Start the tunnel using the selected provider
+	if err := provider.StartTunnel(ctx, serverName, finalTargetURI); err != nil {
+		return fmt.Errorf("failed to start tunnel: %w", err)
+	}
+
+	// Consume until interrupt
+	<-ctx.Done()
+	logger.Info("Shutting down tunnel")
+	return nil
+}
+
+func resolveTarget(ctx context.Context, target string) (string, error) {
+	// If it's a URL, validate and return it
+	if looksLikeURL(target) {
+		if err := validateProxyTargetURI(target); err != nil {
+			return "", fmt.Errorf("invalid target URI: %w", err)
+		}
+		return target, nil
+	}
+
+	// Otherwise treat as workload name
+	workloadManager, err := workloads.NewManager(ctx)
+	if err != nil {
+		return "", fmt.Errorf("failed to create workload manager: %w", err)
+	}
+	tunnelWorkload, err := workloadManager.GetWorkload(ctx, target)
+	if err != nil {
+		return "", fmt.Errorf("failed to get workload %q: %w", target, err)
+	}
+	if tunnelWorkload.URL == "" {
+		return "", fmt.Errorf("workload %q has empty URL", target)
+	}
+	return tunnelWorkload.URL, nil
+}
+
+func looksLikeURL(s string) bool {
+	// Fast-path for common schemes
+	if strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://") {
+		return true
+	}
+	// Fallback parse check
+	u, err := url.Parse(s)
+	return err == nil && u.Scheme != "" && u.Host != ""
+}

docs/cli/thv_proxy.md

@@ -118,6 +118,7 @@ require (
 	github.com/go-openapi/strfmt v0.23.0 // indirect
 	github.com/go-openapi/swag v0.23.1 // indirect
 	github.com/go-openapi/validate v0.24.0 // indirect
+	github.com/go-stack/stack v1.8.1 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.3.0 // indirect
 	github.com/gobuffalo/pop/v6 v6.1.1 // indirect
@@ -142,9 +143,12 @@ require (
 	github.com/ianlancetaylor/demangle v0.0.0-20250417193237-f615e6bd150b // indirect
 	github.com/in-toto/attestation v1.1.2 // indirect
 	github.com/in-toto/in-toto-golang v0.9.0 // indirect
+	github.com/inconshreveable/log15 v3.0.0-testing.5+incompatible // indirect
+	github.com/inconshreveable/log15/v3 v3.0.0-testing.5 // indirect
 	github.com/invopop/jsonschema v0.13.0 // indirect
 	github.com/jedisct1/go-minisign v0.0.0-20211028175153-1c139d1cc84b // indirect
 	github.com/josharian/intern v1.0.0 // indirect
+	github.com/jpillora/backoff v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.18.0 // indirect
 	github.com/letsencrypt/boulder v0.0.0-20240620165639-de9c06129bec // indirect
@@ -233,6 +237,8 @@ require (
 	go.uber.org/multierr v1.11.0 // indirect
 	go.uber.org/zap v1.27.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.2 // indirect
+	golang.ngrok.com/muxado/v2 v2.0.1 // indirect
+	golang.ngrok.com/ngrok/v2 v2.0.0 // indirect
 	golang.org/x/exp/event v0.0.0-20250620022241-b7579e27df2b // indirect
 	golang.org/x/net v0.42.0 // indirect
 	golang.org/x/text v0.27.0 // indirect

docs/cli/thv_proxy_tunnel.md

@@ -935,6 +935,8 @@ github.com/go-sql-driver/mysql v1.7.0/go.mod h1:OXbVy3sEdcQ2Doequ6Z5BW6fXNQTmx+9
 github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
 github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
 github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/melR3HDY=
+github.com/go-stack/stack v1.8.1 h1:ntEHSVwIt7PNXNpgPmVfMrNhLtgjlmnZha2kOpuRiDw=
+github.com/go-stack/stack v1.8.1/go.mod h1:dcoOX6HbPZSZptuspn9bctJ+N/CnF5gGygcUP3XYfe4=
 github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
 github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
 github.com/go-test/deep v1.1.1 h1:0r/53hagsehfO4bzD2Pgr/+RgHqhmf+k1Bpse2cTu1U=
@@ -1155,6 +1157,10 @@ github.com/in-toto/attestation v1.1.2 h1:MBFn6lsMq6dptQZJBhalXTcWMb/aJy3V+GX3VYj
 github.com/in-toto/attestation v1.1.2/go.mod h1:gYFddHMZj3DiQ0b62ltNi1Vj5rC879bTmBbrv9CRHpM=
 github.com/in-toto/in-toto-golang v0.9.0 h1:tHny7ac4KgtsfrG6ybU8gVOZux2H8jN05AXJ9EBM1XU=
 github.com/in-toto/in-toto-golang v0.9.0/go.mod h1:xsBVrVsHNsB61++S6Dy2vWosKhuA3lUTQd+eF9HdeMo=
+github.com/inconshreveable/log15 v3.0.0-testing.5+incompatible h1:VryeOTiaZfAzwx8xBcID1KlJCeoWSIpsNbSk+/D2LNk=
+github.com/inconshreveable/log15 v3.0.0-testing.5+incompatible/go.mod h1:cOaXtrgN4ScfRrD9Bre7U1thNq5RtJ8ZoP4iXVGRj6o=
+github.com/inconshreveable/log15/v3 v3.0.0-testing.5 h1:h4e0f3kjgg+RJBlKOabrohjHe47D3bbAB9BgMrc3DYA=
+github.com/inconshreveable/log15/v3 v3.0.0-testing.5/go.mod h1:3GQg1SVrLoWGfRv/kAZMsdyU5cp8eFc1P3cw+Wwku94=
 github.com/inconshreveable/mousetrap v1.0.1/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
@@ -1220,6 +1226,8 @@ github.com/jmoiron/sqlx v1.3.5/go.mod h1:nRVWtLre0KfCLJvgxzCsLVMogSvQ1zNJtpYr2Cc
 github.com/joho/godotenv v1.4.0/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/jpillora/backoff v1.0.0 h1:uvFg412JmmHBHw7iwprIxkPMI+sGQ4kzOWsMeHnm2EA=
+github.com/jpillora/backoff v1.0.0/go.mod h1:J/6gKK9jxlEcS3zixgDgUAsiuZ7yrSoa/FX5e0EB2j4=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
 github.com/jstemmer/go-junit-report v0.0.0-20190106144839-af01ea7f8024/go.mod h1:6v2b51hI/fHJwM22ozAgKL4VKDeJcHhJFhtBdhmNjmU=
@@ -1687,6 +1695,10 @@ go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
 go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
 go.yaml.in/yaml/v3 v3.0.3 h1:bXOww4E/J3f66rav3pX3m8w6jDE4knZjGOw8b5Y6iNE=
 go.yaml.in/yaml/v3 v3.0.3/go.mod h1:tBHosrYAkRZjRAOREWbDnBXUf08JOwYq++0QNwQiWzI=
+golang.ngrok.com/muxado/v2 v2.0.1 h1:jM9i6Pom6GGmnPrHKNR6OJRrUoHFkSZlJ3/S0zqdVpY=
+golang.ngrok.com/muxado/v2 v2.0.1/go.mod h1:wzxJYX4xiAtmwumzL+QsukVwFRXmPNv86vB8RPpOxyM=
+golang.ngrok.com/ngrok/v2 v2.0.0 h1:eUEF7ULph6hUdOVR9r7oue2UhT2vvDoLAo0q//N6vJo=
+golang.ngrok.com/ngrok/v2 v2.0.0/go.mod h1:nppMCtZ44/KeGrDHOV0c4bRyMGdHCEBo2Rvjdv/1Uio=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20190411191339-88737f569e3a/go.mod h1:WFFai1msRO1wXaEeE5yQxYXgSfI8pQAWXbQop6sCtWE=
 golang.org/x/crypto v0.0.0-20190510104115-cbcb75029529/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=

go.mod

@@ -0,0 +1,94 @@
+// Package ngrok provides an implementation of the TunnelProvider interface using ngrok.
+package ngrok
+
+import (
+	"context"
+	"fmt"
+
+	"golang.ngrok.com/ngrok/v2"
+
+	"github.com/stacklok/toolhive/pkg/logger"
+)
+
+// TunnelProvider implements the TunnelProvider interface for ngrok.
+type TunnelProvider struct {
+	config TunnelConfig
+}
+
+// TunnelConfig holds configuration options for the ngrok tunnel provider.
+type TunnelConfig struct {
+	AuthToken string
+	Domain    string // Optional: specify custom domain
+	DryRun    bool
+}
+
+// ParseConfig parses the configuration for the ngrok tunnel provider from a map.
+func (p *TunnelProvider) ParseConfig(raw map[string]any) error {
+	token, ok := raw["ngrok-auth-token"].(string)
+	if !ok || token == "" {
+		return fmt.Errorf("ngrok-auth-token is required")
+	}
+
+	cfg := TunnelConfig{
+		AuthToken: token,
+	}
+
+	if domain, ok := raw["ngrok-domain"].(string); ok {
+		cfg.Domain = domain
+	}
+
+	p.config = cfg
+
+	if dr, ok := raw["dry-run"].(bool); ok {
+		p.config.DryRun = dr
+	}
+	return nil
+}
+
+// StartTunnel starts a tunnel using ngrok to the specified target URI.
+func (p *TunnelProvider) StartTunnel(ctx context.Context, name, targetURI string) error {
+	if p.config.DryRun {
+		// behave like an active tunnel that exits on ctx cancel
+		<-ctx.Done()
+		return nil
+	}
+	logger.Infof("[ngrok] Starting tunnel %q → %s", name, targetURI)
+
+	agent, err := ngrok.NewAgent(
+		ngrok.WithAuthtoken(p.config.AuthToken),
+		ngrok.WithEventHandler(func(e ngrok.Event) {
+			logger.Infof("ngrok event: %s at %s", e.EventType(), e.Timestamp())
+		}),
+	)
+
+	if err != nil {
+		return fmt.Errorf("failed to create ngrok agent: %w", err)
+	}
+
+	// Set up only the necessary endpoint options
+	endpointOpts := []ngrok.EndpointOption{
+		ngrok.WithDescription("tunnel proxy for " + name),
+	}
+	if p.config.Domain != "" {
+		endpointOpts = append(endpointOpts, ngrok.WithURL(p.config.Domain))
+	}
+
+	forwarder, err := agent.Forward(ctx,
+		ngrok.WithUpstream(targetURI),
+		endpointOpts...,
+	)
+	if err != nil {
+		return fmt.Errorf("ngrok.Forward error: %w", err)
+	}
+
+	logger.Infof("ngrok forwarding live at %s", forwarder.URL())
+
+	// Run in background, non-blocking on `.Done()`
+	go func() {
+		<-forwarder.Done()
+		logger.Infof("ngrok forwarding stopped: %s", forwarder.URL())
+	}()
+
+	// Return immediately
+	return nil
+}

go.sum

@@ -0,0 +1,29 @@
+package types
+
+import (
+	"context"
+
+	"github.com/stacklok/toolhive/pkg/transport/tunnel/ngrok"
+)
+
+//go:generate mockgen -destination=mocks/mock_tunnel_provider.go -package=mocks -source=tunnel.go
+
+// SupportedTunnelProviders maps provider names to their implementations.
+var SupportedTunnelProviders = map[string]TunnelProvider{
+	"ngrok": &ngrok.TunnelProvider{},
+}
+
+// TunnelProvider defines the interface for tunnel providers.
+type TunnelProvider interface {
+	ParseConfig(config map[string]any) error
+	StartTunnel(ctx context.Context, name string, targetURI string) error
+}
+
+// GetSupportedProviderNames returns a list of supported tunnel provider names.
+func GetSupportedProviderNames() []string {
+	names := make([]string, 0, len(SupportedTunnelProviders))
+	for name := range SupportedTunnelProviders {
+		names = append(names, name)
+	}
+	return names
+}