Mục lục thư viện

Bắt đầu với Rust

Bài này đưa một chương trình Rust từ con số không tới lần kích hoạt license đầu tiên, rồi tới bản build cho khách: cài SDK, vài dòng mã, chạy thử, xem kết quả trên dashboard, xử lý lỗi và phát hành.

6 phút đọc

Cần có

Rust 1.80 trở lên. Lần build đầu cần mạng để Cargo lấy các crate SDK dùng (ed25519-dalek, ureq, serde…).
Một ứng dụng trên dashboard. Trang Tích hợp › Kết nối phần mềm của nó có địa chỉ API, App ID, khoá công khai và nút Tạo key thử nghiệm. Địa chỉ API kết thúc bằng /api, không có /v1: https://<trang ClavisAUH của bạn>/api.

1. Cài SDK

Tải clavisauh-rust-1.0.0.zip ở trang Tải về, kiểm SHA-256 như trang đó hướng dẫn, rồi giải nén trong thư mục crate của bạn (chương trình mới: chạy cargo new your_app trước; rồi unzip clavisauh-rust-1.0.0.zip, hoặc Expand-Archive clavisauh-rust-1.0.0.zip . trong PowerShell): zip chứa một thư mục clavisauh-rust-1.0.0 là SDK. Thêm nó làm phụ thuộc theo đường dẫn:

cargo add --path clavisauh-rust-1.0.0

Cargo.toml khi đó có, trong [dependencies]:

clavisauh = { version = "1.0.0", path = "clavisauh-rust-1.0.0" }

Dự án tạo bằng cargo new từ Rust 1.85 (edition 2024) tự chọn phiên bản crate hợp với trình biên dịch của bạn. Dự án cũ hơn mà Cargo báo một crate cần rustc mới hơn thì thêm file này, như dự án mẫu:

# Resolve dependencies to versions that still build with the crate's rust-version (Cargo 1.84+ reads this; an older
# Cargo ignores it and uses Cargo.lock as committed).
[resolver]
incompatible-rust-versions = "fallback"

SDK chưa có trên crates.io; khi có, bài này sẽ ghi thêm cách cài từ đó.

2. Mã tối thiểu

Các khối dưới đây là từng phần của một file; file đầy đủ, kèm import và hàm phụ, ở bước 3.

Tạo client một lần khi phần mềm khởi động. Địa chỉ API, App ID và khoá công khai là ba giá trị ở trang Kết nối phần mềm: mẫu đọc chúng từ biến môi trường, phần mềm của bạn thì ghi thẳng vào mã. Khoá thiết bị nằm trong một file chỉ người dùng hiện tại đọc được; phiên và token offline gắn với khoá này, còn suất trên license đi theo các định danh đã băm của máy:

let app_key = var("CLAVIS_APP_KEY");
let mut options = Options::new(
    &var("CLAVIS_BASE_URL"),
    &var("CLAVIS_APP_ID"),
    &[&app_key],
    default_device(None),
);
// The same key every run: sessions and offline tokens stay with this machine.
options.device_key =
    Some(load_or_create_device_key(state.join("device.key")).expect("the device key file"));
options.app_version = Some("1.0.0".into());
let mut client = Client::new(options).expect("the app settings");

Kích hoạt key của khách. Khi không có mạng, token offline lưu lần trước giữ phần mềm chạy tiếp:

let grant = match client
    .init()
    .and_then(|_| client.activate(&var("CLAVIS_LICENSE")))
{
    Ok(grant) => Some(grant),
    Err(err) => {
        // No answer (network_error, timeout...): a token saved last time keeps the software working.
        let token = fs::read_to_string(&saved).unwrap_or_default();
        if !err.retryable() || token.is_empty() || client.verify_offline(Some(&token)).is_none()
        {
            fail(&err, &lang);
        }
        println!("Offline: using the license saved on this machine");
        None
    }
};

Khoá công khai chỉ dùng để kiểm chữ ký, nhúng vào phần mềm là an toàn. Đừng bao giờ nhúng một khoá bí mật nào.

3. Chạy thử

Ở trang Kết nối phần mềm, bấm Tạo key thử nghiệm. Key TEST hết hạn sau 24 giờ và không tính hạn mức.
Lưu file đầy đủ dưới đây thành src/main.rs của dự án (dự án mẫu, mỗi kịch bản một file chạy riêng, có file này là k1_key.rs và chạy bằng cargo run --bin k1_key), đặt bốn cài đặt rồi chạy:

//! K1 · License key only: activate on this machine, keep the session alive, work offline for a while.
//!
//! Run: CLAVIS_BASE_URL=... CLAVIS_APP_ID=... CLAVIS_APP_KEY=... CLAVIS_LICENSE=... cargo run --release
//! (saved as src/main.rs in your crate; the starter project runs it with cargo run --bin k1_key)

use std::env;
use std::fs;
use std::path::PathBuf;
use std::process::exit;

use clavisauh::{default_device, load_or_create_device_key, Client, Error, Options};

fn var(name: &str) -> String {
    env::var(name).unwrap_or_default()
}

/// Prints the sentence for the user and the code, and stops.
fn fail(err: &Error, lang: &str) -> ! {
    println!("{}", err.user_message(lang));
    println!("FAIL {}", err.code);
    exit(1)
}

fn main() {
    let lang = env::var("CLAVIS_LANG").unwrap_or_else(|_| "en".into());
    let state = PathBuf::from(env::var("CLAVIS_STATE_DIR").unwrap_or_else(|_| ".clavis".into()));
    let saved = state.join("offline.token");

    let app_key = var("CLAVIS_APP_KEY");
    let mut options = Options::new(
        &var("CLAVIS_BASE_URL"),
        &var("CLAVIS_APP_ID"),
        &[&app_key],
        default_device(None),
    );
    // The same key every run: sessions and offline tokens stay with this machine.
    options.device_key =
        Some(load_or_create_device_key(state.join("device.key")).expect("the device key file"));
    options.app_version = Some("1.0.0".into());
    let mut client = Client::new(options).expect("the app settings");

    let grant = match client
        .init()
        .and_then(|_| client.activate(&var("CLAVIS_LICENSE")))
    {
        Ok(grant) => Some(grant),
        Err(err) => {
            // No answer (network_error, timeout...): a token saved last time keeps the software working.
            let token = fs::read_to_string(&saved).unwrap_or_default();
            if !err.retryable() || token.is_empty() || client.verify_offline(Some(&token)).is_none()
            {
                fail(&err, &lang);
            }
            println!("Offline: using the license saved on this machine");
            None
        }
    };

    let Some(grant) = grant else {
        println!("OK k1 offline");
        return;
    };
    let until = grant.license.expires_at.as_deref().unwrap_or("forever");
    println!("License {} until {until}", grant.license.status);
    // Every few minutes while the software runs; sessions end after an hour without one.
    if let Err(err) = client.heartbeat() {
        fail(&err, &lang);
    }
    if let Some(token) = &client.offline_token {
        fs::write(&saved, token).expect("saving the offline token");
    }
    let _ = client.logout();
    println!("OK k1 {}", grant.license.status);
}

export CLAVIS_BASE_URL="<địa chỉ API>"
export CLAVIS_APP_ID="<App ID>"
export CLAVIS_APP_KEY="<khoá công khai>"
export CLAVIS_LICENSE="<key thử nghiệm>"
cargo run --release

Trên Windows, trong PowerShell:

$env:CLAVIS_BASE_URL = "<địa chỉ API>"
$env:CLAVIS_APP_ID = "<App ID>"
$env:CLAVIS_APP_KEY = "<khoá công khai>"
$env:CLAVIS_LICENSE = "<key thử nghiệm>"
cargo run --release

Dự án mẫu (nút Tải dự án mẫu (.zip) ở trang Kết nối phần mềm trên dashboard, sau khi chọn Rust; không có ở trang Tải về) chạy kịch bản này bằng ./run.sh <key> hoặc .\run.cmd <key>.

Mẫu in License active until <ngày>, rồi OK k1 active ở dòng cuối. Chạy lại trên cùng máy vẫn thành công và không tốn thêm suất: server nhận ra máy qua các định danh đã băm (Thiết bị, HWID và chuyển máy). Khoá thiết bị, dùng để ký yêu cầu, nằm trong thư mục .clavis dưới thư mục bạn chạy lệnh (hoặc trong CLAVIS_STATE_DIR). Container tạo mới cho mỗi lần chạy thì lần nào cũng giống một máy mới, xem Câu hỏi thường gặp.

4. Thấy trên dashboard

Tích hợp › Kết nối phần mềm: bước 4 chuyển sang Đã kết nối, kèm rust/1.0.0 và hệ điều hành của máy.
Phát hành & bản quyền › License: key chuyển từ Chưa dùng sang Đang dùng.
Người dùng cuối › Thiết bị & phiên: máy vừa chạy, cùng phiên nó vừa mở.

5. Xử lý lỗi

Mọi lần bị từ chối là một clavisauh::Error có ba thứ bạn cần:

err.code: mã trong bảng Mã lỗi, ví dụ invalid_credentials hay device_limit.
err.user_message("vi"): câu cho người dùng phần mềm của bạn, tiếng Việt hoặc "en", hiện thẳng được.
err.retryable(): true khi không nhận được câu trả lời (mất mạng, quá chậm, máy chủ bận); để một lúc rồi thử lại có thể thành công.

Khi err.verification là true, câu trả lời không mang đúng chữ ký của ứng dụng (mã unsigned_response, invalid_response_signature, unknown_key hoặc stale_response). Hãy coi đó như không có câu trả lời; thường là địa chỉ API hoặc khoá công khai trong phần mềm bị sai.

Khi phần mềm đang chạy, gửi heartbeat đều đặn để giữ phiên, khoảng mỗi 5 tới 30 phút: phiên hết sau 60 phút không có heartbeat.

// Every few minutes while the software runs; sessions end after an hour without one.
if let Err(err) = client.heartbeat() {
    fail(&err, &lang);
}

Lưu token offline mới nhất, để lần sau không có mạng vẫn mở được:

if let Some(token) = &client.offline_token {
    fs::write(&saved, token).expect("saving the offline token");
}

Mọi gói đều có token offline, mặc định dùng được 7 ngày; Premium tự chọn thời hạn, còn Chế độ chỉ online thì tắt hẳn. Xem License offline. Cần xem từng lượt gọi khi dò lỗi thì đặt options.debug = Some(Box::new(clavisauh::debug_stderr));: mỗi lượt gọi và kết quả được in ra stderr, key chỉ hiện bốn ký tự đầu và cuối, mật khẩu không bao giờ hiện.

6. Đóng gói và phát hành

Ghi địa chỉ API, App ID và khoá công khai vào mã hoặc vào file cấu hình đi cùng bản build. Máy khách không cần biến môi trường nào.
Đặt thư mục trạng thái (khoá thiết bị, token offline) ở nơi người dùng ghi được, riêng cho từng người dùng: %APPDATA%\TênPhầnMềm trên Windows, ~/Library/Application Support/TênPhầnMềm trên macOS, ~/.config/ten-phan-mem trên Linux. Đừng đặt trong thư mục cài đặt.
Đặt options.app_version đúng phiên bản bạn phát hành: server dùng nó để chặn bản quá cũ và báo có bản mới, xem Bản phát hành có ký và cập nhật.
cargo build --release cho một file chạy. CI của ClavisAUH build chéo mẫu Rust thành .exe từ Linux (target x86_64-pc-windows-gnu) và chạy chúng trên Windows.
Chạy thử bản build tới OK k1 active trên một máy sạch trước khi phát hành.
Trước khi bán, bật Đã phát hành công khai ở Tích hợp › Cài đặt ứng dụng. Mọi key TEST ngừng hoạt động, nên key thử nào lỡ lọt ra ngoài cũng không dùng được nữa.

Câu hỏi thường gặp

Phần mềm có cần mạng mỗi lần mở không? Kích hoạt và heartbeat cần mạng. Khi mất mạng, token đã lưu giữ phần mềm chạy tiếp, mặc định 7 ngày hoặc theo thời hạn chọn trên Premium, được kiểm ngay trên máy mà không cần server.

SDK có async không? Không: mỗi lượt gọi chặn tới khi có câu trả lời (ureq). Trong chương trình async, gọi nó trong spawn_blocking hoặc một luồng riêng.

Giới hạn tính năng theo gói license thế nào? client.has("ten_tinh_nang") cho biết license có quyền tính năng đó không; tạo quyền trong Gói license và quyền tính năng.

Khách cài lại hệ điều hành hay đổi máy thì sao? Cài lại trên cùng máy, server vẫn nhận ra máy nhờ dấu nhận diện phần cứng đã băm. Máy mới chiếm một suất mới; hết suất thì khách nhận device_limit, và bạn Đặt lại thiết bị trong trang License. Xem Thiết bị, HWID và chuyển máy.