url

README

URLs

• Parse a URL: Parses a URL into its components like scheme, host, path, query, and fragment.

• Build a URL from Components: Constructs a complete URL by combining base URL, path, and query parameters.

• Resolve Relative URLs: Resolves a relative URL against a base URL to form an absolute URL.

• URL Encoding: Encodes URL components to ensure they are properly formatted for inclusion in URLs.

Examples:

For examples of each function, please checkout EXAMPLES.md

---

Documentation

Overview

Package url defines url utilities helpers.

Index

• func AddQueryParams(urlStr string, params map[string]string) (string, error)
• func BuildURL(scheme, host, path string, query map[string]string) (string, error)
• func ExtractDomain(urlStr string) (string, error)
• func GetQueryParam(urlStr, param string) (string, error)
• func IsValidURL(urlStr string, allowedReqSchemes []string) bool

Functions

func AddQueryParams

func AddQueryParams(urlStr string, params map[string]string) (string, error)

AddQueryParams adds multiple query parameters to a given URL and returns the updated URL.

Parameters:

• urlStr: A string representing the base URL to which query parameters should be added.
• params: A map[string]string containing key-value pairs of query parameters to add.

Returns:

• string: The updated URL with the new query parameters appended.
• error: An error if the URL cannot be parsed.

Behavior:

• The function parses the provided URL string using `net/url.Parse`.
• Iterates through the `params` map, adding each key-value pair as a query parameter to the URL.
• Encodes the updated query parameters back into the URL.

Example:

baseURL := "https://example.com/path"
params := map[string]string{
    "param1": "value1",
    "param2": "value2",
}
updatedURL, err := AddQueryParams(baseURL, params)
if err != nil {
    fmt.Println("Error:", err)
} else {
    fmt.Println(updatedURL)
    // Output: https://example.com/path?param1=value1&param2=value2
}

Notes:

• If a query parameter key already exists in the URL, `Add` appends the new value instead of overwriting it.
• Use this function when you need to dynamically construct URLs with multiple query parameters.
• The function ensures proper encoding of query parameters.

Usage:

To add query parameters to a URL:
  params := map[string]string{"key": "value", "foo": "bar"}
  updatedURL, err := AddQueryParams("http://example.com", params)
  fmt.Println("Result:", updatedURL)

func BuildURL

func BuildURL(scheme, host, path string, query map[string]string) (string, error)

BuildURL constructs a URL by combining a scheme, host, path, and query parameters.

Parameters:

• scheme: The URL scheme (e.g., "http", "https") to use.
• host: The host or domain name (e.g., "example.com").
• path: The path part of the URL (e.g., "path/to/resource").
• query: A map[string]string containing query parameters to append to the URL.

Returns:

• string: The constructed URL with the scheme, host, path, and query parameters.
• error: An error if the URL could not be parsed or if any issues occurred during URL construction.

Behavior:

• The function concatenates the scheme, host, and path into a URL string.
• It then attempts to parse the constructed URL and add the query parameters.
• If the URL parsing fails, an error is returned.
• Query parameters are added one by one using the `url.Values.Add` method to ensure proper encoding.

Example:

scheme := "https"
host := "example.com"
path := "search"
query := map[string]string{
    "q": "golang",
    "page": "1",
}
fullURL, err := BuildURL(scheme, host, path, query)
if err != nil {
    fmt.Println("Error:", err)
} else {
    fmt.Println(fullURL)
    // Output: https://example.com/search?q=golang&page=1
}

Notes:

• If any query parameters are provided, they will be encoded and appended to the URL.
• If the path is empty, a trailing slash will be included after the host.
• The function ensures the proper encoding of query parameters and safely constructs the final URL.

Usage:

To construct a URL with query parameters:
  queryParams := map[string]string{"key": "value", "anotherKey": "anotherValue"}
  url, err := BuildURL("http", "example.com", "search", queryParams)
  fmt.Println("Constructed URL:", url)

func ExtractDomain

func ExtractDomain(urlStr string) (string, error)

ExtractDomain extracts the domain (hostname) from a given URL string.

Parameters:

• urlStr: A string representing the URL from which to extract the domain.

Returns:

• string: The domain (hostname) extracted from the URL.
• error: An error if the URL is invalid or the domain cannot be determined.

Errors:

• Returns an error if the provided URL string is invalid or cannot be parsed.
• Returns "parameter not found" error if the URL does not contain a hostname.

Example:

url := "https://example.com/path?query=value"
domain, err := ExtractDomain(url)
if err != nil {
    log.Println("Error:", err)
} else {
    log.Println("Domain:", domain) // Output: "example.com"

Notes:

• This function uses `net/url.ParseRequestURI` to validate and parse the URL.
• It extracts the hostname part of the URL and ignores the port, path, query, or fragment.

Usage:

To extract the domain from a URL:
  domain, err := ExtractDomain("http://example.com/some-path")
  if err != nil {
      fmt.Println("Error:", err)
  } else {
      fmt.Println("Domain:", domain)

func GetQueryParam

func GetQueryParam(urlStr, param string) (string, error)

GetQueryParam extracts the value of a specified query parameter from a given URL string.

Parameters:

• urlStr: A string representing the URL containing query parameters.
• param: The name of the query parameter to retrieve.

Returns:

• string: The value of the specified query parameter.
• error: An error if the URL is invalid or the parameter is not found.

Errors:

• Returns an error if the provided URL string is invalid or cannot be parsed.
• Returns "parameter not found" error if the specified parameter does not exist.

Example:

url := "https://example.com?foo=bar&baz=qux"
value, err := GetQueryParam(url, "foo")
if err != nil {
    log.Println("Error:", err)
} else {
    log.Println("Value:", value) // Output: "bar"

Notes:

• This function uses the `net/url` package for robust URL parsing.
• It assumes the URL is properly formatted with query parameters starting after a "?".

Usage:

To retrieve the value of a query parameter from a URL:
  value, err := GetQueryParam("http://example.com?key=value", "key")
  if err != nil {
      fmt.Println("Error:", err)
  } else {
      fmt.Println("Value:", value)

func IsValidURL

func IsValidURL(urlStr string, allowedReqSchemes []string) bool

IsValidURL checks whether a given URL string is valid and its scheme matches the allowed list.

Parameters:

• urlStr: A string representing the URL to validate.
• allowedReqSchemes: A slice of strings containing the allowed schemes (e.g., "http", "https").

Returns:

• bool: `true` if the URL is valid and its scheme is in the allowed list; otherwise, `false`.

Behavior:

• The function attempts to parse the provided URL string using `net/url.Parse`.
• If the URL is invalid or its scheme is not in the allowed list, the function returns `false`.
• If the URL is valid and the scheme is allowed, the function returns `true`.

Example:

url := "https://example.com"
allowed := []string{"http", "https"}
isValid := IsValidURL(url, allowed)
if isValid {
    fmt.Println("URL is valid and uses an allowed scheme.")
} else {
    fmt.Println("Invalid URL or scheme.")
}

Notes:

• The function does not check other parts of the URL (e.g., hostname, path, query parameters).
• Use this function when you need to validate both the structure and scheme of a URL.

Usage:

To validate URLs and restrict their schemes:
  valid := IsValidURL("http://example.com", []string{"http", "https"})
  fmt.Println("Is valid:", valid)