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-rest) 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.
Relationship to azdext.SSRFGuard ¶
This package is not an SSRF control and does not replace one. Everything here is syntactic and offline: it inspects the URL string and never resolves a name or touches the network. github.com/azure/azure-dev/cli/azd/pkg/azdext.SSRFGuard is the SSRF control. It resolves the host and rejects cloud metadata endpoints, RFC 1918 ranges, loopback, link-local, CGNAT, and the IPv6 transition ranges that can embed a private IPv4 address.
They answer different questions and are meant to be layered, not swapped:
- Validating a URL that a user typed into config, which routinely points at localhost or an internal host, use this package. An SSRF guard would reject those by design, and would perform DNS lookups while parsing config.
- Before issuing an outbound request to a URL you did not author, use azdext.SSRFGuard. Syntactic validation cannot tell you where a name resolves.
Index ¶
Constants ¶
const (
// MaxURLLength is the RFC 2616 practical limit for URL length
MaxURLLength = 2048
)
Variables ¶
This section is empty.
Functions ¶
func NormalizeScheme ¶
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 ¶
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 ¶
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 ¶ added in v0.3.2
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 ¶
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)
}
Types ¶
This section is empty.
Source Files