@synopackageland/templates 0.9.4 → 0.9.6

package/README.md

@@ -11,6 +11,11 @@ the files an App owns; the SDK (`github.com/synopackageland/syno-pkg-land-sdk`,
 | `native-go-jobs` | Background job routes in `internal/app` and their page test |
 | `native-go-delegate` | Delegate routes, the delegate background worker, the delegate `CapabilityPanels.vue` |
 | `native-go-root-ops` | Executor routes in `internal/app` and an example `root/whoami.sh` |
+| `native-rust` | Base: `dsm-package.yaml` with `backend.kind: rust`, Cargo package `app` (`backend/src/bin/{api,background-worker}.rs`, `backend/src/app`, `backend/permissions.json`, committed `Cargo.lock`, `rust-toolchain.toml`), plain `ui/`, i18n |
+| `native-rust-vue` | Only the Vue README and gitignore; the shell itself is `native-go-vue`'s `frontend/` |
+| `native-rust-jobs` | `backend/src/app/background_routes.rs`: the background job routes and their tests |
+| `native-rust-delegate` | `delegate_routes.rs` and the delegate `background-worker.rs` |
+| `native-rust-root-ops` | `root_routes.rs`: the executor routes and their tests |
 | `binary` | A prebuilt static CGI (`example/main.go`) with a plain UI |
 | `compose` | Container Manager project (`compose.yaml`, `synology-app.yaml`) |
 | `_shared` | Agent guides, template license, Go license texts, third-party notice writer |
@@ -21,9 +26,22 @@ An overlay may replace `internal/app/*_none.go` (the CLI deletes the matching
 The placeholders `__PACKAGE__` (also the Go module path), `__DISPLAY_NAME__` and
 `__BACKGROUND_ENABLED__` are substituted by `init`.
 
-`backend/go.mod` requires `github.com/synopackageland/syno-pkg-land-sdk v0.9.5`; that line is
+Rust has no build tags, so the `native-rust-*` overlays overwrite same-named
+base files (`background_routes.rs`, `delegate_routes.rs`, `root_routes.rs`,
+`bin/background-worker.rs`) and nothing is removed. They carry only the
+backend. A Rust project borrows the native-go overlays' non-backend files: the
+Vue shell from `native-go-vue` (then `native-rust-vue`), `frontend/` of
+`native-go-jobs` and `native-go-delegate`, and `root/whoami.sh` of
+`native-go-root-ops`. A delegate project without root-ops also takes
+`native-rust-root-ops`'s `root_routes.rs`, the executor shell Go borrows as
+`executor.go`. `scripts/assemble.sh --language rust` does exactly this.
+
+`backend/go.mod` requires `github.com/synopackageland/syno-pkg-land-sdk v0.9.7`; that line is
 the single source of the SDK version and `frontend/package.json` pins
-`@synopackageland/sdk` to the same version.
+`@synopackageland/sdk` to the same version. A Rust project takes it from the
+`tag` of the `syno-pkg-land-sdk` git dependency in `backend/Cargo.toml`, which
+`Cargo.lock` repeats; build-time values reach it through the contract's
+`SYNOPKGLAND_*` environment variables.
 
 ## Notice writer
 
@@ -45,7 +63,8 @@ and `UI-THIRD_PARTY.md` in the output directory; other files there stay.
 export GOPRIVATE='github.com/synopackageland/*'           # the SDK repository is private
 export SYNOPKGLAND_SDK_DIR=~/Public/synopackageland/sdk   # optional sdk checkout: Go module at the root, ts/
 scripts/assemble.sh /tmp/app vue delegate                 # one combination, as init lays it out
-scripts/gate.sh                                           # layout, every combination, binary, npm pack
+scripts/assemble.sh --language rust /tmp/app vue delegate # the same, for native-rust
+scripts/gate.sh                                           # layout, every combination (Go and Rust), binary, npm pack
 ```
 
 Without `SYNOPKGLAND_SDK_DIR` the combinations use the released SDK that
@@ -53,7 +72,11 @@ Without `SYNOPKGLAND_SDK_DIR` the combinations use the released SDK that
 `replace github.com/synopackageland/syno-pkg-land-sdk => $SYNOPKGLAND_SDK_DIR`
 and installs `$SYNOPKGLAND_SDK_DIR/ts` as an `npm pack` tarball (not a link, so Vue
 resolves once). With `SYNOPKGLAND_UI_TARBALL` set it installs that tarball as
-`@synopackageland/ui`, for a UI version not yet on npm. CI is not available; `scripts/gate.sh` is the gate.
+`@synopackageland/ui`, for a UI version not yet on npm. The Rust gate runs `cargo fmt --check`, `cargo clippy -D warnings`, `cargo test --locked`
+and a target clippy for the three DSM targets per combination; `rustup` installs the
+toolchain `backend/rust-toolchain.toml` pins. With `SYNOPKGLAND_SDK_DIR`, `scripts/rust-env.sh`
+(sourced by the gate) makes cargo fetch the SDK's pinned tag from that checkout instead of
+GitHub, leaving the Cargo files as shipped. CI is not available; `scripts/gate.sh` is the gate.
 
 SDK usage, protocol and API documentation: <https://github.com/synopackageland/syno-pkg-land-sdk>.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@synopackageland/templates",
-  "version": "0.9.4",
-  "description": "Project templates for synopkgland init: native-go (plain or Vue, with jobs, delegate and root-ops overlays), binary and compose.",
+  "version": "0.9.6",
+  "description": "Project templates for synopkgland init: native-go and native-rust (plain or Vue, with jobs, delegate and root-ops overlays), binary and compose.",
   "license": "MIT",
   "repository": {"type": "git", "url": "git+https://github.com/synopackageland/syno-pkg-land-templates.git"},
   "exports": {

package/templates/_shared/AGENTS.md

@@ -17,6 +17,9 @@ Only a confirmed refusal (signed out, expired session, not an administrator)
 shows the sign-in page or a `@synopackageland/ui` Dialog; loading text inside a
 section is fine.
 
+Everything below holds for every native backend language; the backend
+sections at the end name each language's files, types and test commands.
+
 From the project root, run `synopkgland check --json`,
 `synopkgland build --json`, then `synopkgland inspect <spk> --json` on the emitted SPK.
 For Vue, first run `npm ci`, `npm test` and `npm run build` in frontend.
@@ -32,7 +35,7 @@ access. One CGI check covers every route; failures refuse; changes apply within
 30 seconds. Never re-implement AppPriv rules in the App.
 Mark routes ordinary users call `authenticated` in permissions.json, keep whole
 admin routes at the default, guard global settings inside shared routes with
-`api.RequireAdmin(caller)`, and hide admin controls with `ctx.user?.isAdmin`
+the SDK's require-admin check, and hide admin controls with `ctx.user?.isAdmin`
 (UI only, never the authority). Example: users read the greeting; only admins
 call `greeting.set`.
 
@@ -51,9 +54,46 @@ admin's session) or Control Panel > Login Portal > Applications. Ordinary users
 get the link from the backend's read-only `portal.status`, else "ask an
 administrator". Never write `AppPortal.json` or `@appconf/<package>`, never add
 a backend route that sets the alias, and never relay QuickConnect responses or
-build QuickConnect links. A portal needs os_min_ver 7.3.2-86009 or later (DSM
-7.1.1 refuses it with error 320; 7.2 is untested) and `add portal` raises it;
-beyond that, support is detected (SYNO.API.Info), not version-gated.
+build QuickConnect links. A portal needs os_min_ver 7.1-42661 or later, and
+`add portal` raises a lower one. Below DSM 7.2 the executor registers the
+entry: there is no alias wizard step, and an administrator enables the entry
+from the portal panel (`ctx.portal.register()`), which the executor's approved
+`portal.register` operation carries out. From 7.2 the SPK registers it as a
+DSM resource. Beyond that, support is detected (SYNO.API.Info), not
+version-gated.
+
+## Background jobs (`jobs`)
+
+The worker runs the App's Work for one claimed job at a time, as the package
+account. The Work receives the job's Task: it reads the private input copy,
+reports progress (`done`/`total`, `bytes`/`totalBytes`, `item`) and saves a
+checkpoint, at most 16 KiB of text, only once the work it describes is done.
+Owners pause and resume their jobs (`bg.jobs.pause`, `bg.jobs.resume`; the
+SDK BackgroundPanel shows the buttons): a queued job pauses at once, a running
+one at its next checkpoint poll. A package stop pauses the running job too, and
+the next start resumes it. A resumed job runs again from its last checkpoint,
+or from the start when it saved none, so a Work must be safe to repeat from any
+checkpoint it saved. Delegated jobs cannot pause, and the pause routes answer
+`conflict` for them. The template's Work hashes the input, reports bytes read
+and checkpoints the hash state every 64 KiB; replace it with the App's own work.
+
+## Uninstall hook (`uninstall`)
+
+Declare `uninstall.purge` in dsm-package.yaml (the template ships it
+commented) to run a fixed package executable on a real uninstall (not an
+upgrade), as the package account, before the executor is removed. It gets
+`SYNOPKGLAND_DELETE_STATE=0|1` and `SYNOPKGLAND_REMOVE_DATA=0|1` from the
+uninstall wizard and nothing else from the environment. Release what the App
+holds outside the package on every uninstall; delete the state listed in
+`uninstall.state.items` (each key needs `uninstall.state.<key>` in
+i18n/messages) only with `SYNOPKGLAND_DELETE_STATE=1`, and keep what a
+reinstall can reuse otherwise. A failure or timeout (2–120 s, default 60) is
+logged to syslog tag `synopkgland-uninstall` with output in
+`var/uninstall-hook.log` and never blocks the uninstall. `purge.root: <op>`
+(rootOps only) adds a root step `root/<op>.sh [delete-state]` that runs only
+while the administrator's approval of that exact policy stands; sessions
+cannot call it through `root.run`. The template backend's `uninstall` mode
+deletes the background job spool when asked.
 
 ## Permanent destination integration
 
@@ -80,8 +120,8 @@ a receipt. Cancel by the same reference; revoke by grant ID. Never resubmit
 uncertain/interrupted work. Admin disable is protected and revokes grants;
 enable/mailbox start does not resurrect them. Keep IDs, never session credentials.
 
-App-owned daemon completion and scheduled CSV export call configured Go
-`Service.MoveFromStaging` with `delegation_id`, stable `job_id`, private relative
+App-owned daemon completion and scheduled CSV export call the configured
+delegate service's move-from-staging with `delegation_id`, stable `job_id`, private relative
 `staging`, `name`, `size`. No owner/UID selector. Bounds: 16 GiB/file, queued16,
 active1/package, 24-hour attempt, 5-second revalidation, 10 MiB operation records,
 50 MiB audit. Scope is a usage restriction, not hard subtree confinement.
@@ -93,7 +133,7 @@ Admission recovery (per job): on `EXECUTOR_UNAVAILABLE`, `EXECUTOR_TIMEOUT`,
 `EXECUTOR_PROTOCOL`, `canceled`, `EXECUTOR_PAUSED`, `queue-full`,
 `STORAGE_ERROR`, `ADMISSION_PENDING`, `jobs_busy` or `jobs_unavailable` (the
 package journal was busy or failed transiently; a caller deadline or cancel
-spent waiting for it is `canceled`), call `MoveFromStaging` again later with
+spent waiting for it is `canceled`), call move-from-staging again later with
 the same exact params. It queries the original reference first and re-sends
 admission only when the executor does not know it and the pinned source is
 unchanged; executor tuple deduplication keeps one operation, so a lost reply or a
@@ -105,11 +145,11 @@ retry: `APP_DENIED`, `DELEGATION_DENIED`, `operation-conflict`, `disabled`,
 spool first), and `operation-not-found` for an accepted operation.
 Never change job/grant IDs, delete mirrors or call the socket directly to retry.
 
-Cancellation (per job): `CancelOperation` / `delegate.operations.cancel` with the
+Cancellation (per job): the service's cancel-operation / `delegate.operations.cancel` with the
 original ref is idempotent; repeat it with the same ref after any retryable
 error or a lost reply. A reply `queued`→`canceled` is final at once. A copy in
 flight answers `copying` with code `CANCEL_REQUESTED`: the cancel is accepted and
-durable, not finished; poll `OperationStatus` on the same ref until terminal
+durable, not finished; poll the operation status on the same ref until terminal
 (repeating the cancel is harmless). `canceled` (`OPERATION_CANCELED`) guarantees the writer
 stopped, its part file is removed, nothing was published and staging is kept; it
 stays canceled across executor crash, package stop/start and logout. `committed`
@@ -118,7 +158,7 @@ the app record may be dropped. `uncertain` means a publish attempt failed before
 the cancel; keep querying. A cancel of a ref the executor has not admitted yet
 (reserved/sent mirror) returns `canceled` and leaves a tombstone, so a late or
 recovered admission of that ref returns `canceled` and never copies; a producer
-cancel is also written to the mirror first, so `MoveFromStaging` and the worker
+cancel is also written to the mirror first, so move-from-staging and the worker
 sweep forward the cancel instead of admitting it.
 
 
@@ -142,14 +182,51 @@ sweep forward the cancel instead of admitting it.
   sdk.destination('save')` returns typed `{key, selection, destination, status}`.
   `selection` contains `{scope, root, generation}`; `destination` is this caller's
   grant or null. Handle active/missing/reselection-required/needs-scope-confirmation/disabled.
-- Go: `Service.Destination(ctx, caller, request, key)` verifies the fresh DSM
-  session and username+UID. Capture its active grant ID into the App job. The
-  offline producer uses existing `Service.MoveFromStaging`; no user/UID selector,
-  cookie, token, or browser path cache. Executor revalidates at use/publication.
+- Backend: the service's destination lookup verifies the fresh DSM session and
+  username+UID. Capture its active grant ID into the App job. The offline
+  producer uses the existing move-from-staging; no user/UID selector, cookie,
+  token, or browser path cache. Executor revalidates at use/publication.
 - The generated Background saves page includes a working **Save example file**
-  (`sdk.exportExample({key, job_id})`, `delegate.example.export`). Go
-  `ExportExample` creates a private JSON file, calls `MoveFromStaging` once, and
-  repeats the original request on repeated IDs. Review `example.go` to
-  adapt a real producer; show Saved only from a protected committed receipt.
+  (`sdk.exportExample({key, job_id})`, `delegate.example.export`). The SDK's
+  export-example creates a private JSON file, calls move-from-staging once, and
+  repeats the original request on repeated IDs. Review it in the SDK's delegate
+  package to adapt a real producer; show Saved only from a protected committed
+  receipt.
 - Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
   forward. This is not proof of other DSM releases or full writer/reboot behavior.
+
+## Go backend
+
+- Routes: `backend/internal/app` (`routes.go` registers them); App
+  permissions: `backend/internal/api/permissions.json`. Test with
+  `(cd backend && go test ./...)`, then `go vet ./...` and `gofmt -l .`.
+- Admin guard inside a shared route: `api.RequireAdmin(caller)`.
+- Jobs: `background.Work` is `func(ctx, *background.Task) (background.Result,
+  error)`; call `t.Report(background.Progress{...})` and `t.Checkpoint(state)`,
+  and resume from `t.Job.Checkpoint`. The template's Work is
+  `app.HashWork` (`background_work.go`), set as `Runner.Work` in
+  `cmd/background-worker` and as `delegate.Service.Work` with delegate.
+- Uninstall hook: `app.Uninstall(dataDir, deleteState)` (`uninstall.go`),
+  reached by `api.cgi uninstall`.
+- Delegate: `delegate.Service.Destination(ctx, caller, request, key)`,
+  `Service.MoveFromStaging`, `Service.CancelOperation`,
+  `Service.OperationStatus`, `Service.ExportExample` (the SDK's
+  `delegate/example.go`).
+
+## Rust backend
+
+- Routes: `backend/src/app/routes.rs`; App permissions:
+  `backend/permissions.json`. Test with `(cd backend && cargo test --locked)`,
+  then `cargo clippy --locked --all-targets -- -D warnings` and
+  `cargo fmt --check`.
+- Admin guard inside a shared route: `api::require_admin(caller)`.
+- Jobs: `background::Work` is `Arc<dyn Fn(&Context, &mut Task<'_>) ->
+  Result<JobResult, BoxError>>`; call `t.report(Progress {..})` and
+  `t.checkpoint(state)`, and resume from `t.job.checkpoint`. The template's
+  Work is `app::hash_work` (`app/background/work.rs`, hash state through
+  `sha256::Sha256::save`/`restore`), set as `Runner.work` in
+  `bin/background-worker.rs` and as `delegate::Service.work` with delegate.
+- Uninstall hook: `app::uninstall(data_dir, delete_state)`
+  (`app/uninstall.rs`), reached by `api.cgi uninstall`.
+- Delegate: `Service::destination`, `move_from_staging`, `cancel_operation`,
+  `operation_status`, `export_example` (the SDK's `delegate/example.rs`).

package/templates/native-go/backend/THIRD_PARTY_NOTICES.txt

@@ -1,6 +1,6 @@
 Native Go package build dependencies
 
-github.com/synopackageland/syno-pkg-land-sdk v0.9.5 (MIT)
+github.com/synopackageland/syno-pkg-land-sdk v0.9.7 (MIT)
 
 Copyright (c) 2026 synopkgland
 

package/templates/native-go/backend/cmd/app/main.go

@@ -1,5 +1,6 @@
 // Command app is the package backend. DSM runs it as a CGI (ui/cgi/api.cgi in
-// the package) under the package account, once per request.
+// the package) under the package account, once per request, and as the
+// uninstall hook (`api.cgi uninstall`) when dsm-package.yaml declares one.
 //
 //line __PACKAGE__/cmd/app/main.go:1
 package main
@@ -36,13 +37,20 @@ var (
 	identity = ""
 	// dsm-package.yaml entry: "admin-only" or "app-privilege"; empty keeps the route policy alone.
 	entry = ""
-	// "on" when dsm-package.yaml declares portal: serves portal.status.
+	// "on" when dsm-package.yaml declares portal: serves portal.status;
+	// "executor" below DSM 7.2, where the executor registers the entry.
 	portal = ""
 )
 
 func main() {
 	log.SetFlags(0)
 	log.SetPrefix(packageID + ": ")
+	if os.Getenv("GATEWAY_INTERFACE") == "" && len(os.Args) == 2 && os.Args[1] == "uninstall" {
+		if err := app.Uninstall("/var/packages/"+packageID+"/var", os.Getenv("SYNOPKGLAND_DELETE_STATE") == "1"); err != nil {
+			log.Fatal(err)
+		}
+		return
+	}
 	if os.Getenv("GATEWAY_INTERFACE") == "" {
 		fmt.Fprintf(os.Stderr, "%s %s: this program runs as the package's DSM CGI; open the app from the DSM main menu.\n", packageID, version)
 		os.Exit(2)
@@ -53,10 +61,11 @@ func main() {
 		DelegateDestinationsJSON: delegateDestinationsJSON,
 		DelegateLifetime:         delegateLifetime,
 		ExecutorDigest:           executorDigest, PolicyDigest: policyDigest,
-		PackageID: packageID,
-		Version:   version,
-		DataDir:   "/var/packages/" + packageID + "/var",
-		Portal:    portal == "on",
+		PackageID:      packageID,
+		Version:        version,
+		DataDir:        "/var/packages/" + packageID + "/var",
+		Portal:         portal != "",
+		PortalExecutor: portal == "executor",
 	}
 	if _, err := app.ParseDelegateConfig(cfg); err != nil {
 		log.Fatal(err)

package/templates/native-go/backend/cmd/background-worker/main.go

@@ -13,6 +13,8 @@ import (
 	"syscall"
 
 	"github.com/synopackageland/syno-pkg-land-sdk/background"
+
+	"__PACKAGE__/internal/app"
 )
 
 // Set by `synopkgland build-spk` through -ldflags -X.
@@ -32,7 +34,9 @@ func main() {
 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
 	defer stop()
 	log.Printf("started as uid %s", strconv.Itoa(info.UID))
-	if err := background.NewRunner("/var/packages/"+packageID+"/var/background", info).Run(ctx); err != nil {
+	runner := background.NewRunner("/var/packages/"+packageID+"/var/background", info)
+	runner.Work = app.HashWork
+	if err := runner.Run(ctx); err != nil {
 		log.Fatal(err)
 	}
 }

package/templates/native-go/backend/go.mod

@@ -4,6 +4,6 @@ go 1.25.0
 
 toolchain go1.26.9
 
-require github.com/synopackageland/syno-pkg-land-sdk v0.9.5
+require github.com/synopackageland/syno-pkg-land-sdk v0.9.7
 
 require golang.org/x/sys v0.44.0 // indirect

package/templates/native-go/backend/go.sum

@@ -1,4 +1,4 @@
-github.com/synopackageland/syno-pkg-land-sdk v0.9.5 h1:Kab3TVny+Zqqy7tzp5YqT1ZdcUhzVtH0uL3uu58wPXo=
-github.com/synopackageland/syno-pkg-land-sdk v0.9.5/go.mod h1:JNoqISvR4biA9IuLi0CFe4c272tsKzCN9Nyj71nrXsQ=
+github.com/synopackageland/syno-pkg-land-sdk v0.9.7 h1:i8Zeowz7pLu3dI7v5/RijCw5OwMoZdMgzUoV/sD68n8=
+github.com/synopackageland/syno-pkg-land-sdk v0.9.7/go.mod h1:hlsvaVuH2wsAoR8jzI1Rg/NeejQSFpAaN6zpIWsVbjI=
 golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
 golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

package/templates/native-go/backend/internal/app/background.go

@@ -65,6 +65,8 @@ func newBackgroundRoutes(store *background.Store, files backgroundFiles) []api.R
 		api.HandleRequest("bg.jobs.list", b.owner(b.list)),
 		api.HandleRequest("bg.jobs.get", b.owner(b.get)),
 		api.HandleRequest("bg.jobs.cancel", b.owner(b.cancel)),
+		api.HandleRequest("bg.jobs.pause", b.owner(b.pause)),
+		api.HandleRequest("bg.jobs.resume", b.owner(b.resume)),
 		api.HandleRequest("bg.jobs.result", b.owner(b.result)),
 	}
 }
@@ -175,20 +177,28 @@ func (b backgroundAPI) list(ctx context.Context, _ api.Caller, _ *http.Request,
 }
 
 func (b backgroundAPI) get(ctx context.Context, _ api.Caller, _ *http.Request, params json.RawMessage) (any, error) {
-	var in idParams
-	if err := decodeParams(params, &in); err != nil {
-		return nil, err
-	}
-	job, err := b.store.GetFor(ctx, in.ID, accessFrom(ctx))
-	return jobOrError(job, err)
+	return b.byID(ctx, params, b.store.GetFor)
 }
 
 func (b backgroundAPI) cancel(ctx context.Context, _ api.Caller, _ *http.Request, params json.RawMessage) (any, error) {
+	return b.byID(ctx, params, b.store.CancelFor)
+}
+
+// pause holds a queued job at once; a running job pauses at its next checkpoint.
+func (b backgroundAPI) pause(ctx context.Context, _ api.Caller, _ *http.Request, params json.RawMessage) (any, error) {
+	return b.byID(ctx, params, b.store.PauseFor)
+}
+
+func (b backgroundAPI) resume(ctx context.Context, _ api.Caller, _ *http.Request, params json.RawMessage) (any, error) {
+	return b.byID(ctx, params, b.store.ResumeFor)
+}
+
+func (b backgroundAPI) byID(ctx context.Context, params json.RawMessage, act func(context.Context, string, background.Access) (background.Job, error)) (any, error) {
 	var in idParams
 	if err := decodeParams(params, &in); err != nil {
 		return nil, err
 	}
-	job, err := b.store.CancelFor(ctx, in.ID, accessFrom(ctx))
+	job, err := act(ctx, in.ID, accessFrom(ctx))
 	return jobOrError(job, err)
 }
 
@@ -239,7 +249,8 @@ func backgroundError(err error) error {
 		return &api.Error{Code: "queue-full", Message: "the background queue is full"}
 	case errors.Is(err, background.ErrQuota):
 		return &api.Error{Code: "quota-exceeded", Message: "the background spool is full"}
-	case errors.Is(err, background.ErrKeyConflict), errors.Is(err, background.ErrNotCancelable):
+	case errors.Is(err, background.ErrKeyConflict), errors.Is(err, background.ErrNotCancelable),
+		errors.Is(err, background.ErrNotPausable):
 		return &api.Error{Code: "conflict", Message: "the request conflicts with the job's current state"}
 	case errors.Is(err, background.ErrNotFound):
 		return &api.Error{Code: "not_found", Message: "job not found"}

package/templates/native-go/backend/internal/app/background_owner_test.go

@@ -52,7 +52,7 @@ func TestBackgroundOwnersAreIsolatedIncludingKeysAndCounts(t *testing.T) {
 			t.Fatalf("status leaks: %v", out)
 		}
 	}
-	for _, method := range []string{"bg.jobs.get", "bg.jobs.cancel", "bg.jobs.result"} {
+	for _, method := range []string{"bg.jobs.get", "bg.jobs.cancel", "bg.jobs.pause", "bg.jobs.resume", "bg.jobs.result"} {
 		for _, id := range []string{a, c, strings.Repeat("0", 32)} {
 			if code, out := e.call(bob, method, `{"id":"`+id+`"}`); code != "not_found" {
 				t.Fatalf("%s %s: %s %v", method, id, code, out)
@@ -144,7 +144,7 @@ func TestFreshOrdinaryUserJobsNeedNoAdminSetup(t *testing.T) {
 		}
 	}
 	id := ownerSubmit(t, e, bob, "fresh")
-	for _, method := range []string{"bg.jobs.get", "bg.jobs.cancel"} {
+	for _, method := range []string{"bg.jobs.get", "bg.jobs.cancel", "bg.jobs.pause", "bg.jobs.resume"} {
 		if code, _ := e.call(carol, method, `{"id":"`+id+`"}`); code != "not_found" {
 			t.Fatalf("other owner %s: %s", method, code)
 		}

package/templates/native-go/backend/internal/app/background_test.go

@@ -91,6 +91,8 @@ var bgSample = map[string]string{
 	"bg.jobs.list":         `{}`,
 	"bg.jobs.get":          `{"id":"` + strings.Repeat("a", 32) + `"}`,
 	"bg.jobs.cancel":       `{"id":"` + strings.Repeat("a", 32) + `"}`,
+	"bg.jobs.pause":        `{"id":"` + strings.Repeat("a", 32) + `"}`,
+	"bg.jobs.resume":       `{"id":"` + strings.Repeat("a", 32) + `"}`,
 	"bg.jobs.result":       `{"id":"` + strings.Repeat("a", 32) + `"}`,
 }
 
@@ -262,6 +264,28 @@ func TestBackgroundCancelQueuedJob(t *testing.T) {
 	}
 }
 
+func TestBackgroundPauseAndResumeQueuedJob(t *testing.T) {
+	e := newBgEnv(t)
+	_, out := e.call(alice, "bg.jobs.submit", `{"key":"k1","folder":"/share","relative":"a.txt"}`)
+	idp := `{"id":"` + data(out)["job"].(map[string]any)["id"].(string) + `"}`
+	for method, state := range map[string]string{"bg.jobs.pause": "paused", "bg.jobs.resume": "queued"} {
+		if code, out := e.call(alice, method, idp); code != "" || data(out)["job"].(map[string]any)["state"] != state {
+			t.Fatalf("%s: %s %v", method, code, out)
+		}
+	}
+	if code, _ := e.call(alice, "bg.jobs.cancel", idp); code != "" {
+		t.Fatal(code)
+	}
+	for _, m := range []string{"bg.jobs.pause", "bg.jobs.resume"} {
+		if code, _ := e.call(alice, m, idp); code != "conflict" {
+			t.Fatalf("%s after cancel: %q", m, code)
+		}
+		if code, _ := e.call(alice, m, `{"id":"`+strings.Repeat("0", 32)+`"}`); code != "not_found" {
+			t.Fatalf("%s unknown id: %q", m, code)
+		}
+	}
+}
+
 func TestBackgroundWorkerAliveExpires(t *testing.T) {
 	if workerAlive(background.WorkerInfo{At: time.Now().Add(-time.Minute)}, time.Now()) || !workerAlive(background.WorkerInfo{At: time.Now()}, time.Now()) {
 		t.Fatal("a stale heartbeat is not alive")

package/templates/native-go/backend/internal/app/background_work.go

@@ -0,0 +1,94 @@
+package app
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"hash"
+	"io"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/background"
+)
+
+// hashCheckpointEvery spaces HashWork's checkpoints; a resumed job repeats at
+// most this much hashing. A Work over larger input saves less often.
+const hashCheckpointEvery = 64 << 10
+
+// hashState is HashWork's checkpoint: the bytes already hashed and the hash
+// state after them.
+type hashState struct {
+	Offset int64  `json:"offset"`
+	State  []byte `json:"state"`
+}
+
+// HashWork is the App's sha256-v1 Work: it reports progress as it reads and
+// checkpoints the hash state, so a job paused by its owner or by a package
+// stop resumes where it left off instead of from the start.
+func HashWork(ctx context.Context, t *background.Task) (background.Result, error) {
+	h, done, err := resumeHash(t.Job.Checkpoint, t.Input)
+	if err != nil {
+		return background.Result{}, err
+	}
+	total, saved := int64(t.Job.InputBytes), done
+	buf := make([]byte, 32<<10)
+	for {
+		if err := ctx.Err(); err != nil {
+			return background.Result{}, err
+		}
+		n, err := t.Input.Read(buf)
+		h.Write(buf[:n])
+		done += int64(n)
+		t.Report(background.Progress{Bytes: done, TotalBytes: total})
+		if errors.Is(err, io.EOF) {
+			return background.Result{SHA256: hex.EncodeToString(h.Sum(nil)), Bytes: int(done)}, nil
+		}
+		if err != nil {
+			return background.Result{}, err
+		}
+		if done-saved >= hashCheckpointEvery {
+			state, err := saveHash(h, done)
+			if err == nil {
+				err = t.Checkpoint(state)
+			}
+			if err != nil {
+				return background.Result{}, err
+			}
+			saved = done
+		}
+	}
+}
+
+func saveHash(h hash.Hash, offset int64) (string, error) {
+	state, err := h.(encoding.BinaryMarshaler).MarshalBinary()
+	if err != nil {
+		return "", err
+	}
+	out, err := json.Marshal(hashState{Offset: offset, State: state})
+	return string(out), err
+}
+
+// resumeHash continues the hash a checkpoint saved, past the input it covered.
+func resumeHash(checkpoint string, in io.Reader) (hash.Hash, int64, error) {
+	h := sha256.New()
+	if checkpoint == "" {
+		return h, 0, nil
+	}
+	var saved hashState
+	if err := json.Unmarshal([]byte(checkpoint), &saved); err != nil {
+		return nil, 0, fmt.Errorf("checkpoint: %w", err)
+	}
+	if saved.Offset < 0 {
+		return nil, 0, errors.New("checkpoint: negative offset")
+	}
+	if err := h.(encoding.BinaryUnmarshaler).UnmarshalBinary(saved.State); err != nil {
+		return nil, 0, fmt.Errorf("checkpoint: %w", err)
+	}
+	if _, err := io.CopyN(io.Discard, in, saved.Offset); err != nil {
+		return nil, 0, fmt.Errorf("checkpoint: %w", err)
+	}
+	return h, saved.Offset, nil
+}

package/templates/native-go/backend/internal/app/background_work_test.go

@@ -0,0 +1,95 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/background"
+)
+
+func TestHashWorkResumesFromItsCheckpoint(t *testing.T) {
+	head, tail := bytes.Repeat([]byte("h"), 1000), bytes.Repeat([]byte("t"), 3000)
+	h := sha256.New()
+	h.Write(head)
+	saved, err := saveHash(h, int64(len(head)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The input's first bytes differ from what the checkpoint hashed: only a
+	// Work that skips them and continues the saved hash reaches this digest.
+	input := append(bytes.Repeat([]byte("x"), len(head)), tail...)
+	task := &background.Task{Job: background.Job{Checkpoint: saved}, Input: bytes.NewReader(input)}
+	got, err := HashWork(context.Background(), task)
+	want := sha256.Sum256(append(head, tail...))
+	if err != nil || got.SHA256 != hex.EncodeToString(want[:]) || got.Bytes != len(input) {
+		t.Fatalf("%+v %v", got, err)
+	}
+}
+
+func TestHashWorkRefusesAForeignCheckpoint(t *testing.T) {
+	for _, saved := range []string{"{", `{"offset":-1,"state":""}`, `{"offset":3,"state":"AAAA"}`} {
+		task := &background.Task{Job: background.Job{Checkpoint: saved}, Input: bytes.NewReader([]byte("abc"))}
+		if _, err := HashWork(context.Background(), task); err == nil {
+			t.Errorf("%s: accepted", saved)
+		}
+	}
+}
+
+// stopAfter ends the worker's context once n bytes have been read, like a
+// package stop in the middle of a job.
+type stopAfter struct {
+	io.Reader
+	n    int
+	stop context.CancelFunc
+}
+
+func (s *stopAfter) Read(p []byte) (int, error) {
+	n, err := s.Reader.Read(p)
+	if s.n -= n; s.n <= 0 {
+		s.stop()
+	}
+	return n, err
+}
+
+func TestHashWorkReportsProgressAndCheckpointsBeforeAStop(t *testing.T) {
+	store := background.NewStore(filepath.Join(t.TempDir(), "background"))
+	ctx := context.Background()
+	data := bytes.Repeat([]byte("0123456789abcdef"), 16<<10)
+	job, _, err := store.Submit(ctx, background.SubmitRequest{Key: "k", Name: "a.bin", Data: data, Submitter: background.Submitter{User: "alice", UID: "1024"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	worker, stop := context.WithCancel(ctx)
+	runner := &background.Runner{Store: store, Timeout: time.Minute, CancelPoll: 10 * time.Millisecond, Work: func(ctx context.Context, t *background.Task) (background.Result, error) {
+		t.Input = &stopAfter{Reader: t.Input, n: 3 * int(hashCheckpointEvery) / 2, stop: stop}
+		return HashWork(ctx, t)
+	}}
+	claimed, err := store.Claim(ctx)
+	if err != nil || claimed == nil {
+		t.Fatalf("%+v %v", claimed, err)
+	}
+	runner.Process(worker, claimed)
+	paused, err := store.Get(ctx, job.ID)
+	if err != nil || paused.State != background.StatePaused || paused.Checkpoint == "" || paused.Progress == nil ||
+		paused.Progress.Bytes < hashCheckpointEvery || paused.Progress.TotalBytes != int64(len(data)) {
+		t.Fatalf("%+v %+v %v", paused, paused.Progress, err)
+	}
+	if err := store.Recover(ctx); err != nil {
+		t.Fatal(err)
+	}
+	claimed, err = store.Claim(ctx)
+	if err != nil || claimed == nil || claimed.Checkpoint != paused.Checkpoint {
+		t.Fatalf("%+v %v", claimed, err)
+	}
+	runner.Work = HashWork
+	runner.Process(ctx, claimed)
+	if done, err := store.Get(ctx, job.ID); err != nil || done.State != background.StateSucceeded || done.Progress.Bytes != int64(len(data)) {
+		t.Fatalf("%+v %v", done, err)
+	}
+}