refactor: move URL normalization to shared pathutil package

dionesiusap · claude · dionesiusap · commit cc64aa43fb60 · 2026-04-16T15:28:17.000+02:00
Extracted URL normalization logic into internal/pathutil for reuse
across components (OData clients, REST clients with OpenAPI, etc.).

Changes:
- Added pathutil.NormalizeURL() - converts relative paths to absolute file:// URLs
- Added pathutil.PathFromURL() - extracts filesystem path from file:// URLs
- Removed duplicate normalizeMetadataUrl() from cmd_odata.go
- Updated executor to use pathutil.NormalizeURL()
- Added comprehensive tests for new functions

Benefits:
- Single source of truth for URL normalization logic
- Reusable for REST clients with OpenAPI contracts
- Better test coverage
- Consistent behavior across all components

Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/internal/pathutil/uri.go b/internal/pathutil/uri.go
@@ -3,8 +3,11 @@
 package pathutil
 
 import (
+	"fmt"
 	"net/url"
+	"os"
 	"path/filepath"
+	"strings"
 )
 
 // URIToPath converts a file:// URI to a filesystem path.
@@ -21,3 +24,71 @@ func URIToPath(rawURI string) string {
 	// If no scheme, treat as a raw path
 	return rawURI
 }
+
+// NormalizeURL converts relative paths to absolute file:// URLs, while preserving HTTP(S) URLs.
+// This is useful for storing URLs in a way that external tools (like Mendix Studio Pro) can
+// reliably distinguish between local files and HTTP endpoints.
+//
+// Supported input formats:
+//   - https://... or http://... → returned as-is
+//   - file:///abs/path → returned as-is
+//   - ./path or path/file.xml → converted to file:///absolute/path
+//
+// If baseDir is provided, relative paths are resolved against it.
+// Otherwise, they're resolved against the current working directory.
+//
+// Returns an error if the path cannot be resolved to an absolute path.
+func NormalizeURL(rawURL string, baseDir string) (string, error) {
+	if rawURL == "" {
+		return "", nil
+	}
+
+	// HTTP(S) URLs are already normalized
+	if strings.HasPrefix(rawURL, "http://") || strings.HasPrefix(rawURL, "https://") {
+		return rawURL, nil
+	}
+
+	// Extract file path from file:// URLs or use raw input
+	filePath := rawURL
+	if strings.HasPrefix(rawURL, "file://") {
+		filePath = URIToPath(rawURL)
+		if filePath == "" {
+			return "", fmt.Errorf("invalid file:// URI: %s", rawURL)
+		}
+	}
+
+	// Convert relative paths to absolute
+	if !filepath.IsAbs(filePath) {
+		if baseDir != "" {
+			filePath = filepath.Join(baseDir, filePath)
+		} else {
+			// No base directory - use cwd
+			cwd, err := os.Getwd()
+			if err != nil {
+				return "", fmt.Errorf("failed to resolve relative path: %w", err)
+			}
+			filePath = filepath.Join(cwd, filePath)
+		}
+	}
+
+	// Convert to absolute path (clean up ./ and ../)
+	absPath, err := filepath.Abs(filePath)
+	if err != nil {
+		return "", fmt.Errorf("failed to get absolute path: %w", err)
+	}
+
+	// Return as file:// URL with forward slashes (cross-platform)
+	return "file://" + filepath.ToSlash(absPath), nil
+}
+
+// PathFromURL extracts a filesystem path from a URL, handling both file:// URLs and HTTP(S) URLs.
+// For file:// URLs, returns the local filesystem path.
+// For HTTP(S) URLs or other schemes, returns an empty string.
+// This is the inverse of converting a path to a file:// URL.
+func PathFromURL(rawURL string) string {
+	if strings.HasPrefix(rawURL, "file://") {
+		return URIToPath(rawURL)
+	}
+	// Not a file:// URL
+	return ""
+}
diff --git a/internal/pathutil/uri_test.go b/internal/pathutil/uri_test.go
@@ -3,7 +3,9 @@
 package pathutil
 
 import (
+	"path/filepath"
 	"runtime"
+	"strings"
 	"testing"
 )
 
@@ -80,3 +82,141 @@ func TestURIToPath_Windows(t *testing.T) {
 		})
 	}
 }
+
+func TestNormalizeURL(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	tests := []struct {
+		name       string
+		input      string
+		baseDir    string
+		wantPrefix string
+		wantErr    bool
+	}{
+		{
+			name:       "HTTP URL unchanged",
+			input:      "https://api.example.com/$metadata",
+			baseDir:    "",
+			wantPrefix: "https://",
+			wantErr:    false,
+		},
+		{
+			name:       "HTTPS URL unchanged",
+			input:      "http://localhost:8080/odata/$metadata",
+			baseDir:    "",
+			wantPrefix: "http://",
+			wantErr:    false,
+		},
+		{
+			name:       "Absolute file:// URL unchanged",
+			input:      "file:///tmp/metadata.xml",
+			baseDir:    "",
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+		{
+			name:       "Relative path with ./ normalized",
+			input:      "./metadata.xml",
+			baseDir:    tmpDir,
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+		{
+			name:       "Bare relative path normalized",
+			input:      "metadata.xml",
+			baseDir:    tmpDir,
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+		{
+			name:       "Absolute path normalized to file://",
+			input:      "/tmp/metadata.xml",
+			baseDir:    "",
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+		{
+			name:       "Subdirectory relative path",
+			input:      "contracts/metadata.xml",
+			baseDir:    tmpDir,
+			wantPrefix: "file://",
+			wantErr:    false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := NormalizeURL(tt.input, tt.baseDir)
+
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("Expected error but got none")
+				}
+				return
+			}
+
+			if err != nil {
+				t.Errorf("Unexpected error: %v", err)
+				return
+			}
+
+			if !strings.HasPrefix(result, tt.wantPrefix) {
+				t.Errorf("Result %q does not start with %q", result, tt.wantPrefix)
+			}
+
+			// Verify file:// URLs contain absolute paths
+			if strings.HasPrefix(result, "file://") {
+				path := strings.TrimPrefix(result, "file://")
+				if !filepath.IsAbs(path) {
+					t.Errorf("file:// URL contains relative path: %q", result)
+				}
+			}
+
+			// Verify relative paths are resolved correctly
+			if tt.baseDir != "" && !strings.HasPrefix(tt.input, "http") && !strings.HasPrefix(tt.input, "file://") {
+				path := strings.TrimPrefix(result, "file://")
+				if !strings.Contains(path, filepath.ToSlash(tmpDir)) {
+					t.Errorf("Relative path not resolved against baseDir. Got: %q", result)
+				}
+			}
+		})
+	}
+}
+
+func TestPathFromURL(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "file:// URL extracts path",
+			input:    "file:///tmp/metadata.xml",
+			expected: "/tmp/metadata.xml",
+		},
+		{
+			name:     "HTTP URL returns empty",
+			input:    "https://api.example.com/$metadata",
+			expected: "",
+		},
+		{
+			name:     "HTTPS URL returns empty",
+			input:    "http://localhost:8080/metadata",
+			expected: "",
+		},
+		{
+			name:     "bare path returns empty",
+			input:    "/tmp/file.xml",
+			expected: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := PathFromURL(tt.input)
+			if runtime.GOOS != "windows" && result != tt.expected {
+				t.Errorf("PathFromURL(%q) = %q, want %q", tt.input, result, tt.expected)
+			}
+		})
+	}
+}
diff --git a/mdl/executor/cmd_odata.go b/mdl/executor/cmd_odata.go
@@ -1016,7 +1016,7 @@ func (e *Executor) createODataClient(stmt *ast.CreateODataClientStmt) error {
 		}
 
 		// Normalize MetadataUrl: convert relative paths to absolute file:// URLs
-		normalizedUrl, err := normalizeMetadataUrl(newSvc.MetadataUrl, mprDir)
+		normalizedUrl, err := pathutil.NormalizeURL(newSvc.MetadataUrl, mprDir)
 		if err != nil {
 			return fmt.Errorf("failed to normalize MetadataUrl: %w", err)
 		}
@@ -1424,59 +1424,6 @@ func astEntityDefToModel(def *ast.PublishedEntityDef) (*model.PublishedEntityTyp
 	return entityType, entitySet
 }
 
-// normalizeMetadataUrl converts relative paths to absolute file:// URLs.
-// This ensures Studio Pro can properly detect local file vs HTTP metadata sources.
-//
-// Input formats:
-//   - https://... or http://... → returned as-is
-//   - file:///abs/path → returned as-is
-//   - ./path or path/file.xml → converted to file:///absolute/path
-//
-// If mprDir is provided, relative paths are resolved against it.
-// Otherwise, they're resolved against the current working directory.
-func normalizeMetadataUrl(metadataUrl string, mprDir string) (string, error) {
-	if metadataUrl == "" {
-		return "", nil
-	}
-
-	// HTTP(S) URLs are already normalized
-	if strings.HasPrefix(metadataUrl, "http://") || strings.HasPrefix(metadataUrl, "https://") {
-		return metadataUrl, nil
-	}
-
-	// Extract file path
-	filePath := metadataUrl
-	if strings.HasPrefix(metadataUrl, "file://") {
-		filePath = pathutil.URIToPath(metadataUrl)
-		if filePath == "" {
-			return "", fmt.Errorf("invalid file:// URI: %s", metadataUrl)
-		}
-	}
-
-	// Convert relative paths to absolute
-	if !filepath.IsAbs(filePath) {
-		if mprDir != "" {
-			filePath = filepath.Join(mprDir, filePath)
-		} else {
-			// No project loaded - use cwd
-			cwd, err := os.Getwd()
-			if err != nil {
-				return "", fmt.Errorf("failed to resolve relative path: %w", err)
-			}
-			filePath = filepath.Join(cwd, filePath)
-		}
-	}
-
-	// Convert to absolute path (clean up ./ and ../)
-	absPath, err := filepath.Abs(filePath)
-	if err != nil {
-		return "", fmt.Errorf("failed to get absolute path: %w", err)
-	}
-
-	// Return as file:// URL
-	return "file://" + filepath.ToSlash(absPath), nil
-}
-
 // fetchODataMetadata downloads or reads the $metadata document.
 // Supports:
 //   - https://... or http://... (HTTP fetch)
diff --git a/mdl/executor/cmd_odata_test.go b/mdl/executor/cmd_odata_test.go
@@ -7,6 +7,8 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/mendixlabs/mxcli/internal/pathutil"
 )
 
 func TestFetchODataMetadata_LocalFile(t *testing.T) {
@@ -99,57 +101,57 @@ func TestNormalizeMetadataUrl(t *testing.T) {
 	tests := []struct {
 		name       string
 		input      string
-		mprDir     string
+		baseDir    string
 		wantPrefix string
 		wantErr    bool
 	}{
 		{
 			name:       "HTTP URL unchanged",
 			input:      "https://api.example.com/$metadata",
-			mprDir:     "",
+			baseDir:    "",
 			wantPrefix: "https://",
 			wantErr:    false,
 		},
 		{
 			name:       "HTTPS URL unchanged",
 			input:      "http://localhost:8080/odata/$metadata",
-			mprDir:     "",
+			baseDir:    "",
 			wantPrefix: "http://",
 			wantErr:    false,
 		},
 		{
 			name:       "Absolute file:// unchanged",
 			input:      "file:///tmp/metadata.xml",
-			mprDir:     "",
+			baseDir:    "",
 			wantPrefix: "file://",
 			wantErr:    false,
 		},
 		{
 			name:       "Relative path normalized to file://",
 			input:      "./metadata.xml",
-			mprDir:     tmpDir,
+			baseDir:    tmpDir,
 			wantPrefix: "file://",
 			wantErr:    false,
 		},
 		{
 			name:       "Bare relative path normalized to file://",
 			input:      "metadata.xml",
-			mprDir:     tmpDir,
+			baseDir:    tmpDir,
 			wantPrefix: "file://",
 			wantErr:    false,
 		},
 		{
 			name:       "Absolute path normalized to file://",
 			input:      "/tmp/metadata.xml",
-			mprDir:     "",
+			baseDir:    "",
 			wantPrefix: "file://",
 			wantErr:    false,
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			result, err := normalizeMetadataUrl(tt.input, tt.mprDir)
+			result, err := pathutil.NormalizeURL(tt.input, tt.baseDir)
 
 			if tt.wantErr {
 				if err == nil {
