πΊπΏ uz-types
Rust loyihalari (ayniqsa O'zbekiston domeniga oid backend tizimlar) uchun qat'iy tiplangan (strongly typed), xavfsiz va qayta ishlatiladigan value object kutubxonasi.
Oddiy String o'rniga Passport, Pinfl, PhoneNumber kabi tiplardan foydalanasiz β qiymat tipga faqat validatsiyadan o'tib kiradi, keyin esa u bilan ishlash xavfsiz.
Bu README β kutubxonani qanday ishlatish bo'yicha foydalanuvchi qo'llanmasi.
Ichkarida u qanday va nega ishlashi, dizayn qarorlari hamda maintainer
retseptlari uchun docs/architecture.md ga qarang.
use *;
let passport = parse.unwrap;
assert_eq!; // trim + katta harf avtomatik
let phone = parse.unwrap;
assert_eq!; // ajratuvchilar tozalandi
let pinfl = parse_strict.unwrap;
assert_eq!; // rasmiy checksum + struktura tekshirildi
Mundarija
- Imkoniyatlar
- O'rnatish va feature'lar
- Tezkor boshlash
- Asosiy g'oya: ikki qatlamli validatsiya
- Tiplar
- Xatolar bilan ishlash
- serde integratsiyasi
- sqlx integratsiyasi
- Cheklovlar
- MSRV va semver
- Rivojlantirish
- Litsenziya
Imkoniyatlar
| Nima beradi | |
|---|---|
| Qat'iy tiplash | Passport, Pinfl, PhoneNumber, EmailAddress, BirthDate, Id<Tag>, NumId<Tag>, AccessToken, RefreshToken, ClientSecret |
| Yagona konstruktor yo'li | parse(), FromStr, TryFrom, serde Deserialize, sqlx Decode β hammasi bitta validatsiya yo'lidan o'tadi. Validatsiyani chetlab o'tib tip yaratib bo'lmaydi |
| Ikki qatlamli validatsiya | parse() β hech qachon o'zgarmaydigan struktura; parse_strict() β o'zgaruvchan qoidalar (operator kodlari ro'yxati, PINFL checksum) |
| Aniq xatolar | Har bir tipning o'z error enum'i (PassportError, PinflError, β¦); umumiy TypeError ? orqali avtomatik yig'iladi |
| Xavfsiz sirlar | Token tiplarida Display yo'q, Debug yashirilgan, taqqoslash constant-time; sirni faqat expose_secret() ochadi |
| Minimal allocation | String dan yaratishda qo'shimcha allocation yo'q (normalizatsiya in-place); &str dan β bitta |
| Opt-in integratsiyalar | serde, sqlx (Postgres/MySQL/SQLite), zeroize β faqat feature yoqilganda kompilyatsiya bo'ladi |
| Xavfsiz kod | #![deny(unsafe_code)], panic yo'llari yo'q (property-based testlar bilan qulflangan) |
O'rnatish va feature'lar
[]
= "0.22"
Yoki kerakli feature'lar bilan:
[]
= { = "0.22", = ["serde", "sqlx-postgres"] }
| Feature | Default | Nima yoqadi | Qo'shimcha dependency |
|---|---|---|---|
date |
β | BirthDate, DateFormat, Pinfl::birth_date() |
chrono |
id |
β | Id<Tag> (UUID), NumId<Tag, R> (BIGINT) β nomlarni o'zingiz berasiz |
uuid |
serde |
Serialize / Deserialize barcha tiplar uchun (sirlar β faqat Deserialize) |
serde |
|
sqlx |
Type / Encode / Decode β driver'ga bog'liq emas |
sqlx |
|
sqlx-postgres |
sqlx + PgHasArrayType (Vec<T>, = ANY($1)) |
sqlx/postgres |
|
zeroize |
Sir tiplari Drop da xotirani nolga to'ldiradi |
zeroize |
|
serialize-secrets |
Sir tiplari uchun Serialize (masalan, auth-servis token javobi) |
serde |
Qoida: tiplar default'da bor, integratsiyalar β siz tanlaysiz. Faqat Passport kerak bo'lgan servis chrono/uuid ni ham xohlamasa:
= { = "0.22", = false }
Tezkor boshlash
use *;
// ID nomlari sizniki: tag e'lon qiling, so'ng alias bering (pastda batafsil)
pub type JobId = ;
Asosiy g'oya: ikki qatlamli validatsiya
Har bir qoida ikki turdan biriga kiradi:
| Qatlam | Nima tekshiradi | O'zgaradimi? | Qayerda |
|---|---|---|---|
| Struktura | uzunlik, belgilar, prefiks, kalendar sanasi | Hech qachon | parse() |
| Registry / biznes | operator kodi ro'yxatda bormi, PINFL nazorat raqami to'g'rimi | Ha, vaqt-vaqti bilan | is_*() metodlar va parse_strict() |
Nega shunday? Agar operator kodlari ro'yxati parse() ichida bo'lsa, yangi kod ajratilganda yangi foydalanuvchilar rad etiladi, tuzatish uchun esa crate relizi va barcha servislarni deploy qilish kerak β DB yoki Kafka'dagi eski yozuvlar ham o'qilmay qoladi. Shuning uchun:
use *;
// Struktura o'tadi β 998 + 9 raqam. Bu qiymat DB'dan yoki event'dan kelgan bo'lishi mumkin.
let phone = parse.unwrap;
assert!;
// Registratsiya formasida qat'iylik kerak β parse_strict
assert_eq!;
Qisqa qoida: DB/Kafka/ichki chegara β parse(); foydalanuvchi kiritgan ma'lumot β parse_strict().
Tiplar
Passport
O'zbekiston pasporti yoki ID-kartasi seriyasi va raqami: 2 ta lotin harfi + 7 ta raqam.
use ;
let p = parse.unwrap;
assert_eq!; // trim, ichki bo'sh joy olib tashlandi, katta harf
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Faqat format tekshiriladi β seriya amaldagi ro'yxatga kiradimi, bu tekshirilmaydi (ZZ0000000 ham qabul qilinadi).
Pinfl (JShShIR)
14 raqamli shaxsiy identifikatsiya raqami. Struktura rasmiy hujjatga asoslangan (Vazirlar Mahkamasining 2022-yil 12-apreldagi 177-son qarori):
| Raqamlar | Ma'nosi |
|---|---|
| 1 | jins va asr: 1,2 β 1800-yillar; 3,4 β 1900-yillar; 5,6 β 2000-yillar (toq β erkak, juft β ayol) |
| 2β7 | tug'ilgan sana DDMMYY |
| 8β10 | tug'ilgan hudud kodi |
| 11β13 | tartib raqami |
| 14 | nazorat raqami: birinchi 13 raqam 7,3,1,7,3,1,β¦ vaznlar bilan ko'paytirilib qo'shiladi, mod 10 |
use ;
// parse β faqat struktura (14 raqam). DB'dan o'qish, event'lar uchun.
let p = parse.unwrap;
assert!;
assert_eq!;
assert_eq!;
assert_eq!; // (yil, oy, kun)
assert_eq!;
assert_eq!;
// parse_strict β struktura + checksum + jins/asr belgisi + sana strukturasi
assert!;
assert_eq!;
assert_eq!;
// `date` feature bilan: haqiqiy kalendar sanasi sifatida
let birth_date = p.birth_date.unwrap;
assert_eq!;
PhoneNumber
O'zbekiston telefon raqami. Ichkarida har doim 998 + 9 raqam (+ siz, 12 raqam).
use ;
// Bo'sh joy, `-`, `(`, `)` va boshidagi `+` β hammasi tozalanadi
for input in
let phone = parse.unwrap;
assert_eq!;
assert_eq!;
assert_eq!;
assert!; // 71 β Toshkent shahar kodi
assert!; // hudud kodlari oralig'ida (60..=79)
assert_eq!;
assert_eq!;
assert_eq!;
Ma'lum kodlar PhoneNumber::MOBILE_CODES (slice) va PhoneNumber::REGIONAL_CODES (60..=79) konstantalarida. Ro'yxat eskirsa ham parse() ishlayveradi β faqat is_known_operator() / parse_strict() ta'sirlanadi.
EmailAddress
local-part@domain.tld, lowercase saqlanadi. Faqat ASCII manzillar.
use ;
let e = parse.unwrap;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!; // TLD yo'q
assert_eq!; // bo'sh label
assert!;
Tekshiriladigan qoidalar: local-part bo'sh emas va 64 belgidan uzun emas, . bilan boshlanmaydi/tugamaydi, .. yo'q, faqat RFC 5322 ruxsat bergan belgilar; domain kamida ikki label, har label [a-z0-9-], - bilan boshlanmaydi/tugamaydi, TLD kamida 2 ta harf; umumiy uzunlik β€ 254.
BirthDate (feature date)
Tug'ilgan sana: MIN_YEAR (1800) dan keyin va kelajakda emas (UTC bo'yicha ertangi kungacha yon beriladi β UTC+14 gacha bo'lgan mintaqalar uchun).
MIN_YEAR β sanity floor, biznes qoidasi emas. 1800 tanlangani: PINFL 1-raqami 1/2 bo'lganda asr 1800 bo'ladi (Pinfl::century()), shuning uchun MIN_YEAR = 1900 da Pinfl::birth_date() bunday PINFL uchun har doim None qaytarardi. Yosh chegarasi (>= 18, <= 120 va h.k.) β ilova qatlamining ishi, age_at() bilan tekshiring.
use ;
use NaiveDate;
let d = parse.unwrap; // YYYY-MM-DD
let same = parse_with_format.unwrap;
assert_eq!;
assert_eq!;
assert_eq!;
// Deterministik (testlanadigan) variantlar β "bugun" tashqaridan beriladi
let today = from_ymd_opt.unwrap;
assert_eq!;
assert_eq!;
assert!;
assert_eq!;
age() va parse() tizim soatidan (UTC) foydalanadi; age_at(), parse_with_format_at(), from_naive_date_at() β deterministik. Kelajak tekshiruvi monoton: bir marta qabul qilingan sana keyinchalik hech qachon rad etilmaydi, shuning uchun saqlangan ma'lumotni qayta o'qish (replay) xavfsiz.
Id<Tag> va NumId<Tag> (feature id)
Crate tayyor ID nomlarini bermaydi. OrderId, SessionId, UserId β bular sizning domeningiz, crate'niki emas: nomni ham, ko'rinishni ham siz tanlaysiz. Crate faqat ikkita mexanizm beradi:
| Mexanizm | Postgres ustuni | Qachon |
|---|---|---|
Id<Tag> |
UUID |
yangi jadvallar β sxemani o'zingiz boshqarasiz |
NumId<Tag, R> |
BIGINT |
mavjud BIGINT ustunlar, eski tizim ID'lari |
Yaratish tartibi β 3 qadam
use ;
// Qadam 1 β TAG'LAR. Butun loyiha uchun bitta modulda.
// Qadam 2 β ALIAS. Ko'rinish (UUID yoki BIGINT) aynan shu yerda tanlanadi.
pub type OrderId = ; // UUID
pub type SessionId = ; // UUID
pub type LegacyInvoiceId = ; // BIGINT
// Qadam 3 β ISHLATISH.
let a = now_v7; // v7 β vaqt bo'yicha tartiblangan, DB primary key uchun
let b = new_v4; // v4 β tasodifiy, yaratilish vaqtini oshkor qilmaydi
assert_ne!;
assert_eq!;
assert_eq!;
// BIGINT ID β manfiy legacy qiymatlar ham qabul qilinadi
let inv = parse.unwrap;
assert_eq!;
assert_eq!; // raqam UUID emas
1-qadam haqida. enum {} β uninhabited: instansiya yaratib bo'lmaydi, faqat compile-time belgisi (runtime'da hajmi nol). Tag'ni ikki joyda e'lon qilmang β Id<a::Order> va Id<b::Order> bir-biriga to'g'ri kelmaydigan turli tiplar.
2-qadam haqida. Session'ni raqamli qilmoqchimisiz? Faqat shu qatorni o'zgartiring β NumId<tag::Session, i64>. Crate bu qarorni siz uchun qilmaydi.
Nima uchun shunday. SessionId, OrderId β domen nomlari. Agar crate ularni o'zi e'lon qilsa, (a) use uz_types::prelude::* sizning nomlaringiz bilan to'qnashadi, (b) ko'rinish (UUID) sizga majburlanadi. Shuning uchun 0.20.0 dan boshlab crate faqat mexanizmni beradi.
Tip xavfsizligi β asosiy foyda:
use Id;
type OrderId = ;
type SessionId = ;
let s = now_v7;
cancel; // β compile error: expected Id<tag::Order>, found Id<tag::Session>
Xususiyatlari
Id<Tag>β istalgan RFC 9562 UUID'ni qabul qiladi (hyphenated, simple, braced, urn). Versiya cheklovi kerak bo'lsaversion()bilan tekshiring; nil UUID (0000β¦) ham o'tadi β muhim bo'lsais_nil().Id<Tag>JSON'da har doim string,NumId<Tag, R>β har doim integer. DB'da mos ravishdaUUIDvaBIGINT.- Ikkala tip ham
Copy,Eq,Ord,Hash,Send + SyncβTagqanday bo'lishidan qat'i nazar. uuidre-export qilinmagan:Uuidbilan bevosita ishlasangiz (from_uuid,version) uni o'zCargo.tomlingizga qo'shing.- Konversiya sirti crate'dagi boshqa tiplar bilan bir xil:
parse(),FromStr,TryFrom<&str>,TryFrom<String>vaFrom<T> for String. Ya'nifn ingest<T: TryFrom<String>>(β¦)kabi generic kodId<Tag>,NumId<Tag, R>va string tiplarining hammasi bilan ishlaydi.
NumId ning ichki ko'rinishi: u64 yoki i64
DB'dagi BIGINT β bu i64. u64 esa kengroq, ya'ni type system va DB bir xil narsani va'da qilmaydi. Farq faqat runtime'da chiqadi, shuning uchun ko'rinish R parametri bilan tanlanadi (default u64 β mavjud kod o'zgarmaydi):
NumId<Tag> (u64) |
NumId<Tag, i64> |
|
|---|---|---|
| Diapazon | 0..=u64::MAX |
i64::MIN..=i64::MAX |
Encode β BIGINT |
> i64::MAX β IdError::NumberTooLarge |
xato yo'li yo'q |
Decode β BIGINT |
manfiy β IdError::NumberNegative |
xato yo'li yo'q |
| Manfiy legacy ID | β | β |
use ;
type LegacyOrderId = ;
// u64 repr: `new`/`parse` kengroq β xato faqat query paytida chiqardi.
let too_big = new;
assert!;
// ...shuning uchun chegarani INPUT tomonida qo'ying, query paytida emas:
assert!;
assert!;
// Ko'rinishlar orasida konversiya har doim tekshiriladi
assert_eq!;
DB bilan ishlaganda i64 ko'rinishi runtime xatolarining butun sinfini yo'q qiladi β legacy BIGINT ustunlar uchun shuni tanlang. u64 faqat qiymat haqiqatan ham manfiy bo'lmasligi domen fakti bo'lganda mantiqli.
Sir tiplari: AccessToken, RefreshToken, ClientSecret
Sir tiplari tasodifan oshkor bo'lmasligi uchun tip darajasida cheklangan:
| Sir tiplari | |
|---|---|
Display ({}, .to_string()) |
β compile error |
Debug ({:?}) |
AccessToken([REDACTED]) |
as_str(), AsRef<str>, into_inner() |
β |
| Qiymatga kirish | faqat expose_secret() |
== |
constant-time (subtle) |
| serde | Deserialize β
; Serialize faqat serialize-secrets feature'da |
| sqlx | β (token DB'da saqlanmasligi kerak) |
zeroize feature |
Drop da xotira tozalanadi |
use ;
let token = parse.unwrap;
assert_eq!; // logga tushmaydi
assert_eq!; // yagona ochiq yo'l
assert_eq!;
assert!;
MAX_TOKEN_LEN (8 KiB) β mantiqiy chegara, xotira DoS'idan himoya emas: String bu tekshiruvga kelguncha allaqachon ajratilgan bo'ladi. Body-limit HTTP qatlamida turishi kerak.
Xatolar bilan ishlash
Har bir parse() o'zining aniq error tipini qaytaradi. Umumiy TypeError β ? operatori orqali avtomatik yig'iladigan aggregate:
use ;
// Aniq tip β ikki holat uchun ikki qatorli match
match parse
// Application kodda `?` TypeError ga o'tadi
assert!;
Modulga xos leaf error tiplari (PassportError, PinflError va boshqalar)
std::error::Error, Copy, Eq va #[non_exhaustive]. Ularni yig'uvchi
TypeError ham std::error::Error, Clone, Eq va #[non_exhaustive], ammo
Copy emas; uning variantlari #[error(transparent)], ya'ni xabar ichki
xatonikidir.
serde integratsiyasi
features = ["serde"]. Har tip JSON'da bitta shaklga ega:
| Tip | JSON |
|---|---|
Passport, Pinfl, PhoneNumber, EmailAddress |
"AA1234567" (normalizatsiya qilingan string) |
BirthDate |
"1990-05-15" |
Id<Tag> |
"9b7e597e-893e-4e11-92cf-f4e7d4f923b1" (bincode/postcard'da 16 bayt) |
NumId<Tag, R> |
42 / -1 (faqat integer; "42" string qabul qilinmaydi) |
AccessToken va boshqa sirlar |
Deserialize β
; Serialize faqat serialize-secrets |
Deserializatsiya validatsiyadan o'tadi β noto'g'ri JSON Err beradi, #[derive(Deserialize)] kabi smart constructor chetlab o'tilmaydi:
#
serde dependency'si derive feature'siz ulanadi β proc-macro kompilyatsiyasi kerak emas.
sqlx integratsiyasi
features = ["sqlx-postgres"] (yoki faqat sqlx + o'zingizning driver'ingiz). Ustun tiplari:
| Tip | Postgres ustuni |
|---|---|
Passport, Pinfl, PhoneNumber, EmailAddress |
TEXT / VARCHAR |
BirthDate |
DATE |
Id<Tag> |
UUID |
NumId<Tag, R> |
BIGINT |
Decode ham parse() orqali o'tadi: DB'dagi buzuq yozuv try_get da xato beradi, jimgina ichkariga kirmaydi.
use *;
// query_as! da maxsus tip uchun ustun override sintaksisi: `ustun AS "ustun: Tip"`
let row = query_as!
.fetch_one
.await?;
// bind β Encode
query
.bind
.bind
.execute
.await?;
// Vec<T> β PgHasArrayType (sqlx-postgres)
let passports: = vec!;
query.bind;
Migratsiya eslatmasi: eski tizimdan kelgan DB'da parse() strukturasiga mos kelmaydigan yozuvlar (masalan, 13 raqamli PINFL) bo'lsa, ular SELECT da xato beradi β migratsiyadan oldin ma'lumotni tozalang. parse_strict darajasi (checksum) talab qilinmaydi.
Cheklovlar
| Tip | Cheklov |
|---|---|
Passport |
Faqat format. Seriya amaldagi ro'yxatga kiradimi β tekshirilmaydi. |
Pinfl |
parse() faqat 14 raqam. Checksum, jins/asr va sana β parse_strict() yoki query metodlar. Haqiqiy shaxsga tegishliligini faqat davlat xizmati (my.gov.uz va h.k.) tasdiqlaydi. |
PhoneNumber |
9 raqamli mahalliy shakl (90 123 45 67) qabul qilinmaydi β 998 bilan yuboring. MOBILE_CODES ro'yxati crate ichida; eskirsa parse() ta'sirlanmaydi, is_known_operator() / parse_strict() ta'sirlanadi. |
EmailAddress |
Faqat ASCII. IDN (unicode domenlar), quoted local-part ("a b"@x.com) va IP-literal (a@[1.2.3.4]) qabul qilinmaydi. Local-part ham lowercase qilinadi. |
BirthDate |
parse()/age() tizim soatiga (UTC) tayanadi; testlarda *_at() variantlarini ishlating. |
NumId<Tag> |
u64 repr: i64::MAX dan katta qiymat Encode da, DB'dagi manfiy qiymat Decode da xato beradi β ya'ni query paytida. Chegarani parse_db_safe()/try_new_db_safe() bilan input tomoniga qo'ying yoki NumId<Tag, i64> ishlating (u yerda xato yo'li umuman yo'q). 2^53 dan katta ID JSON orqali JS client'ga borsa aniqligini yo'qotadi. |
| Sir tiplari | zeroize β "best effort": String realloc/clone nusxalari va HTTP/serde buferlari tozalanmaydi. |
MSRV va semver
- MSRV: Rust 1.85 (edition 2024). MSRV ko'tarilishi minor reliz hisoblanadi.
sqlxvasqlx-postgresfeature'lari Rust 1.94+ talab qiladi (sqlx 0.9ning o'z MSRV'i). Cargo per-feature MSRV'ni qo'llab-quvvatlamaydi, shuning uchunCargo.tomldagirust-versioneng past umumiy qiymat β 1.85. CI ikkala polni alohida tekshiradi.- MSRV kutubxona iste'molchisi uchun: dev-dependency'lar (
criterionβ 1.86) hisobga olinmaydi, chunki downstream ularni yuklamaydi.cargo benchuchun 1.86+ kerak. - Barcha public enum'lar
#[non_exhaustive]βmatchda_tarmog'ini qoldiring. - Public konstantalar slice/
RangeInclusiveβ yangi kod qo'shilishi breaking emas. - Feature nomlari 1.0 gacha qulflangan:
date,id,serde,sqlx,sqlx-postgres,zeroize,serialize-secrets. - Breaking o'zgarishlar CHANGELOG da migratsiya jadvali bilan beriladi.
Rivojlantirish
Talab: just, cargo-hack, cargo-audit, cargo-machete, cargo-semver-checks.
just ci β CI'dagi job'larning aynan o'zi; publish-check unga tayanadi. Alohida qismlar:
| Recipe | Nima qiladi |
|---|---|
just features |
cargo hack β powerset (90 kombinatsiya) + har feature alohida test |
just msrv |
1.85 (sqlx'siz) va 1.94 (--all-features) pollari |
just semver |
tanlangan versiya bump'i o'zgarishlarni qoplaydimi |
just semver-detail |
aynan nima breaking ekanini ko'rsatadi β CHANGELOG yozishdan oldin |
just audit |
cargo audit (CVE) + cargo machete (ishlatilmagan dep) β tarmoq kerak |
just bench |
criterion benchmark (benches/parse.rs) β Rust 1.86+ kerak |
just check ataylab tarmoqsiz va tez; audit va semver ci da turadi.
Justfile RUSTFLAGS=-D warnings ni CI bilan bir xil qilib eksport qiladi β shuning
uchun just test va oddiy cargo test orasida almashganda qayta build bo'ladi.
Testlar: unit (modul ichida) + integration (tests/serde.rs, tests/sqlx_bounds.rs,
tests/compile_fail.rs) + property-based. tests/props.rs to'rtta string_newtype!
tipini \\PC{0,64} generatorida panic qilmaslik va muvaffaqiyatli parsening
idempotentligi bo'yicha tekshiradi. tests/sqlx_bounds.rs SQLx trait'larini
compile-time'da qulflaydi β jonli DB talab qilinmaydi va Postgres integration
testi hozircha yo'q.
README src/lib.rs orqali crate hujjatiga date va id feature'lari yoqilganda
qo'shiladi. cargo test --all-features --doc oddiy rust bloklarini bajaradi va
rust,compile_fail blokining kompilyatsiya bo'lmasligini tekshiradi. SQLx bo'limidagi
rust,ignore blok esa pool va iste'molchi tiplari kontekstini ko'rsatadigan namuna:
u doctest sifatida kompilyatsiya qilinmaydi.
Litsenziya
MIT yoki Apache-2.0 β o'zingizga qulayini tanlang.