Nicola Belluti
00133fc217
All checks were successful
Build and Publish / build (push) Successful in 2m5s
555 lines
16 KiB
Markdown
555 lines
16 KiB
Markdown
+++
|
|
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
|
|
+++
|
|
|
|
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).
|
|
|
|
{{< gitea server="https://git.nicolabelluti.me" repo="nicolabelluti/r701" >}}
|
|
|
|
## 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)| {
|
|
// ...
|
|
});
|
|
}
|
|
``
|