@synopackageland/templates 0.9.5 → 0.9.6

package/templates/native-rust/backend/src/bin/background-worker.rs

@@ -0,0 +1,37 @@
+//! The package's fixed background worker. DSM runs it as the package's
+//! systemd user unit under the package account; it never runs as root and
+//! takes no input except the jobs in its private spool.
+
+use std::process::exit;
+use std::sync::Arc;
+
+use app::app::hash_work;
+use app::build_env::Build;
+use app::process::{current_username, until_terminated};
+use syno_pkg_land_sdk::BoxError;
+use syno_pkg_land_sdk::background::{Runner, WorkerInfo, refuse_root};
+
+fn main() {
+    let package = Build::compiled().package_id;
+    if let Err(e) = run(package) {
+        eprintln!("{package} background: {e}");
+        exit(1);
+    }
+}
+
+fn run(package: &str) -> Result<(), BoxError> {
+    // SAFETY: these take no arguments and cannot fail.
+    let (euid, uid, pid) = unsafe { (libc::geteuid(), libc::getuid(), libc::getpid()) };
+    refuse_root(euid)?;
+    let info = WorkerInfo {
+        pid: i64::from(pid),
+        uid: i64::from(uid),
+        username: current_username(),
+        ..WorkerInfo::default()
+    };
+    let ctx = until_terminated();
+    eprintln!("{package} background: started as uid {uid}");
+    let mut runner = Runner::new(format!("/var/packages/{package}/var/background"), info);
+    runner.work = Arc::new(hash_work);
+    runner.run(&ctx)
+}

package/templates/native-rust/backend/src/build_env.rs

@@ -0,0 +1,155 @@
+//! What `synopkgland build` fixes in the binary through SYNOPKGLAND_*
+//! environment variables at compile time; never read from a request. An empty
+//! or absent variable is unset. The SDK reads SYNOPKGLAND_SDK_PERMISSIONS_DIGEST
+//! itself.
+
+use std::sync::Arc;
+
+use syno_pkg_land_sdk::filestation::Service;
+
+use crate::app::{Config, session_files_enabled};
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct Build {
+    pub package_id: &'static str,
+    pub version: &'static str,
+    pub delegate_scope: &'static str,
+    pub delegate_operations: &'static str,
+    pub delegate_destinations: &'static str,
+    pub delegate_lifetime: &'static str,
+    pub executor_digest: &'static str,
+    pub policy_digest: &'static str,
+    /// "standalone" enables the SDK identity adapter; the runtime owns
+    /// authentication.
+    pub identity: &'static str,
+    /// "session" when the project opted into the interactive File Station
+    /// adapter.
+    pub file_station: &'static str,
+    /// dsm-package.yaml entry: "admin-only" or "app-privilege"; empty keeps
+    /// the route policy alone.
+    pub entry: &'static str,
+    /// "on" when dsm-package.yaml declares portal: serves portal.status;
+    /// "executor" below DSM 7.2, where the executor registers the entry.
+    pub portal: &'static str,
+}
+
+impl Build {
+    /// The build this binary was compiled as; direct development builds get
+    /// the package "dev" at version "0.0.0".
+    pub fn compiled() -> Build {
+        Build {
+            package_id: or_default(option_env!("SYNOPKGLAND_PACKAGE"), "dev"),
+            version: or_default(option_env!("SYNOPKGLAND_VERSION"), "0.0.0"),
+            delegate_scope: or_default(option_env!("SYNOPKGLAND_DELEGATE_SCOPE"), ""),
+            delegate_operations: or_default(option_env!("SYNOPKGLAND_DELEGATE_OPERATIONS"), ""),
+            delegate_destinations: or_default(option_env!("SYNOPKGLAND_DELEGATE_DESTINATIONS"), ""),
+            delegate_lifetime: or_default(option_env!("SYNOPKGLAND_DELEGATE_LIFETIME"), ""),
+            executor_digest: or_default(option_env!("SYNOPKGLAND_EXECUTOR_DIGEST"), ""),
+            policy_digest: or_default(option_env!("SYNOPKGLAND_POLICY_DIGEST"), ""),
+            identity: or_default(option_env!("SYNOPKGLAND_IDENTITY"), ""),
+            file_station: or_default(option_env!("SYNOPKGLAND_FILE_STATION"), ""),
+            entry: or_default(option_env!("SYNOPKGLAND_ENTRY"), ""),
+            portal: or_default(option_env!("SYNOPKGLAND_PORTAL"), ""),
+        }
+    }
+
+    /// The package's persistent, package-owned directory.
+    pub fn data_dir(&self) -> String {
+        format!("/var/packages/{}/var", self.package_id)
+    }
+
+    /// The App's configuration for this build.
+    pub fn config(&self) -> Config {
+        let data_dir = self.data_dir();
+        Config {
+            delegate_scope: self.delegate_scope.into(),
+            delegate_operations_json: self.delegate_operations.into(),
+            delegate_destinations_json: self.delegate_destinations.into(),
+            delegate_lifetime: self.delegate_lifetime.into(),
+            executor_digest: self.executor_digest.into(),
+            policy_digest: self.policy_digest.into(),
+            session_files: session_files_enabled(self.file_station)
+                .then(|| Arc::new(Service::local(data_dir.as_ref()))),
+            package_id: self.package_id.into(),
+            version: self.version.into(),
+            data_dir: data_dir.into(),
+            portal: !self.portal.is_empty(),
+            portal_executor: self.portal == "executor",
+            ..Config::default()
+        }
+    }
+}
+
+fn or_default(value: Option<&'static str>, default: &'static str) -> &'static str {
+    value.filter(|v| !v.is_empty()).unwrap_or(default)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn an_unset_or_empty_variable_takes_the_default() {
+        assert_eq!(or_default(None, "dev"), "dev");
+        assert_eq!(or_default(Some(""), "dev"), "dev");
+        assert_eq!(or_default(Some("Hello"), "dev"), "Hello");
+    }
+
+    #[test]
+    fn config_derives_the_data_directory_and_portal_modes() {
+        let build = Build {
+            package_id: "HelloRust",
+            version: "1.2.3-0004",
+            portal: "executor",
+            ..Build::default()
+        };
+        let cfg = build.config();
+        assert_eq!(cfg.package_id, "HelloRust");
+        assert_eq!(cfg.version, "1.2.3-0004");
+        assert_eq!(
+            cfg.data_dir,
+            std::path::PathBuf::from("/var/packages/HelloRust/var")
+        );
+        assert!(cfg.portal && cfg.portal_executor);
+        assert!(cfg.session_files.is_none());
+
+        let cfg = Build {
+            portal: "on",
+            file_station: "session",
+            ..build
+        }
+        .config();
+        assert!(cfg.portal && !cfg.portal_executor);
+        assert!(cfg.session_files.is_some());
+
+        let cfg = Build::default().config();
+        assert!(!cfg.portal && !cfg.portal_executor);
+    }
+
+    #[test]
+    fn config_carries_the_delegate_settings_and_pins() {
+        let cfg = Build {
+            delegate_scope: "files",
+            delegate_operations: r#"["files.read"]"#,
+            delegate_destinations: r#"["save"]"#,
+            delegate_lifetime: "until-revoked",
+            executor_digest: "e1",
+            policy_digest: "p1",
+            ..Build::default()
+        }
+        .config();
+        assert_eq!(
+            (
+                cfg.delegate_scope.as_str(),
+                cfg.delegate_operations_json.as_str()
+            ),
+            ("files", r#"["files.read"]"#)
+        );
+        assert_eq!(cfg.delegate_destinations_json, r#"["save"]"#);
+        assert_eq!(cfg.delegate_lifetime, "until-revoked");
+        assert_eq!(
+            (cfg.executor_digest.as_str(), cfg.policy_digest.as_str()),
+            ("e1", "p1")
+        );
+    }
+}

package/templates/native-rust/backend/src/lib.rs

@@ -0,0 +1,6 @@
+//! This App's backend: routes, handlers and their policy.
+
+pub mod app;
+pub mod build_env;
+pub mod permissions;
+pub mod process;

package/templates/native-rust/backend/src/permissions.rs

@@ -0,0 +1,54 @@
+//! This App's method policy. The SDK's own capability methods keep the SDK
+//! policy; permissions.json only configures App methods.
+
+use std::error::Error;
+
+use syno_pkg_land_sdk::BoxError;
+use syno_pkg_land_sdk::sha256;
+
+const PERMISSIONS_JSON: &[u8] = include_bytes!("../permissions.json");
+
+/// Set by `synopkgland build` to bind the policy it validated to the compiled
+/// CGI. Unset only in direct development builds.
+const EXPECTED_DIGEST: Option<&str> = option_env!("SYNOPKGLAND_PERMISSIONS_DIGEST");
+
+/// Returns permissions.json, refusing a file that differs from the one the
+/// package build validated.
+pub fn permissions() -> Result<&'static [u8], BoxError> {
+    checked(PERMISSIONS_JSON, EXPECTED_DIGEST.unwrap_or(""))
+}
+
+fn checked<'a>(json: &'a [u8], expected_digest: &str) -> Result<&'a [u8], BoxError> {
+    if !expected_digest.is_empty() && sha256::hex_digest(json) != expected_digest {
+        return Err(Box::<dyn Error + Send + Sync>::from(
+            "API permissions do not match package build policy",
+        ));
+    }
+    Ok(json)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn permissions_without_a_build_digest_are_the_embedded_file() {
+        assert_eq!(checked(PERMISSIONS_JSON, "").unwrap(), PERMISSIONS_JSON);
+        assert_eq!(permissions().unwrap(), PERMISSIONS_JSON);
+    }
+
+    #[test]
+    fn permissions_matching_the_build_digest_are_accepted() {
+        let digest = sha256::hex_digest(PERMISSIONS_JSON);
+        assert_eq!(
+            checked(PERMISSIONS_JSON, &digest).unwrap(),
+            PERMISSIONS_JSON
+        );
+    }
+
+    #[test]
+    fn permissions_differing_from_the_build_digest_are_refused() {
+        let digest = sha256::hex_digest(b"other");
+        assert!(checked(PERMISSIONS_JSON, &digest).is_err());
+    }
+}

package/templates/native-rust/backend/src/process.rs

@@ -0,0 +1,91 @@
+//! What the background worker needs of its process: when it is asked to stop
+//! and which account it runs as.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+
+use syno_pkg_land_sdk::ctx::Context;
+
+static TERMINATION_REQUESTED: AtomicBool = AtomicBool::new(false);
+
+extern "C" fn on_termination(_: libc::c_int) {
+    TERMINATION_REQUESTED.store(true, Ordering::SeqCst);
+}
+
+/// A context that ends when the process receives SIGTERM or SIGINT, like
+/// Go's signal.NotifyContext.
+pub fn until_terminated() -> Context {
+    for signal in [libc::SIGTERM, libc::SIGINT] {
+        // SAFETY: the handler only stores to an atomic, which is
+        // async-signal-safe, and the zeroed sigaction is a valid starting
+        // value for sigaction.
+        unsafe {
+            let mut action: libc::sigaction = std::mem::zeroed();
+            action.sa_sigaction = on_termination as extern "C" fn(libc::c_int) as usize;
+            action.sa_flags = libc::SA_RESTART;
+            libc::sigemptyset(&mut action.sa_mask);
+            libc::sigaction(signal, &action, std::ptr::null_mut());
+        }
+    }
+    let (ctx, cancel) = Context::background().with_cancel();
+    std::thread::spawn(move || {
+        while !TERMINATION_REQUESTED.load(Ordering::SeqCst) {
+            std::thread::sleep(Duration::from_millis(50));
+        }
+        cancel.cancel();
+    });
+    ctx
+}
+
+/// The account name of the process's real user; empty when it has none.
+pub fn current_username() -> String {
+    let mut size = 1024;
+    while size <= 1 << 20 {
+        let mut buf = vec![0 as libc::c_char; size];
+        // SAFETY: a zeroed passwd is a valid out-parameter for getpwuid_r.
+        let mut pwd: libc::passwd = unsafe { std::mem::zeroed() };
+        let mut found = std::ptr::null_mut();
+        // SAFETY: every pointer refers to a live buffer of the given size.
+        let rc = unsafe {
+            libc::getpwuid_r(libc::getuid(), &mut pwd, buf.as_mut_ptr(), size, &mut found)
+        };
+        match rc {
+            0 if found.is_null() => return String::new(),
+            0 => {
+                // SAFETY: pw_name points into buf and is NUL-terminated.
+                let name = unsafe { std::ffi::CStr::from_ptr(pwd.pw_name) };
+                return name.to_string_lossy().into_owned();
+            }
+            libc::ERANGE => size *= 2,
+            _ => return String::new(),
+        }
+    }
+    String::new()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sigterm_ends_the_context() {
+        let ctx = until_terminated();
+        assert!(ctx.err().is_none());
+        // SAFETY: raising a signal whose handler this process installed.
+        unsafe { libc::raise(libc::SIGTERM) };
+        assert!(ctx.sleep(Duration::from_secs(5)).is_err());
+        assert!(ctx.err().is_some());
+    }
+
+    #[test]
+    fn the_current_user_resolves_to_the_same_uid() {
+        let name = current_username();
+        assert!(!name.is_empty());
+        // SAFETY: getuid takes no arguments and cannot fail.
+        let uid = unsafe { libc::getuid() };
+        assert_eq!(
+            syno_pkg_land_sdk::delegate::lookup_uid(&name),
+            uid.to_string()
+        );
+    }
+}

package/templates/native-rust/dsm-package.yaml

@@ -0,0 +1,89 @@
+# Standalone native DSM package: an unsigned SPK that runs as its own package
+# `synopkgland build` reads this file.
+schema: 2
+
+# INFO.package: letters and digits, starting with a letter. It also names the
+# DSM app (SYNO.SDS.<package>) and the CGI URL /webman/3rdparty/<package>/.
+package: __PACKAGE__
+version: 0.1.0
+# Increase for every SPK you hand out with the same version (INFO 0.1.0-0001).
+build: 1
+displayname: __DISPLAY_NAME__
+description: A native DSM package with a Rust backend and a DSM window UI.
+# Package Center and DSM window icon: a square PNG of at least 256x256, or a
+# folder of icon_<size>.png. Omit to use the SDK default icon.
+# icon: assets/icon.png
+maintainer: Your Name
+# Optional INFO/website metadata. Omit fields you do not need.
+# metadata:
+#   contact_email: you@example.com
+#   support_email: support@example.com
+#   homepage: https://example.com
+#   source_url: https://github.com/you/your-app
+#   issues_url: https://github.com/you/your-app/issues
+#   license: MIT
+#   long_description:
+#     en: |-
+#       Explain what the app does and how to use it.
+#     zh-TW: Translated description.
+#   changelog:          # text, or per-language like long_description
+#     en: |-
+#       - Most important change first. Omit to use Release notes.
+#     zh-TW: |-
+#       - Translated changes.
+#   screenshots: [https://example.com/screenshot.png]
+os_min_ver: "7.1-42661"
+
+# One SPK per architecture. Supported: x86_64, aarch64, armv7 (add it here to
+# build it; armv7 jobs/delegate/root-ops/daemon are built but not NAS-verified).
+arches: [x86_64, aarch64]
+
+backend:
+  kind: rust
+  dir: backend
+  package: app
+
+ui:
+  # Static files served at /webman/3rdparty/<package>/app/. app.js and app.css
+  # are required; anything else (images, chunks) is copied as is.
+  dir: ui
+
+# UI languages: i18n/messages/<locale>.json for en, zh-TW, zh-CN, ja, ko, de,
+# fr, es and it (DSM's other languages fall back to English). build checks
+# that every language has the en.json keys and placeholders, and that the keys
+# listed in the glossary use DSM's own wording.
+i18n:
+  messages: i18n/messages
+  glossary: i18n/glossary.json
+  # Package Center text per language (INFO displayname_<lang>/description_<lang>).
+  # English comes from displayname/description above.
+  info:
+    zh-TW: { description: 以 Rust 後端與 DSM 視窗介面打造的原生 DSM 套件。 }
+    zh-CN: { description: 以 Rust 后端与 DSM 窗口界面构建的原生 DSM 套件。 }
+    ja: { description: Rust バックエンドと DSM ウィンドウ UI を備えたネイティブ DSM パッケージ。 }
+    ko: { description: Rust 백엔드와 DSM 창 UI를 갖춘 네이티브 DSM 패키지. }
+    de: { description: Ein natives DSM-Paket mit Rust-Backend und DSM-Fenster-Oberfläche. }
+    fr: { description: Un paquet DSM natif avec un backend Rust et une interface en fenêtre DSM. }
+    es: { description: Un paquete nativo de DSM con backend en Rust e interfaz en ventana de DSM. }
+    it: { description: Un pacchetto DSM nativo con backend Rust e interfaccia in una finestra DSM. }
+
+# Optional SDK capabilities; delegate/rootOps share administrator-approved executor setup.
+capabilities: {}
+
+# Optional uninstall hook. DSM runs `exec args` as the package account on a
+# real uninstall (not an upgrade), before the executor is removed, with
+# SYNOPKGLAND_DELETE_STATE=0|1 and SYNOPKGLAND_REMOVE_DATA=0|1 from the wizard.
+# A failure or timeout is logged (syslog tag synopkgland-uninstall, output in
+# var/uninstall-hook.log) and never blocks the uninstall. The backend's
+# `uninstall` mode deletes the background job spool when the admin ticks
+# "delete state"; add uninstall.state.jobs to i18n/messages in every language.
+# uninstall:
+#   purge:
+#     exec: ui/cgi/api.cgi
+#     args: [uninstall]
+#     timeout: 60            # seconds, 2..120
+#     # root: purge          # rootOps only: root/purge.sh runs as root at
+#     #                      # uninstall, and only while its approval stands
+#   state:
+#     items:
+#       - key: jobs          # i18n key uninstall.state.jobs

package/templates/native-rust/gitignore

@@ -0,0 +1,2 @@
+dist/
+backend/target/