在實作 Web 服務時,會需要去讀取客戶端傳送來的 HTTP 請求標頭中的 User-Agent 欄位,來判斷客戶端是使用什麼產品(如應用程式)和 Web 引擎來發送請求,以及客戶端環境的作業系統、CPU 架構和所用的裝置等資訊。

Linux Mint 上 Firefox 60 ESR 所發送的 HTTP 請求中的 User-Agent 欄位內容如下:

Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0

從以上內容,我們可以知道這個客戶端的作業系統是 Ubuntu,瀏覽器是 Firefox,Web 引擎是 Gecko,CPU 架構是 x86_64 (amd64)。我們只要用一個正規表示式,就可以很輕易地用程式抓出這些資訊。

不過,事實上,User-Agent 欄位的內容幾乎沒有格式的限制,例如 Apple Watch 發送出來的 User-Agent 欄位內容如下:

atc/1.0 watchOS/5.1.3 model/Watch3,4 hwp/t8004 build/16S535 (6; dt:156)

所以要對 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

user-agent-parser = "*"

使用方法

建立 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])
}