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 ¶
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 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