@synopackageland/templates 0.9.9 → 0.10.1

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

@@ -0,0 +1,352 @@
+//! The App's methods. Register a method in `build` and list it in
+//! dsm-package.yaml's `backend.methods`; give it a rule in permissions.json
+//! unless only administrators may call it. The runtime has checked the DSM
+//! session, the entry gate and that rule before a handler runs.
+
+use serde::{Deserialize, Serialize};
+use serde_json::{Value, json};
+use std::fs;
+use std::io::{ErrorKind, Write};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+use syno_pkg_land_app::{App, Context, Error, Params};
+
+/// Where the App's state lives; the runtime sets the environment.
+#[derive(Clone)]
+pub struct Config {
+    pub package: String,
+    /// The package's own data directory (/var/packages/<package>/var), kept across upgrades.
+    pub data_dir: PathBuf,
+    pub packages_root: PathBuf,
+}
+
+impl Config {
+    pub fn from_env() -> Self {
+        let var = |name| std::env::var_os(name).unwrap_or_default();
+        Config {
+            package: var("SYNOPKGLAND_PACKAGE").to_string_lossy().into_owned(),
+            data_dir: var("SYNOPKGLAND_DATA_DIR").into(),
+            packages_root: "/var/packages".into(),
+        }
+    }
+}
+
+pub fn build(cfg: Config) -> App {
+    let mut app = App::new();
+    let c = cfg.clone();
+    app.method("app.status", move |ctx, _| Ok(status(&c, ctx)));
+    let c = cfg.clone();
+    app.method("greeting.get", move |_, _| get_greeting(&c));
+    let c = cfg.clone();
+    app.method("greeting.set", move |ctx, params| {
+        set_greeting(&c, ctx, params)
+    });
+    // Each capability module is a stub until `synopkgland init --with` adds its example.
+    crate::jobs::register(&mut app, &cfg);
+    crate::root_ops::register(&mut app, &cfg);
+    crate::delegate::register(&mut app, &cfg);
+    app
+}
+
+fn status(cfg: &Config, ctx: &Context) -> Value {
+    let (uid, gid) = unsafe { (libc::getuid(), libc::getgid()) };
+    let mut status = json!({
+        "package": cfg.package,
+        "version": installed_version(cfg),
+        "user": ctx.user,
+        "admin": ctx.admin,
+        "process": {"uid": uid, "gid": gid},
+        "language": "Rust",
+        "platform": format!("{}/{}", std::env::consts::OS, std::env::consts::ARCH),
+        "time": utc_now(),
+    });
+    // Served only when dsm-package.yaml declares a portal.
+    if let Ok(portal) = ctx.runtime::<Value>("portal.status", &()) {
+        status["portal"] = portal;
+    }
+    status
+}
+
+/// The version in the package's INFO, or "" outside DSM.
+fn installed_version(cfg: &Config) -> String {
+    let info =
+        fs::read_to_string(cfg.packages_root.join(&cfg.package).join("INFO")).unwrap_or_default();
+    info.lines()
+        .find_map(|line| line.strip_prefix("version="))
+        .map(|v| v.trim_matches('"').to_string())
+        .unwrap_or_default()
+}
+
+#[derive(Serialize, Deserialize)]
+struct Greeting {
+    text: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    updated_by: Option<String>,
+}
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct SetGreeting {
+    text: String,
+}
+
+fn greeting_path(cfg: &Config) -> PathBuf {
+    cfg.data_dir.join("greeting.json")
+}
+
+fn get_greeting(cfg: &Config) -> Result<Greeting, Error> {
+    match fs::read(greeting_path(cfg)) {
+        Err(e) if e.kind() == ErrorKind::NotFound => Ok(Greeting {
+            text: "Hello".into(),
+            updated_by: None,
+        }),
+        Err(e) => Err(internal(e)),
+        Ok(data) => serde_json::from_slice(&data).map_err(internal),
+    }
+}
+
+fn set_greeting(cfg: &Config, ctx: &Context, params: &Params) -> Result<Greeting, Error> {
+    let SetGreeting { text } = params.decode()?;
+    if !(1..=200).contains(&text.chars().count()) {
+        return Err(Error::bad_request("text must be 1 to 200 characters"));
+    }
+    let greeting = Greeting {
+        text,
+        updated_by: Some(ctx.user.clone()),
+    };
+    write_file_atomic(
+        &greeting_path(cfg),
+        &serde_json::to_vec(&greeting).map_err(internal)?,
+    )
+    .map_err(internal)?;
+    Ok(greeting)
+}
+
+/// An unexpected failure: logged to stderr (the package's log), `internal` for the browser.
+pub fn internal(e: impl std::fmt::Display) -> Error {
+    eprintln!("{e}");
+    Error::new("internal", "internal error")
+}
+
+/// Replaces path in one rename, so readers never see half a file.
+pub fn write_file_atomic(path: &Path, data: &[u8]) -> std::io::Result<()> {
+    let nanos = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| d.subsec_nanos());
+    let tmp = path.with_file_name(format!(".tmp-{}-{nanos}", std::process::id()));
+    let written = fs::File::create_new(&tmp)
+        .and_then(|mut f| f.write_all(data))
+        .and_then(|_| fs::rename(&tmp, path));
+    if written.is_err() {
+        let _ = fs::remove_file(&tmp);
+    }
+    written
+}
+
+/// Now as 2006-01-02T15:04:05Z.
+pub fn utc_now() -> String {
+    let secs = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| d.as_secs());
+    let (days, rest) = (secs / 86400, secs % 86400);
+    // Civil date from days since 1970-01-01 (Howard Hinnant's algorithm).
+    let z = days as i64 + 719_468;
+    let era = z.div_euclid(146_097);
+    let doe = z - era * 146_097;
+    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let day = doy - (153 * mp + 2) / 5 + 1;
+    let month = if mp < 10 { mp + 3 } else { mp - 9 };
+    let year = yoe + era * 400 + i64::from(month <= 2);
+    format!(
+        "{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}Z",
+        rest / 3600,
+        rest % 3600 / 60,
+        rest % 60
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_support::{Services, TempDir, call};
+    use serde_json::{Value, json};
+    use std::fs;
+
+    fn setup() -> (TempDir, Config) {
+        let dir = TempDir::new();
+        let cfg = Config {
+            package: "ExampleApp".into(),
+            data_dir: dir.path().join("var"),
+            packages_root: dir.path().join("packages"),
+        };
+        fs::create_dir(&cfg.data_dir).unwrap();
+        (dir, cfg)
+    }
+
+    fn files(cfg: &Config) -> Vec<String> {
+        fs::read_dir(&cfg.data_dir)
+            .unwrap()
+            .map(|e| e.unwrap().file_name().into_string().unwrap())
+            .collect()
+    }
+
+    #[test]
+    fn status_reports_the_caller_and_the_installed_version() {
+        let (_dir, cfg) = setup();
+        fs::create_dir_all(cfg.packages_root.join("ExampleApp")).unwrap();
+        fs::write(
+            cfg.packages_root.join("ExampleApp/INFO"),
+            "package=\"ExampleApp\"\nversion=\"0.1.0-0001\"\n",
+        )
+        .unwrap();
+        let reply = call(
+            build(cfg),
+            "app.status",
+            Value::Null,
+            "alice",
+            &Services::new(),
+        );
+        assert_eq!(reply.code(), "");
+        let s = reply.data;
+        assert_eq!(
+            (&s["package"], &s["version"], &s["user"], &s["admin"]),
+            (
+                &json!("ExampleApp"),
+                &json!("0.1.0-0001"),
+                &json!("alice"),
+                &json!(false)
+            )
+        );
+        let (uid, gid) = unsafe { (libc::getuid(), libc::getgid()) };
+        assert_eq!(s["process"], json!({"uid": uid, "gid": gid}));
+        assert_eq!(s["language"], "Rust");
+        assert_eq!(
+            s["platform"],
+            format!("{}/{}", std::env::consts::OS, std::env::consts::ARCH)
+        );
+        let time = s["time"].as_str().unwrap();
+        assert!(
+            time.len() == 20 && time.ends_with('Z') && &time[10..11] == "T",
+            "{time}"
+        );
+    }
+
+    #[test]
+    fn status_without_info_has_no_version() {
+        let (_dir, cfg) = setup();
+        let reply = call(
+            build(cfg),
+            "app.status",
+            Value::Null,
+            "admin",
+            &Services::new(),
+        );
+        assert_eq!(reply.data["version"], "");
+    }
+
+    #[test]
+    fn status_shows_the_portal_when_the_runtime_offers_it() {
+        let (_dir, cfg) = setup();
+        let portal = json!({"enabled": true, "alias": "example"});
+        let answer = portal.clone();
+        let services: Services = [(
+            "portal.status",
+            Box::new(move |_: &Value| Ok(answer.clone())) as _,
+        )]
+        .into();
+        let reply = call(build(cfg), "app.status", Value::Null, "admin", &services);
+        assert_eq!(reply.data["portal"], portal);
+        assert_eq!(
+            reply.services,
+            vec![("portal.status".to_string(), Value::Null)]
+        );
+    }
+
+    #[test]
+    fn status_without_a_portal_leaves_it_out() {
+        let (_dir, cfg) = setup();
+        let reply = call(
+            build(cfg),
+            "app.status",
+            Value::Null,
+            "admin",
+            &Services::new(),
+        );
+        assert_eq!(reply.code(), "");
+        assert!(reply.data.get("portal").is_none());
+    }
+
+    #[test]
+    fn greeting_defaults_to_hello() {
+        let (_dir, cfg) = setup();
+        let reply = call(
+            build(cfg),
+            "greeting.get",
+            Value::Null,
+            "admin",
+            &Services::new(),
+        );
+        assert_eq!(reply.data, json!({"text": "Hello"}));
+    }
+
+    #[test]
+    fn greeting_set_stores_the_text_and_who_set_it() {
+        let (_dir, cfg) = setup();
+        let reply = call(
+            build(cfg.clone()),
+            "greeting.set",
+            json!({"text": "Hi 👋"}),
+            "alice",
+            &Services::new(),
+        );
+        assert_eq!(reply.data, json!({"text": "Hi 👋", "updated_by": "alice"}));
+        let reply = call(
+            build(cfg.clone()),
+            "greeting.get",
+            Value::Null,
+            "admin",
+            &Services::new(),
+        );
+        assert_eq!(reply.data, json!({"text": "Hi 👋", "updated_by": "alice"}));
+        assert_eq!(files(&cfg), ["greeting.json"]);
+    }
+
+    #[test]
+    fn greeting_counts_characters_not_bytes() {
+        let (_dir, cfg) = setup();
+        let reply = call(
+            build(cfg),
+            "greeting.set",
+            json!({"text": "é".repeat(200)}),
+            "admin",
+            &Services::new(),
+        );
+        assert_eq!(reply.code(), "");
+    }
+
+    #[test]
+    fn greeting_set_refuses_invalid_params_and_keeps_the_old_text() {
+        let (_dir, cfg) = setup();
+        for params in [
+            Value::Null,
+            json!([]),
+            json!({}),
+            json!({"text": ""}),
+            json!({"text": "x".repeat(201)}),
+            json!({"text": 5}),
+            json!({"text": "hi", "extra": 1}),
+        ] {
+            let reply = call(
+                build(cfg.clone()),
+                "greeting.set",
+                params.clone(),
+                "admin",
+                &Services::new(),
+            );
+            assert_eq!(reply.code(), "bad_request", "{params}");
+        }
+        assert!(files(&cfg).is_empty());
+    }
+}

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

@@ -0,0 +1,91 @@
+//! Calls an App method the way the runtime does: over a channel, with the
+//! hello, the call, the services the method asks for and its result.
+
+use serde_json::{Value, json};
+use std::collections::HashMap;
+use std::io::{BufRead, BufReader, Write};
+use std::os::unix::net::UnixStream;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::thread;
+use syno_pkg_land_app::{App, Error};
+
+/// Each op the method may ask for: its result, or a refusal. An op it lacks is `unknown_service`.
+pub type Services = HashMap<&'static str, Box<dyn Fn(&Value) -> Result<Value, Error>>>;
+
+pub struct Reply {
+    pub data: Value,
+    pub error: Option<Error>,
+    /// The services the method asked for, in order.
+    pub services: Vec<(String, Value)>,
+}
+
+impl Reply {
+    pub fn code(&self) -> &str {
+        self.error.as_ref().map_or("", |e| e.code.as_str())
+    }
+}
+
+pub fn call(app: App, method: &str, params: Value, user: &str, services: &Services) -> Reply {
+    let (runtime, app_end) = UnixStream::pair().unwrap();
+    let w = app_end.try_clone().unwrap();
+    let serving = thread::spawn(move || app.serve(app_end, w));
+    let mut out = runtime.try_clone().unwrap();
+    let mut send = |frame: Value| out.write_all(format!("{frame}\n").as_bytes()).unwrap();
+    let mut lines = BufReader::new(runtime.try_clone().unwrap()).lines();
+    send(json!({"t": "hello", "versions": [1]}));
+    lines.next();
+    let ctx = json!({"user": user, "admin": user == "admin", "locale": "en", "request_id": "0".repeat(32), "deadline_ms": 30000});
+    send(json!({"t": "call", "id": "1", "method": method, "params": params, "ctx": ctx}));
+    let mut asked = Vec::new();
+    for line in lines {
+        let frame: Value = serde_json::from_str(&line.unwrap()).unwrap();
+        if frame["t"] == "result" {
+            runtime.shutdown(std::net::Shutdown::Both).unwrap();
+            serving.join().unwrap();
+            let error = (frame["ok"] == false)
+                .then(|| serde_json::from_value(frame["error"].clone()).unwrap());
+            return Reply {
+                data: frame["data"].clone(),
+                error,
+                services: asked,
+            };
+        }
+        let op = frame["op"].as_str().unwrap().to_string();
+        asked.push((op.clone(), frame["params"].clone()));
+        let answer = match services.get(op.as_str()) {
+            None => Err(Error::new("unknown_service", &format!("no service {op}"))),
+            Some(service) => service(&frame["params"]),
+        };
+        send(match answer {
+            Ok(result) => {
+                json!({"t": "svc_result", "id": frame["id"], "ok": true, "result": result})
+            }
+            Err(e) => json!({"t": "svc_result", "id": frame["id"], "ok": false, "error": e}),
+        });
+    }
+    panic!("the App ended the channel without a result");
+}
+
+/// A directory removed when the test ends.
+pub struct TempDir(PathBuf);
+
+impl TempDir {
+    pub fn new() -> Self {
+        static NEXT: AtomicU32 = AtomicU32::new(0);
+        let n = NEXT.fetch_add(1, Ordering::SeqCst);
+        let dir = std::env::temp_dir().join(format!("app-test-{}-{n}", std::process::id()));
+        std::fs::create_dir_all(&dir).unwrap();
+        TempDir(dir)
+    }
+
+    pub fn path(&self) -> &Path {
+        &self.0
+    }
+}
+
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}

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

@@ -35,13 +35,20 @@ maintainer: Your Name
 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).
+# build it; armv7 is built but not NAS-verified).
 arches: [x86_64, aarch64]
 
+# The SDK's Go runtime is the CGI: it checks the DSM session, the entry gate
+# and permissions.json, then runs the App binary as the package account, once
+# per call. The build cross-compiles the Cargo project in backend (cargo
+# zigbuild) and reads the SDK release from Cargo.lock. A cross-compiled binary
+# cannot run on the build machine, so methods lists every method the App
+# registers, as `synopkgland check` compares them with the App's hello.
 backend:
-  kind: rust
+  runtime: rust
   dir: backend
-  package: app
+  entry: app
+  methods: [app.status, greeting.get, greeting.set]
 
 ui:
   # Static files served at /webman/3rdparty/<package>/app/. app.js and app.css
@@ -69,21 +76,3 @@ i18n:
 
 # 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-delegate/backend/src/delegate.rs

@@ -0,0 +1,171 @@
+//! Delegated writes: save a report into a folder the caller chose. The
+//! package writes the report into its executor staging directory; the
+//! executor moves it to the caller's destination with the caller's own
+//! permission, so the package never needs write access to that folder.
+
+use crate::routes::{Config, internal, utc_now};
+use serde::Deserialize;
+use serde_json::{Value, json};
+use std::fs::OpenOptions;
+use std::io::{ErrorKind, Write};
+use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt};
+use syno_pkg_land_app::{App, Context, Error, Params};
+
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct SaveReport {
+    delegation_id: String,
+    job_id: String,
+}
+
+pub fn register(app: &mut App, cfg: &Config) {
+    let cfg = cfg.clone();
+    app.method("report.save", move |ctx, params| save(&cfg, ctx, params));
+}
+
+/// A job id names one file: a letter or digit, then up to 127 of them or `._-`.
+fn valid_job_id(id: &str) -> bool {
+    let ok = |c: char| c.is_ascii_alphanumeric() || "._-".contains(c);
+    id.len() <= 128 && id.starts_with(|c: char| c.is_ascii_alphanumeric()) && id.chars().all(ok)
+}
+
+fn save(cfg: &Config, ctx: &Context, params: &Params) -> Result<Value, Error> {
+    let p: SaveReport = params.decode()?;
+    if !valid_job_id(&p.job_id) {
+        return Err(Error::bad_request(
+            "job_id must be 1 to 128 letters, digits, '.', '_' or '-'",
+        ));
+    }
+    let staging = cfg.data_dir.join("executor-staging");
+    std::fs::DirBuilder::new()
+        .recursive(true)
+        .mode(0o700)
+        .create(&staging)
+        .map_err(internal)?;
+    let name = format!("report-{}.txt", p.job_id);
+    let path = staging.join(&name);
+    // A retried save sends the file it wrote the first time.
+    match OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o600)
+        .open(&path)
+    {
+        Ok(mut file) => {
+            let report = format!("Report for {}, {}\n", ctx.user, utc_now());
+            file.write_all(report.as_bytes()).map_err(internal)?;
+        }
+        Err(e) if e.kind() == ErrorKind::AlreadyExists => {}
+        Err(e) => return Err(internal(e)),
+    }
+    let size = std::fs::metadata(&path).map_err(internal)?.len();
+    ctx.runtime(
+        "delegate.move_from_staging",
+        &json!({"delegation_id": p.delegation_id, "job_id": p.job_id, "staging": name, "name": name, "size": size}),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::routes::{Config, build};
+    use crate::test_support::{Services, TempDir, call};
+    use serde_json::{Value, json};
+    use std::os::unix::fs::PermissionsExt;
+    use syno_pkg_land_app::Error;
+
+    fn setup() -> (TempDir, Config) {
+        let dir = TempDir::new();
+        let cfg = Config {
+            package: "ExampleApp".into(),
+            data_dir: dir.path().into(),
+            packages_root: dir.path().into(),
+        };
+        (dir, cfg)
+    }
+
+    fn moved() -> Services {
+        [(
+            "delegate.move_from_staging",
+            Box::new(|_: &Value| Ok(json!({"state": "queued"}))) as _,
+        )]
+        .into()
+    }
+
+    fn save(cfg: &Config, user: &str, services: &Services) -> crate::test_support::Reply {
+        call(
+            build(cfg.clone()),
+            "report.save",
+            json!({"delegation_id": "d1", "job_id": "job-1"}),
+            user,
+            services,
+        )
+    }
+
+    #[test]
+    fn save_moves_a_private_report_to_the_callers_destination() {
+        let (_dir, cfg) = setup();
+        let reply = save(&cfg, "alice", &moved());
+        assert_eq!(reply.data, json!({"state": "queued"}));
+        let path = cfg.data_dir.join("executor-staging/report-job-1.txt");
+        assert!(std::fs::read_to_string(&path).unwrap().contains("alice"));
+        let meta = std::fs::metadata(&path).unwrap();
+        assert_eq!(meta.permissions().mode() & 0o777, 0o600);
+        let params = json!({"delegation_id": "d1", "job_id": "job-1", "staging": "report-job-1.txt", "name": "report-job-1.txt", "size": meta.len()});
+        assert_eq!(
+            reply.services,
+            vec![("delegate.move_from_staging".to_string(), params)]
+        );
+    }
+
+    #[test]
+    fn a_repeated_save_sends_the_same_file_again() {
+        let (_dir, cfg) = setup();
+        let first = save(&cfg, "alice", &moved()).services;
+        let path = cfg.data_dir.join("executor-staging/report-job-1.txt");
+        let report = std::fs::read_to_string(&path).unwrap();
+        assert_eq!(save(&cfg, "bob", &moved()).services, first);
+        assert_eq!(std::fs::read_to_string(&path).unwrap(), report);
+    }
+
+    #[test]
+    fn save_passes_on_the_executors_refusal() {
+        let (_dir, cfg) = setup();
+        let services: Services = [(
+            "delegate.move_from_staging",
+            Box::new(|_: &Value| {
+                Err(Error::new(
+                    "DELEGATION_DENIED",
+                    "The destination is no longer allowed.",
+                ))
+            }) as _,
+        )]
+        .into();
+        assert_eq!(save(&cfg, "alice", &services).code(), "DELEGATION_DENIED");
+    }
+
+    #[test]
+    fn save_refuses_invalid_params_before_writing() {
+        let (_dir, cfg) = setup();
+        for params in [
+            Value::Null,
+            json!({"delegation_id": "d1"}),
+            json!({"delegation_id": "d1", "job_id": "../x"}),
+            json!({"delegation_id": "d1", "job_id": ""}),
+            json!({"delegation_id": 1, "job_id": "j"}),
+        ] {
+            let reply = call(
+                build(cfg.clone()),
+                "report.save",
+                params.clone(),
+                "alice",
+                &Services::new(),
+            );
+            assert_eq!(
+                (reply.code(), reply.services.len()),
+                ("bad_request", 0),
+                "{params}"
+            );
+        }
+        assert!(!cfg.data_dir.join("executor-staging").exists());
+    }
+}