ss_url_fmt

English | 中文

English

Purpose

ss_url_fmt is a lightweight Rust utility designed to format ss:// URLs for safe display and logging. Its primary function is to parse a URL, hide the sensitive user information part by replacing it with an asterisk (*), and decode any percent-encoded characters in the URL fragment (the part after #).

This is crucial in environments where URLs need to be displayed or logged without exposing credentials, enhancing privacy and security.

Usage

Here is a basic example of how to use the ss_url_fmt function:

use ss_url_fmt::ss_url_fmt;

fn main() {
  let url = "ss://YWVzLTI1Ni1nY206cGFzc3dvcmQ@example.com:8388#%E8%8A%82%E7%82%B91";
  let formatted_url = ss_url_fmt(url);

  println!("Original URL:  {}", url);
  // Original URL:  ss://YWVzLTI1Ni1nY206cGFzc3dvcmQ@example.com:8388#%E8%8A%82%E7%82%B91

  println!("Formatted URL: {}", formatted_url);
  // Formatted URL: ss://*@example.com:8388#节点1
}

Design and Technology

The utility is intentionally designed to be simple and efficient, with zero dependencies outside of the standard library and percent-encoding.

• No Regex: To ensure high performance and minimize binary size, the implementation avoids using regular expressions. It relies on standard string manipulation methods like strip_prefix and rfind for parsing.
• URL Fragment Decoding: It uses the percent-encoding crate to correctly handle and decode non-ASCII characters in the URL fragment, making the output more readable.
• Idiomatic Rust: The code is written in modern, idiomatic Rust, leveraging features like if let chains and labeled blocks to create clean and maintainable logic.

File Structure

The project follows a standard Rust library structure:

• Cargo.toml: The manifest file containing metadata, dependencies, and keywords.
• src/lib.rs: The core logic of the library.
• tests/main.rs: Unit tests to ensure the function behaves as expected across various scenarios.

A Little Story: The Deprecated userinfo

Have you ever wondered about the user:password@ part in URLs? This userinfo component was defined in the early days of the internet (RFC 1738, 1994) as a straightforward way to embed access credentials directly into a URL. It was convenient for protocols like FTP, where you might need to log in to access a resource.

However, this convenience came at a great security cost. Storing passwords in plain text within a URL meant they could be easily exposed through server logs, browser history, bookmarks, or network monitoring. Anyone who saw the URL could see the password.

Recognizing this significant risk, the Internet Engineering Task Force (IETF) officially deprecated this practice in RFC 3986 (2005). While many browsers and applications still offer backward compatibility for it, its use is strongly discouraged. The modern, secure standard for authentication is to use HTTP Authorization headers, which keep credentials separate from the URL itself. This project, by hiding that very userinfo part, is a small nod to this piece of internet history and the ongoing importance of digital privacy.

中文

项目意义

ss_url_fmt 是一个轻量级的 Rust 工具，旨在格式化 ss:// 链接，以便安全地进行显示和记录。其主要功能是解析 URL，通过将敏感的用户信息部分替换为星号（*）来隐藏它，并对 URL 片段（# 之后的部分）中经过百分号编码的字符进行解码。

在需要显示或记录 URL 而不暴露凭证的环境中，这一点至关重要，能够有效增强隐私和安全性。

使用演示

以下是如何使用 ss_url_fmt 函数的基本示例：

use ss_url_fmt::ss_url_fmt;

fn main() {
  let url = "ss://YWVzLTI1Ni1nY206cGFzc3dvcmQ@example.com:8388#%E8%8A%82%E7%82%B91";
  let formatted_url = ss_url_fmt(url);

  println!("原始链接:  {}", url);
  // 原始链接:  ss://YWVzLTI1Ni1nY206cGFzc3dvcmQ@example.com:8388#%E8%8A%82%E7%82%B91

  println!("格式化后: {}", formatted_url);
  // 格式化后: ss://*@example.com:8388#节点1
}

设计思路与技术栈

本工具在设计上有意保持了简洁和高效，除了标准库和 percent-encoding 之外没有其他依赖。

• 无正则表达式: 为确保高性能和最小化最终文件大小，实现上避免了使用正则表达式。它依赖于 strip_prefix 和 rfind 等标准字符串处理方法进行解析。
• URL 片段解码: 它使用 percent-encoding 包来正确处理和解码 URL 片段中的非 ASCII 字符，使输出更具可读性。
• 地道的 Rust: 代码采用现代、地道的 Rust 风格编写，利用 if let 链和标签块等特性来创建清晰且可维护的逻辑。

文件结构

项目遵循标准的 Rust 库结构：

• Cargo.toml: 清单文件，包含元数据、依赖项和关键字。
• src/lib.rs: 库的核心逻辑。
• tests/main.rs: 单元测试，确保函数在各种场景下都能按预期工作。

相关历史：被废弃的 userinfo

你是否曾对 URL 中的 user:password@ 部分感到好奇？这个 userinfo 组件是在互联网早期（RFC 1738, 1994年）定义的，作为一种将访问凭证直接嵌入 URL 的直接方式。对于像 FTP 这样的协议来说，它很方便，因为你可能需要登录才能访问资源。

然而，这种便利性带来了巨大的安全代价。在 URL 中以纯文本形式存储密码，意味着它们很容易通过服务器日志、浏览器历史、书签或网络监控被泄露。任何看到 URL 的人都能看到密码。

认识到这一重大风险，互联网工程任务组（IETF）在 RFC 3986（2005年）中正式弃用了这种做法。虽然许多浏览器和应用程序为了向后兼容仍支持它，但强烈不建议使用。现代、安全的身份验证标准是使用 HTTP Authorization 头，它将凭证与 URL 本身分开。本项目通过隐藏 userinfo 部分，也是对这段互联网历史和数字隐私重要性的一个小小致敬。

About

This project is an open-source component of i18n.site ⋅ Internationalization Solution.

• i18 : MarkDown Command Line Translation Tool

  The translation perfectly maintains the Markdown format.

  It recognizes file changes and only translates the modified files.

  The translated Markdown content is editable; if you modify the original text and translate it again, manually edited translations will not be overwritten (as long as the original text has not been changed).

• i18n.site : MarkDown Multi-language Static Site Generator

  Optimized for a better reading experience

关于

本项目为 i18n.site ⋅ 国际化解决方案 的开源组件。

• i18 : MarkDown 命令行翻译工具

  翻译能够完美保持 Markdown 的格式。能识别文件的修改，仅翻译有变动的文件。

  Markdown 翻译内容可编辑；如果你修改原文并再次机器翻译，手动修改过的翻译不会被覆盖 （ 如果这段原文没有被修改 ）。

• i18n.site : MarkDown 多语言静态站点生成器 为阅读体验而优化。