Skip to content
1        10        20        30        40        50        60        70        80        90        100       1101use std::collections::{BTreeMap, HashMap};23use serde::{Deserialize, Serialize};45fn null_default<'de, D, T>(deserializer: D) -> Result<T, D::Error>6where7    D: serde::Deserializer<'de>,8    T: Deserialize<'de> + Default,9{10    Ok(Option::<T>::deserialize(deserializer)?.unwrap_or_default())11}1213pub const ONCE_LABEL: &str = "once";14pub const SERVER_LABEL: &str = "ino.server";15pub const SERVER_APP_NAME: &str = "ino-server";1617/// Variables Once derives from app settings. The environment API never sets them.18const ONCE_MANAGED_ENV: &[&str] = &[19    "SECRET_KEY_BASE",20    "VAPID_PUBLIC_KEY",21    "VAPID_PRIVATE_KEY",22    "DISABLE_SSL",23    "NUM_CPUS",24    "BASE_URL",25    "SMTP_ADDRESS",26    "SMTP_PORT",27    "SMTP_USERNAME",28    "SMTP_PASSWORD",29    "MAILER_FROM_ADDRESS",30];3132/// Variables the Ino server keeps for its own runtime, reserved on the server app only.33const SERVER_MANAGED_ENV: &[&str] = &["PORT"];3435pub fn is_reserved_env(name: &str, is_server: bool) -> bool {36    ONCE_MANAGED_ENV.contains(&name) || (is_server && SERVER_MANAGED_ENV.contains(&name))37}3839pub fn reserved_env_names(is_server: bool) -> Vec<&'static str> {40    let mut names = ONCE_MANAGED_ENV.to_vec();41    if is_server {42        names.extend_from_slice(SERVER_MANAGED_ENV);43    }44    names45}4647#[derive(Debug, Clone, PartialEq, Eq, Serialize)]48#[serde(rename_all = "camelCase")]49pub struct AppSummary {50    pub name: String,51    pub host: String,52    pub image: String,53    pub running: bool,54    pub url: Option<String>,55    pub is_server: bool,56}5758/// Non-secret settings of one app. Passwords and Once keys are never included.59#[derive(Debug, Clone, PartialEq, Eq, Serialize)]60#[serde(rename_all = "camelCase")]61pub struct AppDetail {62    #[serde(flatten)]63    pub summary: AppSummary,64    #[serde(rename = "disableTLS")]65    pub disable_tls: bool,66    pub auto_update: bool,67    pub resources: ContainerResources,68    pub backup: BackupSettings,69    pub smtp: SmtpSummary,70    pub registry: RegistrySummary,71}7273#[derive(Debug, Clone, PartialEq, Eq, Serialize)]74#[serde(rename_all = "camelCase")]75pub struct SmtpSummary {76    pub server: String,77    pub port: String,78    pub username: String,79    pub from: String,80}8182#[derive(Debug, Clone, PartialEq, Eq, Serialize)]83#[serde(rename_all = "camelCase")]84pub struct RegistrySummary {85    pub host: String,86    pub username: String,87}8889/// The user-owned environment of one app and the names Ino reserves.90#[derive(Debug, Clone, PartialEq, Eq, Serialize)]91pub struct AppEnvironment {92    pub env: BTreeMap<String, String>,93    pub reserved: Vec<&'static str>,94}9596#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]97#[serde(rename_all = "camelCase")]98pub struct AppSettings {99    #[serde(default)]100    pub name: String,101    #[serde(default)]102    pub image: String,103    #[serde(default)]104    pub host: String,105    #[serde(default, rename = "disableTLS")]106    pub disable_tls: bool,107    #[serde(default, rename = "env", deserialize_with = "null_default")]108    pub env_vars: HashMap<String, String>,109    #[serde(default, deserialize_with = "null_default")]110    pub smtp: SmtpSettings,111    #[serde(default, deserialize_with = "null_default")]112    pub resources: ContainerResources,113    #[serde(default, rename = "autoUpdate")]114    pub auto_update: bool,115    #[serde(default, deserialize_with = "null_default")]116    pub backup: BackupSettings,117    #[serde(default, deserialize_with = "null_default")]118    pub keys: Keys,119    #[serde(default, deserialize_with = "null_default")]120    pub registry: RegistrySettings,121}122123impl AppSettings {124    pub fn tls_enabled(&self) -> bool {125        !self.host.is_empty()126            && !self.disable_tls127            && self.host != "localhost"128            && !self.host.ends_with(".localhost")129    }130131    pub fn url(&self, proxy: Option<&ProxySettings>) -> Option<String> {132        if self.host.is_empty() {133            return None;134        }135        let tls = self.tls_enabled();136        let scheme = if tls { "https" } else { "http" };137        let default_port = if tls { 443 } else { 80 };138        let configured_port = proxy.map_or(default_port, |settings| {139            if tls {140                settings.https_port141            } else {142                settings.http_port143            }144        });145        let mut url = format!("{scheme}://{}", self.host);146        if configured_port != 0 && configured_port != default_port {147            url = format!("{url}:{configured_port}");148        }149        Some(url)150    }151152    pub fn build_env(&self, proxy: Option<&ProxySettings>) -> Vec<String> {153        let mut env = vec![154            format!("SECRET_KEY_BASE={}", self.keys.secret_key_base),155            format!("VAPID_PUBLIC_KEY={}", self.keys.vapid_public_key),156            format!("VAPID_PRIVATE_KEY={}", self.keys.vapid_private_key),157        ];158        if !self.tls_enabled() {159            env.push("DISABLE_SSL=true".to_owned());160        }161        if self.resources.cpus > 0 {162            env.push(format!("NUM_CPUS={}", self.resources.cpus));163        }164        if let Some(url) = self.url(proxy) {165            env.push(format!("BASE_URL={url}"));166        }167        if !self.smtp.server.is_empty() {168            env.extend([169                format!("SMTP_ADDRESS={}", self.smtp.server),170                format!("SMTP_PORT={}", self.smtp.port),171                format!("SMTP_USERNAME={}", self.smtp.username),172                format!("SMTP_PASSWORD={}", self.smtp.password),173                format!("MAILER_FROM_ADDRESS={}", self.smtp.from),174            ]);175        }176        env.extend(177            self.env_vars178                .iter()179                .map(|(key, value)| format!("{key}={value}")),180        );181        env182    }183184    /// The user-owned variables, leaving out names reserved for this kind of app.185    pub fn custom_env(&self, is_server: bool) -> BTreeMap<String, String> {186        self.env_vars187            .iter()188            .filter(|(key, _)| !is_reserved_env(key, is_server))189            .map(|(key, value)| (key.clone(), value.clone()))190            .collect()191    }192193    /// Replaces the user-owned variables. Reserved entries are kept as they are.194    pub fn replace_custom_env(&mut self, env: &BTreeMap<String, String>, is_server: bool) {195        self.env_vars196            .retain(|key, _| is_reserved_env(key, is_server));197        self.env_vars.extend(env.clone());198    }199}200201#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]202#[serde(rename_all = "camelCase")]203pub struct SmtpSettings {204    #[serde(default)]205    pub server: String,206    #[serde(default)]207    pub port: String,208    #[serde(default)]209    pub username: String,210    #[serde(default)]211    pub password: String,212    #[serde(default)]213    pub from: String,214}215216#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]217pub struct ContainerResources {218    #[serde(default)]219    pub cpus: u32,220    #[serde(default, rename = "memoryMB")]221    pub memory_mb: u32,222}223224#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]225#[serde(rename_all = "camelCase")]226pub struct BackupSettings {227    #[serde(default)]228    pub path: String,229    #[serde(default, rename = "autoBackup")]230    pub auto_backup: bool,231}232233#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]234#[serde(rename_all = "camelCase")]235pub struct Keys {236    #[serde(default)]237    pub secret_key_base: String,238    #[serde(default)]239    pub vapid_public_key: String,240    #[serde(default)]241    pub vapid_private_key: String,242}243244#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]245#[serde(rename_all = "camelCase")]246pub struct RegistrySettings {247    #[serde(default)]248    pub host: String,249    #[serde(default)]250    pub username: String,251    #[serde(default)]252    pub password: String,253}254255#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]256#[serde(rename_all = "camelCase")]257// The field names mirror the persisted `httpPort`, `httpsPort` and `metricsPort` keys.258#[allow(clippy::struct_field_names)]259pub struct ProxySettings {260    #[serde(default)]261    pub http_port: u16,262    #[serde(default)]263    pub https_port: u16,264    #[serde(default)]265    pub metrics_port: u16,266}267268#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]269#[serde(rename_all = "camelCase")]270pub struct OnceState {271    #[serde(default)]272    pub apps: HashMap<String, AppState>,273    #[serde(default)]274    pub last_self_update: OperationResult,275}276277#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]278#[serde(rename_all = "camelCase")]279pub struct AppState {280    #[serde(default)]281    pub last_backup: OperationResult,282    #[serde(default)]283    pub last_update: OperationResult,284}285286#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]287pub struct OperationResult {288    #[serde(default = "zero_timestamp")]289    pub at: String,290    #[serde(default)]291    pub error: String,292}293294impl Default for OperationResult {295    fn default() -> Self {296        Self {297            at: zero_timestamp(),298            error: String::new(),299        }300    }301}302303fn zero_timestamp() -> String {304    "0001-01-01T00:00:00Z".to_owned()305}306307impl OnceState {308    pub fn self_update_due(&self) -> bool {309        result_due(&self.last_self_update)310    }311312    pub fn record_self_update(&mut self, error: Option<&str>) {313        self.last_self_update = OperationResult::now(error);314    }315316    pub fn record_backup(&mut self, app_name: &str, error: Option<&str>) {317        self.apps318            .entry(app_name.to_owned())319            .or_default()320            .last_backup = OperationResult::now(error);321    }322323    pub fn record_update(&mut self, app_name: &str, error: Option<&str>) {324        self.apps325            .entry(app_name.to_owned())326            .or_default()327            .last_update = OperationResult::now(error);328    }329330    pub fn backup_due(&self, app_name: &str) -> bool {331        self.operation_due(app_name, |state| &state.last_backup)332    }333334    pub fn update_due(&self, app_name: &str) -> bool {335        self.operation_due(app_name, |state| &state.last_update)336    }337338    fn operation_due<'a>(339        &'a self,340        app_name: &str,341        get: impl FnOnce(&'a AppState) -> &'a OperationResult,342    ) -> bool {343        let Some(state) = self.apps.get(app_name) else {344            return true;345        };346        result_due(get(state))347    }348}349350fn result_due(result: &OperationResult) -> bool {351    if !result.error.is_empty() {352        return true;353    }354    time::OffsetDateTime::parse(&result.at, &time::format_description::well_known::Rfc3339)355        .map_or(true, |at| {356            time::OffsetDateTime::now_utc() - at >= time::Duration::hours(24)357        })358}359360impl OperationResult {361    fn now(error: Option<&str>) -> Self {362        Self {363            at: time::OffsetDateTime::now_utc()364                .format(&time::format_description::well_known::Rfc3339)365                .unwrap_or_default(),366            error: error.unwrap_or_default().to_owned(),367        }368    }369}370371impl ProxySettings {372    pub fn once_defaults() -> Self {373        Self {374            http_port: 80,375            https_port: 443,376            metrics_port: 1318,377        }378    }379}380381#[cfg(test)]382mod tests {383    use super::{AppSettings, OnceState, ProxySettings};384385    #[test]386    fn app_settings_decode_and_encode_once_v034_json_names() {387        let settings: AppSettings = serde_json::from_str(include_str!(388            "../../../tests/fixtures/once-v0.3.4/application-settings.json"389        ))390        .unwrap();391392        assert_eq!(settings.name, "writer");393        assert_eq!(settings.resources.memory_mb, 2048);394        assert_eq!(settings.smtp.server, "smtp.example.test");395        assert_eq!(settings.env_vars["APP_MODE"], "production");396397        let value = serde_json::to_value(settings).unwrap();398        assert!(value.get("disableTLS").is_some());399        assert!(value.get("autoUpdate").is_some());400        assert_eq!(value["resources"]["memoryMB"], 2048);401        assert_eq!(value["env"]["APP_MODE"], "production");402    }403404    #[test]405    fn app_settings_treat_null_once_metadata_objects_as_empty_defaults() {406        let settings: AppSettings = serde_json::from_str(407            r#"{"name":"writer","env":null,"smtp":null,"resources":null,"backup":null,"keys":null,"registry":null}"#,408        )409        .unwrap();410411        assert_eq!(settings.name, "writer");412        assert!(settings.env_vars.is_empty());413        assert_eq!(settings.smtp, super::SmtpSettings::default());414        assert_eq!(settings.resources, super::ContainerResources::default());415        assert_eq!(settings.backup, super::BackupSettings::default());416        assert_eq!(settings.keys, super::Keys::default());417        assert_eq!(settings.registry, super::RegistrySettings::default());418    }419420    #[test]421    fn proxy_settings_decode_once_v034_json_names() {422        let settings: ProxySettings = serde_json::from_str(include_str!(423            "../../../tests/fixtures/once-v0.3.4/proxy-settings.json"424        ))425        .unwrap();426427        assert_eq!(settings.http_port, 80);428        assert_eq!(settings.https_port, 443);429        assert_eq!(settings.metrics_port, 1318);430    }431432    #[test]433    fn application_environment_matches_once_deployment_contract() {434        let settings = AppSettings {435            host: "app.localhost".into(),436            env_vars: std::collections::HashMap::from([("CUSTOM".into(), "value".into())]),437            resources: super::ContainerResources {438                cpus: 3,439                memory_mb: 512,440            },441            smtp: super::SmtpSettings {442                server: "smtp.example.test".into(),443                port: "587".into(),444                username: "u".into(),445                password: "p".into(),446                from: "from@example.test".into(),447            },448            keys: super::Keys {449                secret_key_base: "secret".into(),450                vapid_public_key: "pub".into(),451                vapid_private_key: "priv".into(),452            },453            ..Default::default()454        };455        let env = settings.build_env(None);456        for value in [457            "SECRET_KEY_BASE=secret",458            "VAPID_PUBLIC_KEY=pub",459            "VAPID_PRIVATE_KEY=priv",460            "DISABLE_SSL=true",461            "NUM_CPUS=3",462            "BASE_URL=http://app.localhost",463            "SMTP_ADDRESS=smtp.example.test",464            "SMTP_PORT=587",465            "SMTP_USERNAME=u",466            "SMTP_PASSWORD=p",467            "MAILER_FROM_ADDRESS=from@example.test",468            "CUSTOM=value",469        ] {470            assert!(env.iter().any(|entry| entry == value), "missing {value}");471        }472473        let public_settings = AppSettings {474            host: "books.example.test".into(),475            keys: settings.keys.clone(),476            ..Default::default()477        };478        let proxy = ProxySettings {479            http_port: 8080,480            https_port: 8443,481            metrics_port: 1318,482        };483        assert!(484            public_settings485                .build_env(Some(&proxy))486                .iter()487                .any(|entry| entry == "BASE_URL=https://books.example.test:8443")488        );489    }490491    #[test]492    fn custom_environment_hides_reserved_names_and_replace_keeps_them() {493        let mut settings = super::AppSettings {494            env_vars: std::collections::HashMap::from([495                ("SECRET_KEY_BASE".into(), "once-secret".into()),496                ("PORT".into(), "8080".into()),497                ("MODE".into(), "old".into()),498            ]),499            ..Default::default()500        };501502        let custom = settings.custom_env(true);503        assert_eq!(custom.len(), 1);504        assert_eq!(custom["MODE"], "old");505        assert_eq!(settings.custom_env(false).len(), 2);506507        let replacement = std::collections::BTreeMap::from([("NEW".into(), "1".into())]);508        settings.replace_custom_env(&replacement, true);509        assert_eq!(settings.env_vars.len(), 3);510        assert_eq!(settings.env_vars["SECRET_KEY_BASE"], "once-secret");511        assert_eq!(settings.env_vars["PORT"], "8080");512        assert_eq!(settings.env_vars["NEW"], "1");513        assert!(!settings.env_vars.contains_key("MODE"));514    }515516    #[test]517    fn operation_state_uses_once_due_and_error_rules() {518        let mut state = OnceState::default();519        assert!(state.update_due("writer"));520        state.record_update("writer", None);521        assert!(!state.update_due("writer"));522        state.record_backup("writer", Some("backup failed"));523        assert!(state.backup_due("writer"));524        let value = serde_json::to_value(state).unwrap();525        assert!(value["apps"]["writer"]["lastUpdate"]["at"].is_string());526        assert_eq!(527            value["apps"]["writer"]["lastBackup"]["error"],528            "backup failed"529        );530        assert_eq!(value["lastSelfUpdate"]["at"], "0001-01-01T00:00:00Z");531    }532533    #[test]534    fn operation_state_decodes_once_v034_fixture() {535        let state: OnceState = serde_json::from_str(include_str!(536            "../../../tests/fixtures/once-v0.3.4/state.json"537        ))538        .unwrap();539        assert_eq!(state.apps["writer"].last_backup.at, "2026-10-08T00:00:00Z");540        assert_eq!(state.last_self_update.at, "2026-10-08T00:00:00Z");541    }542}