fix(service-cloud): require Turso on Vercel — no silent /tmp SQLite fallback

Copilot · hotlong · web-flow · commit 72c100c94f50 · 2026-05-08T00:24:33.000Z
Replace the ephemeral /tmp SQLite fallback (introduced in 5833df4) with a fail-fast error on serverless platforms. /tmp on Vercel/Lambda/Netlify is per-instance and ephemeral — SQLite there silently corrupts data across concurrent cold starts. The correct default for Vercel is Turso (libSQL), which ObjectStack already supports as the natural serverless pairing. Behaviour: - resolveDefaultDataDir() throws on serverless (Vercel / AWS Lambda / Netlify / OS_READONLY_FS=1) unless OS_DATA_DIR is set, with an error message naming TURSO_DATABASE_URL, TURSO_AUTH_TOKEN, OS_CONTROL_DATABASE_URL, and OS_DATA_DIR (escape hatch for EFS / mounted volumes). - cloud-stack.ts evaluates the file-backed default lazily so any of OS_CONTROL_DATABASE_URL / OS_DATABASE_URL / TURSO_DATABASE_URL short-circuit it (Vercel deployments configured with Turso boot cleanly). - On writable filesystems (objectstack dev / serve, Docker, bare metal) the existing <cwd>/.objectstack/data behaviour is preserved. Tests rewritten (15 cases) to assert throw-on-serverless and error message contents. CHANGELOG entry updated. Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/9969986e-eb1d-4d25-b31b-75fb22429b04 Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Fixed
-- **Cold-start `ENOENT: mkdir '/var/task/.objectstack'` on Vercel/Lambda** (`@objectstack/service-cloud`) — `createCloudStack()`, `createRuntimeStack()`, `DefaultProjectKernelFactory`, `DefaultEnvironmentDriverRegistry`, and `ArtifactEnvironmentDriverRegistry` previously hard-coded the SQLite/InMemoryDriver default data directory to `<process.cwd()>/.objectstack/data`. On serverless platforms the bundle root is read-only, which made `apps/cloud` fail to boot whenever no explicit `OS_CONTROL_DATABASE_URL` was configured. Centralised the resolution in a new `resolveDefaultDataDir()` helper that honours `OS_DATA_DIR`, then falls back to `<cwd>/.objectstack/data` on writable filesystems and `<os.tmpdir()>/.objectstack/data` (with a one-time warning) on Vercel / AWS Lambda / Netlify (or any environment where `OS_READONLY_FS=1`). Production deployments must still configure a persistent database; this only restores cold-start safety so the warning surfaces instead of an opaque `ENOENT`. Helper covered by 12 new unit tests in `packages/services/service-cloud/test/data-dir.test.ts`.
+- **Cold-start `ENOENT: mkdir '/var/task/.objectstack'` on Vercel/Lambda** (`@objectstack/service-cloud`) — `createCloudStack()`, `createRuntimeStack()`, `DefaultProjectKernelFactory`, `DefaultEnvironmentDriverRegistry`, and `ArtifactEnvironmentDriverRegistry` previously hard-coded the SQLite/InMemoryDriver default data directory to `<process.cwd()>/.objectstack/data`. On serverless platforms (Vercel `/var/task`, AWS Lambda, Netlify) the bundle root is read-only, so `apps/cloud` failed to boot whenever no explicit persistent DB URL was configured. Centralised the resolution in a new `resolveDefaultDataDir()` helper (`packages/services/service-cloud/src/data-dir.ts`) that honours `OS_DATA_DIR`, returns `<cwd>/.objectstack/data` on writable filesystems, and **throws a fail-fast error on serverless** pointing at `TURSO_DATABASE_URL` (recommended on Vercel — Turso is the default ObjectStack pairing for serverless), `OS_CONTROL_DATABASE_URL`, and `OS_DATA_DIR` (escape hatch for EFS / mounted volumes). File-backed SQLite on serverless `/tmp` is rejected by design because `/tmp` is per-instance and ephemeral, which silently corrupts data across concurrent invocations. The `cloud-stack` control-driver default is now lazy so deployments that set `TURSO_DATABASE_URL` never hit the throw. 15 unit tests cover the precedence, error message contents, and platform detection in `test/data-dir.test.ts`.
 - **`@objectstack/studio` Vercel build: `webcrypto` not exported by `mocks/node-polyfills.ts`** — `@objectstack/runtime` imports `webcrypto` from `crypto`, but the studio Vite alias swaps `crypto` for the local node polyfill which did not export it. Added a `webcrypto` shim that proxies to `globalThis.crypto`, restoring the rolldown build.
 - **`@objectstack/driver-sql` tests failing in CI** — Added `vitest.config.ts` with resolve aliases for `@objectstack/spec/*` subpath exports (`/data`, `/contracts`, `/system`). Without these aliases, vitest could not resolve the source paths at test time, causing all 81 tests to fail with `ERR_MODULE_NOT_FOUND`.
 - **RLS fail-open across tenants** (`@objectstack/plugin-security`) — A logged-in user with no active organization (e.g. immediately after sign-up, before joining or creating one) was previously seeing every tenant's data on `account`, `sys_member`, `sys_organization`, etc. Multiple compounding bugs were responsible:
diff --git a/packages/services/service-cloud/src/cloud-stack.ts b/packages/services/service-cloud/src/cloud-stack.ts
@@ -71,7 +71,11 @@ export async function createCloudStack(config: CloudStackConfig): Promise<{
     const {
         authSecret,
         baseUrl,
-        controlDriverUrl = `file:${resolvePath(resolveDefaultDataDir(), 'control.db')}`,
+        // NOTE: no eager default here. The file-backed fallback is computed
+        // lazily below so that serverless deployments which configure
+        // TURSO_DATABASE_URL / OS_CONTROL_DATABASE_URL never trip the
+        // resolveDefaultDataDir() throw-on-serverless guard.
+        controlDriverUrl,
         controlDriverAuthToken,
         basePlugins,
         appBundles,
@@ -89,12 +93,19 @@ export async function createCloudStack(config: CloudStackConfig): Promise<{
     //   3. OS_DATABASE_URL          (legacy alias — only used here when no
     //                                higher-priority source is set; reserved
     //                                going forward for the project's data DB)
-    //   4. TURSO_DATABASE_URL       (legacy alias)
-    //   5. file:./.objectstack/data/control.db (default)
+    //   4. TURSO_DATABASE_URL       (legacy alias — recommended on Vercel)
+    //   5. file:<resolveDefaultDataDir()>/control.db on writable filesystems.
+    //      On serverless (Vercel / Lambda / Netlify) without any of the above,
+    //      resolveDefaultDataDir() throws with a message pointing at Turso —
+    //      we never silently fall back to ephemeral /tmp SQLite.
     const explicitControlUrl = process.env.OS_CONTROL_DATABASE_URL?.trim();
     const legacyControlUrl = (process.env.OS_DATABASE_URL || process.env.TURSO_DATABASE_URL)?.trim();
+    const resolvedControlUrl = explicitControlUrl
+        || controlDriverUrl
+        || legacyControlUrl
+        || `file:${resolvePath(resolveDefaultDataDir(), 'control.db')}`;
     const controlDriverPromise = buildControlDriver(
-        explicitControlUrl || controlDriverUrl || legacyControlUrl || `file:${resolvePath(resolveDefaultDataDir(), 'control.db')}`,
+        resolvedControlUrl,
         process.env.OS_CONTROL_DATABASE_AUTH_TOKEN || process.env.OS_DATABASE_AUTH_TOKEN || process.env.TURSO_AUTH_TOKEN || controlDriverAuthToken,
     );
 
diff --git a/packages/services/service-cloud/src/data-dir.ts b/packages/services/service-cloud/src/data-dir.ts
@@ -1,42 +1,47 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * Default data-directory resolution.
+ * Default data-directory + serverless-platform detection.
  *
  * Single source of truth for the on-disk location of the control-plane
  * SQLite file (`control.db`), per-project SQLite files, and InMemoryDriver
- * persistence JSON files. All cloud-stack / runtime-stack code paths
- * resolve their default paths through {@link resolveDefaultDataDir} so
- * that the same precedence and serverless fallback applies everywhere.
+ * persistence JSON files in **non-serverless** deployments.
  *
- * Resolution order:
+ * On serverless platforms with a read-only application bundle (Vercel,
+ * AWS Lambda, Netlify Functions, Cloudflare Workers Node compat) the
+ * file-backed default is unsupported — `/var/task` is read-only and
+ * `/tmp` is per-instance, ephemeral, and not shared between concurrent
+ * cold starts. Persisting business data there silently corrupts
+ * deployments. The recommended (and only sensible) default for these
+ * platforms is **Turso / libSQL** — set `TURSO_DATABASE_URL` (or
+ * `OS_CONTROL_DATABASE_URL=libsql://…`) and the cloud-stack driver
+ * factory will pick it up automatically.
  *
- *   1. `OS_DATA_DIR` environment variable (explicit override — wins always).
- *   2. `<cwd>/.objectstack/data` on a writable filesystem (the default for
- *      `objectstack dev`, `objectstack serve`, Docker, bare metal, …).
- *   3. `<os.tmpdir()>/.objectstack/data` when running on a serverless
- *      platform with a read-only application bundle (Vercel, AWS Lambda,
- *      Netlify Functions, Cloudflare Workers Node compat). A one-time
- *      warning is emitted because `/tmp` is ephemeral — production
- *      deployments must configure a real database via
- *      `OS_CONTROL_DATABASE_URL` (and `OS_DATABASE_URL` for project data).
+ * Resolution order for {@link resolveDefaultDataDir}:
  *
- * Centralising this logic prevents the "ENOENT: mkdir '/var/task/.objectstack'"
- * class of cold-start failures on serverless without forcing every caller
- * to re-implement detection.
+ *   1. `OS_DATA_DIR` environment variable (explicit override — wins
+ *      always, even on serverless; intended for self-managed mounts
+ *      such as a network volume or EFS share).
+ *   2. `<cwd>/.objectstack/data` on a writable filesystem (the default
+ *      for `objectstack dev`, `objectstack serve`, Docker, bare metal, …).
+ *   3. **THROWS** on a detected serverless read-only filesystem. The
+ *      error message tells the user exactly which env var to set.
+ *
+ * Centralising this logic prevents both
+ * (a) the "ENOENT: mkdir '/var/task/.objectstack'" cold-start crash, and
+ * (b) the worse failure mode where an ephemeral `/tmp` SQLite "works"
+ *     for a single cold start and silently loses data on the next one.
  */
 
 import { resolve as resolvePath } from 'node:path';
-import { tmpdir } from 'node:os';
-
-let _warned = false;
 
 /**
  * Returns `true` when the current process is running on a serverless
- * platform whose application bundle is a read-only filesystem. The set
- * of detected platforms intentionally matches the ones where ObjectStack
- * is regularly deployed today; new platforms can be added via the
- * `OS_READONLY_FS=1` escape hatch.
+ * platform whose application bundle is a read-only filesystem and whose
+ * `/tmp` is per-instance / ephemeral. The set of detected platforms
+ * intentionally matches the ones where ObjectStack is regularly deployed
+ * today; new platforms can be added via the `OS_READONLY_FS=1` escape
+ * hatch.
  */
 export function isServerlessReadOnlyFs(env: NodeJS.ProcessEnv = process.env): boolean {
     if (env.OS_READONLY_FS && ['1', 'true', 'yes', 'on'].includes(env.OS_READONLY_FS.trim().toLowerCase())) {
@@ -51,10 +56,38 @@ export function isServerlessReadOnlyFs(env: NodeJS.ProcessEnv = process.env): bo
     return false;
 }
 
+/**
+ * Build the standard "configure a persistent database" error message
+ * shown when a file-backed default is requested on serverless.
+ * @internal
+ */
+export function buildServerlessPersistenceError(role: 'control' | 'project' = 'control'): Error {
+    const urlVar = role === 'control' ? 'TURSO_DATABASE_URL (or OS_CONTROL_DATABASE_URL)' : 'OS_DATABASE_URL';
+    const tokenVar = role === 'control' ? 'TURSO_AUTH_TOKEN (or OS_CONTROL_DATABASE_AUTH_TOKEN)' : 'OS_DATABASE_AUTH_TOKEN';
+    return new Error(
+        `[objectstack/service-cloud] Detected a serverless read-only filesystem ` +
+        `(Vercel / AWS Lambda / Netlify) but no persistent database is configured ` +
+        `for the ${role === 'control' ? 'control plane' : 'project data plane'}. ` +
+        `Set ${urlVar} to a libsql:// URL (recommended on Vercel — Turso is the ` +
+        `default ObjectStack pairing for serverless) and ${tokenVar} to the ` +
+        `matching auth token. ` +
+        `For self-hosted Postgres / MySQL, set the same variable to a ` +
+        `postgres:// or mysql:// URL instead. ` +
+        `If you have a writable persistent mount (EFS, network volume, …), ` +
+        `set OS_DATA_DIR to its path to opt out of this check. ` +
+        `File-backed SQLite is rejected on these platforms because /tmp is ` +
+        `per-instance and ephemeral, which silently corrupts data across ` +
+        `concurrent invocations.`,
+    );
+}
+
 /**
  * Resolve the canonical default data directory for SQLite / file-backed
  * driver persistence. See module docstring for precedence rules.
  *
+ * Throws on serverless platforms unless `OS_DATA_DIR` is set — see
+ * {@link buildServerlessPersistenceError} for the rationale.
+ *
  * @param env - Optional process-env override, primarily for tests.
  * @returns Absolute filesystem path. Never returns a trailing slash.
  */
@@ -63,29 +96,8 @@ export function resolveDefaultDataDir(env: NodeJS.ProcessEnv = process.env): str
     if (explicit) return resolvePath(explicit);
 
     if (isServerlessReadOnlyFs(env)) {
-        const dir = resolvePath(tmpdir(), '.objectstack/data');
-        if (!_warned) {
-            _warned = true;
-            // eslint-disable-next-line no-console
-            console.warn(
-                `[objectstack] Detected serverless read-only filesystem. ` +
-                `Falling back to ephemeral data directory: ${dir}. ` +
-                `Set OS_CONTROL_DATABASE_URL (and OS_DATABASE_URL for project data) ` +
-                `to a persistent database (libsql://, postgres://, mysql://, …) for production.`,
-            );
-        }
-        return dir;
+        throw buildServerlessPersistenceError('control');
     }
 
     return resolvePath(process.cwd(), '.objectstack/data');
 }
-
-/**
- * Test-only helper: reset the one-shot warning latch so test suites can
- * assert the warning is emitted exactly once per process.
- *
- * @internal
- */
-export function __resetDataDirWarningForTests(): void {
-    _warned = false;
-}
diff --git a/packages/services/service-cloud/test/data-dir.test.ts b/packages/services/service-cloud/test/data-dir.test.ts
@@ -1,62 +1,60 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import { resolve as resolvePath } from 'node:path';
-import { tmpdir } from 'node:os';
 import {
     resolveDefaultDataDir,
     isServerlessReadOnlyFs,
-    __resetDataDirWarningForTests,
+    buildServerlessPersistenceError,
 } from '../src/data-dir.js';
 
 describe('resolveDefaultDataDir', () => {
-    beforeEach(() => {
-        vi.restoreAllMocks();
-        __resetDataDirWarningForTests();
-    });
-
     it('honours OS_DATA_DIR when set', () => {
         const dir = resolveDefaultDataDir({ OS_DATA_DIR: '/custom/path' });
         expect(dir).toBe(resolvePath('/custom/path'));
     });
 
-    it('OS_DATA_DIR wins over serverless detection', () => {
-        const dir = resolveDefaultDataDir({ OS_DATA_DIR: '/custom/path', VERCEL: '1' });
-        expect(dir).toBe(resolvePath('/custom/path'));
+    it('OS_DATA_DIR wins over serverless detection (escape hatch for EFS / mounted volumes)', () => {
+        const dir = resolveDefaultDataDir({ OS_DATA_DIR: '/mnt/efs', VERCEL: '1' });
+        expect(dir).toBe(resolvePath('/mnt/efs'));
     });
 
     it('defaults to <cwd>/.objectstack/data on a writable filesystem', () => {
         const dir = resolveDefaultDataDir({});
         expect(dir).toBe(resolvePath(process.cwd(), '.objectstack/data'));
     });
 
-    it('falls back to /tmp when running on Vercel', () => {
-        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-        const dir = resolveDefaultDataDir({ VERCEL: '1' });
-        expect(dir).toBe(resolvePath(tmpdir(), '.objectstack/data'));
-        expect(warn).toHaveBeenCalledOnce();
-        warn.mockRestore();
+    it('throws on Vercel without OS_DATA_DIR — points at TURSO_DATABASE_URL', () => {
+        expect(() => resolveDefaultDataDir({ VERCEL: '1' })).toThrowError(/TURSO_DATABASE_URL/);
+    });
+
+    it('throws on AWS Lambda without OS_DATA_DIR', () => {
+        expect(() => resolveDefaultDataDir({ AWS_LAMBDA_FUNCTION_NAME: 'fn' })).toThrowError(
+            /serverless read-only filesystem/,
+        );
     });
 
-    it('falls back to /tmp on AWS Lambda', () => {
-        vi.spyOn(console, 'warn').mockImplementation(() => {});
-        const dir = resolveDefaultDataDir({ AWS_LAMBDA_FUNCTION_NAME: 'my-fn' });
-        expect(dir).toBe(resolvePath(tmpdir(), '.objectstack/data'));
+    it('throws on Netlify without OS_DATA_DIR', () => {
+        expect(() => resolveDefaultDataDir({ NETLIFY: 'true' })).toThrowError(/Netlify/);
     });
 
-    it('warns only once per process', () => {
-        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-        resolveDefaultDataDir({ VERCEL: '1' });
-        resolveDefaultDataDir({ VERCEL: '1' });
-        resolveDefaultDataDir({ VERCEL: '1' });
-        expect(warn).toHaveBeenCalledOnce();
-        warn.mockRestore();
+    it('throws when OS_READONLY_FS=1 escape hatch is set without OS_DATA_DIR', () => {
+        expect(() => resolveDefaultDataDir({ OS_READONLY_FS: '1' })).toThrowError(
+            /TURSO_DATABASE_URL/,
+        );
     });
 
-    it('OS_READONLY_FS escape hatch triggers tmpdir fallback', () => {
-        vi.spyOn(console, 'warn').mockImplementation(() => {});
-        const dir = resolveDefaultDataDir({ OS_READONLY_FS: '1' });
-        expect(dir).toBe(resolvePath(tmpdir(), '.objectstack/data'));
+    it('error message mentions both URL and auth-token env vars and explains why /tmp is rejected', () => {
+        try {
+            resolveDefaultDataDir({ VERCEL: '1' });
+            expect.fail('should have thrown');
+        } catch (e: any) {
+            expect(e.message).toMatch(/TURSO_DATABASE_URL/);
+            expect(e.message).toMatch(/TURSO_AUTH_TOKEN/);
+            expect(e.message).toMatch(/OS_CONTROL_DATABASE_URL/);
+            expect(e.message).toMatch(/OS_DATA_DIR/);
+            expect(e.message).toMatch(/per-instance|ephemeral/);
+        }
     });
 });
 
@@ -79,3 +77,13 @@ describe('isServerlessReadOnlyFs', () => {
         expect(isServerlessReadOnlyFs({ OS_READONLY_FS: '0' })).toBe(false);
     });
 });
+
+describe('buildServerlessPersistenceError', () => {
+    it('control-plane variant mentions TURSO_DATABASE_URL', () => {
+        expect(buildServerlessPersistenceError('control').message).toMatch(/TURSO_DATABASE_URL/);
+    });
+    it('project variant mentions OS_DATABASE_URL', () => {
+        expect(buildServerlessPersistenceError('project').message).toMatch(/OS_DATABASE_URL/);
+    });
+});
+
