This commit is contained in:
@ -0,0 +1,554 @@
|
||||
+++
|
||||
title = "Re-implementare un protocollo in Rust"
|
||||
summary = "Step 3: creare una libreria basata sul reverse engineering"
|
||||
date = "2024-08-01"
|
||||
|
||||
tags = ["Libreria", "Lettore di presenze", "TCP", "Rust"]
|
||||
categories = ["Progetti"]
|
||||
series = ["Lettore di presenze"]
|
||||
series_order = 3
|
||||
|
||||
draft = true
|
||||
+++
|
||||
|
||||
Nell'articolo precedente siamo riusciti a comprendere il significato dei
|
||||
pacchetti che vengono scambiati fra il client ufficiale ed il lettore di
|
||||
presenze.
|
||||
|
||||
Rimane solo una cosa da fare: **Riscrivere l'API in Rust!**
|
||||
|
||||
|
||||
|
||||
## Ricreare l'API ufficiale
|
||||
|
||||
Per iniziare [installiamo Rust](https://rust-lang.org/tools/install/) e creiamo
|
||||
un nuovo progetto tramite Cargo, il *package manager* di Rust, con il seguente
|
||||
comando:
|
||||
|
||||
```shell
|
||||
cargo new r701
|
||||
```
|
||||
|
||||
Possiamo poi aprire il progetto col nostro [text editor di
|
||||
fiducia](https://neovim.io/).
|
||||
|
||||
Dato che dobbiamo creare una libreria, andiamo a creare il file `src/lib.rs` e
|
||||
cominciamo a scrivere la struct che descriverà il nostro lettore:
|
||||
|
||||
```rust
|
||||
// src/lib.rs
|
||||
use std::io::Result;
|
||||
use std::net::{TcpStream, ToSocketAddrs};
|
||||
|
||||
#[derive(Debug)]
|
||||
pub struct R701 {
|
||||
tcp_stream: TcpStream,
|
||||
sequence_number: u16,
|
||||
}
|
||||
|
||||
impl R701 {
|
||||
pub fn connect(connection_info: impl ToSocketAddrs) -> Result<Self> {
|
||||
// Create a new R701 struct
|
||||
let mut new = Self {
|
||||
tcp_stream: TcpStream::connect(connection_info)?,
|
||||
sequence_number: 0,
|
||||
};
|
||||
|
||||
// Try to ping the endpoint
|
||||
new.ping()?;
|
||||
Ok(new)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
La nostra struct contiene due campi:
|
||||
|
||||
* `tcp_stream`, che contiene il descrittore della connessione al nostro
|
||||
lettore;
|
||||
* `sequence_number`, che memorizza il numero dell'ultimo pacchetto inviato.
|
||||
|
||||
Per provare se la nostra struct si connette correttamente possiamo modificare
|
||||
il file `src/main.rs` in modo che si connetta al nostro endpoint:
|
||||
|
||||
```rust
|
||||
// src/main.rs
|
||||
use r701::R701;
|
||||
|
||||
fn main() {
|
||||
let r701 = R701::connect("127.0.0.1:5005").unwrap();
|
||||
println!("{:?}", r701);
|
||||
}
|
||||
```
|
||||
|
||||
Se adesso eseguiamo `cargo run`...
|
||||
|
||||
|
||||
|
||||
**Urrà!** Il nostro client si connette con successo al server TCP!
|
||||
|
||||
Il prossimo step sarà quello di utilizzare la libreria
|
||||
[std::net::TcpStream](https://doc.rust-lang.org/std/net/struct.TcpStream.html)
|
||||
per andare ad eseguire le query che abbiamo ricavato dal nostro tentativo di
|
||||
[reverse
|
||||
engineering](/it/posts/2024/05/studying-a-communication-protocol)
|
||||
e ottenere ed elaborare le risposte.
|
||||
|
||||
Dato che [tutte le richieste hanno una struttura
|
||||
standard](/it/posts/2024/05/studying-a-communication-protocol#richieste),
|
||||
possiamo andare a creare un metodo che prende in input il payload di una
|
||||
richiesta (rappresentata da una slice di 12 `u8`) e ritorni un `Vec<u8>`
|
||||
contenente la risposta:
|
||||
|
||||
```rust { hl_lines=["6-23"] }
|
||||
// src/lib.rs
|
||||
|
||||
impl R701 {
|
||||
// ...
|
||||
|
||||
pub fn request(&mut self, payload: &[u8; 12]) -> Result<Vec<u8>> {
|
||||
// Create a blank request
|
||||
let mut request = [0x55, 0xaa, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
|
||||
|
||||
// Insert the payload
|
||||
request[2..14].clone_from_slice(payload);
|
||||
|
||||
// Insert the sequence number
|
||||
request[14..].clone_from_slice(&self.sequence_number.to_le_bytes());
|
||||
self.sequence_number += 1;
|
||||
|
||||
// Send the request
|
||||
self.tcp_stream.write_all(&request)?;
|
||||
|
||||
// Create a buffer and return the response
|
||||
let mut buffer = BufReader::new(&self.tcp_stream);
|
||||
Ok(buffer.fill_buf()?.to_vec())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Possiamo verificare che tutto funzioni correttamente inviando un [pacchetto di
|
||||
ping](/it/posts/2024/05/studying-a-communication-protocol#ping) e aspettandoci
|
||||
la risposta corretta:
|
||||
|
||||
```rust { hl_lines=["7-10"] }
|
||||
// src/main.rs
|
||||
use r701::R701;
|
||||
|
||||
fn main() {
|
||||
let r701 = R701::connect("127.0.0.1:5005").unwrap();
|
||||
|
||||
assert_eq!(
|
||||
r701.request(&[0x01, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]).unwrap(),
|
||||
[0xaa, 0x55, 0x01, 0x01, 0, 0, 0, 0, 0, 0],
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Potremmo addirittura rendere il ping un metodo a se stante nella nostra struct:
|
||||
|
||||
```rust { hl_lines=["6-16"] }
|
||||
// src/lib.rs
|
||||
|
||||
impl R701 {
|
||||
// ...
|
||||
|
||||
pub fn ping(&mut self) -> Result<()> {
|
||||
// Create a request with a payload of `01 80 00 00 00 00 00 00 00 00 00 00`
|
||||
let response = self.request(&[0x01, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])?;
|
||||
|
||||
// If the response is not `aa 55 01 01 00 00 00 00 00 00` then return an error
|
||||
if response != [0xaa, 0x55, 0x01, 0x01, 0, 0, 0, 0, 0, 0] {
|
||||
return Err(Error::new(InvalidData, "Malformed response"));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Con questo metodo possiamo andare a creare anche i metodi per ottenere il [nome
|
||||
di un
|
||||
dipendente](/it/posts/2024/05/studying-a-communication-protocol#nome-del-dipendente),
|
||||
il [numero totale di
|
||||
presenze](/it/posts/2024/05/studying-a-communication-protocol#numero-totale-di-presenze)
|
||||
ed un [blocco di
|
||||
presenze](/it/posts/2024/05/studying-a-communication-protocol#scaricamento-di-tutte-le-presenze).
|
||||
|
||||
Se siete interessati, tutto il codice sorgente è già presente su
|
||||
[nicolabelluti/r701](https://git.nicolabelluti.me/nicolabelluti/r701/src/branch/main/src/r701.rs).
|
||||
|
||||
## Estrarre le presenze tramite il trait TryInto
|
||||
|
||||
Una volta creato il metodo che ci permette di estrarre un blocco di presenze,
|
||||
bisogna trovare il modo idiomatico per trasformarlo da un array di byte a una
|
||||
struct che rappresenti una singola presenza.
|
||||
|
||||
Per iniziare facciamo un po' di *refactoring* rinominando `src/lib.rs` in
|
||||
`src/r701.rs` e creando un nuovo `src/lib.rs` contenente queste righe:
|
||||
|
||||
```rust
|
||||
// src/lib.rs
|
||||
mod r701;
|
||||
pub use r701::R701;
|
||||
```
|
||||
|
||||
In questo modo l'interfaccia esterna della nostra libreria non cambierà, però
|
||||
così facendo possiamo organizzare il nostro codice in diversi file.
|
||||
|
||||
Aggiungiamo il file `src/record.rs` e includiamolo in `src/lib.rs`
|
||||
|
||||
```rust { hl_lines=[3,6] }
|
||||
// src/lib.rs
|
||||
mod r701;
|
||||
mod record;
|
||||
|
||||
pub use r701::R701;
|
||||
pub use record::{Record, Clock};
|
||||
```
|
||||
|
||||
```rust
|
||||
// src/record.rs
|
||||
use chrono::{DateTime, Local, TimeZone};
|
||||
|
||||
pub enum Clock {
|
||||
FirstIn,
|
||||
FirstOut,
|
||||
SecondIn,
|
||||
SecondOut,
|
||||
}
|
||||
|
||||
pub struct Record {
|
||||
pub employee_id: u32,
|
||||
pub clock: Clock,
|
||||
pub datetime: DateTime<Local>,
|
||||
}
|
||||
```
|
||||
|
||||
Con questo codice abbiamo definito la struttura di una presenza che, come
|
||||
abbiamo detto nell'articolo precedente, è composta dall'ID del dipendente,
|
||||
dalla data e dall'ora alla quale è stata registrata e dallo stato (se è la
|
||||
prima entrata, la prima uscita, la seconda entrata o la seconda uscita).
|
||||
|
||||
Dato che [non vogliamo impazzire gestendo il
|
||||
tempo](https://www.youtube.com/watch?v=-5wpm-gesOY), andiamo ad importare il
|
||||
*crate* [chrono](https://crates.io/crates/chrono/) per la gestione delle date:
|
||||
|
||||
```shell
|
||||
cargo add chrono --no-default-features --features clock
|
||||
```
|
||||
|
||||
Per facilitare la conversione da un vettore di byte alla nostra struct `Record`
|
||||
possiamo implementare il trait
|
||||
[TryInto](https://doc.rust-lang.org/std/convert/trait.TryInto.html):
|
||||
|
||||
```rust
|
||||
// src/record.rs
|
||||
impl TryFrom<&[u8]> for Record {
|
||||
type Error = &'static str;
|
||||
|
||||
fn try_from(record_bytes: &[u8]) -> Result<Self, Self::Error> {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Il codice finito è disponibile
|
||||
[qua](https://git.nicolabelluti.me/nicolabelluti/r701/src/branch/main/src/record.rs#L32).
|
||||
|
||||
Possiamo testare se la conversione è corretta tramite un semplice test:
|
||||
|
||||
```rust
|
||||
// src/record.rs
|
||||
|
||||
// ...
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn valid_record_conversion() {
|
||||
let record_bytes: &[u8] = &[0x10, 0x23, 0x0b, 0x1d, 0x01, 0, 0, 0, 0xb2, 0x17, 0x01, 0];
|
||||
|
||||
assert_eq!(
|
||||
record_bytes.try_into(),
|
||||
Ok(Record {
|
||||
employee_id: 1,
|
||||
clock: Clock::FirstIn,
|
||||
datetime: Local.with_ymd_and_hms(1970, 1, 1, 0, 0, 0).single().unwrap(),
|
||||
})
|
||||
)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Unire il tutto tramite gli iteratori
|
||||
|
||||
Una volta trovato un modo per estrarre dei byte dal dispositivo ed un modo per
|
||||
convertirli in una struct, dobbiamo trovare il modo idiomatico per mettere
|
||||
insieme le due cose, ed è proprio qua che entrano in gioco gli iteratori.
|
||||
|
||||
Per implemetare il trait
|
||||
[Iterator](https://doc.rust-lang.org/std/iter/trait.Iterator.html) bisogna
|
||||
definire solo il metodo `next()` che, partendo dal primo elemento, ritorna
|
||||
l'elemento successivo.
|
||||
|
||||
Una volta definito questo metodo avremmo accesso a molti altri strumenti, come
|
||||
[map()](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.map),
|
||||
[filter()](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.filter),
|
||||
[fold()](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.fold) e,
|
||||
se andiamo ad importare il *crate*
|
||||
[itertools](https://crates.io/crates/itertools), anche
|
||||
[sorted()](https://docs.rs/itertools/0.12.1/itertools/trait.Itertools.html#method.sorted)
|
||||
e
|
||||
[into_group_map_by()](https://docs.rs/itertools/0.12.1/itertools/trait.Itertools.html#method.into_group_map_by),
|
||||
giusto per elencarne alcuni.
|
||||
|
||||
Come prima cosa andiamo a creare una nuova struct `RecordIterator` con un
|
||||
costruttore `from()` che ci permetta di generare un iteratore prendendo in
|
||||
input una *reference* mutabile ad una struct `R701`:
|
||||
|
||||
```rust { hl_lines=[4,8] }
|
||||
// src/lib.rs
|
||||
mod r701;
|
||||
mod record;
|
||||
mod record_iterator;
|
||||
|
||||
pub use r701::R701;
|
||||
pub use record::{Record, Clock};
|
||||
pub use record_iterator::RecordIterator;
|
||||
```
|
||||
|
||||
```rust
|
||||
// src/record_iterator.rs
|
||||
use crate::R701;
|
||||
use std::io::Result;
|
||||
|
||||
#[derive(Debug)]
|
||||
pub struct RecordIterator<'a> {
|
||||
r701: &'a mut R701,
|
||||
input_buffer: Vec<u8>,
|
||||
sequence_number: u16,
|
||||
total_records: u16,
|
||||
record_count: u16,
|
||||
}
|
||||
|
||||
impl<'a> RecordIterator<'a> {
|
||||
pub fn from(r701: &'a mut R701) -> Result<Self> {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Il metodo `from()` richiede al lettore il numero totale di timbrate ed il primo
|
||||
blocco di presenze , salvandoli rispettivamente nella variabile `total_records`
|
||||
e nel vettore `input_buffer`.
|
||||
|
||||
Il metodo `next()` del trait `Iterator` andrà poi a prendere i primi 12 byte
|
||||
dell'`input buffer` e li trasformerà in una struct `Record` tramite il trait
|
||||
`TryInto` che abbiamo implementato nel capitolo precedente.
|
||||
|
||||
Quando `input_buffer` è vuoto allora viene richiesto al lettore un'altro blocco
|
||||
di presenze, fino a che non vengono lette tutte.
|
||||
|
||||
Se siete interessati tutto il codice è già [disponibile su
|
||||
Git](https://git.nicolabelluti.me/nicolabelluti/r701/src/branch/main/src/record_iterator.rs).
|
||||
|
||||
```rust
|
||||
// src/record_iterator.rs
|
||||
|
||||
// ...
|
||||
|
||||
impl<'a> Iterator for RecordIterator<'a> {
|
||||
type Item = Record;
|
||||
|
||||
fn next(&mut self) -> Option<Self::Item> {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Giusto per completezza possiamo implementare un metodo `into_record_iter` nella
|
||||
struct `R701`, per semplificare l'utilizzo dell'iteratore:
|
||||
|
||||
```rust { hl_lines=[2,"9-11"] }
|
||||
// src/r701.rs
|
||||
use crate::RecordIterator;
|
||||
|
||||
// ...
|
||||
|
||||
impl R701 {
|
||||
// ...
|
||||
|
||||
pub fn into_record_iter(&mut self) -> Result<RecordIterator> {
|
||||
RecordIterator::from(self)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rendere il tutto *Blazingly Fast*
|
||||
|
||||
Come prima cosa andiamo a creare un main che crei un file con la stessa
|
||||
struttura del file `AGLog_001.txt` che abbiamo visto nel [primo
|
||||
capitolo](/it/posts/2024/04/reverse-engineering-an-attendance-reader/#dump-delle-registrazioni-tramite-usb)
|
||||
di questa serie:
|
||||
|
||||
```rust
|
||||
// src/main.rs
|
||||
use r701::R701;
|
||||
|
||||
fn main() {
|
||||
let mut r701 = R701::connect("127.0.0.1:5005").unwrap();
|
||||
|
||||
println!("No\tMchn\tEnNo\t\tName\t\tMode\tIOMd\tDateTime\t");
|
||||
r701.into_record_iter()
|
||||
.unwrap()
|
||||
.collect::<Vec<_>>()
|
||||
.iter()
|
||||
.enumerate()
|
||||
.for_each(|(id, record)| {
|
||||
let name = r701
|
||||
.get_name(record.employee_id)
|
||||
.unwrap()
|
||||
.unwrap_or(format!("user #{}", record.employee_id));
|
||||
|
||||
println!(
|
||||
"{:0>6}\t{}\t{:0>9}\t{: <10}\t{}\t{}\t{}",
|
||||
id + 1,
|
||||
1,
|
||||
record.employee_id,
|
||||
name,
|
||||
35,
|
||||
record.clock as u8,
|
||||
record.datetime.format("%Y/%m/%d %H:%M:%S"),
|
||||
);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
Già con questo `main()` riusciamo ad ottenere tutti i record in un po' meno di
|
||||
un minuto, che è la metà del tempo che impiega il [client closed source
|
||||
ufficiale](/it/posts/2024/05/studying-a-communication-protocol/#configurazione-del-client).
|
||||
|
||||
Certo, stiamo leggermente barando dato che il nostro client non riesce ad
|
||||
estrarre l'ID del registratore, la modalità di registrazione della presenza ed
|
||||
i secondi del campo `DateTime`, ma per il momento possiamo ignorarli dato che
|
||||
sono campi superflui.
|
||||
|
||||
### Memoizzare il nome dei dipendenti
|
||||
|
||||
Per velocizzare ancora di più le cose potremmo evitare di chiedere al tibratore
|
||||
il nome dei dipendente per ogni record.
|
||||
|
||||
Possiamo creare un `HashMap` di nomi e, per ogni record, verificare se il nome
|
||||
è già presente al suo interno. Se no, allora si può chiedere al timbratore il
|
||||
nome del dipendente per poi salvarlo all'interno dell `HashMap`.
|
||||
|
||||
In questo modo andiamo a ridurre il numero di richieste al minimo
|
||||
indispensabile.
|
||||
|
||||
```rust { hl_lines=[3,6,"16-20"] }
|
||||
// src/main.rs
|
||||
use r701::R701;
|
||||
use std::collections::HashMap;
|
||||
|
||||
fn main() {
|
||||
let mut names = HashMap::new();
|
||||
let mut r701 = R701::connect("127.0.0.1:5005").unwrap();
|
||||
|
||||
println!("No\tMchn\tEnNo\t\tName\t\tMode\tIOMd\tDateTime\t");
|
||||
r701.into_record_iter()
|
||||
.unwrap()
|
||||
.collect::<Vec<_>>()
|
||||
.iter()
|
||||
.enumerate()
|
||||
.for_each(|(id, record)| {
|
||||
let name = names.entry(record.employee_id).or_insert_with(|| {
|
||||
r701.get_name(record.employee_id)
|
||||
.unwrap()
|
||||
.unwrap_or(format!("user #{}", record.employee_id))
|
||||
});
|
||||
|
||||
// ...
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
Con questa semplice modifica passiamo da ottenere tutti i record in un minuto
|
||||
ad ottenerli in **un secondo**. Questo sì che è *blazingly fast*!
|
||||
|
||||
### Limitare la lettura delle presenze ad un certo arco temporale
|
||||
|
||||
Dato che mi interessano i dati dell'ultimo mese, possiamo utilizzare i metodi
|
||||
[take_while()](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.take_while)
|
||||
e
|
||||
[skip_while()](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.skip_while)
|
||||
per escludere tutti gli elementi precedenti allo scorso mese e per fermare
|
||||
l'iteratore una volta estratti tutti i record interessati:
|
||||
|
||||
```rust { hl_lines=[4,"7-8","16-17"] }
|
||||
// src/main.rs
|
||||
use r701::R701;
|
||||
use std::collections::HashMap;
|
||||
use chrono::{Local, TimeZone};
|
||||
|
||||
fn main() {
|
||||
let start = Local.with_ymd_and_hms(2024, 7, 1, 0, 0, 0).unwrap();
|
||||
let end = Local.with_ymd_and_hms(2024, 8, 1, 0, 0, 0).unwrap();
|
||||
let mut names = HashMap::new();
|
||||
|
||||
let mut r701 = R701::connect("127.0.0.1:5005").unwrap();
|
||||
|
||||
println!("No\tMchn\tEnNo\t\tName\t\tMode\tIOMd\tDateTime\t");
|
||||
r701.into_record_iter()
|
||||
.unwrap()
|
||||
.take_while(|record| record.datetime < end)
|
||||
.skip_while(|record| record.datetime < start)
|
||||
.collect::<Vec<_>>()
|
||||
.iter()
|
||||
.enumerate()
|
||||
.for_each(|(id, record)| {
|
||||
// ...
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
Questa modifica non migliora in alcun modo le performance, ma c'è un ultima
|
||||
miglioria molto semplice che possiamo applicare per questo specifico caso
|
||||
d'uso...
|
||||
|
||||
### Leggere le presenze al contrario
|
||||
|
||||
Al posto di iniziare dal primo record mai registrato ed escludere tutti i
|
||||
record fino ad arrivare al primo del mese interessato potremmo leggere i record
|
||||
al contrario, partendo da quello più recente ed andando verso a quello più
|
||||
datato.
|
||||
|
||||
Questa miglioria richiede [un po' di
|
||||
modifiche](https://git.nicolabelluti.me/nicolabelluti/r701/compare/f0ac5fe7..0dd05c0d#diff-44adb0ed617220e3fd4a4bbb2e361059ac47d9c4),
|
||||
ma ne vale la pena considerando che ci fa passare da un po' meno di un secondo
|
||||
a **0,2 secondi**!
|
||||
|
||||
```rust { hl_lines=["11-12",15] }
|
||||
// src/main.rs
|
||||
|
||||
// ...
|
||||
|
||||
fn main() {
|
||||
// ...
|
||||
|
||||
println!("No\tMchn\tEnNo\t\tName\t\tMode\tIOMd\tDateTime\t");
|
||||
r701.into_record_iter()
|
||||
.unwrap()
|
||||
.take_while(|record| record.datetime >= start)
|
||||
.skip_while(|record| record.datetime >= end)
|
||||
.collect::<Vec<_>>()
|
||||
.iter()
|
||||
.rev()
|
||||
.enumerate()
|
||||
.for_each(|(id, record)| {
|
||||
// ...
|
||||
});
|
||||
}
|
||||
``
|
||||
Reference in New Issue
Block a user