urlutil

Documentation

Overview

Package urlutil provides URL validation and parsing utilities with RFC-compliant validation.

This package makes it easy for consumers (like azd-app and azd-exec) to validate and parse HTTP/HTTPS URLs with comprehensive validation rules. It uses the standard library's net/url.Parse for robust parsing and adds additional security and validation checks such as protocol restrictions, host validation, and length limits.

Usage

Use Validate for comprehensive HTTP/HTTPS URL validation:

import "github.com/jongio/azd-core/urlutil"

// Validate custom URL from config
if err := urlutil.Validate(customURL); err != nil {
	return fmt.Errorf("invalid custom URL: %w", err)
}

Use ValidateHTTPSOnly for production environments requiring HTTPS:

// Enforce HTTPS-only (allows localhost HTTP for development)
if err := urlutil.ValidateHTTPSOnly(apiEndpoint); err != nil {
	return fmt.Errorf("API endpoint must use HTTPS: %w", err)
}

Use Parse to parse and normalize URLs:

// Parse and normalize user-provided URL
parsed, err := urlutil.Parse(userProvidedURL)
if err != nil {
	return err
}
fmt.Printf("Accessing: %s://%s\n", parsed.Scheme, parsed.Host)

Use NormalizeScheme to ensure URLs have proper protocols:

// Add default https:// if missing
normalized := urlutil.NormalizeScheme("example.com", "https")
// Returns: "https://example.com"

Validation Rules

The validation functions enforce the following rules:

• URL must not be empty or only whitespace
• URL must use http:// or https:// protocol (rejects ftp://, file://, javascript://, etc.)
• URL must have a valid host/domain (rejects "http://", "https://")
• URL must not exceed 2048 characters (RFC 2616 practical limit)
• URL must be parseable by net/url.Parse (RFC 3986 compliant)

Security Considerations

This package helps prevent common security issues:

• Protocol validation prevents javascript:, file:, and data: URL injection
• Host validation prevents malformed URLs that could bypass security checks
• Length limits prevent DoS via extremely long URLs
• Uses net/url.Parse for RFC-compliant parsing (prevents parsing bypasses)

For production environments, use ValidateHTTPSOnly to enforce encrypted connections, while still allowing localhost HTTP for local development.

Index

• Constants
• func NormalizeScheme(rawURL, defaultScheme string) string
• func Parse(rawURL string) (*neturl.URL, error)
• func Validate(rawURL string) error
• func ValidateDomain(domain string) error
• func ValidateHTTPSOnly(rawURL string) error

Constants

const (
	// MaxURLLength is the RFC 2616 practical limit for URL length
	MaxURLLength = 2048
)

Functions

func NormalizeScheme

func NormalizeScheme(rawURL, defaultScheme string) string

NormalizeScheme ensures URL has http:// or https:// prefix. If the URL already has a valid scheme (http:// or https://), it is returned unchanged. If the URL has no scheme or an invalid scheme, the defaultScheme is prepended.

The defaultScheme should be either "http" or "https" (without "://").

Example:

normalized := urlutil.NormalizeScheme("example.com", "https")
// Returns: "https://example.com"

normalized = urlutil.NormalizeScheme("http://example.com", "https")
// Returns: "http://example.com" (already has valid scheme)

func Parse

func Parse(rawURL string) (*neturl.URL, error)

Parse parses and normalizes URLs with trimming and validation. It returns a *url.URL if the URL is valid, or an error if validation fails.

This is a convenience wrapper around Validate and net/url.Parse.

Example:

parsed, err := urlutil.Parse(userInput)
if err != nil {
	return err
}
fmt.Printf("Host: %s\n", parsed.Host)

func Validate

func Validate(rawURL string) error

Validate performs comprehensive HTTP/HTTPS URL validation using net/url.Parse. It validates that the URL:

• Is not empty or only whitespace
• Uses http:// or https:// protocol
• Has a valid host/domain
• Does not exceed MaxURLLength (2048 characters)
• Can be parsed by net/url.Parse (RFC 3986 compliant)

Returns an error with context if validation fails.

Example:

if err := urlutil.Validate("https://example.com"); err != nil {
	return fmt.Errorf("invalid URL: %w", err)
}

func ValidateDomain

func ValidateDomain(domain string) error

ValidateDomain validates a domain name without protocol. It validates that the domain:

• Is not empty or only whitespace
• Does not include a protocol (http:// or https://)
• Is a valid domain name format
• Does not exceed 253 characters (max domain length)

This is useful for configuration fields that expect domain names rather than full URLs (e.g., Azure custom domains).

Returns an error with context if validation fails.

Example:

if err := urlutil.ValidateDomain("www.example.com"); err != nil {
	return fmt.Errorf("invalid domain: %w", err)
}

func ValidateHTTPSOnly

func ValidateHTTPSOnly(rawURL string) error

ValidateHTTPSOnly enforces HTTPS-only URLs for production use. It allows HTTP for localhost (127.0.0.1, ::1, localhost) for local development, but rejects all other HTTP URLs.

This is useful for production environments where encrypted connections are required, while still allowing local development workflows.

Example:

if err := urlutil.ValidateHTTPSOnly(apiEndpoint); err != nil {
	return fmt.Errorf("production endpoint must use HTTPS: %w", err)
}