#![forbid(unsafe_code)]
#![warn(missing_docs)]
mod admin;
mod codec;
mod general;
mod project;
#[cfg(feature = "qr")]
mod qr;
pub use admin::Admin;
pub use codec::{decode, encode, encode_json, Error};
pub use general::{
Autosend, BasemapSource, ConstraintBehavior, FontSize, FormUpdateMode, General, GuidanceHint,
ImageSize, Navigation, PeriodicCheck, Theme,
};
pub use project::Project;
#[cfg(feature = "qr")]
pub use qr::{render_svg, QrOptions};
#[cfg(feature = "qr")]
pub use qrcode::{EcLevel, QrCode};
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct Settings {
#[serde(default)]
pub general: General,
#[serde(default)]
pub admin: Admin,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub project: Option<Project>,
}
impl Settings {
pub fn to_json(&self) -> Result<String, Error> {
Ok(serde_json::to_string(self)?)
}
pub fn to_json_pretty(&self) -> Result<String, Error> {
Ok(serde_json::to_string_pretty(self)?)
}
pub fn encode(&self) -> Result<String, Error> {
encode(self)
}
pub fn decode(payload: &str) -> Result<Settings, Error> {
decode(payload)
}
pub fn warnings(&self) -> Vec<String> {
let mut w = Vec::new();
let g = &self.general;
let a = &self.admin;
match g.server_url.as_deref() {
None | Some("") => w.push("general.server_url is empty: the app will keep its current server".into()),
Some(u) if !u.starts_with("https://") => {
w.push(format!("server_url `{u}` is not https: Collect refuses Basic auth over plain http"))
}
Some(u) if is_kpi_host(u) => w.push(format!(
"server_url `{u}` looks like the KoboToolbox web interface (KPI); the app must point at the KoboCAT host (kc.… / kc-eu.…)"
)),
_ => {}
}
if a.admin_pw.as_deref().map_or(true, str::is_empty) && a.locks_anything() {
w.push("admin section locks features but admin_pw is empty: anyone can open the protected menu".into());
}
if a.qr_code_scanner == Some(true) && a.locks_anything() {
w.push("qr_code_scanner is allowed: any other QR code can undo these locks".into());
}
if a.change_server == Some(true) && a.locks_anything() {
w.push("change_server is allowed: the interviewer can switch account or server".into());
}
if g.form_update_mode == Some(FormUpdateMode::MatchExactly)
&& g.automatic_update == Some(false)
{
w.push("form_update_mode is match_exactly but automatic_update is false: new versions will wait for a manual refresh".into());
}
if g.form_update_mode.is_some()
&& g.form_update_mode != Some(FormUpdateMode::Manual)
&& g.periodic_form_updates_check.is_none()
{
w.push("periodic_form_updates_check is unset: the app will use its default interval (every 24 hours)".into());
}
if a.get_blank == Some(false)
&& g.form_update_mode
.map_or(true, |m| m == FormUpdateMode::Manual)
{
w.push("get_blank is hidden and form_update_mode is manual: nobody can download forms on the device".into());
}
if a.send_finalized == Some(false) && g.autosend.map_or(true, |m| m == Autosend::Off) {
w.push(
"send_finalized is hidden and autosend is off: finalized forms can never be sent"
.into(),
);
}
if g.delete_send == Some(true) {
w.push(
"delete_send is true: the local copy is removed as soon as a form is sent".into(),
);
}
if let Some(p) = &self.project {
if p.icon.as_ref().is_some_and(|i| i.chars().count() > 1) {
w.push("project.icon should be a single character".into());
}
}
w
}
}
fn is_kpi_host(url: &str) -> bool {
let host = url
.trim_start_matches("https://")
.trim_start_matches("http://")
.split(['/', '?', '#'])
.next()
.unwrap_or("")
.split('@')
.next_back()
.unwrap_or("")
.split(':')
.next()
.unwrap_or("")
.to_ascii_lowercase();
host.starts_with("kf.") || host == "eu.kobotoolbox.org"
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn kpi_host_detection() {
assert!(is_kpi_host("https://kf.kobotoolbox.org"));
assert!(is_kpi_host("https://eu.kobotoolbox.org/"));
assert!(is_kpi_host("https://kf.prompt.tec.br"));
assert!(!is_kpi_host("https://kc-eu.kobotoolbox.org"));
assert!(!is_kpi_host("https://kc.kobotoolbox.org/owner"));
assert!(!is_kpi_host(
"https://central.example.org/v1/key/abc/projects/1"
));
}
#[test]
fn roundtrip() {
let s = Settings {
general: General {
server_url: Some("https://kc.example.org".into()),
username: Some("u".into()),
password: Some("p".into()),
autosend: Some(Autosend::WifiOnly),
..Default::default()
},
admin: Admin::locked_interviewer("x"),
project: Some(Project::new("P").icon('P').color("#000000")),
};
let enc = s.encode().unwrap();
assert_eq!(Settings::decode(&enc).unwrap(), s);
}
#[test]
fn empty_sections_are_present() {
let json = Settings::default().to_json().unwrap();
assert_eq!(json, r#"{"general":{},"admin":{}}"#);
}
#[test]
fn warns_about_kpi_host() {
let s = Settings {
general: General {
server_url: Some("https://kf.kobotoolbox.org".into()),
..Default::default()
},
..Default::default()
};
assert!(s.warnings().iter().any(|w| w.contains("KoboCAT")));
}
}