在實作 Web 服務時,會需要去讀取客戶端傳送來的 HTTP 請求標頭中的 User-Agent 欄位,來判斷客戶端是使用什麼產品(如應用程式)和 Web 引擎來發送請求,以及客戶端環境的作業系統、CPU 架構和所用的裝置等資訊。
Linux Mint 上 Firefox 60 ESR 所發送的 HTTP 請求中的 User-Agent 欄位內容如下:
從以上內容,我們可以知道這個客戶端的作業系統是 Ubuntu,瀏覽器是 Firefox,Web 引擎是 Gecko,CPU 架構是 x86_64 (amd64)。我們只要用一個正規表示式,就可以很輕易地用程式抓出這些資訊。
不過,事實上,User-Agent 欄位的內容幾乎沒有格式的限制,例如 Apple Watch 發送出來的 User-Agent 欄位內容如下:
所以要對 User-Agent 欄位的內容進行完美解析是不可能的事情。還好,在 GitHub 上有一個 uap-core 開源專案,整理了用來解析已知(有流通)的 User-Agent 的正規表示式(都存在 regexes.yaml 檔案中),以及在各種場景下的測試案例。
然而,uap-core 只有整理解析 User-Agent 中產品、作業系統和裝置的部份,而並沒有 CPU 架構和 Web 引擎。後面這兩個未支援的部份,在 ua-parser-js 這個開源專案是有支援的,而且也是使用正規表示式來解析。
也就是說,我們其實可以利用 uap-core 和 ua-parser-js 提供的正規表示式,來在 Rust 程式語言中實現解析 User-Agent 欄位的功能。
User Agent Parser
「User Agent Parser」是筆者開發的套件,受到 uap-core 和 ua-parser-js 的啟發,可以用來解析 User-Agent 欄位,從中獲得客戶端的產品、作業系統、裝置、CPU 架構和 Web 引擎等資訊。
Crates.io
Cargo.toml
使用方法
建立 regexes.yaml
以下是一個簡單的 regexes.yaml 範例:
user_agent_parsers:
- regex: '(ESPN)[%20| ]+Radio/(\d+)\.(\d+)\.(\d+) CFNetwork'
- regex: '(Namoroka|Shiretoko|Minefield)/(\d+)\.(\d+)\.(\d+(?:pre|))'
family_replacement: 'Firefox ($1)'
- regex: '(Android) Eclair'
v1_replacement: '2'
v2_replacement: '1'
os_parsers:
- regex: 'Win(?:dows)? ?(95|98|3.1|NT|ME|2000|XP|Vista|7|CE)'
os_replacement: 'Windows'
os_v1_replacement: '$1'
device_parsers:
- regex: '\bSmartWatch *\( *([^;]+) *; *([^;]+) *;'
device_replacement: '$1 $2'
brand_replacement: '$1'
model_replacement: '$2'
regexes.yaml 為一個 Map 結構,user_agent_parsers 這個鍵值存放著解析產品所需的正規表示式和取代字串的樣本,os_parsers 這個鍵值存放著解析作業系統所需的正規表示式和取代字串的樣本,device_parsers 這個鍵值存放著解析裝置所需的正規表示式和取代字串的樣本。取代字串的樣本中,如果有以錢字號 $ 來接著數字的部份,就會被這數字對應到的正規表示式群組所匹配到的字串來取代。
如果不需要自行撰寫 regexes.yaml 的話,可以到 uap-core 專案中取得標準的 regexes.yaml。
讀取 regexes.yaml
建立好 regexes.yaml,可以利用 user_agent_parser 這個 crate 所提供的 UserAgentParser 結構體的 from_path 或是 from_str 關聯函數來讀取,並建立出 UserAgentParser 結構實體。
from_path 可以從檔案讀取 regexes.yaml 的資料,例如:
use user_agent_parser::UserAgentParser;
let ua_parser = UserAgentParser::from_path("/path/to/regexes.yaml").unwrap();
from_str 可以從記憶體讀取 regexes.yaml 的資料,建議搭配 include_str 巨集一同使用,例如:
use user_agent_parser::UserAgentParser;
let ua_parser = UserAgentParser::from_str(include_str!("/path/to/regexes.yaml")).unwrap();
解析
利用 UserAgentParser 提供的名稱以 parse_ 為開頭的方法,來解析透過參數傳入的 User-Agent 欄位內容的字串。
例如:
use user_agent_parser::UserAgentParser;
let ua_parser = UserAgentParser::from_path("/path/to/regexes.yaml").unwrap();
let user_agent = "Mozilla/5.0 (X11; Linux x86_64; rv:10.0) Gecko/20100101 Firefox/10.0 [FBAN/FBIOS;FBAV/8.0.0.28.18;FBBV/1665515;FBDV/iPhone4,1;FBMD/iPhone;FBSN/iPhone OS;FBSV/7.0.4;FBSS/2; FBCR/Telekom.de;FBID/phone;FBLC/de_DE;FBOP/5]";
let product = ua_parser.parse_product(user_agent);
println!("{:#?}", product);
// Product {
// name: Some(
// "Facebook",
// ),
// major: Some(
// "8",
// ),
// minor: Some(
// "0",
// ),
// patch: Some(
// "0",
// ),
// }
let os = ua_parser.parse_os(user_agent);
println!("{:#?}", os);
// OS {
// name: Some(
// "iOS",
// ),
// major: None,
// minor: None,
// patch: None,
// patch_minor: None,
// }
let device = ua_parser.parse_device(user_agent);
println!("{:#?}", device);
// Device {
// name: Some(
// "iPhone",
// ),
// brand: Some(
// "Apple",
// ),
// model: Some(
// "iPhone4,1",
// ),
// }
let cpu = ua_parser.parse_cpu(user_agent);
println!("{:#?}", cpu);
// CPU {
// architecture: Some(
// "amd64",
// ),
// }
let engine = ua_parser.parse_engine(user_agent);
println!("{:#?}", engine);
// Engine {
// name: Some(
// "Gecko",
// ),
// major: Some(
// "10",
// ),
// minor: Some(
// "0",
// ),
// patch: None,
// }
生命周期
parse_* 方法所回傳的資料模型實體,其生命周期相依於 User-Agent 欄位內容的字串和 UserAgentParser 結構實體。如果要讓模型沒有生命周期相依性,可以使用其提供的 into_owned 方法。
use user_agent_parser::UserAgentParser;
let ua_parser = UserAgentParser::from_path("/path/to/regexes.yaml").unwrap();
let product = ua_parser.parse_product("Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.12) Gecko/20101027 Ubuntu/10.04 (lucid) Firefox/3.6.12").into_owned();
Rocket 框架支援
Rocket 是 Rust 的一個 Web 框架(Web Framework),如果想要讓 Rocket 能夠解析 User-Agent 欄位的話,可以考慮與這個 User Agent Parser 一同使用。首先要啟用 User Agent Parser 的 rocket 特色,Cargo.toml 設定檔的寫法如下:
[dependencies.user-agent-parser]
version = "*"
features = ["rocket"]
接著那些 parse_* 方法所回傳的資料模型,也就是 Product、OS、Device、CPU、Engine 結構體,就可以直接被當作請求守衛來用了!另外,如果不想解析 User-Agent 欄位的內容,也可以使用 UserAgent 這個請求守衛。不過要記得將一個 UserAgentParser 結構實體註冊給 Rocket 使用。
程式範例如下:
#[macro_use]
extern crate rocket;
use user_agent_parser::{UserAgentParser, UserAgent, Product, OS, Device, CPU, Engine};
#[get("/")]
fn index(user_agent: UserAgent, product: Product, os: OS, device: Device, cpu: CPU, engine: Engine) -> String {
format!("{user_agent:#?}\n{product:#?}\n{os:#?}\n{device:#?}\n{cpu:#?}\n{engine:#?}",
user_agent = user_agent,
product = product,
os = os,
device = device,
cpu = cpu,
engine = engine,
)
}
#[launch]
fn rocket() -> _ {
rocket::build()
.manage(UserAgentParser::from_path("/path/to/regexes.yaml").unwrap())
.mount("/", routes![index])
}
