Merge pull request #4 from nebari-dev/aktech/add-root-path-subst

Add root path substitution

Author: aktech

README.md

@@ -106,6 +106,32 @@ jhub-app-proxy --port 8000 --destport 8050 --authtype none --log-format pretty \
 - `--destport` - Internal subprocess port (0 = random, default: 0)
 - `--authtype` - Authentication type: `oauth`, `none` (default: `oauth`)
 
+### Template Substitution
+
+JHub Apps Proxy supports template placeholders in your application commands that are automatically replaced at runtime:
+
+#### Port Templating
+Use `{port}` in your command and it will be replaced with the actual port allocated for internal routing:
+
+```bash
+jhub-app-proxy --port 8000 --destport 8501 --authtype none \
+  -- streamlit run app.py --server.port {port}
+```
+
+#### Root Path Templating
+Use `{root_path}` when your application needs to know its deployment prefix. This is especially useful when apps are deployed at dynamic URLs that aren't known in advance.
+
+The `{root_path}` placeholder is automatically replaced with the appropriate path constructed from the `JUPYTERHUB_SERVICE_PREFIX` environment variable (prepended with `/hub`).
+
+**Example:** If `JUPYTERHUB_SERVICE_PREFIX=/user/[email protected]/myapp/`, then `{root_path}` becomes `/hub/user/[email protected]/myapp`
+
+```bash
+jhub-app-proxy --port 8000 --destport 8050 --authtype none \
+  -- panel serve app.py --port {port} --prefix {root_path}
+```
+
+This eliminates the need to hardcode deployment paths in your application commands, making them portable across different JupyterHub deployments.
+
 ### Process Management
 - `--conda-env` - Conda environment to activate before running command
 - `--workdir` - Working directory for the process

pkg/command/builder.go

@@ -55,18 +55,44 @@ func (b *Builder) GetCondaWarning() string {
 	return b.condaWarning
 }
 
+// GetRootPath constructs the root path from JUPYTERHUB_SERVICE_PREFIX
+// by prepending /hub and ensuring proper path formatting (no double slashes, proper trailing slash handling)
+func GetRootPath() string {
+	servicePrefix := os.Getenv("JUPYTERHUB_SERVICE_PREFIX")
+	if servicePrefix == "" {
+		return ""
+	}
+
+	// Ensure service prefix starts with /
+	if !strings.HasPrefix(servicePrefix, "/") {
+		servicePrefix = "/" + servicePrefix
+	}
+
+	// Remove trailing slash from service prefix for consistent joining
+	servicePrefix = strings.TrimSuffix(servicePrefix, "/")
+
+	// Construct root path: /hub + service_prefix
+	rootPath := "/hub" + servicePrefix
+
+	return rootPath
+}
+
 // SubstitutePort replaces jhsingle-native-proxy style placeholders in command arguments
-// Handles: {port} → actual port, {-} → -, {--} → --, and strips surrounding quotes
+// Handles: {port} → actual port, {root_path} → JupyterHub root path, {-} → -, {--} → --, and strips surrounding quotes
 func SubstitutePort(command []string, allocatedPort int) []string {
 	result := make([]string, len(command))
 	portStr := fmt.Sprintf("%d", allocatedPort)
+	rootPath := GetRootPath()
 
 	for i, arg := range command {
 		processed := arg
 
 		// Replace port placeholder
 		processed = strings.ReplaceAll(processed, "{port}", portStr)
 
+		// Replace root_path placeholder
+		processed = strings.ReplaceAll(processed, "{root_path}", rootPath)
+
 		// Replace dash placeholders (jhsingle-native-proxy compatibility)
 		processed = strings.ReplaceAll(processed, "{-}", "-")
 		processed = strings.ReplaceAll(processed, "{--}", "--")

pkg/command/builder_test.go

@@ -0,0 +1,139 @@
+package command
+
+import (
+	"os"
+	"testing"
+)
+
+func TestGetRootPath(t *testing.T) {
+	tests := []struct {
+		name          string
+		servicePrefix string
+		expected      string
+	}{
+		{
+			name:          "standard service prefix",
+			servicePrefix: "/user/fakeuser/myapp/",
+			expected:      "/hub/user/fakeuser/myapp",
+		},
+		{
+			name:          "service prefix without trailing slash",
+			servicePrefix: "/user/testuser/app",
+			expected:      "/hub/user/testuser/app",
+		},
+		{
+			name:          "service prefix without leading slash",
+			servicePrefix: "user/demouser/app/",
+			expected:      "/hub/user/demouser/app",
+		},
+		{
+			name:          "empty service prefix",
+			servicePrefix: "",
+			expected:      "",
+		},
+		{
+			name:          "simple service prefix",
+			servicePrefix: "/user/alice/",
+			expected:      "/hub/user/alice",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Set environment variable
+			if tt.servicePrefix != "" {
+				os.Setenv("JUPYTERHUB_SERVICE_PREFIX", tt.servicePrefix)
+			} else {
+				os.Unsetenv("JUPYTERHUB_SERVICE_PREFIX")
+			}
+			defer os.Unsetenv("JUPYTERHUB_SERVICE_PREFIX")
+
+			result := GetRootPath()
+			if result != tt.expected {
+				t.Errorf("GetRootPath() = %q, want %q", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestSubstitutePort(t *testing.T) {
+	tests := []struct {
+		name          string
+		command       []string
+		port          int
+		servicePrefix string
+		expected      []string
+	}{
+		{
+			name:          "substitute port only",
+			command:       []string{"python", "-m", "http.server", "{port}"},
+			port:          8080,
+			servicePrefix: "",
+			expected:      []string{"python", "-m", "http.server", "8080"},
+		},
+		{
+			name:          "substitute root_path only",
+			command:       []string{"myapp", "--root-path", "{root_path}"},
+			port:          8080,
+			servicePrefix: "/user/test/app/",
+			expected:      []string{"myapp", "--root-path", "/hub/user/test/app"},
+		},
+		{
+			name:          "substitute both port and root_path",
+			command:       []string{"myapp", "--port", "{port}", "--root-path", "{root_path}"},
+			port:          9000,
+			servicePrefix: "/user/bob/dashboard/",
+			expected:      []string{"myapp", "--port", "9000", "--root-path", "/hub/user/bob/dashboard"},
+		},
+		{
+			name:          "substitute dash placeholders",
+			command:       []string{"myapp", "{-}p", "{port}", "{--}root-path", "{root_path}"},
+			port:          8888,
+			servicePrefix: "/user/test/",
+			expected:      []string{"myapp", "-p", "8888", "--root-path", "/hub/user/test"},
+		},
+		{
+			name:          "strip single quotes",
+			command:       []string{"'myapp --port {port}'"},
+			port:          3000,
+			servicePrefix: "",
+			expected:      []string{"myapp --port 3000"},
+		},
+		{
+			name:          "strip double quotes",
+			command:       []string{`"myapp --root-path {root_path}"`},
+			port:          3000,
+			servicePrefix: "/user/demo/",
+			expected:      []string{"myapp --root-path /hub/user/demo"},
+		},
+		{
+			name:          "empty root_path when no service prefix",
+			command:       []string{"myapp", "--root-path", "{root_path}"},
+			port:          5000,
+			servicePrefix: "",
+			expected:      []string{"myapp", "--root-path", ""},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Set environment variable
+			if tt.servicePrefix != "" {
+				os.Setenv("JUPYTERHUB_SERVICE_PREFIX", tt.servicePrefix)
+			} else {
+				os.Unsetenv("JUPYTERHUB_SERVICE_PREFIX")
+			}
+			defer os.Unsetenv("JUPYTERHUB_SERVICE_PREFIX")
+
+			result := SubstitutePort(tt.command, tt.port)
+			if len(result) != len(tt.expected) {
+				t.Fatalf("SubstitutePort() returned %d args, want %d", len(result), len(tt.expected))
+			}
+			for i := range result {
+				if result[i] != tt.expected[i] {
+					t.Errorf("SubstitutePort()[%d] = %q, want %q", i, result[i], tt.expected[i])
+				}
+			}
+		})
+	}
+}