@synopackageland/cli 0.4.1 → 0.5.3

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

@@ -0,0 +1,346 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"dsmapp/internal/api"
+	"dsmapp/internal/background"
+	"dsmapp/internal/filestation"
+)
+
+type fakeFiles struct {
+	data   []byte
+	err    error
+	calls  int
+	folder string
+	rel    string
+	offset int
+	page   filestation.Page
+}
+
+func (f *fakeFiles) Browse(_ context.Context, _ api.Caller, _ *http.Request, folder string, offset int) (filestation.Page, error) {
+	f.calls++
+	f.folder, f.offset = folder, offset
+	return f.page, f.err
+}
+
+func (f *fakeFiles) ReadFile(_ context.Context, _ api.Caller, _ *http.Request, folder, rel string) ([]byte, error) {
+	f.calls++
+	f.folder, f.rel = folder, rel
+	return f.data, f.err
+}
+
+type bgEnv struct {
+	t     *testing.T
+	store *background.Store
+	files *fakeFiles
+	srv   map[string]*api.Server
+}
+
+func newBgEnv(t *testing.T) *bgEnv {
+	lookupSubmitterUID = func(string) string { return "1024" }
+	t.Cleanup(func() { lookupSubmitterUID = osLookupUID })
+	store := background.NewStore(filepath.Join(t.TempDir(), "background"))
+	files := &fakeFiles{data: []byte("hello")}
+	return &bgEnv{t: t, store: store, files: files, srv: map[string]*api.Server{}}
+}
+
+func (e *bgEnv) call(auth api.Authenticator, method, params string) (string, map[string]any) {
+	e.t.Helper()
+	srv, err := api.NewServer(auth, newBackgroundRoutes(e.store, e.files)...)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api.cgi", strings.NewReader(`{"method":"`+method+`","params":`+params+`}`))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+	var out map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		e.t.Fatalf("not JSON: %s", rec.Body.String())
+	}
+	code := ""
+	if er, ok := out["error"].(map[string]any); ok {
+		code, _ = er["code"].(string)
+	}
+	return code, out
+}
+
+func (e *bgEnv) enable() {
+	e.t.Helper()
+	if code, out := e.call(alice, "bg.mode.set", `{"enabled":true}`); code != "" {
+		e.t.Fatalf("%s %v", code, out)
+	}
+}
+
+func data(out map[string]any) map[string]any { return out["data"].(map[string]any) }
+
+var bgSample = map[string]string{
+	"bg.schedules.list":    `{}`,
+	"bg.schedules.create":  `{"key":"schedule","jobId":"missing","intervalSeconds":3600,"consent":true}`,
+	"bg.schedules.disable": `{"id":"missing"}`,
+	"bg.schedules.delete":  `{"id":"missing"}`,
+	"bg.schedules.enable":  `{"id":"missing","consent":true}`,
+	"bg.status":            `{}`,
+	"bg.users.set":         `{"allowOrdinaryUsers":true}`,
+	"bg.jobs.purge":        `{"owner":{"user":"bob","uid":"1025"}}`,
+	"bg.mode.set":          `{"enabled":true}`,
+	"bg.browse":            `{"folder":"/share","offset":0}`,
+	"bg.jobs.submit":       `{"key":"k1","folder":"/share","relative":"a.txt"}`,
+	"bg.jobs.list":         `{}`,
+	"bg.jobs.get":          `{"id":"` + strings.Repeat("a", 32) + `"}`,
+	"bg.jobs.cancel":       `{"id":"` + strings.Repeat("a", 32) + `"}`,
+	"bg.jobs.result":       `{"id":"` + strings.Repeat("a", 32) + `"}`,
+}
+
+func TestBackgroundRoutesAreAdminOnlyByUnsupportedForOrdinaryUsers(t *testing.T) {
+	e := newBgEnv(t)
+	routes := newBackgroundRoutes(e.store, e.files)
+	if len(routes) != len(bgSample) {
+		t.Fatalf("%d routes, %d samples", len(routes), len(bgSample))
+	}
+	for _, r := range routes {
+		if r.Public() {
+			t.Errorf("%s must not be public", r.Method())
+		}
+		params, ok := bgSample[r.Method()]
+		if !ok {
+			t.Fatalf("no sample for %s", r.Method())
+		}
+		if code, _ := e.call(bob, r.Method(), params); code != "unsupported" {
+			t.Errorf("%s as an ordinary user: %q", r.Method(), code)
+		}
+		if code, _ := e.call(nobody, r.Method(), params); code != "session_required" {
+			t.Errorf("%s without a session: %q", r.Method(), code)
+		}
+	}
+	if e.files.calls != 0 {
+		t.Fatal("an ordinary user must not trigger a NAS read")
+	}
+}
+
+func TestBackgroundStatusReportsModeLimitsAndWorker(t *testing.T) {
+	e := newBgEnv(t)
+	code, out := e.call(alice, "bg.status", `{}`)
+	d := data(out)
+	if code != "" || d["enabled"] != false || d["algorithm"] != "sha256-v1" || d["worker"] != nil {
+		t.Fatalf("%s %v", code, out)
+	}
+	limits := d["limits"].(map[string]any)
+	if limits["maxInputBytes"].(float64) != 512*1024 || limits["maxQueued"].(float64) != 16 || limits["maxTotalBytes"].(float64) != 16<<20 || limits["jobTimeoutSeconds"].(float64) != 60 {
+		t.Fatalf("limits: %v", limits)
+	}
+	if err := e.store.Heartbeat(context.Background(), background.WorkerInfo{PID: 9, UID: 255853, Username: "pkg"}); err != nil {
+		t.Fatal(err)
+	}
+	_, out = e.call(alice, "bg.status", `{}`)
+	w := data(out)["worker"].(map[string]any)
+	if w["alive"] != true || w["uid"].(float64) != 255853 {
+		t.Fatalf("worker: %v", w)
+	}
+}
+
+func TestBackgroundSubmitRefusedWhileOffAndDoesNotReadNAS(t *testing.T) {
+	e := newBgEnv(t)
+	code, _ := e.call(alice, "bg.jobs.submit", bgSample["bg.jobs.submit"])
+	if code != "disabled" || e.files.calls != 0 {
+		t.Fatalf("%q, NAS reads %d", code, e.files.calls)
+	}
+}
+
+func TestBackgroundSubmitImportsSelectedFileAndIsIdempotent(t *testing.T) {
+	e := newBgEnv(t)
+	e.enable()
+	params := `{"key":"k1","folder":"/share","relative":"docs/a.txt"}`
+	code, out := e.call(alice, "bg.jobs.submit", params)
+	job := data(out)["job"].(map[string]any)
+	if code != "" || job["state"] != "queued" || job["name"] != "a.txt" || data(out)["duplicate"] != false {
+		t.Fatalf("%s %v", code, out)
+	}
+	if e.files.folder != "/share" || e.files.rel != "docs/a.txt" {
+		t.Fatalf("adapter saw %q %q", e.files.folder, e.files.rel)
+	}
+	submitter := job["submitter"].(map[string]any)
+	if submitter["user"] != "alice" || submitter["uid"] != "1024" {
+		t.Fatalf("submitter: %v", submitter)
+	}
+	_, again := e.call(alice, "bg.jobs.submit", params)
+	if data(again)["duplicate"] != true || data(again)["job"].(map[string]any)["id"] != job["id"] {
+		t.Fatalf("duplicate: %v", again)
+	}
+	e.files.data = []byte("other")
+	if code, _ := e.call(alice, "bg.jobs.submit", params); code != "conflict" {
+		t.Fatalf("same key with different bytes: %q", code)
+	}
+}
+
+func TestBackgroundSubmitPassesAdapterRefusalsThrough(t *testing.T) {
+	e := newBgEnv(t)
+	e.enable()
+	e.files.err = &api.Error{Code: "limit-exceeded", Message: "x"}
+	if code, _ := e.call(alice, "bg.jobs.submit", bgSample["bg.jobs.submit"]); code != "limit-exceeded" {
+		t.Fatalf("%q", code)
+	}
+	if jobs, _ := e.store.List(context.Background()); len(jobs) != 0 {
+		t.Fatal("a failed import must never enter the queue")
+	}
+}
+
+func TestBackgroundSubmitValidatesParams(t *testing.T) {
+	e := newBgEnv(t)
+	e.enable()
+	for _, p := range []string{
+		`{}`, `{"key":"k","folder":"/share","relative":"a","extra":1}`, `{"key":"bad key","folder":"/share","relative":"a"}`,
+		`{"key":"k","folder":"/share","relative":""}`,
+	} {
+		if code, _ := e.call(alice, "bg.jobs.submit", p); code != "bad_request" {
+			t.Errorf("%s: %q", p, code)
+		}
+	}
+}
+
+func TestBackgroundQueueFullAndQuotaErrorsHaveStableCodes(t *testing.T) {
+	e := newBgEnv(t)
+	e.enable()
+	for i := 0; i < background.MaxQueued; i++ {
+		lookupSubmitterUID = func(string) string { return fmt.Sprint(1024 + i/2) }
+		key := "k" + string(rune('a'+i))
+		if code, _ := e.call(alice, "bg.jobs.submit", `{"key":"`+key+`","folder":"/share","relative":"a.txt"}`); code != "" {
+			t.Fatalf("%d: %q", i, code)
+		}
+	}
+	lookupSubmitterUID = func(string) string { return "9999" }
+	if code, _ := e.call(alice, "bg.jobs.submit", `{"key":"more","folder":"/share","relative":"a.txt"}`); code != "queue-full" {
+		t.Fatalf("%q", code)
+	}
+}
+
+func TestBackgroundListGetCancelAndResult(t *testing.T) {
+	e := newBgEnv(t)
+	e.enable()
+	_, out := e.call(alice, "bg.jobs.submit", `{"key":"k1","folder":"/share","relative":"a.txt"}`)
+	id := data(out)["job"].(map[string]any)["id"].(string)
+	idp := `{"id":"` + id + `"}`
+
+	if _, out = e.call(alice, "bg.jobs.list", `{}`); len(data(out)["jobs"].([]any)) != 1 {
+		t.Fatalf("%v", out)
+	}
+	if code, out := e.call(alice, "bg.jobs.get", idp); code != "" || data(out)["job"].(map[string]any)["id"] != id {
+		t.Fatalf("%s %v", code, out)
+	}
+	if code, _ := e.call(alice, "bg.jobs.result", idp); code != "not_ready" {
+		t.Fatalf("result of a queued job: %q", code)
+	}
+	ctx := context.Background()
+	if _, err := e.store.Claim(ctx); err != nil {
+		t.Fatal(err)
+	}
+	sum := "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+	if err := e.store.Finish(ctx, id, background.Outcome{State: background.StateSucceeded, Result: &background.Result{SHA256: sum, Bytes: 5}}); err != nil {
+		t.Fatal(err)
+	}
+	code, out := e.call(alice, "bg.jobs.result", idp)
+	res := data(out)["result"].(map[string]any)
+	if code != "" || res["sha256"] != sum || res["bytes"].(float64) != 5 || res["worker"] != "sha256-v1" || res["jobId"] != id {
+		t.Fatalf("%s %v", code, out)
+	}
+	if code, _ := e.call(alice, "bg.jobs.cancel", idp); code != "conflict" {
+		t.Fatalf("cancel after completion: %q", code)
+	}
+	for _, m := range []string{"bg.jobs.get", "bg.jobs.cancel", "bg.jobs.result"} {
+		if code, _ := e.call(alice, m, `{"id":"`+strings.Repeat("0", 32)+`"}`); code != "not_found" {
+			t.Fatalf("%s unknown id: %q", m, code)
+		}
+	}
+}
+
+func TestBackgroundCancelQueuedJob(t *testing.T) {
+	e := newBgEnv(t)
+	e.enable()
+	_, out := e.call(alice, "bg.jobs.submit", `{"key":"k1","folder":"/share","relative":"a.txt"}`)
+	id := data(out)["job"].(map[string]any)["id"].(string)
+	code, out := e.call(alice, "bg.jobs.cancel", `{"id":"`+id+`"}`)
+	if code != "" || data(out)["job"].(map[string]any)["state"] != "canceled" {
+		t.Fatalf("%s %v", code, out)
+	}
+}
+
+func TestBackgroundModeOffCancelsQueuedWork(t *testing.T) {
+	e := newBgEnv(t)
+	e.enable()
+	_, out := e.call(alice, "bg.jobs.submit", `{"key":"k1","folder":"/share","relative":"a.txt"}`)
+	id := data(out)["job"].(map[string]any)["id"].(string)
+	if code, _ := e.call(alice, "bg.mode.set", `{"enabled":false}`); code != "" {
+		t.Fatal(code)
+	}
+	_, out = e.call(alice, "bg.jobs.get", `{"id":"`+id+`"}`)
+	if job := data(out)["job"].(map[string]any); job["state"] != "canceled" || job["errorCode"] != "disabled" {
+		t.Fatalf("%v", job)
+	}
+}
+
+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")
+	}
+}
+
+func TestBackgroundBrowseListsThroughTheCallersSession(t *testing.T) {
+	e := newBgEnv(t)
+	e.files.page = filestation.Page{Files: []filestation.Entry{{Name: "a.txt", Path: "/share/a.txt"}}, Total: 1}
+	code, out := e.call(alice, "bg.browse", `{"folder":"/share","offset":100}`)
+	if code != "" {
+		t.Fatalf("%s %v", code, out)
+	}
+	if e.files.folder != "/share" || e.files.offset != 100 {
+		t.Fatalf("browsed %q at %d", e.files.folder, e.files.offset)
+	}
+	files := data(out)["files"].([]any)
+	if len(files) != 1 || files[0].(map[string]any)["path"] != "/share/a.txt" {
+		t.Fatalf("page %v", out)
+	}
+}
+
+func TestBackgroundBrowseWithoutFolderListsTheShares(t *testing.T) {
+	e := newBgEnv(t)
+	if code, out := e.call(alice, "bg.browse", `{}`); code != "" {
+		t.Fatalf("%s %v", code, out)
+	}
+	if e.files.folder != "" || e.files.offset != 0 {
+		t.Fatalf("browsed %q at %d", e.files.folder, e.files.offset)
+	}
+}
+
+func TestBackgroundBrowseValidatesParamsAndPassesRefusalsThrough(t *testing.T) {
+	e := newBgEnv(t)
+	for _, params := range []string{`{"offset":-1}`, `{"folder":"/share","extra":1}`, `{"offset":"1"}`} {
+		if code, _ := e.call(alice, "bg.browse", params); code != "bad_request" {
+			t.Errorf("%s: %q", params, code)
+		}
+	}
+	if e.files.calls != 0 {
+		t.Fatal("invalid params must not reach the NAS")
+	}
+	e.files.err = &api.Error{Code: "denied", Message: "no"}
+	if code, _ := e.call(alice, "bg.browse", `{"folder":"/share"}`); code != "denied" {
+		t.Fatalf("got %q", code)
+	}
+}
+
+func TestBackgroundListWithoutJobsIsAnEmptyArray(t *testing.T) {
+	e := newBgEnv(t)
+	e.enable()
+	_, out := e.call(alice, "bg.jobs.list", `{}`)
+	jobs, ok := data(out)["jobs"].([]any)
+	if !ok || len(jobs) != 0 {
+		t.Fatalf("jobs must be [] not null: %v", out)
+	}
+}

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

@@ -0,0 +1,16 @@
+package app
+
+import (
+	"context"
+
+	"dsmapp/internal/helper"
+)
+
+// integrationState is the helper's trusted health, or, for an integration
+// built without a helper, a fixed package-only state: there is nothing to approve.
+func (cfg Config) integrationState(ctx context.Context) helper.State {
+	if cfg.PackageIntegration {
+		return helper.State{State: "ready", Reason: "package-only", PackageRunning: "running", Scheduler: "not-required"}
+	}
+	return helper.NewClient(cfg.HelperInventory).Status(ctx)
+}

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

@@ -0,0 +1,41 @@
+package app
+
+import (
+	"os"
+
+	"dsmapp/internal/datamigrate"
+)
+
+// Migrations returns this app's schema migrations. The template ships one
+// empty example; replace it with your own steps. Versions start at 1 and never
+// change meaning. Every step must be idempotent: a crash between Apply and the
+// recorded version, or two CGI requests racing on the first run after an
+// upgrade, can run one step twice. A failed step stops the run with the
+// previous version still recorded, and the next run resumes from there; the
+// utility itself never deletes or rewrites data.
+func Migrations() []datamigrate.Migration {
+	return []datamigrate.Migration{
+		{
+			Version: 1,
+			Name:    "example",
+			Apply: func(datamigrate.Context) error {
+				// Nothing to do yet. Read ctx.DataDir, rewrite files with a
+				// temporary file + rename, and keep the step idempotent.
+				return nil
+			},
+		},
+	}
+}
+
+// Migrate applies Migrations to the package's persistent var directory. The
+// CGI calls it once per request; the recorded data-version makes that a cheap
+// no-op. SYNOPKG_OLD_PKGVER is set when DSM starts the app from a lifecycle
+// script; in a plain CGI request the version of the last successful run is
+// used instead.
+func Migrate(cfg Config) error {
+	_, err := datamigrate.Run(cfg.DataDir, datamigrate.Info{
+		OldPkgVer: os.Getenv("SYNOPKG_OLD_PKGVER"),
+		NewPkgVer: cfg.Version,
+	}, Migrations())
+	return err
+}

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

@@ -0,0 +1,41 @@
+package app
+
+import (
+	"testing"
+
+	"dsmapp/internal/datamigrate"
+)
+
+func TestMigrationsAreOrderedUniqueAndValid(t *testing.T) {
+	migrations := Migrations()
+	if len(migrations) == 0 {
+		t.Fatal("the template must ship one example migration")
+	}
+	for i, migration := range migrations {
+		if migration.Version < 1 || migration.Apply == nil || migration.Name == "" {
+			t.Fatalf("migration %d is invalid: %+v", i, migration)
+		}
+		if i > 0 && migrations[i-1].Version >= migration.Version {
+			t.Fatalf("migrations are not strictly version-ascending: %+v", migrations)
+		}
+	}
+}
+
+func TestMigrateRecordsTheSchemaAndPackageVersion(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("SYNOPKG_OLD_PKGVER", "0.1.0-0001")
+	cfg := Config{DataDir: dir, Version: "0.2.0-0002"}
+	if err := Migrate(cfg); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+	state, err := datamigrate.Load(dir)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if state.Schema != 1 || state.PackageVersion != "0.2.0-0002" {
+		t.Fatalf("recorded state = %+v", state)
+	}
+	if err := Migrate(cfg); err != nil {
+		t.Fatalf("second Migrate must be a no-op: %v", err)
+	}
+}

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

@@ -103,6 +103,14 @@ func TestS8FinalCGIArtifactRefusal(t *testing.T) {
 				t.Fatal(err, string(b))
 			}
 			want := "unknown_method"
+			// Protocol 2 now installs the interactive File Station adapter. This
+			// historical fixture has only a fixture cookie, never a real DSM id cookie.
+			switch method {
+			case "nas.discovery", "nas.grants.confirm", "nas.grants.list", "nas.files.stat", "nas.files.list", "nas.files.read", "nas.files.create":
+				want = "session_required"
+			case "nas.files.publish":
+				want = "unsupported"
+			}
 			if method == "nas.files.read.binary" {
 				want = "unsupported"
 			}

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

@@ -1,6 +1,10 @@
+//go:build !synopkgland_sdk_workers
+
 // Package app holds this package's business operations. Add a route here and
 // pick its policy: api.User (any signed-in DSM user), api.Admin (DSM
 // administrators only) or, rarely, api.Public (no sign-in at all).
+//
+//line dsmapp/internal/app/routes.go:1
 package app
 
 import (
@@ -17,29 +21,42 @@ import (
 	"unicode/utf8"
 
 	"dsmapp/internal/api"
+	"dsmapp/internal/filestation"
 	"dsmapp/internal/helper"
 )
 
 // Config is fixed at build time and startup, never taken from a request.
 type Config struct {
+	RootAuthorization string
+
+	// SessionFiles is the interactive File Station adapter; nil keeps legacy refusal.
+	SessionFiles    *filestation.Service
 	PackageID       string
 	Version         string
 	HelperInventory helper.Inventory
+	// PackageIntegration marks an integration built without a privileged
+	// helper: its features run as the package account and are ready by themselves.
+	PackageIntegration bool
 	// Staged trusted adapter. Nil refuses; no production data transport is installed.
 	NASBinaryRead api.BinaryReadHandler
 	// DataDir is the package's persistent, package-owned directory
 	// (/var/packages/<package>/var). It survives upgrades.
 	DataDir string
+	// VolumeRoot is where /volumeN lives; empty means "/". Tests set it.
+	VolumeRoot string
 }
 
 func Routes(cfg Config) []api.Route {
-	routes := []api.Route{
+	routes := cfg.authorizationRoutes()
+	routes = append(routes, []api.Route{
 		api.User("integration.status", cfg.integrationStatus),
 		api.BoundedRead(cfg.binaryRead),
 		api.User("app.status", cfg.status),
 		api.User("greeting.get", cfg.getGreeting),
 		api.Admin("greeting.set", cfg.setGreeting),
-	}
+	}...)
+	routes = append(routes, cfg.SessionFiles.Routes()...)
+	routes = append(routes, cfg.backgroundRoutes()...)
 	return append(routes, cfg.rootRoutes()...)
 }
 
@@ -47,11 +64,11 @@ func (cfg Config) integrationStatus(ctx context.Context, _ api.Caller, params js
 	if err := decodeParams(params, &struct{}{}); err != nil {
 		return nil, err
 	}
-	return helper.NewClient(cfg.HelperInventory).Status(ctx), nil
+	return cfg.integrationState(ctx), nil
 }
 
 func (cfg Config) status(_ context.Context, caller api.Caller, _ json.RawMessage) (any, error) {
-	return map[string]any{
+	return cfg.withSharedFolders(map[string]any{
 		"package":    cfg.PackageID,
 		"version":    cfg.Version,
 		"user":       caller.User(),
@@ -60,7 +77,7 @@ func (cfg Config) status(_ context.Context, caller api.Caller, _ json.RawMessage
 		"go_version": runtime.Version(),
 		"platform":   runtime.GOOS + "/" + runtime.GOARCH,
 		"time":       time.Now().UTC().Format(time.RFC3339),
-	}, nil
+	}), nil
 }
 
 type greeting struct {

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

@@ -64,6 +64,10 @@ var sampleParams = map[string]string{
 	"greeting.set":          `{"text":"Hi"}`,
 }
 
+// sampleOutcome is the error code an administrator gets from a route's sample
+// params; routes that are not listed (and not jobs.*) succeed.
+var sampleOutcome = map[string]string{"nas.files.read.binary": "unsupported"}
+
 func TestIntegrationStatusIsReadableByOrdinaryUsers(t *testing.T) {
 	code, out := call(t, testConfig(t), bob, "integration.status", `{}`)
 	if code != "" || out["data"].(map[string]any)["state"] != "not-enabled" {
@@ -75,6 +79,19 @@ func TestIntegrationStatusIsReadableByOrdinaryUsers(t *testing.T) {
 	}
 }
 
+func TestPackageOnlyIntegrationIsReadyWithoutAHelper(t *testing.T) {
+	cfg := testConfig(t)
+	cfg.PackageIntegration = true
+	code, out := call(t, cfg, bob, "integration.status", `{}`)
+	data, _ := out["data"].(map[string]any)
+	if code != "" || data["state"] != "ready" || data["reason"] != "package-only" || data["scheduler"] != "not-required" || data["packageRunning"] != "running" {
+		t.Fatalf("%s: %v", code, out)
+	}
+	if _, cleanup := data["cleanup"]; cleanup {
+		t.Fatal("no helper means no cleanup state")
+	}
+}
+
 func TestEveryRouteHasSampleParamsAndNoneIsPublic(t *testing.T) {
 	routes := Routes(testConfig(t))
 	if len(routes) != len(sampleParams) {
@@ -118,9 +135,9 @@ func TestEveryAdminRouteRefusesOrdinaryUsersAndChangesNothing(t *testing.T) {
 func TestEveryRouteSucceedsForAnAdmin(t *testing.T) {
 	for _, r := range Routes(testConfig(t)) {
 		code, out := call(t, testConfig(t), alice, r.Method(), sampleParams[r.Method()])
-		want := ""
-		if r.Method() == "nas.files.read.binary" {
-			want = "unsupported"
+		want := sampleOutcome[r.Method()]
+		if strings.HasPrefix(r.Method(), "jobs.") {
+			want = "unavailable"
 		}
 		if code != want {
 			t.Errorf("%s: %q %v", r.Method(), code, out)

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

@@ -0,0 +1,70 @@
+//go:build synopkgland_sdk_workers
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"dsmapp/internal/api"
+	"dsmapp/internal/helper"
+	"encoding/json"
+	"io"
+	"net"
+	"net/http"
+)
+
+type sdkCarrierKey struct{}
+
+// Only session carriers from the HTTP request are forwarded. The authenticated
+// Caller and root NativeActor remain independent trust decisions.
+func SDKHandler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		raw, err := io.ReadAll(http.MaxBytesReader(w, r.Body, api.MaxRequestBytes))
+		if err != nil || helper.ValidateSDKEnvelope(raw) != "" {
+			w.Header().Set("Content-Type", "application/json")
+			w.Header().Set("Cache-Control", "no-store")
+			io.WriteString(w, `{"success":false,"error":{"code":"invalid-request","message":"Invalid request"}}`)
+			return
+		}
+		r.Body = io.NopCloser(bytes.NewReader(raw))
+		address, _, err := net.SplitHostPort(r.RemoteAddr)
+		if err != nil {
+			address = r.RemoteAddr
+		}
+		c := helper.SessionCarriers{Cookie: r.Header.Get("Cookie"), SynoToken: r.Header.Get("X-SYNO-TOKEN"), ClientAddress: address}
+		next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), sdkCarrierKey{}, c)))
+	})
+}
+func (cfg Config) sdkJobRoutes() []api.Route {
+	routes := []api.Route{}
+	for _, method := range []string{"jobs.prepare", "jobs.submit", "jobs.status", "jobs.lookup", "jobs.result", "jobs.cancel", "jobs.revoke", "jobs.attach", "jobs.admin.status", "jobs.admin.cancel"} {
+		name := method
+		handler := func(ctx context.Context, caller api.Caller, args json.RawMessage) (any, error) {
+			if !caller.Authenticated() {
+				return nil, &api.Error{Code: "session_required", Message: "Sign in again"}
+			}
+			if code := helper.ValidateSDKArgs(name, args); code != "" {
+				return nil, &api.Error{Code: string(code), Message: "Job request refused"}
+			}
+			c, ok := ctx.Value(sdkCarrierKey{}).(helper.SessionCarriers)
+			if !ok {
+				return nil, &api.Error{Code: "unavailable", Message: "Native proof unavailable"}
+			}
+			invoke := cfg.SDKJobs
+			if invoke == nil {
+				invoke = helper.NewClient(cfg.HelperInventory).SDKJobs
+			}
+			data, code := invoke(ctx, name, c, args)
+			if code != "" {
+				return nil, &api.Error{Code: string(code), Message: "Job request refused"}
+			}
+			return data, nil
+		}
+		if name == "jobs.admin.status" || name == "jobs.admin.cancel" {
+			routes = append(routes, api.Admin(name, handler))
+		} else {
+			routes = append(routes, api.User(name, handler))
+		}
+	}
+	return routes
+}