@synopackageland/templates 0.9.8 → 0.10.0

package/templates/native-python-delegate/backend/tests/test_delegate.py

@@ -0,0 +1,58 @@
+import os
+import stat
+import tempfile
+import unittest
+
+from support import Error, call
+
+import routes
+
+SAVED = {"state": "queued"}
+
+
+class DelegateTest(unittest.TestCase):
+    def setUp(self):
+        self.dir = tempfile.TemporaryDirectory()
+        self.addCleanup(self.dir.cleanup)
+        self.staging = os.path.join(self.dir.name, "executor-staging")
+        self.app = routes.build(routes.Config("ExampleApp", self.dir.name))
+
+    def save(self, job_id="job-1", user="alice", move=lambda p: SAVED):
+        params = {"delegation_id": "d1", "job_id": job_id}
+        return call(self.app, "report.save", params, user=user, admin=False, services={"delegate.move_from_staging": move})
+
+    def test_save_moves_a_private_report_to_the_callers_destination(self):
+        reply = self.save()
+        self.assertEqual(reply.data, SAVED)
+        path = os.path.join(self.staging, "report-job-1.txt")
+        with open(path, encoding="utf-8") as f:
+            self.assertIn("alice", f.read())
+        self.assertEqual(stat.S_IMODE(os.stat(path).st_mode), 0o600)
+        move = {"delegation_id": "d1", "job_id": "job-1", "staging": "report-job-1.txt", "name": "report-job-1.txt", "size": os.path.getsize(path)}
+        self.assertEqual(reply.services, [("delegate.move_from_staging", move)])
+
+    def test_a_repeated_save_sends_the_same_file_again(self):
+        first = self.save().services
+        path = os.path.join(self.staging, "report-job-1.txt")
+        with open(path, encoding="utf-8") as f:
+            report = f.read()
+        self.assertEqual(self.save(user="bob").services, first)
+        with open(path, encoding="utf-8") as f:
+            self.assertEqual(f.read(), report)
+
+    def test_save_passes_on_the_executors_refusal(self):
+        def denied(params):
+            raise Error("DELEGATION_DENIED", "The destination is no longer allowed.")
+
+        self.assertEqual(self.save(move=denied).error["code"], "DELEGATION_DENIED")
+
+    def test_save_refuses_invalid_params_before_writing(self):
+        for params in [None, {"delegation_id": "d1"}, {"delegation_id": "d1", "job_id": "../x"}, {"delegation_id": "d1", "job_id": ""}, {"delegation_id": 1, "job_id": "j"}]:
+            with self.subTest(params=params):
+                reply = call(self.app, "report.save", params)
+                self.assertEqual((reply.error["code"], reply.services), ("bad_request", []))
+        self.assertFalse(os.path.exists(self.staging))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/templates/native-python-jobs/backend/app/jobs.py

@@ -0,0 +1,40 @@
+"""Background jobs: hash a NAS file the caller may read.
+
+The SDK's worker runs each job as the package account: it hashes the job's
+input (SHA-256) and keeps the result for the job's owner, the caller. The
+runtime serves files.read with the caller's DSM session and bg.* for the
+caller's own jobs only.
+"""
+
+import os
+import shutil
+import tempfile
+
+from synopkgland_app import Error
+
+from params import fields
+
+# A job's input is at most 512 KiB, copied into the job when it is submitted.
+MAX_INPUT = 512 * 1024
+
+
+def register(app, cfg):
+    app.method("hash.submit")(lambda ctx, params: submit(cfg, ctx, params))
+    app.method("hash.get")(lambda ctx, params: ctx.runtime("bg.get", fields(params, id=str)))
+    app.method("hash.cancel")(lambda ctx, params: ctx.runtime("bg.cancel", fields(params, id=str)))
+
+
+def submit(cfg, ctx, params):
+    p = fields(params, key=str, path=str)
+    read = ctx.runtime("files.read", {"path": p["path"]})
+    if read["size"] > MAX_INPUT:
+        raise Error("limit_exceeded", "The file is larger than allowed.")
+    # bg.submit takes its input from the data directory; the call's spool is elsewhere.
+    inputs = os.path.join(cfg.data_dir, "hash-inputs")
+    os.makedirs(inputs, mode=0o700, exist_ok=True)
+    with open(read["path"], "rb") as source, tempfile.NamedTemporaryFile(dir=inputs, delete=False) as copy:
+        shutil.copyfileobj(source, copy)
+    try:
+        return ctx.runtime("bg.submit", {"key": p["key"], "name": os.path.basename(p["path"]), "input": copy.name})
+    finally:
+        os.unlink(copy.name)

package/templates/native-python-jobs/backend/tests/test_jobs.py

@@ -0,0 +1,72 @@
+import os
+import tempfile
+import unittest
+
+from support import Error, call
+
+import routes
+
+JOB = {"job": {"id": "j1", "state": "queued"}, "duplicate": False}
+
+
+class JobsTest(unittest.TestCase):
+    def setUp(self):
+        self.dir = tempfile.TemporaryDirectory()
+        self.addCleanup(self.dir.cleanup)
+        self.data = os.path.join(self.dir.name, "var")
+        os.mkdir(self.data)
+        self.app = routes.build(routes.Config("ExampleApp", self.data))
+        self.submitted = []
+
+    def spool(self, content):
+        path = os.path.join(self.dir.name, "spool")
+        with open(path, "wb") as f:
+            f.write(content)
+        return {"path": path, "size": len(content)}
+
+    def submit(self, params):
+        # The runtime reads the input file while it answers bg.submit.
+        with open(params["input"], "rb") as f:
+            self.submitted.append(dict(params, content=f.read()))
+        return JOB
+
+    def test_submit_hashes_a_copy_of_the_callers_file(self):
+        services = {"files.read": lambda p: self.spool(b"hello"), "bg.submit": self.submit}
+        reply = call(self.app, "hash.submit", {"key": "k1", "path": "/home/report.txt"}, services=services)
+        self.assertEqual(reply.data, JOB)
+        self.assertEqual([op for op, _ in reply.services], ["files.read", "bg.submit"])
+        self.assertEqual(reply.services[0][1], {"path": "/home/report.txt"})
+        [submitted] = self.submitted
+        self.assertEqual((submitted["key"], submitted["name"], submitted["content"]), ("k1", "report.txt", b"hello"))
+        self.assertTrue(submitted["input"].startswith(self.data + os.sep))
+        self.assertFalse(os.path.exists(submitted["input"]), "the copy is removed once submitted")
+
+    def test_submit_refuses_a_file_over_the_job_input_limit(self):
+        services = {"files.read": lambda p: self.spool(b"x" * (512 * 1024 + 1)), "bg.submit": self.submit}
+        reply = call(self.app, "hash.submit", {"key": "k1", "path": "/home/big.bin"}, services=services)
+        self.assertEqual(reply.error["code"], "limit_exceeded")
+        self.assertEqual(self.submitted, [])
+
+    def test_submit_passes_on_the_runtimes_refusal(self):
+        def unreadable(params):
+            raise Error("read_failed", "Unable to read the file.")
+
+        reply = call(self.app, "hash.submit", {"key": "k1", "path": "/home/a"}, services={"files.read": unreadable})
+        self.assertEqual(reply.error["code"], "read_failed")
+
+    def test_submit_refuses_invalid_params_before_any_service(self):
+        for params in [None, {"key": "k1"}, {"key": 1, "path": "/home/a"}, {"key": "k1", "path": "/home/a", "x": 1}]:
+            with self.subTest(params=params):
+                reply = call(self.app, "hash.submit", params)
+                self.assertEqual((reply.error["code"], reply.services), ("bad_request", []))
+
+    def test_get_and_cancel_act_on_the_callers_job(self):
+        for method, op in [("hash.get", "bg.get"), ("hash.cancel", "bg.cancel")]:
+            with self.subTest(method=method):
+                reply = call(self.app, method, {"id": "j1"}, services={op: lambda p: JOB["job"]})
+                self.assertEqual((reply.data, reply.services), (JOB["job"], [(op, {"id": "j1"})]))
+                self.assertEqual(call(self.app, method, {}).error["code"], "bad_request")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/templates/native-python-root-ops/backend/app/root_ops.py

@@ -0,0 +1,18 @@
+"""Root operations: run root/whoami.sh as root.
+
+The executor runs only the root programs an administrator approved, and
+checks the caller's DSM session and Application Privileges itself; the App
+names the program and never runs anything as root.
+"""
+
+from synopkgland_app import Error
+
+
+def register(app, cfg):
+    app.method("whoami.run")(lambda ctx, params: whoami(ctx, params))
+
+
+def whoami(ctx, params):
+    if params not in (None, {}):
+        raise Error.bad_request("whoami.run takes no params")
+    return ctx.runtime("root.run", {"name": "whoami"})

package/templates/native-python-root-ops/backend/tests/test_root_ops.py

@@ -0,0 +1,34 @@
+import tempfile
+import unittest
+
+from support import Error, call
+
+import routes
+
+
+class RootOpsTest(unittest.TestCase):
+    def setUp(self):
+        self.dir = tempfile.TemporaryDirectory()
+        self.addCleanup(self.dir.cleanup)
+        self.app = routes.build(routes.Config("ExampleApp", self.dir.name))
+
+    def test_whoami_runs_the_approved_root_program(self):
+        output = {"exit_code": 0, "stdout": "0\n", "stderr": ""}
+        for params in [None, {}]:
+            with self.subTest(params=params):
+                reply = call(self.app, "whoami.run", params, services={"root.run": lambda p: output})
+                self.assertEqual((reply.data, reply.services), (output, [("root.run", {"name": "whoami"})]))
+
+    def test_whoami_passes_on_the_executors_refusal(self):
+        def paused(params):
+            raise Error("EXECUTOR_PAUSED", "The executor is paused.")
+
+        reply = call(self.app, "whoami.run", {}, services={"root.run": paused})
+        self.assertEqual(reply.error["code"], "EXECUTOR_PAUSED")
+
+    def test_whoami_takes_no_params(self):
+        self.assertEqual(call(self.app, "whoami.run", {"name": "other"}).error["code"], "bad_request")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/templates/native-python-vue/README.md

@@ -0,0 +1,56 @@
+# Native Python with Vue
+
+The Vue shell is the same as the Go template's. Edit `frontend/src/App.vue`
+and `main.ts` to build a DSM-window app with the public `@synopackageland/ui`
+components and embedded theme. The shell, sign-in, files, portal, jobs and
+delegate components come from `@synopackageland/sdk/vue` (types from
+`@synopackageland/sdk`); its version must equal the `backend.sdk` in dsm-package.yaml. See
+<https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
+
+```sh
+cd frontend
+npm ci
+npm test
+npm run build
+```
+
+The base app reads package status and edits the package greeting through
+`ctx.call`. Errors show the app's own `frontend/src/i18n` text, or the SDK's
+`bridgeErrorCopy` for the codes the bridge runtime adds (`app_unavailable`
+and the services' refusals). Each window has its own Vue mount, request state
+and host subscriptions; unmount disposes subscriptions and ignores late responses.
+
+The `--with jobs`, `root-ops` and `delegate` examples add their methods to
+the Python App; the shell's panels call them with `ctx.call`. The SDK's
+background-jobs page and executor settings call the runtime's own browser
+methods (`bg.*`, `executor.*`); check the SDK release notes for the ones a
+bridge App's runtime serves.
+
+Use the installed `@synopackageland/ui`; package.json pins its version.
+`App.vue` lays the shell out with the SDK's `AppShell` (`@synopackageland/sdk/vue`):
+`pages` from `shellPages`, the header buttons in `#actions` and the pages in its
+default slot. Given `ctx`, it follows the launch. In a DSM desktop window it
+keeps `wide-layout="window"`, even maximized; the DSM host sets the 700px
+minimum window width. A Portal or standalone launch owns the whole page
+(`ctx.fullPage`, from the generated window): `AppShell` takes
+`wide-layout="web"` (the SaaS layout at 1200px or wider, mobile on a phone) and
+a device-width viewport, undone at unmount, since DSM's page has no
+device-width viewport. Its full-page sidebar names the App with
+`ctx.displayName` and `ctx.appIcon` (without them the page title and icon) and
+shows the signed-in DSM account and its role from `ctx.user`. See the ui's
+`docs/adaptive-layout.md`.
+`AppShell`'s `app-root` wraps it in an app-local `AppRoot` (app modal scope, on
+a full page as well, bounded at `height: 100%`) with the UI locale from
+`locale`; do not add another `AppRoot`.
+In a DSM window (not a full page) that `AppRoot` takes
+`dialog-bounds="viewport"`, so Dialogs can be dragged out of the window, and
+pressing one calls `ctx.host.activateWindow()` to bring the window to the
+front. Elsewhere Dialogs stay inside the App. A confirmed sign-in need sets
+`denied`: the `#denied` slot's `LoginPage` takes the place of the App's pages.
+Import `themes/dsm7-embedded.css` and assign each mount a unique
+`app.config.idPrefix` before mounting.
+
+Start with AGENTS.md, `synopkgland skill list` and `synopkgland skill path`.
+Read `synopkgland skill show ui-vue` for direct Vue component work. For UI
+discovery, run `npx --no syno-pkg-land-ui catalog --json` and
+`npx --no syno-pkg-land-ui describe Button --json` from the installed frontend.

package/templates/native-python-vue/gitignore

@@ -0,0 +1,3 @@
+dist/
+__pycache__/
+node_modules/