egui_extras: percent-decode file:// URIs in the file loader (#8342)

`FileLoader` strips the `file://` prefix but does not percent-decode the
path,
so a `file://` URI with an escape such as `%20` fails to resolve on disk
(the
function's own doc noted "percent un-encoding are not handled").

`convert_uri_to_path` now decodes `%XX` escapes (e.g. `%20` -> space)
after
stripping the scheme, using a small inline decoder so no dependency is
added.
Invalid or truncated escapes are left as-is, and UTF-8 multibyte
sequences round
-trip. Added `%20` cases to the existing `check_convert_uri_to_path`
test for
both the Windows and non-Windows paths.

`cargo test`, `clippy`, and `fmt` pass for `egui_extras`.

Closes #8288

---------

Signed-off-by: 林晨 (Leo Cheng) <leo-cheng@vip.qq.com>
Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
This commit is contained in:
禾可andEmil Ernerfeldt authored and GitHub committed 2026-10-06 07:31:27 +00:00
1 parent deb9ed9feb
commit e19e45cd2f
4 files changed
+268 -47

No files matched your search

+1
View File
@@ -1436,6 +1436,7 @@ dependencies = [
"resvg",
"serde",
"syntect",
"tempfile",
]
[[package]]
+1
View File
@@ -108,3 +108,4 @@ ehttp = { workspace = true, optional = true }
[dev-dependencies]
egui = { workspace = true, features = ["default_fonts"] }
tempfile.workspace = true
+3
View File
@@ -38,6 +38,9 @@
/// - Relative paths are relative to the current working directory
/// - Absolute paths are left as is.
///
/// If no file exists at that path, and the path contains percent-escapes (like `%20`),
/// the loader will also try the percent-decoded path (e.g. `file:///tmp/a%20b.png` → `/tmp/a b.png`).
///
/// The `http` loader is a [`BytesLoader`][`egui::load::BytesLoader`].
/// It will attempt to load `http://` and `https://` URIs, and infer the content type from the `Content-Type` header.
///
+263 -47
View File
@@ -4,7 +4,11 @@ use egui::{
load::{Bytes, BytesLoadResult, BytesLoader, BytesPoll, LoadError},
mutex::Mutex,
};
use std::{path::PathBuf, sync::Arc, thread};
use std::{
path::{Path, PathBuf},
sync::Arc,
thread,
};
#[derive(Clone)]
struct File {
@@ -26,39 +30,137 @@ impl FileLoader {
const PROTOCOL: &str = "file://";
/// Converts a hopefully uri encoded string into a `PathBuf`
/// Converts a `file://` URI into a `PathBuf`, without any percent-decoding.
///
/// Note that there is only minimal translation of the uri string into a path to support windows
/// file and unc paths. Other translations like percent un-encoding are not handled.
fn convert_uri_to_path(s: &str) -> Result<PathBuf, egui::load::LoadError> {
/// file and unc paths.
///
/// See also [`convert_uri_to_decoded_path`].
fn convert_uri_to_path(uri: &str) -> Result<PathBuf, egui::load::LoadError> {
// File loader only supports the `file` protocol.
let s = s
let s = uri
.strip_prefix(PROTOCOL)
.ok_or(egui::load::LoadError::NotSupported)?;
Ok(uri_path_to_path(s))
}
if cfg!(target_os = "windows") {
// Standard windows file uris should have the form
//
// file:///c:/path/to/the%20file.txt
//
// in which the hostname field is left out. Check for this by looking at the next character
// after the schema, if it's a slash then we likely have a standard file path.
if let Some(stripped) = s.strip_prefix("/") {
let path = PathBuf::from(stripped);
return Ok(path);
/// Like [`convert_uri_to_path`], but with `%XX` escapes (e.g. `%20`) percent-decoded.
///
/// Returns `None` if the uri is not a `file://` uri, if it contains no valid escapes
/// (so the result would be the same as [`convert_uri_to_path`]),
/// or if the decoded bytes are not a valid path on this platform.
fn convert_uri_to_decoded_path(uri: &str) -> Option<PathBuf> {
let s = uri.strip_prefix(PROTOCOL)?;
let bytes = percent_decode(s)?;
cfg_select! {
unix => {
use std::os::unix::ffi::OsStringExt as _;
Some(PathBuf::from(std::ffi::OsString::from_vec(bytes)))
}
_ => {
let s = String::from_utf8(bytes).ok()?;
Some(uri_path_to_path(&s))
}
// If it's not a standard file uri, it might be a UNC network path of the form
//
// file://hostname/path/to/the%20file.txt
//
// These file uris need to be converted into UNC correct and so need to have the leading
// two backslashes prepended.
let path = PathBuf::from(format!("\\\\{s}"));
return Ok(path);
}
}
Ok(PathBuf::from(s))
/// Converts the part of a `file://` uri after the protocol into a path.
fn uri_path_to_path(s: &str) -> PathBuf {
cfg_select! {
target_os = "windows" => {
// Standard windows file uris should have the form
//
// file:///c:/path/to/the%20file.txt
//
// in which the hostname field is left out. Check for this by looking at the next character
// after the schema, if it's a slash then we likely have a standard file path.
if let Some(stripped) = s.strip_prefix("/") {
PathBuf::from(stripped)
} else {
// If it's not a standard file uri, it might be a UNC network path of the form
//
// file://hostname/path/to/the%20file.txt
//
// These file uris need to be converted into UNC correct and so need to have the leading
// two backslashes prepended.
PathBuf::from(format!("\\\\{s}"))
}
}
_ => PathBuf::from(s),
}
}
/// Percent-decodes `%XX` escapes, leaving any invalid escape (like `%zz` or a trailing `%`) as-is.
///
/// Returns `None` if there was nothing to decode.
fn percent_decode(s: &str) -> Option<Vec<u8>> {
let bytes = s.as_bytes();
let mut out: Vec<u8> = Vec::with_capacity(bytes.len());
let mut decoded_any = false;
let mut i = 0;
while i < bytes.len() {
if bytes[i] == b'%'
&& i + 2 < bytes.len()
&& let (Some(hi), Some(lo)) = (hex_digit(bytes[i + 1]), hex_digit(bytes[i + 2]))
{
out.push((hi << 4) | lo);
decoded_any = true;
i += 3;
continue;
}
out.push(bytes[i]);
i += 1;
}
decoded_any.then_some(out)
}
fn hex_digit(b: u8) -> Option<u8> {
match b {
b'0'..=b'9' => Some(b - b'0'),
b'a'..=b'f' => Some(b - b'a' + 10),
b'A'..=b'F' => Some(b - b'A' + 10),
_ => None,
}
}
/// Reads the file at `path`, falling back to `decoded_path` if `path` does not exist.
///
/// We try the raw path first so that paths that worked before percent-decoding was added
/// (e.g. a file literally named `My%20Doc.png`, or `format!("file://{}", path.display())`)
/// keep resolving exactly as before.
fn read_file(path: &Path, decoded_path: Option<&Path>) -> Result<File, String> {
let (path, bytes) = match std::fs::read(path) {
Ok(bytes) => (path, bytes),
Err(err) => match decoded_path {
Some(decoded_path) if err.kind() == std::io::ErrorKind::NotFound => {
match std::fs::read(decoded_path) {
Ok(bytes) => (decoded_path, bytes),
Err(_) => return Err(err.to_string()),
}
}
_ => return Err(err.to_string()),
},
};
Ok(File {
bytes: bytes.into(),
mime: guess_mime(path),
})
}
fn guess_mime(path: &Path) -> Option<String> {
cfg_select! {
feature = "file" => {
mime_guess2::from_path(path)
.first_raw()
.map(|v| v.to_owned())
}
_ => {
_ = path;
None
}
}
}
impl BytesLoader for FileLoader {
@@ -68,6 +170,7 @@ impl BytesLoader for FileLoader {
fn load(&self, ctx: &egui::Context, uri: &str) -> BytesLoadResult {
let path = convert_uri_to_path(uri)?;
let decoded_path = convert_uri_to_decoded_path(uri);
let mut cache = self.cache.lock();
if let Some(entry) = cache.get(uri).cloned() {
@@ -97,23 +200,7 @@ impl BytesLoader for FileLoader {
let cache = Arc::clone(&self.cache);
let uri = uri.to_owned();
move || {
let result = match std::fs::read(&path) {
Ok(bytes) => {
#[cfg(feature = "file")]
let mime = mime_guess2::from_path(&path)
.first_raw()
.map(|v| v.to_owned());
#[cfg(not(feature = "file"))]
let mime = None;
Ok(File {
bytes: bytes.into(),
mime,
})
}
Err(err) => Err(err.to_string()),
};
let result = read_file(&path, decoded_path.as_deref());
let repaint = {
let mut cache = cache.lock();
if let std::collections::hash_map::Entry::Occupied(mut entry) = cache.entry(uri.clone()) {
@@ -206,18 +293,147 @@ mod tests {
Ok(PathBuf::from("\\\\host\\share\\path\\to\\image.jpg")),
"file uris with a host are turned into UNC paths with leading backslashes on windows.",
),
(
"file:///c:/path/to/the%20image.jpg",
Ok(PathBuf::from("c:\\path\\to\\the%20image.jpg")),
"the raw path is not percent-decoded.",
),
];
checks.append(&mut windows_checks);
} else {
let mut more_checks = vec![(
"file://path/to/image.jpg",
Ok(PathBuf::from("path/to/image.jpg")),
"file uris are turned into bare paths.",
)];
let mut more_checks = vec![
(
"file://path/to/image.jpg",
Ok(PathBuf::from("path/to/image.jpg")),
"file uris are turned into bare paths.",
),
(
"file://path/to/the%20image.jpg",
Ok(PathBuf::from("path/to/the%20image.jpg")),
"the raw path is not percent-decoded.",
),
];
checks.append(&mut more_checks);
}
for (uri_s, path, reason) in checks {
assert_eq!(convert_uri_to_path(uri_s), path, "{reason}");
}
}
#[test]
fn check_percent_decode() {
assert_eq!(percent_decode("a/b.png"), None, "nothing to decode");
assert_eq!(
percent_decode("a%20b.png").as_deref(),
Some(&b"a b.png"[..])
);
assert_eq!(
percent_decode("na%C3%AFve.png").as_deref(),
Some("naïve.png".as_bytes()),
"multi-byte UTF-8"
);
assert_eq!(
percent_decode("na%c3%afve.png").as_deref(),
Some("naïve.png".as_bytes()),
"lower-case hex"
);
assert_eq!(
percent_decode("100%25.png").as_deref(),
Some(&b"100%.png"[..])
);
assert_eq!(
percent_decode("%2520").as_deref(),
Some(&b"%20"[..]),
"no double-decoding"
);
// Invalid escapes are left as-is:
assert_eq!(percent_decode("a%zzb"), None);
assert_eq!(percent_decode("a%"), None);
assert_eq!(percent_decode("a%2"), None);
assert_eq!(percent_decode("a%2g"), None);
assert_eq!(percent_decode("%zz%20%").as_deref(), Some(&b"%zz %"[..]));
// Invalid UTF-8 is kept losslessly:
assert_eq!(percent_decode("na%EFve").as_deref(), Some(&b"na\xEFve"[..]));
}
#[test]
fn check_convert_uri_to_decoded_path() {
assert_eq!(convert_uri_to_decoded_path("http://host/a%20b.jpg"), None);
assert_eq!(
convert_uri_to_decoded_path("file://path/to/image.jpg"),
None
);
if cfg!(target_os = "windows") {
assert_eq!(
convert_uri_to_decoded_path("file:///c:/path/to/the%20image.jpg"),
Some(PathBuf::from("c:\\path\\to\\the image.jpg")),
);
assert_eq!(
convert_uri_to_decoded_path("file://host/share/na%C3%AFve.jpg"),
Some(PathBuf::from("\\\\host\\share\\naïve.jpg")),
);
} else {
assert_eq!(
convert_uri_to_decoded_path("file:///path/to/the%20image.jpg"),
Some(PathBuf::from("/path/to/the image.jpg")),
);
assert_eq!(
convert_uri_to_decoded_path("file:///na%C3%AFve/100%25.jpg"),
Some(PathBuf::from("/naïve/100%.jpg")),
);
}
cfg_select! {
unix => {
use std::os::unix::ffi::OsStrExt as _;
assert_eq!(
convert_uri_to_decoded_path("file:///na%EFve.jpg"),
Some(PathBuf::from(std::ffi::OsStr::from_bytes(b"/na\xEFve.jpg"))),
"invalid UTF-8 is a valid path on unix"
);
}
_ => {
assert_eq!(
convert_uri_to_decoded_path("file:///c:/na%EFve.jpg"),
None,
"invalid UTF-8 can't be decoded"
);
}
}
}
#[test]
fn check_read_file_fallback() {
let dir = tempfile::tempdir().unwrap();
let dir = dir.path();
let read = |name: &str| {
let uri = if cfg!(target_os = "windows") {
format!("{PROTOCOL}/{}/{name}", dir.display())
} else {
format!("{PROTOCOL}{}/{name}", dir.display())
};
let path = convert_uri_to_path(&uri).unwrap();
let decoded_path = convert_uri_to_decoded_path(&uri);
read_file(&path, decoded_path.as_deref()).map(|file| file.bytes.to_vec())
};
std::fs::write(dir.join("a b.txt"), "space").unwrap();
std::fs::write(dir.join("My%20Doc.txt"), "literal").unwrap();
std::fs::write(dir.join("both%20.txt"), "both raw").unwrap();
std::fs::write(dir.join("both .txt"), "both decoded").unwrap();
assert_eq!(read("a%20b.txt").unwrap(), b"space", "decoded");
assert_eq!(read("a b.txt").unwrap(), b"space", "unencoded");
assert_eq!(
read("My%20Doc.txt").unwrap(),
b"literal",
"literal %20 in file name"
);
assert_eq!(read("both%20.txt").unwrap(), b"both raw", "raw wins");
assert!(read("missing%20.txt").is_err());
}
}