@synopackageland/sdk 0.10.2 → 0.10.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/sdk",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Frontend SDK for DSM packages built with synopkgland: headless client and Vue components",
   "license": "MIT",
   "homepage": "https://github.com/synopackageland/syno-pkg-land-sdk/tree/main/ts#readme",
@@ -26,6 +26,10 @@
       "import": "./dist/vue.js"
     },
     "./vue/style.css": "./dist/style.css",
+    "./native": {
+      "types": "./dist/src/native.d.ts",
+      "import": "./dist/native.js"
+    },
     "./i18n/*": "./dist/i18n/*"
   },
   "files": [
@@ -40,7 +44,7 @@
   },
   "peerDependencies": {
     "@lucide/vue": "^1.48.0",
-    "@synopackageland/ui": "^0.9.4",
+    "@synopackageland/ui": "^0.9.5",
     "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
@@ -53,7 +57,7 @@
   },
   "devDependencies": {
     "@lucide/vue": "1.48.0",
-    "@synopackageland/ui": "0.9.4",
+    "@synopackageland/ui": "0.9.6",
     "@types/node": "24.19.2",
     "@vitejs/plugin-vue": "6.0.9",
     "jsdom": "27.4.0",

package/spec/protocol/v1/README.md

@@ -15,6 +15,7 @@ the executor against the vectors here.
 | `schema/<op>.json` | JSON Schema (draft 2020-12) of the `params` of each op, with `since` |
 | `errors.json` | Every code: `code`, `kind`, `retryable`, `httpStatus`, `en`, `zh-TW`. The only source of codes; the Go constants are generated from it |
 | `vectors/*.jsonl` | One request per line: `{name, request, policy, state, expect}` |
+| `timeouts.json` | The timeouts of the section Timeouts, in seconds; the SDK's constants and tests read it |
 
 ## Transport
 
@@ -27,6 +28,38 @@ the executor against the vectors here.
 4. The executor MUST answer one line of JSON ending in `\n` and close.
 5. The executor SHOULD close a connection that sends nothing for 15 seconds.
 
+## Timeouts
+
+Since 0.10.3. Every layer between the browser and a root program waits
+longer than the layer it calls, so the inner answer, or the inner refusal,
+arrives before the outer layer gives up. The margin is 10 seconds between
+the executor and its client and between the client and the request; the
+browser waits 2 seconds past the request (`timeouts.json` holds the values).
+
+| Layer | Waits for | Bound |
+|---|---|---|
+| Root program (`run.timeout_s`) | its own work | 1–120 s, default 20; the process group is then killed |
+| Executor, `root.run` | the program, then its reply | answers within 130 s (120 + 10) |
+| Executor, every other op | its DSM calls | answers within 30 s |
+| Executor client (Go `delegate.Client`, the bridge runtime's `root.*` and `delegate.*`) | the executor | `root.run` 140 s (`delegate.RootRunTimeout`), every other op 40 s (`delegate.ExecutorTimeout`) |
+| Request (`api.Timeout`, manifest `timeout_seconds`) | the App's backend | default 60 s (`api.DefaultRequestTimeout`), 1–3600 |
+| Browser (`clientTimeout`, the CLI window's `call`) | the request | the request's deadline + 2 s |
+
+- The request's deadline ends every inner wait: a client never waits past it.
+  An App whose backend awaits `root.run` therefore needs a deadline of at
+  least the program's `run.timeout_s` + 20 seconds (the executor's 10 and the
+  client's 10), so a 120-second program needs `timeout_seconds` 140; a build
+  tool SHOULD refuse less. The default 60 covers programs of up to 40 seconds.
+- A client that gave up does not stop the work: `root.run` runs on (it cannot
+  be canceled), and `portal.register` and `portal.unregister` finish their
+  steps within 2 minutes. The client reads the result again (`status`,
+  `root.jobs.get`) instead of repeating the work.
+- The start step (Package start step) is waited on by no request: while it
+  runs (at most 60 seconds) every op but `status` is refused at once with
+  `EXECUTOR_STARTING` (retryable). A window that waits for the executor to
+  become ready polls `status` for longer than 60 seconds before it reports
+  the start step as still running.
+
 ## Request
 
 ```json
@@ -70,6 +103,19 @@ the executor against the vectors here.
   as `EXECUTOR_PROTOCOL`, and an unreachable socket as
   `EXECUTOR_UNAVAILABLE`. Codes of kind `client` are never sent by the
   executor.
+- A client that knows the package's lifecycle mailbox (`<data
+  dir>/executor/control`) answers an unreachable socket with `APP_STOPPED`
+  when its last request is `stop`; within 10 seconds of a `start` it waits
+  for the socket and ends with `APP_STARTING`. Neither sends a byte, so the
+  caller MAY repeat the request.
+- Such a client answers `EXECUTOR_UNAVAILABLE` only for a package that runs
+  and was not started in the last 10 seconds, yet whose executor does not
+  listen: it is not approved, awaits approval after an upgrade, or failed.
+  `retryable` says that nothing was sent, not that waiting helps: a browser
+  client repeats `APP_STOPPED`, `APP_STARTING` and `EXECUTOR_STARTING` on its
+  own, but shows `EXECUTOR_UNAVAILABLE` as the approval state at once, since
+  only an administrator's approval (which also restarts the executor) changes
+  it.
 
 ## Status
 
@@ -78,7 +124,9 @@ and `policy_digest`. With `auth` (since 0.9.6) it also answers `allowed`:
 whether DSM's Application Privileges let the caller use the App and File
 Station from `remote_addr`, the check `delegate.create` makes; an invalid
 session is `AUTH_DENIED`. A CGI sends the caller's `auth` so an App the
-executor would refuse is never shown as ready. The executor MUST NOT report the SDK version; the binary
+executor would refuse is never shown as ready. While a due start step runs
+(see Package start step), `status` answers `ready: false` with `state`
+`"starting"` and both digests. The executor MUST NOT report the SDK version; the binary
 digest MUST change only when the executor source changes.
 
 ## Application Portal
@@ -136,7 +184,7 @@ Every root program, whatever starts it:
 | Variable | Set for | Value |
 |---|---|---|
 | `SYNOPKGLAND_PACKAGE` | all | the package name |
-| `SYNOPKGLAND_ROOT_MODE` | all | `run`, `job`, `stop` or `purge` |
+| `SYNOPKGLAND_ROOT_MODE` | all | `run`, `job`, `start`, `stop` or `purge` |
 | `SYNOPKGLAND_REQUESTED_BY` | run, job | the verified DSM user name |
 | `SYNOPKGLAND_REQUEST_ID` | run | 64 hex digits, unique per call |
 | `SYNOPKGLAND_JOB_ID` | job | the job's `job_id` |
@@ -155,11 +203,16 @@ Every root program, whatever starts it:
 - A program that exits, whatever its status, is a result: `request_id`,
   `exit_code`, `stderr` and either `output` (UTF-8, in a reply under 64 KiB)
   or `staging` and `size`, a package-owned staging file the client reads and
-  removes. Past the timeout the process group is killed (`ROOT_TIMEOUT`);
+  removes. `staging` is a bare file name, `root-` and 32 lowercase hex
+  digits, never a path: the client joins it to the package staging folder,
+  `/var/packages/<package>/var/executor-staging`. The executor MUST create
+  that folder, owned by the package account with mode 0700, when it is
+  missing; a staging folder it cannot use is `ROOT_FAILED` with the message
+  `root output staging unavailable`. Past the timeout the process group is killed (`ROOT_TIMEOUT`);
   output past `max_output` is `limit-exceeded`; a full staging quota is
   `ROOT_STAGING_FULL`; two running programs make a third `ROOT_BUSY`.
 - A `root.run` request MAY be up to 1 MiB; the executor answers within 130
-  seconds and a client SHOULD wait 140.
+  seconds and a client SHOULD wait 140 (Timeouts).
 - `root.run` cannot be canceled: a closed connection does not stop the
   program, which runs until it exits or its timeout. Work that may be stopped
   is a root job (`root.start`, `root.jobs.stop`).
@@ -250,7 +303,48 @@ use it), and `stop` otherwise; jobs are canceled with `upgrade` or `stop`
 accordingly. It runs for at most 30 seconds, only while the approval is live
 (as for the purge step), its exit and output go to the executor log, and a
 failure does not stop the stop. `root.run` and `root.start` refuse it with
-`POLICY_DENIED`.
+`POLICY_DENIED`, so a policy whose stop or purge entry declares `run` or
+`job` is invalid; the entry is a lifecycle step only, either
+with neither member or as the shorthand digest. Session work takes another
+entry, which may pin the same digest under another name.
+
+## Package start step
+
+Since 0.10.3. A policy MAY carry `"start": "<name>"`, naming a `root` entry
+the executor runs once after each install or upgrade, with no session:
+
+- The executor MUST run it at the first start of a package version (the
+  `version` of the package INFO), after the pins matched. The socket opens first
+  and the step runs once the executor has read the
+  approval tasks back; until the step ends, `status` answers `ready: false`
+  and `state` `"starting"`, and every other request is refused with
+  `EXECUTOR_STARTING` (retryable), so no session reaches the App's root work
+  while the step runs. Its
+  arguments are `install` when the executor has recorded no earlier start,
+  and `upgrade` followed by the version recorded before otherwise. Every
+  start records its version, also for a policy without the step; a package
+  that adds the step in an upgrade therefore gets `upgrade`, except on the
+  first start under an executor that predates the record, which is `install`.
+- It runs only while the approval is live (as for the purge step); otherwise
+  it MUST log `start root step skipped: not approved` and run at the next
+  start. A step cut short because the executor ended also runs again.
+- It runs for at most 60 seconds; its exit and output go to the executor log,
+  and the executor MUST become ready whatever it answers. A failure is the result of
+  that version: the step does not run again until the next upgrade or
+  reinstall, so the program should be idempotent.
+- `status` answers `start_step` for such a policy: `{"state": "pending"}`
+  until the step ran for the version being served, then `state` `ok` (exit
+  `0`) or `failed`, `reason` (`install` or `upgrade`), `previous_version` for
+  an upgrade, `exit` (an exit code, `timeout`, `signal` or `refused`),
+  `output` (at most 4 KiB, which the package account can read) and
+  `finished_at` (RFC 3339).
+- As for stop and purge, `root.run` and `root.start` refuse it with
+  `POLICY_DENIED`, and an entry that declares `run` or `job` makes the policy
+  invalid.
+
+Because DSM's package start only writes the start request, `postinst`,
+`postupgrade` and `start` scripts run before or while the step runs; they
+MUST NOT expect its result. The App reads it from `status`.
 
 ## Root state directory
 

package/spec/protocol/v1/errors.json

@@ -106,6 +106,14 @@
       "en": "The executor is paused, for example while the package stops or upgrades.",
       "zh-TW": "executor 已暫停，例如套件停止或升級期間。"
     },
+    {
+      "code": "EXECUTOR_STARTING",
+      "kind": "refusal",
+      "retryable": true,
+      "httpStatus": 503,
+      "en": "The executor is running the App's start step after an install or upgrade; status answers state starting until it ends.",
+      "zh-TW": "executor 正在執行安裝或升級後的 App start 步驟；結束前 status 回報 state starting。"
+    },
     {
       "code": "STORAGE_ERROR",
       "kind": "refusal",
@@ -466,6 +474,22 @@
       "en": "The client could not connect to the executor socket.",
       "zh-TW": "用戶端無法連到 executor socket。"
     },
+    {
+      "code": "APP_STOPPED",
+      "kind": "client",
+      "retryable": true,
+      "httpStatus": 503,
+      "en": "The package is stopped: its lifecycle mailbox asks the executor to stop. The client sent nothing.",
+      "zh-TW": "套件已停止：生命週期信箱要求 executor 停止。用戶端沒有送出任何內容。"
+    },
+    {
+      "code": "APP_STARTING",
+      "kind": "client",
+      "retryable": true,
+      "httpStatus": 503,
+      "en": "The package was just started and its executor is not listening yet. The client sent nothing.",
+      "zh-TW": "套件剛啟動，executor 尚未開始接聽。用戶端沒有送出任何內容。"
+    },
     {
       "code": "EXECUTOR_TIMEOUT",
       "kind": "client",

package/spec/protocol/v1/timeouts.json

@@ -0,0 +1,21 @@
+{
+  "$comment": "Timeouts on the call chain to the executor, in seconds unless the name says ms. Each layer waits margin_s longer than the layer it calls, so the inner answer arrives first; README.md, Timeouts.",
+  "margin_s": 10,
+  "executor": {
+    "op_s": 30,
+    "root_run_program_default_s": 20,
+    "root_run_program_max_s": 120,
+    "root_run_answer_s": 130,
+    "start_step_s": 60
+  },
+  "client": {
+    "op_s": 40,
+    "root_run_s": 140
+  },
+  "request": {
+    "default_s": 60
+  },
+  "browser": {
+    "margin_ms": 2000
+  }
+}