sjgandClaude Opus 5
ee185b98bc
Phase 5 of the logbook: the exchange, the entry sponsors take, and the confirmations an award counts. Contest fields go on the contact — the contest, the serials both ways as numbers and as words, and the zones — because an exchange is not always a number: a zone, a section or a name goes in as written. The serial sent and the contest stay between contacts, since they belong to the session and not to the contact just logged, and the serial counts on by itself rather than being retyped forty times an hour. Cabrillo 3.0 is written because ADIF cannot do this job: sponsors take Cabrillo and reject everything else. Its shape is not ADIF's either — the frequency is kilohertz below 30 MHz and a band designator above it, the modes are CW, PH, FM, RY and DG, and the contacts go oldest first, as a contest log is read. The header cannot be derived from a log — how many operators, how much power, what the score is claimed to be — so it comes from the operator, with single-op, low power, all bands and mixed behind it. QSL, LoTW and eQSL states are held as ADIF's single letters, and anything else is refused rather than written: a log that grew states of its own would be one no other program could read. A contact is confirmed when any one of the three says so — an award wants a card or an electronic match, not one of each, and counting them separately would tell the operator they were short of what they have. The bands report counts contacts, distinct stations and confirmations per band, ordered by wavelength as a band plan reads. Closes #54 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SyX26FCpMQxiBoC7r5K1A7 Signed-off-by: Stan Grams <sjg@haxx.space>
511 lines
18 KiB
Rust
511 lines
18 KiB
Rust
// SPDX-FileCopyrightText: 2026 Stan Grams <sjg@haxx.space>
|
|
//
|
|
// SPDX-License-Identifier: GPL-2.0-or-later
|
|
|
|
//! The station logbook: contacts, the file they live in, and ADIF in and out.
|
|
//!
|
|
//! One log per station rather than one per rig. Awards and uploads count the
|
|
//! callsign, not the radio — a station worked on the second rig is still worked
|
|
//! — so the rig is recorded on the contact instead of dividing the log by it.
|
|
//! Where a rig stands does follow the contact, though: `my_gridsquare` comes
|
|
//! from the rig that made it, because rigs can be in different places.
|
|
|
|
pub mod adif;
|
|
pub mod cabrillo;
|
|
pub mod dedupe;
|
|
pub mod qso;
|
|
pub mod store;
|
|
|
|
use std::path::PathBuf;
|
|
use std::sync::{Arc, Mutex};
|
|
|
|
use chrono::{DateTime, Utc};
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
pub use cabrillo::{write_cabrillo, CabrilloHeader};
|
|
pub use dedupe::{worked_before, DuplicateIndex, MATCH_WINDOW_MINUTES};
|
|
pub use qso::Qso;
|
|
pub use store::LogStore;
|
|
|
|
/// A fresh contact identity.
|
|
pub fn new_id() -> String {
|
|
uuid::Uuid::new_v4().to_string()
|
|
}
|
|
|
|
/// Where the log lives when the configuration does not say.
|
|
///
|
|
/// The data directory, not the config directory the bookmarks use and not the
|
|
/// cache directory the decode logs use: a log is neither a setting nor
|
|
/// disposable, and cache directories get swept by cleaners.
|
|
pub fn default_log_path() -> PathBuf {
|
|
dirs::data_dir()
|
|
.map(|dir| dir.join("trx-rs").join("logbook.jsonl"))
|
|
.unwrap_or_else(|| PathBuf::from("logbook.jsonl"))
|
|
}
|
|
|
|
/// What a filtered read asks for.
|
|
#[derive(Debug, Default, Clone, Deserialize)]
|
|
pub struct LogQuery {
|
|
/// Substring of the callsign, case-insensitive.
|
|
#[serde(default)]
|
|
pub call: Option<String>,
|
|
/// Only contacts in this contest.
|
|
#[serde(default)]
|
|
pub contest: Option<String>,
|
|
/// Only contacts the other station has confirmed, or only those they have
|
|
/// not.
|
|
#[serde(default)]
|
|
pub confirmed: Option<bool>,
|
|
#[serde(default)]
|
|
pub band: Option<String>,
|
|
#[serde(default)]
|
|
pub mode: Option<String>,
|
|
/// Inclusive bounds on the contact's time.
|
|
#[serde(default)]
|
|
pub from: Option<DateTime<Utc>>,
|
|
#[serde(default)]
|
|
pub to: Option<DateTime<Utc>>,
|
|
#[serde(default)]
|
|
pub limit: Option<usize>,
|
|
#[serde(default)]
|
|
pub offset: Option<usize>,
|
|
}
|
|
|
|
/// One band's worth of the log.
|
|
#[derive(Debug, Clone, Serialize)]
|
|
pub struct BandStatistics {
|
|
pub band: String,
|
|
pub contacts: usize,
|
|
/// Distinct callsigns, which is the number an award counts.
|
|
pub stations: usize,
|
|
pub confirmed: usize,
|
|
}
|
|
|
|
/// What an import did.
|
|
#[derive(Debug, Default, Clone, Serialize)]
|
|
pub struct ImportOutcome {
|
|
pub added: usize,
|
|
/// Already held, by callsign, band, mode and the two-minute window.
|
|
pub duplicate: usize,
|
|
/// Records that could not be read as contacts, with the reason.
|
|
pub rejected: Vec<String>,
|
|
}
|
|
|
|
/// The logbook, shared by whoever serves it.
|
|
#[derive(Clone)]
|
|
pub struct Logbook {
|
|
store: Arc<Mutex<LogStore>>,
|
|
}
|
|
|
|
impl Logbook {
|
|
pub fn open(path: &std::path::Path) -> std::io::Result<Self> {
|
|
Ok(Self {
|
|
store: Arc::new(Mutex::new(LogStore::open(path)?)),
|
|
})
|
|
}
|
|
|
|
fn with_store<T>(&self, f: impl FnOnce(&mut LogStore) -> T) -> T {
|
|
// A poisoned lock means a panic while holding it, not a corrupt log --
|
|
// the file is on disk either way -- so carry on with what is there.
|
|
let mut store = self.store.lock().unwrap_or_else(|e| e.into_inner());
|
|
f(&mut store)
|
|
}
|
|
|
|
pub fn path(&self) -> PathBuf {
|
|
self.with_store(|store| store.path().to_path_buf())
|
|
}
|
|
|
|
pub fn count(&self) -> usize {
|
|
self.with_store(|store| store.len())
|
|
}
|
|
|
|
/// Contacts matching `query`, newest first.
|
|
pub fn query(&self, query: &LogQuery) -> Vec<Qso> {
|
|
self.with_store(|store| {
|
|
let call = query.call.as_deref().map(str::to_uppercase);
|
|
let band = query.band.as_deref().map(str::to_lowercase);
|
|
let mode = query.mode.as_deref().map(str::to_uppercase);
|
|
let contest = query.contest.clone();
|
|
let matching: Vec<Qso> = store
|
|
.all()
|
|
.into_iter()
|
|
.filter(|qso| {
|
|
call.as_ref().is_none_or(|c| qso.call.contains(c.as_str()))
|
|
&& band
|
|
.as_ref()
|
|
.is_none_or(|b| qso.band().is_some_and(|found| found == b))
|
|
&& mode.as_ref().is_none_or(|m| qso.mode == *m)
|
|
&& query.from.is_none_or(|from| qso.started_at >= from)
|
|
&& query.to.is_none_or(|to| qso.started_at <= to)
|
|
&& contest.as_ref().is_none_or(|wanted| {
|
|
qso.contest_id
|
|
.as_deref()
|
|
.is_some_and(|held| held.eq_ignore_ascii_case(wanted))
|
|
})
|
|
&& query
|
|
.confirmed
|
|
.is_none_or(|wanted| qso.is_confirmed() == wanted)
|
|
})
|
|
.collect();
|
|
let offset = query.offset.unwrap_or(0).min(matching.len());
|
|
let end = query
|
|
.limit
|
|
.map_or(matching.len(), |limit| (offset + limit).min(matching.len()));
|
|
matching[offset..end].to_vec()
|
|
})
|
|
}
|
|
|
|
pub fn get(&self, id: &str) -> Option<Qso> {
|
|
self.with_store(|store| store.get(id).cloned())
|
|
}
|
|
|
|
/// Add a contact, or replace one with the same id.
|
|
pub fn put(&self, qso: Qso) -> std::io::Result<Qso> {
|
|
self.with_store(|store| store.put(qso.clone()))?;
|
|
Ok(qso)
|
|
}
|
|
|
|
pub fn delete(&self, id: &str) -> std::io::Result<bool> {
|
|
self.with_store(|store| store.delete(id))
|
|
}
|
|
|
|
/// Which bands and modes a callsign has been worked on.
|
|
pub fn worked_before(&self, call: &str) -> Vec<(String, String)> {
|
|
self.with_store(|store| dedupe::worked_before(&store.all(), call))
|
|
}
|
|
|
|
/// Export as Cabrillo, for submitting a contest entry.
|
|
pub fn export_cabrillo(&self, query: &LogQuery, header: &CabrilloHeader) -> String {
|
|
cabrillo::write_cabrillo(&self.query(query), header)
|
|
}
|
|
|
|
/// What has been worked, and what has been confirmed, band by band.
|
|
///
|
|
/// One confirmation counts wherever it came from: an award wants a card or
|
|
/// an electronic match, not one of each.
|
|
pub fn band_statistics(&self) -> Vec<BandStatistics> {
|
|
self.with_store(|store| {
|
|
let mut by_band: std::collections::HashMap<String, BandStatistics> =
|
|
std::collections::HashMap::new();
|
|
let mut stations: std::collections::HashMap<String, std::collections::HashSet<String>> =
|
|
std::collections::HashMap::new();
|
|
for qso in store.all() {
|
|
let band = qso.band().unwrap_or("other").to_string();
|
|
let entry = by_band
|
|
.entry(band.clone())
|
|
.or_insert_with(|| BandStatistics {
|
|
band: band.clone(),
|
|
contacts: 0,
|
|
stations: 0,
|
|
confirmed: 0,
|
|
});
|
|
entry.contacts += 1;
|
|
if qso.is_confirmed() {
|
|
entry.confirmed += 1;
|
|
}
|
|
stations.entry(band).or_default().insert(qso.call.clone());
|
|
}
|
|
let mut all: Vec<BandStatistics> = by_band
|
|
.into_values()
|
|
.map(|mut entry| {
|
|
entry.stations = stations
|
|
.get(&entry.band)
|
|
.map_or(0, std::collections::HashSet::len);
|
|
entry
|
|
})
|
|
.collect();
|
|
// Ordered by wavelength, longest first, as a band plan reads.
|
|
all.sort_by_key(|entry| qso::band_order(&entry.band));
|
|
all
|
|
})
|
|
}
|
|
|
|
/// Export as ADIF, honouring the same filters as a read.
|
|
pub fn export_adi(&self, query: &LogQuery, program_version: &str) -> String {
|
|
adif::write_adi(&self.query(query), program_version)
|
|
}
|
|
|
|
/// Import an ADIF file, skipping contacts already held.
|
|
pub fn import_adi(&self, input: &[u8]) -> std::io::Result<ImportOutcome> {
|
|
let report = adif::parse_adi(input);
|
|
let mut outcome = ImportOutcome {
|
|
rejected: report.rejected,
|
|
..ImportOutcome::default()
|
|
};
|
|
self.with_store(|store| {
|
|
let mut index = DuplicateIndex::build(&store.all());
|
|
let mut fresh = Vec::new();
|
|
for qso in report.qsos {
|
|
if index.contains(&qso) {
|
|
outcome.duplicate += 1;
|
|
continue;
|
|
}
|
|
index.insert(&qso);
|
|
fresh.push(qso);
|
|
}
|
|
outcome.added = fresh.len();
|
|
store.put_all(fresh)
|
|
})?;
|
|
Ok(outcome)
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
use crate::qso::parse_adif_datetime;
|
|
|
|
fn new_book() -> (tempfile::TempDir, Logbook) {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let book = Logbook::open(&dir.path().join("logbook.jsonl")).expect("open");
|
|
(dir, book)
|
|
}
|
|
|
|
fn qso(call: &str, hz: u64, mode: &str, time: &str) -> Qso {
|
|
Qso::new(
|
|
new_id(),
|
|
parse_adif_datetime("20260807", Some(time)).expect("time"),
|
|
call,
|
|
hz,
|
|
mode,
|
|
)
|
|
}
|
|
|
|
#[test]
|
|
fn a_log_answers_the_filters_it_is_asked() {
|
|
let (_dir, book) = new_book();
|
|
book.put(qso("SP1AA", 14_074_000, "FT8", "120000"))
|
|
.expect("put");
|
|
book.put(qso("SP2BB", 7_030_000, "CW", "130000"))
|
|
.expect("put");
|
|
book.put(qso("DL3CC", 14_200_000, "SSB", "140000"))
|
|
.expect("put");
|
|
|
|
assert_eq!(book.count(), 3);
|
|
assert_eq!(book.query(&LogQuery::default()).len(), 3);
|
|
// Newest first.
|
|
assert_eq!(book.query(&LogQuery::default())[0].call, "DL3CC");
|
|
|
|
let by_band = LogQuery {
|
|
band: Some("20m".into()),
|
|
..LogQuery::default()
|
|
};
|
|
assert_eq!(book.query(&by_band).len(), 2);
|
|
|
|
let by_call = LogQuery {
|
|
call: Some("sp".into()),
|
|
..LogQuery::default()
|
|
};
|
|
assert_eq!(book.query(&by_call).len(), 2);
|
|
|
|
let by_mode = LogQuery {
|
|
mode: Some("cw".into()),
|
|
..LogQuery::default()
|
|
};
|
|
assert_eq!(book.query(&by_mode)[0].call, "SP2BB");
|
|
|
|
let paged = LogQuery {
|
|
limit: Some(1),
|
|
offset: Some(1),
|
|
..LogQuery::default()
|
|
};
|
|
assert_eq!(book.query(&paged).len(), 1);
|
|
// Newest first, so offset 1 is the middle contact.
|
|
assert_eq!(book.query(&paged)[0].call, "SP2BB");
|
|
}
|
|
|
|
#[test]
|
|
fn an_import_skips_what_is_already_held_and_says_so() {
|
|
let (_dir, book) = new_book();
|
|
book.put(qso("SP1AA", 14_074_000, "FT8", "120000"))
|
|
.expect("put");
|
|
|
|
let file = concat!(
|
|
// the one already held, a minute out, as another logger stamped it
|
|
"<call:5>SP1AA<qso_date:8>20260807<time_on:6>120100<freq:6>14.074<mode:3>FT8<eor>\n",
|
|
// a new one
|
|
"<call:5>DL2XY<qso_date:8>20260807<time_on:6>121500<freq:6>14.074<mode:3>FT8<eor>\n",
|
|
// and something that is not a contact
|
|
"<call:5>NODAT<eor>\n",
|
|
);
|
|
let outcome = book.import_adi(file.as_bytes()).expect("import");
|
|
assert_eq!(outcome.added, 1);
|
|
assert_eq!(outcome.duplicate, 1);
|
|
assert_eq!(outcome.rejected.len(), 1);
|
|
assert_eq!(book.count(), 2);
|
|
|
|
// And importing the same file again adds nothing.
|
|
let again = book.import_adi(file.as_bytes()).expect("import again");
|
|
assert_eq!(again.added, 0);
|
|
assert_eq!(again.duplicate, 2);
|
|
assert_eq!(book.count(), 2);
|
|
}
|
|
|
|
#[test]
|
|
fn an_export_can_be_imported_into_an_empty_log() {
|
|
let (_dir, book) = new_book();
|
|
book.put(qso("SP1AA", 14_074_000, "FT8", "120000"))
|
|
.expect("put");
|
|
book.put(qso("DL3CC", 14_200_000, "SSB", "140000"))
|
|
.expect("put");
|
|
let exported = book.export_adi(&LogQuery::default(), "0.1.0");
|
|
|
|
let (_other_dir, other) = new_book();
|
|
let outcome = other.import_adi(exported.as_bytes()).expect("import");
|
|
assert_eq!(outcome.added, 2);
|
|
assert_eq!(other.count(), 2);
|
|
assert_eq!(other.query(&LogQuery::default())[0].call, "DL3CC");
|
|
}
|
|
|
|
#[test]
|
|
fn worked_before_reads_through_the_log() {
|
|
let (_dir, book) = new_book();
|
|
book.put(qso("SP1AA", 14_074_000, "FT8", "120000"))
|
|
.expect("put");
|
|
book.put(qso("SP1AA", 7_030_000, "CW", "130000"))
|
|
.expect("put");
|
|
assert_eq!(book.worked_before("sp1aa").len(), 2);
|
|
assert!(book.worked_before("SP9ZZ").is_empty());
|
|
}
|
|
|
|
#[test]
|
|
fn statistics_count_stations_and_confirmations_band_by_band() {
|
|
let (_dir, book) = new_book();
|
|
let mut first = qso("SP1AA", 14_074_000, "FT8", "120000");
|
|
first.lotw_qsl_rcvd = Some("Y".into());
|
|
book.put(first).expect("put");
|
|
// The same station again on the same band: one station, two contacts.
|
|
book.put(qso("SP1AA", 14_100_000, "SSB", "121000"))
|
|
.expect("put");
|
|
let mut third = qso("DL2BB", 7_030_000, "CW", "130000");
|
|
third.qsl_rcvd = Some("Y".into());
|
|
book.put(third).expect("put");
|
|
book.put(qso("OZ3CC", 7_040_000, "CW", "131000"))
|
|
.expect("put");
|
|
|
|
let stats = book.band_statistics();
|
|
// Longest wavelength first, as a band plan reads.
|
|
assert_eq!(
|
|
stats.iter().map(|s| s.band.as_str()).collect::<Vec<_>>(),
|
|
vec!["40m", "20m"]
|
|
);
|
|
let forty = &stats[0];
|
|
assert_eq!((forty.contacts, forty.stations, forty.confirmed), (2, 2, 1));
|
|
let twenty = &stats[1];
|
|
assert_eq!(
|
|
(twenty.contacts, twenty.stations, twenty.confirmed),
|
|
(2, 1, 1)
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_contest_entry_holds_only_that_contest() {
|
|
let (_dir, book) = new_book();
|
|
for (call, contest, serial) in [
|
|
("SP1AA", Some("CQ-WW-SSB"), 1),
|
|
("DL2BB", Some("CQ-WW-SSB"), 2),
|
|
("OZ3CC", None, 0),
|
|
] {
|
|
let mut entry = qso(call, 14_200_000, "SSB", "120000");
|
|
entry.contest_id = contest.map(str::to_string);
|
|
entry.stx = Some(serial);
|
|
entry.station_callsign = Some("SP0TRX".into());
|
|
entry.rst_sent = Some("59".into());
|
|
entry.rst_rcvd = Some("59".into());
|
|
book.put(entry).expect("put");
|
|
}
|
|
let query = LogQuery {
|
|
contest: Some("cq-ww-ssb".into()),
|
|
..LogQuery::default()
|
|
};
|
|
assert_eq!(
|
|
book.query(&query).len(),
|
|
2,
|
|
"the contest filter is case-sensitive"
|
|
);
|
|
|
|
let text = book.export_cabrillo(
|
|
&query,
|
|
&CabrilloHeader {
|
|
contest: Some("CQ-WW-SSB".into()),
|
|
callsign: Some("SP0TRX".into()),
|
|
..CabrilloHeader::default()
|
|
},
|
|
);
|
|
let lines: Vec<&str> = text
|
|
.lines()
|
|
.filter(|line| line.starts_with("QSO:"))
|
|
.collect();
|
|
assert_eq!(lines.len(), 2, "{text}");
|
|
assert!(
|
|
!text.contains("OZ3CC"),
|
|
"a contact outside the contest was submitted"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn confirmations_come_from_whichever_bureau_answered() {
|
|
let (_dir, book) = new_book();
|
|
let mut card = qso("SP1AA", 14_074_000, "FT8", "120000");
|
|
card.qsl_rcvd = Some("Y".into());
|
|
let mut lotw = qso("DL2BB", 14_074_000, "FT8", "121000");
|
|
lotw.lotw_qsl_rcvd = Some("Y".into());
|
|
let mut requested = qso("OZ3CC", 14_074_000, "FT8", "122000");
|
|
requested.qsl_rcvd = Some("R".into());
|
|
for entry in [card, lotw, requested] {
|
|
book.put(entry).expect("put");
|
|
}
|
|
let confirmed = LogQuery {
|
|
confirmed: Some(true),
|
|
..LogQuery::default()
|
|
};
|
|
let calls: Vec<String> = book.query(&confirmed).into_iter().map(|q| q.call).collect();
|
|
assert_eq!(calls.len(), 2, "{calls:?}");
|
|
assert!(calls.contains(&"SP1AA".to_string()) && calls.contains(&"DL2BB".to_string()));
|
|
// Requested is not confirmed.
|
|
let outstanding = LogQuery {
|
|
confirmed: Some(false),
|
|
..LogQuery::default()
|
|
};
|
|
assert_eq!(book.query(&outstanding)[0].call, "OZ3CC");
|
|
}
|
|
|
|
#[test]
|
|
fn the_contest_and_qsl_fields_survive_a_trip_through_adif() {
|
|
let (_dir, book) = new_book();
|
|
let mut entry = qso("SP1AA", 14_200_000, "SSB", "120000");
|
|
entry.contest_id = Some("CQ-WW-SSB".into());
|
|
entry.stx = Some(7);
|
|
entry.srx_string = Some("BAVARIA".into());
|
|
entry.cqz = Some(15);
|
|
entry.qsl_sent = Some("Y".into());
|
|
entry.lotw_qsl_rcvd = Some("Y".into());
|
|
book.put(entry).expect("put");
|
|
|
|
let exported = book.export_adi(&LogQuery::default(), "0.1.0");
|
|
let (_other_dir, other) = new_book();
|
|
other.import_adi(exported.as_bytes()).expect("import");
|
|
let back = &other.query(&LogQuery::default())[0];
|
|
assert_eq!(back.contest_id.as_deref(), Some("CQ-WW-SSB"));
|
|
assert_eq!(back.stx, Some(7));
|
|
assert_eq!(back.srx_string.as_deref(), Some("BAVARIA"));
|
|
assert_eq!(back.cqz, Some(15));
|
|
assert_eq!(back.qsl_sent.as_deref(), Some("Y"));
|
|
assert!(back.is_confirmed());
|
|
}
|
|
|
|
#[test]
|
|
fn a_contact_can_be_changed_and_forgotten() {
|
|
let (_dir, book) = new_book();
|
|
let mut entry = qso("SP1AA", 14_074_000, "FT8", "120000");
|
|
let id = entry.id.clone();
|
|
book.put(entry.clone()).expect("put");
|
|
entry.rst_rcvd = Some("-11".into());
|
|
book.put(entry).expect("edit");
|
|
assert_eq!(book.get(&id).and_then(|q| q.rst_rcvd), Some("-11".into()));
|
|
assert!(book.delete(&id).expect("delete"));
|
|
assert!(book.get(&id).is_none());
|
|
assert_eq!(book.count(), 0);
|
|
}
|
|
}
|