feat(http): add URL replacement feature for HTTP requests

[ThomasSteinbach]

• Support string and regex-based URL replacements via url_replacements setting
• Enable protocol, hostname, and path modifications for HTTP(S) downloads
• Configure replacements in mise.toml or globally in settings

What problem does this feature solve?

• mise has no inbuilt registry it downloads artifacts from.
• Instead it reads remote registry manifests.
• Those manifests contain URLs with where to download tools from.
• In some environments (enterprise, DMZs, ...) those URLs are not directly accessible but mostly by a proxy.
• mise currently has no configuration for a general URL redirection to that proxy.
• This is exactly what this feature provides.
• It is a mechanism where you can tell mise to replace/modify any URL request as desired.

Solves #5660

---

Full Documentation

... as from the update mise docs:

url_replacements

• Type: object (optional)
• Env: MISE_URL_REPLACEMENTS
• Default: None

Map of URL patterns to replacement URLs. This feature supports both simple hostname replacements
and advanced regex-based URL transformations for download mirroring and custom registries.

Configuration Examples

Environment variable (JSON format):

# Simple hostname replacement
export MISE_URL_REPLACEMENTS='
{
  "github.com": "myregistry.net", 
  "releases.hashicorp.com": "mirror.example.com"
}'

# Regex pattern (note the escaped backslashes in JSON)
export MISE_URL_REPLACEMENTS='
{
  "regex:https://github\.com/([^/]+)/([^/]+)/releases/download/(.+)":
  "https://mirror.corp.com/github/$1/$2/$3"
}'

In mise.toml:

[settings]
# Simple hostname replacement
url_replacements = { 
  "github.com" = "myregistry.net", 
  "releases.hashicorp.com" = "mirror.example.com" 
}

# Regex patterns
url_replacements = { 
  "regex:^http://(.+)" = "https://$1",
  "regex:https://github\\.com/([^/]+)/([^/]+)/releases/download/(.+)" = 
    "https://mirror.corp.com/github/$1/$2/$3"
}

Simple Hostname Replacement

For simple hostname-based mirroring, the key is the original hostname/domain to replace,
and the value is the replacement string. The replacement happens by searching and replacing
the pattern anywhere in the full URL string (including protocol, hostname, path, and query parameters).

Examples:

• github.com -> myregistry.net replaces GitHub hostnames
• https://github.com -> https://myregistry.net with protocol excludes e.g. 'api.github.com'
• https://github.com -> https://proxy.corp.com/github-mirror replaces GitHub with corporate proxy
• http://host.net -> https://host.net replaces protocol from HTTP to HTTPS

Advanced Regex Replacement

For more complex URL transformations, you can use regex patterns. When a key starts with regex:,
it is treated as a regular expression pattern that can match and transform any part of the URL.
The value can use capture groups from the regex pattern.

Regex Examples

1. Protocol Conversion (HTTP to HTTPS)

[settings]
url_replacements = { 
  "regex:^http://(.+)" = "https://$1" 
}

This converts any HTTP URL to HTTPS by capturing everything after "http://" and replacing it with "https://".

2. GitHub Release Mirroring with Path Restructuring

[settings]
url_replacements = { 
  "regex:https://github\\.com/([^/]+)/([^/]+)/releases/download/(.+)" = 
    "https://mirror.corp.com/github/$1/$2/$3" 
}

Transforms https://github.com/owner/repo/releases/download/v1.0.0/file.tar.gz
to https://mirror.corp.com/github/owner/repo/v1.0.0/file.tar.gz

3. Subdomain to Path Conversion

[settings]
url_replacements = { 
  "regex:https://([^.]+)\\.cdn\\.example\\.com/(.+)" = 
    "https://unified-cdn.com/$1/$2" 
}

Converts subdomain-based URLs to path-based URLs on a unified CDN.

4. Multiple Replacement Patterns (processed in order)

[settings]
url_replacements = { 
  "regex:https://github\\.com/microsoft/(.+)" = 
    "https://internal-mirror.com/microsoft/$1",
  "regex:https://github\\.com/(.+)" = 
    "https://public-mirror.com/github/$1",
  "releases.hashicorp.com" = "hashicorp-mirror.internal.com"
}

First regex catches Microsoft repositories specifically, second catches all other GitHub URLs,
and the simple replacement handles HashiCorp.

Use Cases

1. Corporate Mirrors: Replace public download URLs with internal corporate mirrors
2. Custom Registries: Redirect package downloads to custom or private registries
3. Geographic Optimization: Route downloads to geographically closer mirrors
4. Protocol Changes: Convert HTTP URLs to HTTPS or vice versa

Regex Syntax

mise uses Rust regex engine which supports:

• ^ and $ for anchors (start/end of string)
• (.+) for capture groups (use $1, $2, etc. in replacement)
• [^/]+ for character classes (matches any character except /)
• \\. for escaping special characters (note: double backslash required in TOML)
• *, +, ? for quantifiers
• | for alternation

You can check on regex101.com if your regex works (see example).
Full regex syntax documentation: https://docs.rs/regex/latest/regex/#syntax

Precedence and Matching

• Regex patterns (keys starting with regex:) are processed first, in the order they appear
• Simple hostname replacements are processed second
• The first matching pattern is used; subsequent patterns are ignored for that URL
• If no patterns match, the original URL is used unchanged

Security Considerations

When using regex patterns, ensure your replacement URLs point to trusted sources,
as this feature can redirect tool downloads to arbitrary locations.

---

• This change has been created with heavy use of AI tools (https://opencode.ai, https://claude.ai Sonnet 4, https://github.com/oraios/serena)
• However every line of code (configuration and docs) was reviewed and optimized by a human (me, @ThomasSteinbach)
• Despite using AI I spent hours into optimizing and testing this change to deliver the highest quality possible
• I hope this change is (almost) ready to be merged :)

Kudos to this project <3

[jdx]

bugbot run

[ThomasSteinbach]

bugbot run

[cursor]

Skipping Bugbot: Unable to authenticate your request. Please make sure Bugbot is properly installed and configured for this repository.

[jdx]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no bugs!

---

[puskunalis]

This is a great enhancement and very useful, thank you @ThomasSteinbach!