@synopackageland/templates 0.9.8 → 0.10.0

package/templates/native-rust/backend/src/app/background_routes.rs

@@ -1,22 +0,0 @@
-use std::sync::Arc;
-
-use syno_pkg_land_sdk::api::Route;
-
-use super::Config;
-#[cfg(test)]
-use super::test_support::Sample;
-
-impl Config {
-    /// Empty: this package did not opt in to background jobs.
-    /// `synopkgland init --with jobs` overlays this file with one that serves
-    /// [`super::BackgroundApi`] for the package-user worker unit.
-    pub(super) fn background_routes(self: &Arc<Self>) -> Vec<Route> {
-        Vec::new()
-    }
-}
-
-/// The background routes' samples: none.
-#[cfg(test)]
-pub(super) fn samples() -> Vec<Sample> {
-    Vec::new()
-}

package/templates/native-rust/backend/src/app/delegate_config.rs

@@ -1,188 +0,0 @@
-use std::collections::BTreeSet;
-use std::fmt;
-
-use super::Config;
-
-#[derive(Clone, Debug, Default, PartialEq, Eq)]
-pub struct DelegateSettings {
-    pub scope: String,
-    pub operations: Vec<String>,
-    pub destinations: Vec<String>,
-    pub lifetime: String,
-}
-
-#[derive(Debug, PartialEq, Eq)]
-pub struct InvalidDelegateConfig;
-
-impl fmt::Display for InvalidDelegateConfig {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str("invalid delegate build configuration")
-    }
-}
-
-impl std::error::Error for InvalidDelegateConfig {}
-
-/// The file operations a time-limited delegation may grant.
-const TIME_LIMITED_OPERATIONS: [&str; 10] = [
-    "files.list",
-    "files.info",
-    "files.createFolder",
-    "files.checkPermission",
-    "files.write",
-    "files.read",
-    "files.rename",
-    "files.copy",
-    "files.move",
-    "files.delete",
-];
-
-const PERMANENT_OPERATION: &str = "files.moveFromStaging";
-const PERMANENT_LIFETIME: &str = "until-revoked";
-const MAX_DESTINATIONS: usize = 64;
-
-/// A JSON array of strings; empty text and `null` are an empty list.
-fn string_list(json: &str) -> Result<Vec<String>, InvalidDelegateConfig> {
-    if json.is_empty() {
-        return Ok(Vec::new());
-    }
-    let list: Option<Vec<String>> =
-        serde_json::from_str(json).map_err(|_| InvalidDelegateConfig)?;
-    Ok(list.unwrap_or_default())
-}
-
-/// Go's `^[a-z][a-z0-9_-]{0,63}$`.
-fn destination_key(key: &str) -> bool {
-    (1..=64).contains(&key.len())
-        && key.starts_with(|c: char| c.is_ascii_lowercase())
-        && key
-            .bytes()
-            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == b'_' || c == b'-')
-}
-
-fn all_unique(list: &[String]) -> bool {
-    list.iter().collect::<BTreeSet<_>>().len() == list.len()
-}
-
-/// Consumes only build/startup settings. Legacy declarations retain their
-/// TTL/job branch; absent extension fields never imply permanence.
-pub fn parse_delegate_config(cfg: &Config) -> Result<DelegateSettings, InvalidDelegateConfig> {
-    let out = DelegateSettings {
-        scope: cfg.delegate_scope.clone(),
-        operations: string_list(&cfg.delegate_operations_json)?,
-        destinations: string_list(&cfg.delegate_destinations_json)?,
-        lifetime: cfg.delegate_lifetime.clone(),
-    };
-    let valid = if out.lifetime.is_empty() {
-        out.destinations.is_empty()
-            && out
-                .operations
-                .iter()
-                .all(|op| TIME_LIMITED_OPERATIONS.contains(&op.as_str()))
-            && all_unique(&out.operations)
-    } else {
-        out.lifetime == PERMANENT_LIFETIME
-            && !out.scope.is_empty()
-            && out.operations == [PERMANENT_OPERATION]
-            && (1..=MAX_DESTINATIONS).contains(&out.destinations.len())
-            && out.destinations.iter().all(|key| destination_key(key))
-            && all_unique(&out.destinations)
-    };
-    if valid {
-        Ok(out)
-    } else {
-        Err(InvalidDelegateConfig)
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn permanent() -> Config {
-        Config {
-            delegate_scope: "home".into(),
-            delegate_operations_json: r#"["files.moveFromStaging"]"#.into(),
-            delegate_destinations_json: r#"["save"]"#.into(),
-            delegate_lifetime: "until-revoked".into(),
-            ..Config::default()
-        }
-    }
-
-    #[test]
-    fn delegate_build_config_strictly_separates_legacy_and_permanent() {
-        let settings = parse_delegate_config(&permanent()).unwrap();
-        assert_eq!(settings.lifetime, "until-revoked");
-        assert_eq!(settings.destinations, ["save"]);
-        let legacy = [
-            Config::default(),
-            Config {
-                delegate_scope: "home".into(),
-                ..Config::default()
-            },
-            Config {
-                delegate_scope: "home".into(),
-                delegate_operations_json: r#"["files.write"]"#.into(),
-                ..Config::default()
-            },
-        ];
-        for cfg in legacy {
-            let settings = parse_delegate_config(&cfg).unwrap();
-            assert!(
-                settings.lifetime.is_empty() && settings.destinations.is_empty(),
-                "legacy changed"
-            );
-        }
-        let mutations: [fn(&mut Config); 8] = [
-            |c| c.delegate_lifetime = String::new(),
-            |c| c.delegate_scope = String::new(),
-            |c| c.delegate_operations_json = r#"["files.write"]"#.into(),
-            |c| c.delegate_destinations_json = r#"["save","save"]"#.into(),
-            |c| c.delegate_destinations_json = r#"["Save"]"#.into(),
-            |c| c.delegate_destinations_json = "[]".into(),
-            |c| c.delegate_destinations_json = "null".into(),
-            |c| c.delegate_destinations_json = r#"["save"] {}"#.into(),
-        ];
-        for mutate in mutations {
-            let mut cfg = permanent();
-            mutate(&mut cfg);
-            assert_eq!(
-                parse_delegate_config(&cfg),
-                Err(InvalidDelegateConfig),
-                "invalid trusted config accepted: {}",
-                cfg.delegate_destinations_json
-            );
-        }
-    }
-
-    #[test]
-    fn delegate_build_config_accepts_every_time_limited_file_operation() {
-        let ops = r#"["files.checkPermission","files.copy","files.createFolder","files.delete","files.info","files.list","files.move","files.read","files.rename","files.write"]"#;
-        let settings = parse_delegate_config(&Config {
-            delegate_scope: "shared:media".into(),
-            delegate_operations_json: ops.into(),
-            delegate_destinations_json: "[]".into(),
-            ..Config::default()
-        })
-        .unwrap();
-        assert_eq!(settings.operations.len(), 10);
-        assert!(settings.lifetime.is_empty());
-    }
-
-    #[test]
-    fn destination_keys_follow_the_documented_pattern() {
-        for ok in ["a", "save", "a-b_c9", &format!("a{}", "b".repeat(63))] {
-            assert!(destination_key(ok), "{ok}");
-        }
-        for bad in [
-            "",
-            "1a",
-            "-a",
-            "A",
-            "a b",
-            "é",
-            &format!("a{}", "b".repeat(64)),
-        ] {
-            assert!(!destination_key(bad), "{bad}");
-        }
-    }
-}

package/templates/native-rust/backend/src/app/delegate_routes.rs

@@ -1,22 +0,0 @@
-use std::sync::Arc;
-
-use syno_pkg_land_sdk::api::Route;
-
-use super::Config;
-#[cfg(test)]
-use super::test_support::Sample;
-
-impl Config {
-    /// Empty: this package did not opt in to delegated operations.
-    /// `synopkgland init --with delegate` overlays this file with one that
-    /// serves the SDK's delegate routes.
-    pub(super) fn delegate_routes(self: &Arc<Self>) -> Vec<Route> {
-        Vec::new()
-    }
-}
-
-/// The delegate routes' samples: none.
-#[cfg(test)]
-pub(super) fn samples() -> Vec<Sample> {
-    Vec::new()
-}

package/templates/native-rust/backend/src/app/identity.rs

@@ -1,56 +0,0 @@
-use syno_pkg_land_sdk::BoxError;
-use syno_pkg_land_sdk::identity::{Config as IdentityConfig, Service};
-
-use super::Config;
-
-/// Builds the SDK's standalone identity service, which registers
-/// identity.status/session/login/logout through `Service::wrap`. Business
-/// routes keep their permissions.json policies. Call only for
-/// capabilities.identity=standalone; the path comes from the CGI environment.
-pub fn standalone_identity(cfg: &Config, script_name: &str) -> Result<Service, BoxError> {
-    if !absolute_cgi_path(script_name) {
-        return Err("identity requires an absolute CGI script path".into());
-    }
-    // script_name is .../cgi/api.cgi; the cookie belongs to the folder above cgi.
-    let app_dir = &script_name[..script_name.len() - "/cgi/api.cgi".len()];
-    Service::new(IdentityConfig {
-        data_dir: cfg.data_dir.to_string_lossy().into_owned(),
-        cookie_path: format!("{app_dir}/"),
-        ..IdentityConfig::default()
-    })
-}
-
-/// Whether path is clean, absolute and ends in /cgi/api.cgi.
-fn absolute_cgi_path(path: &str) -> bool {
-    path.starts_with('/')
-        && !path.starts_with("//")
-        && path.ends_with("/cgi/api.cgi")
-        && path
-            .split('/')
-            .skip(1)
-            .all(|s| !matches!(s, "" | "." | ".."))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::super::test_support::Fixture;
-    use super::*;
-
-    #[test]
-    fn identity_application_path() {
-        let fixture = Fixture::new();
-        for (script, valid) in [
-            ("/webman/3rdparty/test/cgi/api.cgi", true),
-            ("/cgi/api.cgi", true),
-            ("", false),
-            ("cgi/api.cgi", false),
-            ("//evil/cgi/api.cgi", false),
-            ("/a/../cgi/api.cgi", false),
-            ("/a//cgi/api.cgi", false),
-            ("/a/cgi/api.cgi/", false),
-        ] {
-            let got = standalone_identity(&fixture.cfg, script);
-            assert_eq!(got.is_ok(), valid, "script {script:?}");
-        }
-    }
-}

package/templates/native-rust/backend/src/app/migrations.rs

@@ -1,79 +0,0 @@
-use syno_pkg_land_sdk::BoxError;
-use syno_pkg_land_sdk::datamigrate::{self, Info, Migration};
-
-use super::Config;
-
-/// This app's schema migrations. The template ships one empty example;
-/// replace it with your own steps. Versions start at 1 and never change
-/// meaning. Every step must be idempotent: a crash between the step and the
-/// recorded version, or two CGI requests racing on the first run after an
-/// upgrade, can run one step twice. A failed step stops the run with the
-/// previous version still recorded, and the next run resumes from there; the
-/// utility itself never deletes or rewrites data.
-pub fn migrations() -> Vec<Migration> {
-    vec![Migration::new(1, "example", |_ctx| {
-        // Nothing to do yet. Read ctx.data_dir, rewrite files with a
-        // temporary file + rename, and keep the step idempotent.
-        Ok(())
-    })]
-}
-
-/// Applies [`migrations`] to the package's persistent var directory. The CGI
-/// calls it once per request; the recorded data-version makes that a cheap
-/// no-op. SYNOPKG_OLD_PKGVER is set when DSM starts the app from a lifecycle
-/// script; in a plain CGI request the version of the last successful run is
-/// used instead.
-pub fn migrate(cfg: &Config) -> Result<(), BoxError> {
-    migrate_from(
-        cfg,
-        &std::env::var("SYNOPKG_OLD_PKGVER").unwrap_or_default(),
-    )
-}
-
-fn migrate_from(cfg: &Config, old_pkg_ver: &str) -> Result<(), BoxError> {
-    let info = Info {
-        old_pkg_ver: old_pkg_ver.to_string(),
-        new_pkg_ver: cfg.version.clone(),
-        log: None,
-    };
-    datamigrate::run(&cfg.data_dir, &info, &migrations())?;
-    Ok(())
-}
-
-#[cfg(test)]
-mod tests {
-    use super::super::test_support::Fixture;
-    use super::*;
-
-    #[test]
-    fn migrations_are_ordered_unique_and_valid() {
-        let migrations = migrations();
-        assert!(
-            !migrations.is_empty(),
-            "the template must ship one example migration"
-        );
-        for (i, migration) in migrations.iter().enumerate() {
-            assert!(
-                migration.version >= 1 && !migration.name.is_empty(),
-                "migration {i} is invalid"
-            );
-            if i > 0 {
-                assert!(
-                    migrations[i - 1].version < migration.version,
-                    "migrations are not strictly version-ascending"
-                );
-            }
-        }
-    }
-
-    #[test]
-    fn migrate_records_the_schema_and_package_version() {
-        let mut fixture = Fixture::new();
-        fixture.cfg.version = "0.2.0-0002".into();
-        migrate_from(&fixture.cfg, "0.1.0-0001").unwrap();
-        let state = datamigrate::load(&fixture.cfg.data_dir).unwrap();
-        assert_eq!(state.schema, 1);
-        assert_eq!(state.package_version, "0.2.0-0002");
-        migrate_from(&fixture.cfg, "0.1.0-0001").expect("a second migrate must be a no-op");
-    }
-}

package/templates/native-rust/backend/src/app/mod.rs

@@ -1,30 +0,0 @@
-//! This package's business operations. Add a route in `routes.rs` and register
-//! its handler there. App permissions live in `permissions.json`; SDK
-//! capability routes use the immutable SDK policy. Unlisted methods require
-//! membership in DSM's administrators group.
-
-mod background;
-mod background_routes;
-mod delegate_config;
-mod delegate_routes;
-mod identity;
-mod migrations;
-mod portal;
-mod root_routes;
-mod routes;
-mod session_files;
-mod shared_folder;
-#[cfg(test)]
-mod test_support;
-mod uninstall;
-
-pub use background::{BackgroundApi, BackgroundFiles, hash_work, system_uid_lookup};
-pub use delegate_config::{DelegateSettings, InvalidDelegateConfig, parse_delegate_config};
-pub use identity::standalone_identity;
-pub use migrations::{migrate, migrations};
-pub use routes::{Config, UidLookup, routes};
-pub use session_files::{FILE_STATION_SESSION, session_files_enabled};
-pub use shared_folder::{
-    SharedFolder, SharedFolderError, read_shared_folders, resolve_shared_folder,
-};
-pub use uninstall::uninstall;