@synopackageland/cli 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.40.0 (2026-10-29)
+
+- `daemon.backend: true` runs the App's own native backend
+  (`ui/cgi/api.cgi`) as the package daemon with `args`, instead of a separate
+  `exec`. The binary keeps the route audit and build digests of the CGI
+  build. `targets` becomes optional; with `daemon.node` the CLI writes its
+  Node launcher and passes `SYNOPKGLAND_NODE` and
+  `SYNOPKGLAND_DAEMON_PAYLOAD` so the backend can start Node children itself.
+  It needs an SDK whose daemon controller supports backend daemons
+  (`STANDALONE_DAEMON_BUILD_FAILED` otherwise) and cannot be combined with
+  `identity_gateway`. `inspect` verifies the `backend` config and the
+  backend's mode.
+- New skill reference `daemon-mode`: when a resident backend daemon pays off
+  and when to stay with the CGI, with a decision table, the factors to
+  measure and decision steps.
+- The route audit accepts `api.ServeIngress` (SDK) like `cgi.Serve`: called
+  directly, and never with a private or raw HTTP handler.
+- Pin templates 0.35.0 and its SDK/App 0.37.0 defaults. `daemon.backend` and
+  `api.ServeIngress` need SDK/App 0.37.0.
+
 ## 0.39.0 (2026-10-29)
 
 - Add schema-2 `dependencies.packages` for DSM package dependencies independent

package/README.md

@@ -78,7 +78,7 @@ alongside npm lockfiles. Do not disable checksum verification for public SDK
 packages. Private mirrors can use explicitly configured Go authentication and
 checksum settings; a failed fetch reports `SDK_DOWNLOAD_FAILED`.
 
-CLI 0.38.0 uses templates ~0.34.0, whose default SDK pin is 0.36.0. Compose import and SDK defaults
+CLI 0.40.0 uses templates ~0.35.0, whose default SDK pin is 0.37.0. Compose import and SDK defaults
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 Every App method must be declared in the permissions table. Dynamic names and
 custom HTTP dispatchers are rejected. With SDK 0.33.0, use fixed
@@ -89,8 +89,8 @@ unimported development commands are excluded. Use
 authentication. See [App entry and registration](docs/app-entry.md).
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.38.0 depends on `~0.34.0`: npm installation or
-update can select the latest templates patch in the 0.34 minor line. Templates
+`@synopackageland/templates`. CLI 0.40.0 depends on `~0.35.0`: npm installation or
+update can select the latest templates patch in the 0.35 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;
 commit a lockfile and use `npm ci` to reproduce a chosen dependency tree.

package/assets/go/route-audit/main.go

@@ -600,6 +600,10 @@ func main() {
 					if !direct[selector] {
 						problem(selector.Pos(), "route constructor aliases cannot be audited; register methods directly")
 					}
+				case "ServeIngress":
+					if !direct[selector] {
+						problem(selector.Pos(), "ingress constructor aliases cannot be audited")
+					}
 				}
 			}
 			if module == "net/http" {
@@ -659,6 +663,10 @@ func main() {
 			if module == "net/http/cgi" && selector.Sel.Name == "Serve" && len(call.Args) > 0 && reusesBoundary(call.Args[0], src, sources, safe, map[ast.Node]bool{}) {
 				problem(call.Pos(), "private or raw HTTP handler reused outside its SDK boundary")
 			}
+			// The daemon ingress serves the same browser requests as cgi.Serve.
+			if module == sdkModule+"/api" && selector.Sel.Name == "ServeIngress" && len(call.Args) > 1 && reusesBoundary(call.Args[1], src, sources, safe, map[ast.Node]bool{}) {
+				problem(call.Pos(), "private or raw HTTP handler reused outside its SDK boundary")
+			}
 			if module == "github.com/synopackageland/syno-pkg-land-sdk/dsm" && selector.Sel.Name == "NewEntryGate" {
 				out.EntryGate = true
 			}

package/dist/skill.js

@@ -57,6 +57,11 @@ const SKILL_CATALOG = [
         file: "reference/backup.md",
         when: "Change or opt out of Hyper Backup application backup",
     },
+    {
+        id: "daemon-mode",
+        file: "reference/daemon-mode.md",
+        when: "Decide whether the backend should run as a resident daemon (daemon.backend)",
+    },
     { id: "deploy", file: "reference/deploy.md", when: "Deploy to a NAS" },
     {
         id: "diagnose",

package/dist/standalone/daemon.d.ts

@@ -7,8 +7,13 @@ import type { StandaloneError, StandaloneManifest } from "./manifest.js";
 export interface Daemon {
     /** Optional bounded recovery; omitted means off. SDK 0.26.0 or later. */
     restart?: DaemonRestart;
-    /** Fixed foreground executable relative to daemon/payload. */
+    /** Fixed foreground executable relative to daemon/payload; empty for a backend daemon. */
     exec: string;
+    /**
+     * The App's own audited backend (ui/cgi/api.cgi) runs as the daemon with
+     * `args`; `node`, if set, is then only a runtime for the backend's children.
+     */
+    backend?: true;
     /** Architecture-specific project directories, copied without links. */
     targets: Partial<Record<NativeArchFamily, string>>;
     args: string[];
@@ -56,6 +61,10 @@ export declare function daemonConfig(manifest: StandaloneManifest): string;
  * launcher with its entry first, and ingress names the socket to listen on.
  */
 export declare function runnableDaemon(pkg: string, daemon: Daemon): Daemon;
+/** What a backend daemon learns about the Node runtime it may start children with. */
+export declare const backendNodeEnv: () => Record<string, string>;
+/** daemonctl runs ui/cgi/api.cgi (`"backend": true`) from SDK/App 0.37.0. */
+export declare function requireBackendDaemonSource(source: string, daemon: Daemon | undefined): void;
 export declare function buildDaemonControl(manifest: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): Promise<string | undefined>;
 export declare function copyDaemonPayload(manifest: StandaloneManifest, arch: NativeArchFamily, target: string, controller: string): void;
 /** Copies a bounded, link-free package-account payload tree. */

package/dist/standalone/daemon.js

@@ -1,6 +1,6 @@
 import { operationBudgetSeconds, runtimeBudgetSdkSupported } from "../runtime/runtime-budgets.js";
 import { goChildEnv } from "../runtime/go-env.js";
-import { chmodSync, existsSync, copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem, } from "../build-spk/go-toolchain.js";
 import { sdkSource, appSdkVersion } from "../runtime/sdk-source.js";
@@ -35,6 +35,7 @@ exec "$node" "$@"
 }
 const fields = new Set([
     "exec",
+    "backend",
     "targets",
     "args",
     "env",
@@ -69,19 +70,25 @@ export function readDaemon(value, root, arches, fail) {
     const invalid = () => {
         fail({
             code: "STANDALONE_DAEMON_INVALID",
-            message: "daemon accepts only fixed exec, targets, args, env and timeouts; paths must be inside the project, and the environment does not accept loader/shell/system variables.",
+            message: "daemon accepts only fixed exec (or backend: true), targets, args, env and timeouts; paths must be inside the project, and the environment does not accept loader/shell/system variables.",
         });
         return undefined;
     };
     if (!record(value) || Object.keys(value).some((k) => !fields.has(k)))
         return invalid();
-    if (!(value.node === undefined ? relativeExec(value.exec) : relativeEntry(value.exec)))
+    const backend = value.backend === true;
+    if (value.backend !== undefined && !backend)
         return invalid();
-    if (!record(value.targets) ||
-        Object.keys(value.targets).length !== arches.length)
+    if (backend ? value.exec !== undefined : !(value.node === undefined ? relativeExec(value.exec) : relativeEntry(value.exec)))
+        return invalid();
+    // A backend daemon needs a payload only for its children's files.
+    const payload = !backend || value.targets !== undefined;
+    if (payload &&
+        (!record(value.targets) ||
+            Object.keys(value.targets).length !== arches.length))
         return invalid();
     const targets = {};
-    for (const arch of arches) {
+    for (const arch of payload ? arches : []) {
         const path = value.targets[arch];
         if (typeof path !== "string" ||
             !path.trim() ||
@@ -123,8 +130,11 @@ export function readDaemon(value, root, arches, fail) {
         return undefined;
     if (ingress && Object.keys(env).some((key) => key in ingressEnv("", ingress)))
         return invalid();
+    if (backend && node && Object.keys(env).some((key) => key in backendNodeEnv()))
+        return invalid();
     return {
-        exec: value.exec,
+        exec: backend ? "" : value.exec,
+        ...(backend ? { backend: true } : {}),
         targets,
         args,
         ...(uninstall ? { uninstall_args: uninstall } : {}),
@@ -171,7 +181,7 @@ export function daemonConfig(manifest) {
             : runnableDaemon(manifest.package, manifest.daemon);
     return (JSON.stringify({
         package: manifest.package,
-        exec,
+        ...(!manifest.compose && manifest.daemon?.backend ? { backend: true } : { exec }),
         args,
         ...(uninstall_args ? { uninstall_args } : {}),
         ...(restart ? { restart } : {}),
@@ -187,8 +197,12 @@ export function daemonConfig(manifest) {
  * launcher with its entry first, and ingress names the socket to listen on.
  */
 export function runnableDaemon(pkg, daemon) {
-    const entry = daemon.node && [`\${SYNOPKG_PKGDEST}/daemon/payload/${daemon.exec}`];
-    const env = daemon.ingress ? { ...daemon.env, ...ingressEnv(pkg, daemon.ingress) } : daemon.env;
+    const entry = daemon.node && !daemon.backend && [`\${SYNOPKG_PKGDEST}/daemon/payload/${daemon.exec}`];
+    const env = {
+        ...daemon.env,
+        ...(daemon.ingress ? ingressEnv(pkg, daemon.ingress) : {}),
+        ...(daemon.backend && daemon.node ? backendNodeEnv() : {}),
+    };
     return {
         ...daemon,
         ...(entry ? { exec: NODE_LAUNCHER, args: [...entry, ...daemon.args] } : {}),
@@ -196,6 +210,19 @@ export function runnableDaemon(pkg, daemon) {
         env: Object.fromEntries(Object.keys(env).sort().map((key) => [key, env[key]])),
     };
 }
+/** What a backend daemon learns about the Node runtime it may start children with. */
+export const backendNodeEnv = () => ({
+    SYNOPKGLAND_DAEMON_PAYLOAD: "${SYNOPKG_PKGDEST}/daemon/payload",
+    SYNOPKGLAND_NODE: `\${SYNOPKG_PKGDEST}/daemon/payload/${NODE_LAUNCHER}`,
+});
+/** daemonctl runs ui/cgi/api.cgi (`"backend": true`) from SDK/App 0.37.0. */
+export function requireBackendDaemonSource(source, daemon) {
+    if (!daemon?.backend)
+        return;
+    const main = join(source, "daemonctl/main.go");
+    if (!existsSync(main) || !readFileSync(main, "utf8").includes("backendExecutable"))
+        throw new StandaloneBuildError("STANDALONE_DAEMON_BUILD_FAILED", "daemon.backend needs an SDK whose daemon controller can run the backend (SDK/App 0.37.0 or later); upgrade the App SDK.");
+}
 export async function buildDaemonControl(manifest, arch, work, run) {
     if (!manifest.daemon && !(manifest.compose && manifest.identityGateway))
         return undefined;
@@ -203,6 +230,7 @@ export async function buildDaemonControl(manifest, arch, work, run) {
     const sdk = daemonSdkVersion(manifest);
     const source = runtimeBudgetSource(sdkSource(sdk).goDir, manifest);
     requireDaemonRestartSource(source, sdk, manifest.daemon?.restart);
+    requireBackendDaemonSource(source, manifest.daemon);
     const result = await run("go", [
         "build",
         "-trimpath",
@@ -233,16 +261,16 @@ export function copyDaemonPayload(manifest, arch, target, controller) {
         copyPayloadTree(manifest.root, source, join(target, "payload"));
     else
         mkdirSync(join(target, "payload"), { recursive: true });
-    if (!manifest.compose && manifest.daemon?.node) {
+    if (!manifest.compose && manifest.daemon?.backend) {
+        // The CLI installs the backend itself at ui/cgi/api.cgi.
+        if (manifest.daemon.node)
+            writeNodeLauncher(source, target, manifest.daemon.node);
+    }
+    else if (!manifest.compose && manifest.daemon?.node) {
         const exec = join(source, daemon.exec);
         if (!existsSync(exec) || !lstatSync(exec).isFile())
             throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `daemon.exec must name the Node entry file inside the payload: ${exec}`);
-        if (existsSync(join(source, NODE_LAUNCHER.split("/")[0])))
-            throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `The daemon payload must not contain ${NODE_LAUNCHER.split("/")[0]}/; the CLI writes its Node launcher there.`);
-        mkdirSync(join(target, "payload", dirname(NODE_LAUNCHER)), { recursive: true });
-        chmodSync(join(target, "payload", dirname(NODE_LAUNCHER)), 0o755);
-        writeFileSync(join(target, "payload", NODE_LAUNCHER), renderNodeLauncher(manifest.daemon.node));
-        chmodSync(join(target, "payload", NODE_LAUNCHER), 0o755);
+        writeNodeLauncher(source, target, manifest.daemon.node);
     }
     else if (!manifest.compose) {
         const exec = join(source, daemon.exec);
@@ -257,6 +285,14 @@ export function copyDaemonPayload(manifest, arch, target, controller) {
         mode: 0o644,
     });
 }
+function writeNodeLauncher(source, target, node) {
+    if (source && existsSync(join(source, NODE_LAUNCHER.split("/")[0])))
+        throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `The daemon payload must not contain ${NODE_LAUNCHER.split("/")[0]}/; the CLI writes its Node launcher there.`);
+    mkdirSync(join(target, "payload", dirname(NODE_LAUNCHER)), { recursive: true });
+    chmodSync(join(target, "payload", dirname(NODE_LAUNCHER)), 0o755);
+    writeFileSync(join(target, "payload", NODE_LAUNCHER), renderNodeLauncher(node));
+    chmodSync(join(target, "payload", NODE_LAUNCHER), 0o755);
+}
 /** Copies a bounded, link-free package-account payload tree. */
 export function copyPayloadTree(root, source, target) {
     const invalid = (message) => {

package/dist/standalone/inspect-spk.js

@@ -24,7 +24,7 @@ import { familyOfArchToken, NATIVE_ARCH_FAMILIES, } from "../build-spk/dsm-arch.
 import { CONTAINER_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM, PORTAL_MIN_DSM, PORTAL_MIN_DSM_REASON, } from "../build-spk/dsm-version.js";
 import { ELF_MACHINE } from "./binary.js";
 import { CGI_PAYLOAD_PATH, entryLauncherAccess } from "./dsm-window.js";
-import { daemonConfig, readDaemon, readLifecycleTimeouts, renderNodeLauncher, nodeDependency, NODE_LAUNCHER } from "./daemon.js";
+import { backendNodeEnv, daemonConfig, readDaemon, readLifecycleTimeouts, renderNodeLauncher, nodeDependency, NODE_LAUNCHER } from "./daemon.js";
 import { DAEMON_INGRESS_CONFIG, daemonIngressMinDsmProblem, readDaemonIngress, renderDaemonIngressConfig } from "./daemon-ingress.js";
 import { daemonRestartSdkProblem, readDaemonRestart } from "./daemon-restart.js";
 import { ROOT_SCRIPT_HINTS } from "./root-ops.js";
@@ -970,6 +970,7 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             Object.keys(config).some((key) => ![
                 "package",
                 "exec",
+                "backend",
                 "args",
                 "env",
                 "timeouts",
@@ -981,8 +982,11 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             throw new Error("package/config mismatch");
         if (!isDeepStrictEqual(config.restart, extras.restart))
             throw new Error("daemon restart differs from its build declaration");
+        const backend = config.backend === true;
+        if (config.backend !== undefined && !backend)
+            throw new Error("invalid backend flag");
         const daemon = readDaemon({
-            exec: config.exec,
+            ...(backend ? { backend: true } : { exec: config.exec }),
             args: config.args,
             uninstall_args: config.uninstall_args,
             env: config.env,
@@ -994,6 +998,12 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             throw new Error("invalid config");
         // The packaged config already carries the launcher argv; only the launcher itself is checked here.
         if (extras.node &&
+            backend &&
+            (daemon.env.SYNOPKGLAND_NODE !== backendNodeEnv().SYNOPKGLAND_NODE ||
+                readOptional(join(unpacked, "daemon/payload", NODE_LAUNCHER)) !== renderNodeLauncher(extras.node)))
+            throw new Error("Node launcher differs from its build declaration");
+        if (extras.node &&
+            !backend &&
             (daemon.exec !== NODE_LAUNCHER ||
                 !daemon.args[0]?.startsWith("${SYNOPKG_PKGDEST}/daemon/payload/") ||
                 readOptional(join(unpacked, "daemon/payload", NODE_LAUNCHER)) !== renderNodeLauncher(extras.node)))
@@ -1007,7 +1017,8 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
                 JSON.stringify(daemon.args) !== '["run"]' ||
                 daemon.uninstall_args))
             throw new Error("compose gateway must run without a child");
-        if (payload.find((p) => p.path === `daemon/payload/${daemon.exec}`)?.mode !==
+        // A backend daemon runs the audited CGI binary.
+        if (payload.find((p) => p.path === (backend ? CGI_PAYLOAD_PATH : `daemon/payload/${daemon.exec}`))?.mode !==
             "0755")
             throw new Error("missing executable");
         const manifest = {

package/dist/standalone/manifest.js

@@ -312,8 +312,8 @@ function readManifest(raw, c) {
         if (problem)
             c.fail("STANDALONE_DAEMON_RESTART_SDK_REQUIRED", problem);
     }
-    if ((daemon?.ingress || daemon?.node) && raw.identity_gateway !== undefined)
-        c.fail("STANDALONE_DAEMON_INVALID", "daemon.node and daemon.ingress run the App's own daemon; identity_gateway runs its gateway as the daemon. Use one or the other.");
+    if ((daemon?.ingress || daemon?.node || daemon?.backend) && raw.identity_gateway !== undefined)
+        c.fail("STANDALONE_DAEMON_INVALID", "daemon.backend, daemon.node and daemon.ingress run the App's own daemon; identity_gateway runs its gateway as the daemon. Use one or the other.");
     if (compose && identityGateway && compose.sdk !== identityGateway.sdk)
         c.fail("STANDALONE_IDENTITY_GATEWAY_INVALID", "compose and identity_gateway must use the same SDK release.");
     if (compose &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.34.0",
+    "@synopackageland/templates": "~0.35.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-The CLI installs templates through `~0.34.0`. A templates patch needs only a
+The CLI installs templates through `~0.35.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -24,7 +24,7 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
-Use SDK/App 0.36.0 and CLI 0.38.0 for App entry enforcement. Declare every App method
+Use SDK/App 0.37.0 and CLI 0.40.0 for App entry enforcement. Declare every App method
 in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
 Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
 paths that rely on upstream authentication. Read
@@ -118,6 +118,8 @@ entries are injected, and the declaration grants no private-data access.
 
 Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting; DSM 7.2-64570+ supports schema-2 Portal without an executor, while DSM 7.1 requires executor registration. Read reference/files.md and reference/identity.md for capability boundaries. RootOps and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate native runtimes in @synopackageland/sdk/native; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
 
+Before choosing `daemon.backend` (the backend as a resident daemon behind `daemon.ingress`) for speed, read [reference/daemon-mode.md](reference/daemon-mode.md): measure the CGI first; the daemon pays off only for repeated, cacheable per-request work on a NAS with memory to spare.
+
 Read [reference/lifecycle.md](reference/lifecycle.md) before editing `dsm-scripts/` (preinst, postinst, preupgrade, postupgrade, preuninst, postuninst, start-stop-status): the SDK runs them inside its generated scripts as the package account; never add root work or repeat SDK steps there.
 
 Native Apps appear in Hyper Backup as applications by default. Read [reference/backup.md](reference/backup.md) before changing `backup` in dsm-package.yaml (opt out with `hyper_backup: false`, online mode, data version, hook). Hyper Backup runs the generated `scripts/backup/` as root; it is a fixed template that only switches to the package account, so never add or edit files there.

package/skills/reference/daemon-mode.md

@@ -0,0 +1,90 @@
+# When to run the backend as a daemon
+
+A native App's backend normally runs as a CGI: DSM starts `ui/cgi/api.cgi`
+for every request, and the process exits when the request ends. With
+`daemon.backend: true` and `daemon.ingress` ([docs/daemon.md](../../docs/daemon.md)),
+the same binary runs once as the package daemon and serves the pages through
+DSM's nginx. The CGI stays for integrations, transfers and fallback.
+
+Daemon mode is not the default recommendation. It removes work that repeats
+on every request. It does not make a single expensive request cheaper, and it
+costs memory for as long as the package runs. Measure first, then decide.
+
+## Decision table
+
+| Factor | Daemon helps | Stay with CGI |
+| --- | --- | --- |
+| Fixed cost per request | High: each request loads or compiles many definitions, opens several stores or runs sign-in checks that could be remembered | Low: the handler reads a row or two and returns |
+| Request rate | Pages send many calls; many users at once | A few calls per page; few users |
+| Repeated, cacheable work | Most of the time goes to work whose result does not change between requests (compiled definitions, permission answers, zone data) | Each request does new work (one-off reports, large exports) |
+| Long connections | Streams, server-sent events, long polling | None |
+| Background work | A tick, outbox sending or polling that should run within seconds | A scheduled task every few minutes is enough |
+| App size | Many Apps, large definitions | One small App |
+| NAS memory | Enough room for the base process plus a bounded cache | Small models (2–4 GB) that already swap; every resident MB competes with DSM and other packages |
+| Idle cost | Acceptable: the process stays up when nobody uses the App | Not acceptable: the App is opened rarely |
+
+The base process is usually small: an idle Go daemon is typically 10–30 MB
+RSS. Measure your own binary. The real variable is the cache, so give every
+cache an upper bound and measure it filled.
+
+## Factors and example numbers
+
+These numbers come from Studio Office. Use them as an example of what
+to measure, not as a budget.
+
+- **CGI cost per request.** On a DS SA3400 with 25 Apps, every Studio call
+  spent 100–140 ms before the handler did any work: process start, the DSM
+  sign-in check (`authenticate.cgi`), the App Privileges check and schema
+  checks. Recompiling App definitions on each request took about 70% of
+  `studio.apps.list`. Measure this on the NAS: time an empty call (for
+  example `app.status`) and the slowest common page calls.
+- **Resident memory.** Measured on macOS arm64 in a Go test process, not
+  on the NAS: 37 MB RSS with the routes built and the store opened, and
+  81 MB after 23 compiled template Apps were kept (about 1.1 MB of
+  heap per App).
+  The Node AI child has not been measured. Measure on the target NAS with your
+  real data before you choose cache sizes.
+- **Cache bounds.** Bound each cache by entry count (LRU) and derive the bound
+  from the measured size per entry. Studio keeps 32 compiled releases, about
+  35 MB at the measured size. Cache only results that are pure functions of
+  their key, such as compiled definitions keyed by a hash of the stored plan,
+  and cache only successes.
+- **Sign-in cache.** `dsm.CacheSessions` remembers verified sessions for a
+  TTL you choose (Studio: 10 minutes). The cost is staleness: a sign-out, a
+  disabled account or a lost administrator role takes effect up to the TTL
+  later. App Privileges keep their own 30-second check.
+- **Crash and restart.** The SDK daemon controller restarts the daemon
+  (`daemon.restart`). Children of the daemon, such as a Node service, are the
+  backend's own job: start them, restart them with backoff and stop them on
+  SIGTERM. Keep the CGI as fallback, so pages still work when the daemon is
+  down. Retry only reads automatically, plus calls the daemon cannot have seen.
+- **Upgrade.** DSM stops the old daemon and starts the new one. In-memory
+  caches start empty and fill on first use. Migrations still run at start.
+  The CGI is the same binary, so both paths always run the same version.
+- **Security boundary.** The daemon serves the same handler as the CGI. Origin,
+  App entry, DSM session and route permission are checked on every request.
+  The ingress socket is mode 0666 because nginx runs as another account, so
+  a local process can connect directly and choose `X-Real-IP`. A valid DSM
+  session is still required, but IP-based App Privileges rules can be
+  bypassed this way. The route audit treats `api.ServeIngress` like
+  `cgi.Serve`.
+
+## Decision steps
+
+1. Measure the CGI. Time an empty authenticated call and the 3–5 calls a
+   common page makes, on the target NAS, a few times each. Count how many
+   calls one page sends.
+2. Find where the time goes. Split fixed cost (process start, sign-in, entry
+   checks) from handler work. Then split handler work into repeated,
+   cacheable work and work that changes per request.
+3. Optimize inside the CGI first, if that is enough:
+   - Send fewer requests: batch reads, and return all items in one page instead
+     of serial paging.
+   - Use disk caches keyed by content hash (for example compiled definitions
+     next to the store).
+   - Avoid loading what the call does not use.
+4. Choose the daemon only when, after step 3, most of the remaining time is
+   fixed cost or cacheable repeated work, and the NAS has memory for the
+   measured base plus the bounded cache.
+5. After switching, measure idle RSS and RSS with a full cache on the NAS, and
+   the same page calls as in step 1. Write the numbers into the App's docs.