@synopackageland/templates 0.9.9 → 0.10.0

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

@@ -1,424 +0,0 @@
-//! The opt-in background jobs API: owner-scoped routes over the SDK's
-//! package-private spool. The overlay `background_routes.rs` decides whether
-//! a build serves them.
-
-mod owner;
-#[cfg(test)]
-mod owner_tests;
-mod schedule;
-#[cfg(test)]
-mod schedule_tests;
-#[cfg(test)]
-mod tests;
-mod work;
-#[cfg(test)]
-mod work_tests;
-
-pub use work::hash_work;
-
-use std::sync::Arc;
-use std::time::Duration;
-
-use serde::Deserialize;
-use serde_json::{Value, json};
-use syno_pkg_land_sdk::api::{self, Caller, Route};
-use syno_pkg_land_sdk::background::{
-    Access, JOB_TIMEOUT, Job, MAX_INPUT_BYTES, MAX_OWNER_BYTES, MAX_OWNER_PENDING, MAX_QUEUED,
-    MAX_SCHEDULES, MAX_TOTAL_BYTES, Store, StoreError, SubmitRequest, WorkerInfo,
-};
-use syno_pkg_land_sdk::ctx::{Context, CtxError};
-use syno_pkg_land_sdk::delegate;
-use syno_pkg_land_sdk::filestation::{Page, Service};
-use syno_pkg_land_sdk::http::Request;
-use syno_pkg_land_sdk::time::Timestamp;
-use syno_pkg_land_sdk::{BoxError, jsonx};
-
-use super::UidLookup;
-use super::routes::decode_params;
-
-/// How recent the worker heartbeat must be to count as running.
-const WORKER_FRESH: Duration = Duration::from_secs(15);
-
-/// Resolves the authenticated DSM username on every request. Unknown UIDs
-/// fail closed for owners and submission.
-pub fn system_uid_lookup() -> UidLookup {
-    Arc::new(delegate::lookup_uid)
-}
-
-/// What the jobs API needs of File Station: browsing and importing one file
-/// through the caller's own DSM session.
-pub trait BackgroundFiles: Send + Sync {
-    fn browse(
-        &self,
-        ctx: &Context,
-        caller: &Caller,
-        req: &Request,
-        folder: &str,
-        offset: i64,
-    ) -> Result<Page, BoxError>;
-
-    fn read_file(
-        &self,
-        ctx: &Context,
-        caller: &Caller,
-        req: &Request,
-        folder: &str,
-        rel: &str,
-    ) -> Result<Vec<u8>, BoxError>;
-}
-
-impl BackgroundFiles for Service {
-    fn browse(
-        &self,
-        ctx: &Context,
-        caller: &Caller,
-        req: &Request,
-        folder: &str,
-        offset: i64,
-    ) -> Result<Page, BoxError> {
-        Service::browse(self, ctx, caller, req, folder, offset)
-    }
-
-    fn read_file(
-        &self,
-        ctx: &Context,
-        caller: &Caller,
-        req: &Request,
-        folder: &str,
-        rel: &str,
-    ) -> Result<Vec<u8>, BoxError> {
-        Service::read_file(self, ctx, caller, req, folder, rel)
-    }
-}
-
-/// A handler of one background route; the access it works under was derived
-/// from the authenticated caller, never from params.
-type Handler =
-    fn(&BackgroundApi, &Context, &Caller, &Request, &Access, &[u8]) -> Result<Value, BoxError>;
-
-pub struct BackgroundApi {
-    store: Arc<Store>,
-    files: Arc<dyn BackgroundFiles>,
-    uid_lookup: UidLookup,
-}
-
-impl BackgroundApi {
-    pub fn new(
-        store: Arc<Store>,
-        files: Arc<dyn BackgroundFiles>,
-        uid_lookup: UidLookup,
-    ) -> Arc<Self> {
-        Arc::new(BackgroundApi {
-            store,
-            files,
-            uid_lookup,
-        })
-    }
-
-    /// The production assembly: the request-bounded spool under the data
-    /// directory and the caller's own File Station session. `synopkgland init
-    /// --with jobs` wires it in through `background_routes.rs`.
-    pub fn production(data_dir: &std::path::Path, uid_lookup: UidLookup) -> Arc<Self> {
-        Self::new(
-            Arc::new(Store::new_request(data_dir.join("background"))),
-            Arc::new(Service::local(data_dir)),
-            uid_lookup,
-        )
-    }
-
-    /// Every request authenticates against DSM afresh. Owner routes are
-    /// available to signed-in users; schedule reapproval and owner cleanup
-    /// are admin-only.
-    pub fn routes(self: &Arc<Self>) -> Vec<Route> {
-        vec![
-            self.owner("bg.status", Self::status),
-            self.owner("bg.schedules.list", Self::schedules),
-            self.owner("bg.schedules.create", Self::create_schedule),
-            self.owner("bg.schedules.disable", Self::disable_schedule),
-            self.owner("bg.schedules.delete", Self::delete_schedule),
-            self.admin("bg.schedules.enable", Self::enable_schedule),
-            self.admin("bg.jobs.purge", Self::purge),
-            self.owner("bg.browse", Self::browse),
-            self.owner("bg.jobs.submit", Self::submit),
-            self.owner("bg.jobs.list", Self::list),
-            self.owner("bg.jobs.get", Self::get),
-            self.owner("bg.jobs.cancel", Self::cancel),
-            self.owner("bg.jobs.pause", Self::pause),
-            self.owner("bg.jobs.resume", Self::resume),
-            self.owner("bg.jobs.result", Self::result),
-        ]
-    }
-
-    fn status(
-        &self,
-        ctx: &Context,
-        _: &Caller,
-        _: &Request,
-        access: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        decode_params::<jsonx::Empty>(params)?;
-        let st = self
-            .store
-            .status_for(ctx, access)
-            .map_err(background_error)?;
-        let worker = st.worker.as_ref().map(|w| {
-            json!({
-                "pid": w.pid, "uid": w.uid, "username": w.username,
-                "revision": w.revision, "at": w.at,
-                "alive": worker_alive(w, Timestamp::now()),
-            })
-        });
-        Ok(json!({
-            "owner": access.owner, "supported": true, "admin": access.admin,
-            "algorithm": st.algorithm, "revision": st.revision,
-            "queued": st.queued, "running": st.running, "worker": worker,
-            "limits": {
-                "maxInputBytes": MAX_INPUT_BYTES, "maxQueued": MAX_QUEUED,
-                "maxSchedules": MAX_SCHEDULES, "intervalSeconds": [3600, 86400, 604800],
-                "maxTotalBytes": MAX_TOTAL_BYTES, "maxOwnerPending": MAX_OWNER_PENDING,
-                "maxOwnerBytes": MAX_OWNER_BYTES,
-                "jobTimeoutSeconds": JOB_TIMEOUT.as_secs(),
-            },
-        }))
-    }
-
-    /// Lists what the caller's own File Station session can see, so the
-    /// panel can pick a file instead of typing a path. It grants nothing:
-    /// submit still reads through the same session.
-    fn browse(
-        &self,
-        ctx: &Context,
-        caller: &Caller,
-        req: &Request,
-        _: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        #[derive(Default, Deserialize)]
-        #[serde(deny_unknown_fields)]
-        struct Params {
-            #[serde(default)]
-            folder: String,
-            #[serde(default)]
-            offset: i64,
-        }
-        let params: Params = decode_params(params)?;
-        if params.offset < 0 {
-            return Err(api::Error::bad_request("offset must not be negative").into());
-        }
-        let page = self
-            .files
-            .browse(ctx, caller, req, &params.folder, params.offset)?;
-        Ok(serde_json::to_value(page)?)
-    }
-
-    fn submit(
-        &self,
-        ctx: &Context,
-        caller: &Caller,
-        req: &Request,
-        access: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        #[derive(Default, Deserialize)]
-        #[serde(deny_unknown_fields)]
-        struct Params {
-            #[serde(default)]
-            key: String,
-            #[serde(default)]
-            folder: String,
-            #[serde(default)]
-            relative: String,
-        }
-        let params: Params = decode_params(params)?;
-        if params.key.is_empty() || params.folder.is_empty() || params.relative.is_empty() {
-            return Err(api::Error::bad_request("key, folder and relative are required").into());
-        }
-        if !access.owner.valid() {
-            return Err(identity_unavailable().into());
-        }
-        let data = self
-            .files
-            .read_file(ctx, caller, req, &params.folder, &params.relative)?;
-        let (job, duplicate) = self
-            .store
-            .submit(
-                ctx,
-                SubmitRequest {
-                    key: params.key,
-                    name: base_name(&params.relative),
-                    data,
-                    submitter: access.owner.clone(),
-                },
-            )
-            .map_err(background_error)?;
-        Ok(json!({"job": job, "duplicate": duplicate}))
-    }
-
-    fn list(
-        &self,
-        ctx: &Context,
-        _: &Caller,
-        _: &Request,
-        access: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        decode_params::<jsonx::Empty>(params)?;
-        let mut jobs = self.store.list_for(ctx, access).map_err(background_error)?;
-        jobs.reverse();
-        Ok(json!({"jobs": jobs}))
-    }
-
-    fn get(
-        &self,
-        ctx: &Context,
-        _: &Caller,
-        _: &Request,
-        access: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        self.by_id(ctx, access, params, Store::get_for)
-    }
-
-    fn cancel(
-        &self,
-        ctx: &Context,
-        _: &Caller,
-        _: &Request,
-        access: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        self.by_id(ctx, access, params, Store::cancel_for)
-    }
-
-    /// Holds a queued job at once; a running job pauses at its next checkpoint.
-    fn pause(
-        &self,
-        ctx: &Context,
-        _: &Caller,
-        _: &Request,
-        access: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        self.by_id(ctx, access, params, Store::pause_for)
-    }
-
-    fn resume(
-        &self,
-        ctx: &Context,
-        _: &Caller,
-        _: &Request,
-        access: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        self.by_id(ctx, access, params, Store::resume_for)
-    }
-
-    fn by_id(
-        &self,
-        ctx: &Context,
-        access: &Access,
-        params: &[u8],
-        act: fn(&Store, &Context, &str, &Access) -> Result<Job, BoxError>,
-    ) -> Result<Value, BoxError> {
-        let id = decode_id(params)?;
-        let job = act(&self.store, ctx, &id, access).map_err(background_error)?;
-        Ok(json!({"job": job}))
-    }
-
-    fn result(
-        &self,
-        ctx: &Context,
-        _: &Caller,
-        _: &Request,
-        access: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        let id = decode_id(params)?;
-        let job = self
-            .store
-            .get_for(ctx, &id, access)
-            .map_err(background_error)?;
-        let result = match (&job.state, &job.result) {
-            (syno_pkg_land_sdk::background::State::Succeeded, Some(result)) => result,
-            _ => return Err(api::Error::new("not_ready", "the job has no result").into()),
-        };
-        Ok(json!({"job": job, "result": {
-            "jobId": job.id, "worker": job.worker, "workerRevision": job.worker_revision,
-            "algorithm": "sha256", "sha256": result.sha256, "bytes": result.bytes,
-            "inputDigest": job.input_digest, "name": job.name,
-        }}))
-    }
-}
-
-fn decode_id(params: &[u8]) -> Result<String, api::Error> {
-    #[derive(Default, Deserialize)]
-    #[serde(deny_unknown_fields)]
-    struct IdParams {
-        #[serde(default)]
-        id: String,
-    }
-    Ok(decode_params::<IdParams>(params)?.id)
-}
-
-fn identity_unavailable() -> api::Error {
-    api::Error::new("identity_unavailable", "DSM user UID could not be resolved")
-}
-
-fn worker_alive(w: &WorkerInfo, now: Timestamp) -> bool {
-    now.unix_nanos() - w.at.unix_nanos() <= WORKER_FRESH.as_nanos() as i128
-}
-
-/// The last element of a slash-separated path, as Go's path.Base.
-fn base_name(path: &str) -> String {
-    if path.is_empty() {
-        return ".".into();
-    }
-    let trimmed = path.trim_end_matches('/');
-    if trimmed.is_empty() {
-        return "/".into();
-    }
-    trimmed.rsplit('/').next().unwrap_or(trimmed).into()
-}
-
-/// Maps the spool's errors to the codes the panel knows; anything else is
-/// logged and reported as unavailable.
-fn background_error(err: BoxError) -> BoxError {
-    let message = |code: &str, text: &str| -> BoxError { api::Error::new(code, text).into() };
-    match api::find_error::<StoreError>(&*err) {
-        Some(StoreError::Busy) => message("jobs_busy", "background jobs are busy; retry later"),
-        Some(StoreError::ScheduleFull) => {
-            message("schedule-full", "the schedule limit has been reached")
-        }
-        Some(StoreError::InputUnavailable) => {
-            message("input-unavailable", "import the private copy again")
-        }
-        Some(StoreError::OwnerQueueFull) => message(
-            "owner-queue-full",
-            "your pending job limit has been reached",
-        ),
-        Some(StoreError::OwnerQuota) => message(
-            "owner-quota-exceeded",
-            "your background storage limit has been reached",
-        ),
-        Some(StoreError::Invalid) => api::Error::bad_request("invalid background request").into(),
-        Some(StoreError::TooLarge) => message(
-            "limit-exceeded",
-            "the file is larger than the background limit",
-        ),
-        Some(StoreError::QueueFull) => message("queue-full", "the background queue is full"),
-        Some(StoreError::Quota) => message("quota-exceeded", "the background spool is full"),
-        Some(StoreError::KeyConflict | StoreError::NotCancelable | StoreError::NotPausable) => {
-            message(
-                "conflict",
-                "the request conflicts with the job's current state",
-            )
-        }
-        Some(StoreError::NotFound) => message("not_found", "job not found"),
-        _ if api::find_error::<CtxError>(&*err).is_some() => err,
-        _ => {
-            eprintln!("background spool error: {err}");
-            message("unavailable", "the background spool is unavailable")
-        }
-    }
-}

package/templates/native-rust/backend/src/app/background/owner.rs

@@ -1,77 +0,0 @@
-//! Who a background request acts for: the authenticated DSM user and the UID
-//! looked up afresh for it.
-
-use std::sync::Arc;
-
-use serde::Deserialize;
-use serde_json::Value;
-use syno_pkg_land_sdk::BoxError;
-use syno_pkg_land_sdk::api::{self, Caller, Route};
-use syno_pkg_land_sdk::background::{Access, Submitter};
-use syno_pkg_land_sdk::ctx::Context;
-use syno_pkg_land_sdk::http::Request;
-
-use super::{BackgroundApi, Handler, background_error, identity_unavailable};
-use crate::app::routes::decode_params;
-
-impl BackgroundApi {
-    pub(super) fn access(&self, caller: &Caller) -> Access {
-        Access {
-            admin: caller.admin(),
-            owner: Submitter {
-                user: caller.user().to_string(),
-                uid: (self.uid_lookup)(caller.user()),
-            },
-        }
-    }
-
-    /// A route for any signed-in user whose UID resolves; administrators see
-    /// every owner's jobs and need no UID.
-    pub(super) fn owner(self: &Arc<Self>, method: &str, handler: Handler) -> Route {
-        let api = self.clone();
-        Route::handle_request(method, move |ctx, caller, req, params| {
-            let access = api.access(caller);
-            if !access.admin && !access.owner.valid() {
-                return Err(identity_unavailable().into());
-            }
-            handler(&api, ctx, caller, req, &access, params)
-        })
-    }
-
-    pub(super) fn admin(self: &Arc<Self>, method: &str, handler: Handler) -> Route {
-        let api = self.clone();
-        Route::handle_request(method, move |ctx, caller, req, params| {
-            if !caller.admin() {
-                return Err(api::Error::new(
-                    "unsupported",
-                    "background jobs need a DSM administrator",
-                )
-                .into());
-            }
-            handler(&api, ctx, caller, req, &api.access(caller), params)
-        })
-    }
-
-    pub(super) fn purge(
-        &self,
-        ctx: &Context,
-        caller: &Caller,
-        _: &Request,
-        _: &Access,
-        params: &[u8],
-    ) -> Result<Value, BoxError> {
-        #[derive(Default, Deserialize)]
-        #[serde(deny_unknown_fields)]
-        struct Params {
-            owner: Option<Submitter>,
-        }
-        let Some(owner) = decode_params::<Params>(params).ok().and_then(|p| p.owner) else {
-            return Err(api::Error::bad_request("exact owner is required").into());
-        };
-        let audit = self
-            .store
-            .purge_owner(ctx, &owner, caller.user())
-            .map_err(background_error)?;
-        Ok(serde_json::to_value(audit)?)
-    }
-}

package/templates/native-rust/backend/src/app/background/owner_tests.rs

@@ -1,174 +0,0 @@
-use serde_json::Value;
-use syno_pkg_land_sdk::background::{JobResult, Outcome, State};
-use syno_pkg_land_sdk::ctx::Context;
-
-use super::tests::{Env, data, id_params};
-use crate::app::test_support::{Stub, alice, bob, carol};
-
-fn ordinary_env() -> Env {
-    let env = Env::new();
-    env.set_uid(|name| match name {
-        "alice" => "1024".into(),
-        "bob" => "1025".into(),
-        "carol" => "1026".into(),
-        _ => String::new(),
-    });
-    env
-}
-
-fn owner_submit(env: &Env, auth: &Stub, key: &str) -> String {
-    let params = format!(r#"{{"key":"{key}","folder":"/share","relative":"a.txt"}}"#);
-    let (code, out) = env.call(auth, "bg.jobs.submit", &params);
-    assert_eq!(code, "", "submit {key}: {out}");
-    data(&out)["job"]["id"].as_str().unwrap().into()
-}
-
-fn job_count(env: &Env, auth: &Stub) -> usize {
-    let (_, out) = env.call(auth, "bg.jobs.list", "{}");
-    data(&out)["jobs"].as_array().unwrap().len()
-}
-
-#[test]
-fn owners_are_isolated_including_keys_and_counts() {
-    let env = ordinary_env();
-    let a = owner_submit(&env, &alice(), "same");
-    let b = owner_submit(&env, &bob(), "same");
-    let c = owner_submit(&env, &carol(), "same");
-    assert!(a != b && b != c, "idempotency key leaked across owners");
-    for auth in [bob(), carol()] {
-        assert_eq!(job_count(&env, &auth), 1);
-        let (_, out) = env.call(&auth, "bg.status", "{}");
-        assert_eq!(data(&out)["queued"], 1, "status leaks: {out}");
-        assert_eq!(data(&out)["admin"], false);
-    }
-    for method in [
-        "bg.jobs.get",
-        "bg.jobs.cancel",
-        "bg.jobs.pause",
-        "bg.jobs.resume",
-        "bg.jobs.result",
-    ] {
-        for id in [&a, &c, &"0".repeat(32)] {
-            let (code, out) = env.call(&bob(), method, &id_params(id));
-            assert_eq!(code, "not_found", "{method} {id}: {out}");
-        }
-    }
-    assert_eq!(job_count(&env, &alice()), 3, "admin must see all");
-    assert_eq!(env.call(&alice(), "bg.jobs.cancel", &id_params(&b)).0, "");
-}
-
-#[test]
-fn owner_result_and_uid_change_fail_closed() {
-    let env = ordinary_env();
-    let id = owner_submit(&env, &bob(), "one");
-    let ctx = Context::background();
-    env.store.claim(&ctx).unwrap();
-    env.store
-        .finish(
-            &ctx,
-            &id,
-            Outcome {
-                state: State::Succeeded,
-                result: Some(JobResult {
-                    sha256: "digest".into(),
-                    bytes: 5,
-                }),
-                ..Outcome::default()
-            },
-        )
-        .unwrap();
-    assert_eq!(env.call(&bob(), "bg.jobs.result", &id_params(&id)).0, "");
-    assert_eq!(
-        env.call(&carol(), "bg.jobs.result", &id_params(&id)).0,
-        "not_found"
-    );
-    env.set_uid(|_| "2000".into());
-    assert_eq!(
-        job_count(&env, &bob()),
-        0,
-        "same name with new UID saw old jobs"
-    );
-    assert_eq!(
-        env.call(&bob(), "bg.jobs.get", &id_params(&id)).0,
-        "not_found"
-    );
-    env.set_uid(|_| String::new());
-    assert_eq!(
-        env.call(&bob(), "bg.jobs.list", "{}").0,
-        "identity_unavailable"
-    );
-}
-
-#[test]
-fn personal_quota_and_admin_only_purge() {
-    let env = ordinary_env();
-    assert_eq!(env.call(&bob(), "bg.jobs.purge", "{}").0, "admin_required");
-    owner_submit(&env, &bob(), "one");
-    owner_submit(&env, &bob(), "two");
-    let params = r#"{"key":"three","folder":"/share","relative":"a.txt"}"#;
-    assert_eq!(
-        env.call(&bob(), "bg.jobs.submit", params).0,
-        "owner-queue-full"
-    );
-    owner_submit(&env, &carol(), "one");
-}
-
-#[test]
-fn purge_requires_an_admin_and_the_exact_owner() {
-    let env = ordinary_env();
-    let id = owner_submit(&env, &bob(), "one");
-    owner_submit(&env, &carol(), "one");
-    for params in [
-        "{}",
-        r#"{"owner":null}"#,
-        r#"{"owner":{"user":"bob","uid":"1025"},"x":1}"#,
-    ] {
-        assert_eq!(
-            env.call(&alice(), "bg.jobs.purge", params).0,
-            "bad_request",
-            "{params}"
-        );
-    }
-    let (code, out) = env.call(
-        &alice(),
-        "bg.jobs.purge",
-        r#"{"owner":{"user":"bob","uid":"1025"}}"#,
-    );
-    assert_eq!(code, "", "{out}");
-    assert_eq!(data(&out)["removed"], 1);
-    assert_eq!(
-        env.call(&alice(), "bg.jobs.get", &id_params(&id)).0,
-        "not_found"
-    );
-    assert_eq!(job_count(&env, &alice()), 1, "purge touched another owner");
-}
-
-#[test]
-fn fresh_ordinary_user_jobs_need_no_admin_setup() {
-    let env = Env::new();
-    env.set_uid(|name| if name == "bob" { "1025" } else { "1026" }.into());
-    let (code, out) = env.call(&bob(), "bg.status", "{}");
-    assert_eq!(code, "", "fresh status: {out}");
-    for key in ["enabled", "allowOrdinaryUsers"] {
-        assert!(
-            data(&out).get(key).is_none(),
-            "obsolete status switch {key}"
-        );
-    }
-    let id = owner_submit(&env, &bob(), "fresh");
-    for method in [
-        "bg.jobs.get",
-        "bg.jobs.cancel",
-        "bg.jobs.pause",
-        "bg.jobs.resume",
-    ] {
-        let (code, _) = env.call(&carol(), method, &id_params(&id));
-        assert_eq!(code, "not_found", "other owner {method}");
-    }
-    assert_eq!(env.call(&bob(), "bg.jobs.get", &id_params(&id)).0, "");
-    assert_eq!(env.call(&bob(), "bg.jobs.cancel", &id_params(&id)).0, "");
-    for method in ["bg.mode.set", "bg.users.set"] {
-        let (code, _): (String, Value) = env.call(&alice(), method, "{}");
-        assert_eq!(code, "unknown_method", "obsolete route {method}");
-    }
-}