create-syncular-app 0.3.0 → 0.4.0

package/template/tauri/src/frontend/main.tsx

@@ -0,0 +1,202 @@
+/**
+ * The shared React tree — every line below `<SyncProvider>` runs unchanged
+ * on BOTH hosts. In a browser it talks to the worker core on OPFS; inside
+ * the Tauri webview it talks to the native Rust core in the host process.
+ * The only host-aware code is `createEngine()` in `./engine.ts`.
+ *
+ * - `useRawSql` — the live todo list; re-runs exactly when `todos`
+ *   invalidates.
+ * - `useMutation` — add / toggle / delete; writes go through the outbox.
+ * - `useSyncStatus` — outbox depth + upgrading / schema-floor badges.
+ */
+import {
+  SyncProvider,
+  useMutation,
+  useRawSql,
+  useSyncStatus,
+} from '@syncular/react';
+import { StrictMode, useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { type TodosRow, todoListSubscription } from '../syncular.generated';
+import { createEngine, type Engine } from './engine';
+
+const LIST_ID = 'welcome';
+
+// -- app (host-agnostic from here down) ---------------------------------------
+
+function StatusLine() {
+  const status = useSyncStatus();
+  if (status.isLoading) return <span className="status">connecting…</span>;
+  return (
+    <span className="status">
+      <span className={`badge ${status.outbox === 0 ? 'ok' : 'warn'}`}>
+        outbox {status.outbox}
+      </span>
+      {status.upgrading ? <span className="badge warn">upgrading…</span> : null}
+      {status.schemaFloor !== undefined ? (
+        <span className="badge warn">schema floor</span>
+      ) : null}
+    </span>
+  );
+}
+
+function TodoApp() {
+  const { mutate, isPending, error } = useMutation();
+
+  // Live local read: re-runs exactly when `todos` invalidates.
+  const { rows, isLoading } = useRawSql<TodosRow>(
+    'SELECT id, list_id AS listId, title, done, position,' +
+      ' updated_at_ms AS updatedAtMs FROM todos WHERE list_id = ?' +
+      ' ORDER BY position, id',
+    [LIST_ID],
+  );
+
+  const add = (title: string) => {
+    const position =
+      rows.reduce((max, row) => Math.max(max, row.position), 0) + 1;
+    void mutate([
+      {
+        table: 'todos',
+        op: 'upsert',
+        values: {
+          id: crypto.randomUUID(),
+          listId: LIST_ID,
+          title,
+          done: false,
+          position,
+          updatedAtMs: Date.now(),
+        },
+      },
+    ]);
+  };
+
+  const toggle = (row: TodosRow) => {
+    void mutate([
+      {
+        table: 'todos',
+        op: 'upsert',
+        values: { ...row, done: !row.done, updatedAtMs: Date.now() },
+      },
+    ]);
+  };
+
+  const remove = (id: string) => {
+    void mutate([{ table: 'todos', op: 'delete', rowId: id }]);
+  };
+
+  return (
+    <>
+      <header>
+        <h1>__PROJECT_NAME__</h1>
+        <StatusLine />
+      </header>
+
+      <form
+        className="add"
+        onSubmit={(e) => {
+          e.preventDefault();
+          const input = e.currentTarget.elements.namedItem(
+            'title',
+          ) as HTMLInputElement;
+          const value = input.value.trim();
+          if (value.length === 0) return;
+          input.value = '';
+          add(value);
+        }}
+      >
+        <input name="title" placeholder="a new todo" autoComplete="off" />
+        <button type="submit" disabled={isPending}>
+          add
+        </button>
+      </form>
+
+      {/* Always render the write error: a dead worker/bridge RPC otherwise
+          fails silently and "add does nothing" is undebuggable. */}
+      {error !== undefined ? (
+        <div className="error">write failed: {String(error)}</div>
+      ) : null}
+
+      {isLoading ? (
+        <div className="empty">loading…</div>
+      ) : rows.length === 0 ? (
+        <div className="empty">no todos yet — add one</div>
+      ) : (
+        <ul className="todos">
+          {rows.map((row) => (
+            <li key={row.id} className={row.done ? 'done' : ''}>
+              <input
+                type="checkbox"
+                checked={Boolean(row.done)}
+                onChange={() => toggle(row)}
+              />
+              <span className="title">{row.title}</span>
+              <button
+                type="button"
+                className="del"
+                title="delete"
+                onClick={() => remove(row.id)}
+              >
+                ×
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <footer>
+        One React tree, two hosts: in the browser this is the worker core on
+        OPFS; in the Tauri window it is the native Rust core. The seam is{' '}
+        <code>src/frontend/engine.ts</code>.
+      </footer>
+    </>
+  );
+}
+
+function Root() {
+  const [engine, setEngine] = useState<Engine | undefined>(undefined);
+  const [error, setError] = useState<string | undefined>(undefined);
+
+  useEffect(() => {
+    let live: Engine | undefined;
+    void createEngine()
+      .then(async (e) => {
+        live = e;
+        await e.subscribe({
+          id: 'todos',
+          table: 'todos',
+          scopes: todoListSubscription.scopes({ listId: LIST_ID }),
+        });
+        // Ride the socket for realtime; HTTP sync still works without it.
+        try {
+          await e.connectRealtime();
+        } catch {
+          // offline / no socket — the host loop keeps syncing over HTTP
+        }
+        setEngine(e);
+      })
+      .catch((err: unknown) => setError(String(err)));
+    return () => {
+      void live?.close();
+    };
+  }, []);
+
+  if (error !== undefined) {
+    return <div className="empty">failed to start: {error}</div>;
+  }
+  if (engine === undefined) {
+    return <div className="empty">starting client core…</div>;
+  }
+  return (
+    <SyncProvider client={engine}>
+      <TodoApp />
+    </SyncProvider>
+  );
+}
+
+const container = document.getElementById('root');
+if (container === null) throw new Error('missing #root');
+createRoot(container).render(
+  <StrictMode>
+    <Root />
+  </StrictMode>,
+);

package/template/tauri/src/frontend/worker.ts

@@ -0,0 +1,9 @@
+/**
+ * The sync worker: the whole client core (SyncClient + transports + sqlite-wasm
+ * on opfs-sahpool) runs here — the page only talks RPC. Built as its own
+ * bundle (`/worker.js`) because module workers do not inherit the page's import
+ * map.
+ */
+import { startSyncWorker } from '@syncular/client/worker';
+
+startSyncWorker();

package/template/tauri/src/server.ts

@@ -0,0 +1,193 @@
+/**
+ * The WEB half of the one-codebase story, in one Bun process:
+ * - POST /sync + GET /segments/:id via the server-hono adapter,
+ * - GET /realtime as a WebSocket wired to the server's RealtimeHub (§8.7),
+ * - the static frontend: TWO bundles built with Bun.build at startup —
+ *   /app.js (the React page) and /worker.js (the sync worker running the
+ *   whole client core on opfs-sahpool). Module workers do not inherit the
+ *   page's import map, so the sqlite-wasm bare specifier is rewritten to the
+ *   served vendor path in both bundles.
+ *
+ * The DESKTOP half is `src-tauri/` — `cargo tauri dev` builds the same
+ * frontend (see `build-frontend.ts`) and hosts the native Rust core, which
+ * syncs against THIS server. One server, two hosts, one React tree.
+ *
+ * Storage is bun:sqlite (in-memory by default; set DB_PATH=path for a file).
+ *
+ * EDIT FIRST: `resolveScopes` + `authenticate` below are the whole
+ * authorization story — they run in YOUR backend next to YOUR auth.
+ */
+import { dirname, join } from 'node:path';
+import {
+  createRealtimeHub,
+  MemorySegmentStore,
+  type RealtimeSession,
+  SqliteServerStorage,
+  type SyncServerConfig,
+} from '@syncular/server';
+import { createSyncularHono } from '@syncular/server-hono';
+import { schema } from './syncular.generated';
+
+const PORT = Number(process.env.PORT ?? 8787);
+const PARTITION = 'demo';
+const ACTOR_ID = 'demo-user';
+
+// -- sync server ------------------------------------------------------------
+
+const storage = new SqliteServerStorage(process.env.DB_PATH ?? ':memory:');
+const segments = new MemorySegmentStore();
+/** Demo authorization: the single actor may see every list. Replace with the
+ * scope values the authenticated actor is allowed to see. */
+const resolveScopes = () => ({ list_id: ['*'] });
+
+const hub = createRealtimeHub({ schema, storage, resolveScopes, segments });
+const config: SyncServerConfig = {
+  schema,
+  storage,
+  segments,
+  resolveScopes,
+  realtime: hub,
+};
+const hono = createSyncularHono({
+  config,
+  // Replace with your real auth: return { actorId, partition } or null (401).
+  authenticate: async () => ({ actorId: ACTOR_ID, partition: PARTITION }),
+});
+
+// -- frontend build + static assets ------------------------------------------
+
+const build = await Bun.build({
+  entrypoints: [
+    join(import.meta.dir, 'frontend', 'main.tsx'),
+    join(import.meta.dir, 'frontend', 'worker.ts'),
+  ],
+  target: 'browser',
+  // Resolve syncular packages through their `bun` condition (TS source,
+  // shipped in the npm tarballs) — bun transpiles it, and a `--local`
+  // workspace link works without a dist build.
+  conditions: ['bun'],
+  sourcemap: 'inline',
+  define: { 'process.env.NODE_ENV': '"development"' },
+  external: ['@sqlite.org/sqlite-wasm'],
+});
+async function bundleText(basename: string): Promise<string> {
+  const artifact = build.outputs.find((output) =>
+    output.path.endsWith(`/${basename}`),
+  );
+  if (artifact === undefined) {
+    throw new Error(`frontend build produced no ${basename}`);
+  }
+  // Both bundles import sqlite-wasm from the served vendor path. An import map
+  // would only cover the page, never the module worker, so the external bare
+  // specifier is rewritten in the emitted JS instead.
+  const text = await artifact.text();
+  return text.replaceAll(
+    /(["'])@sqlite\.org\/sqlite-wasm\1/g,
+    '"/vendor/sqlite-wasm/index.mjs"',
+  );
+}
+const appJs = await bundleText('main.js');
+const workerJs = await bundleText('worker.js');
+const indexHtml = await Bun.file(
+  join(import.meta.dir, 'frontend', 'index.html'),
+).text();
+
+const wasmDir = dirname(
+  Bun.resolveSync('@sqlite.org/sqlite-wasm', import.meta.dir),
+);
+/** Only the files the sqlite-wasm ESM entry actually references. */
+const WASM_FILES: Record<string, string> = {
+  'index.mjs': 'text/javascript',
+  'sqlite3.wasm': 'application/wasm',
+  'sqlite3-opfs-async-proxy.js': 'text/javascript',
+  'sqlite3-worker1.mjs': 'text/javascript',
+};
+
+/** COOP/COEP so OPFS-capable contexts get cross-origin isolation (not
+ * required by opfs-sahpool, but harmless and future-proof). */
+const STATIC_HEADERS = {
+  'Cross-Origin-Opener-Policy': 'same-origin',
+  'Cross-Origin-Embedder-Policy': 'require-corp',
+  'Cache-Control': 'no-store',
+};
+
+function staticResponse(body: string | Uint8Array, type: string): Response {
+  return new Response(body as BodyInit, {
+    headers: { ...STATIC_HEADERS, 'Content-Type': type },
+  });
+}
+
+// -- one process, one port ----------------------------------------------------
+
+interface SocketData {
+  clientId: string;
+  session?: RealtimeSession;
+}
+
+const server = Bun.serve<SocketData, never>({
+  port: PORT,
+  async fetch(request, bunServer) {
+    const url = new URL(request.url);
+    const path = url.pathname;
+
+    if (path === '/realtime') {
+      const clientId = url.searchParams.get('clientId') ?? crypto.randomUUID();
+      if (bunServer.upgrade(request, { data: { clientId } })) {
+        return undefined as unknown as Response;
+      }
+      return new Response('expected a websocket upgrade', { status: 400 });
+    }
+    if (path === '/sync' || path.startsWith('/segments/')) {
+      return hono.fetch(request);
+    }
+    if (path === '/' || path === '/index.html') {
+      return staticResponse(indexHtml, 'text/html; charset=utf-8');
+    }
+    if (path === '/app.js') {
+      return staticResponse(appJs, 'text/javascript; charset=utf-8');
+    }
+    if (path === '/worker.js') {
+      return staticResponse(workerJs, 'text/javascript; charset=utf-8');
+    }
+    if (path.startsWith('/vendor/sqlite-wasm/')) {
+      const name = path.slice('/vendor/sqlite-wasm/'.length);
+      const type = WASM_FILES[name];
+      if (type !== undefined) {
+        const bytes = await Bun.file(join(wasmDir, name)).bytes();
+        return staticResponse(bytes, type);
+      }
+    }
+    return new Response('not found', { status: 404 });
+  },
+  websocket: {
+    open(ws) {
+      hub
+        .connect({
+          partition: PARTITION,
+          actorId: ACTOR_ID,
+          clientId: ws.data.clientId,
+          send: (data) => {
+            ws.send(data);
+          },
+          closeSocket: () => ws.close(1008, 'protocol violation (§8.7)'),
+        })
+        .then((session) => {
+          ws.data.session = session;
+        })
+        .catch(() => ws.close(1011, 'realtime connect failed'));
+    },
+    message(ws, message) {
+      if (typeof message === 'string') {
+        ws.data.session?.handleMessage(message);
+      } else {
+        ws.data.session?.handleBinary(new Uint8Array(message));
+      }
+    },
+    close(ws) {
+      ws.data.session?.close();
+    },
+  },
+});
+
+console.log(`web app:            http://localhost:${server.port}`);
+console.log('desktop (Tauri):    cd src-tauri && cargo tauri dev');

package/template/tauri/src/smoke.test.ts

@@ -0,0 +1,92 @@
+/**
+ * The tauri template's smoke test. Neither frontend host (browser worker +
+ * OPFS, Tauri webview + native core) can run headless in `bun test`, so this
+ * proves the piece that CAN rot silently: the server config + generated
+ * schema this scaffold ships actually sync. It boots the same server core
+ * config as `src/server.ts` on an ephemeral port and drives two bun:sqlite
+ * client cores through real HTTP to convergence.
+ *
+ * The frontend is covered by `tsc` (typecheck); the worker + OPFS path and
+ * the native-core path are exercised by the demo apps / conformance suite /
+ * tauri example in the syncular tree.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import {
+  httpSegmentDownloader,
+  httpSyncTransport,
+  SyncClient,
+} from '@syncular/client';
+import { openBunDatabase } from '@syncular/client/bun';
+import {
+  MemorySegmentStore,
+  SqliteServerStorage,
+  type SyncServerConfig,
+} from '@syncular/server';
+import { createSyncularHono } from '@syncular/server-hono';
+import { schema, todoListSubscription } from './syncular.generated';
+
+let server: ReturnType<typeof Bun.serve>;
+let baseUrl: string;
+
+beforeAll(() => {
+  const config: SyncServerConfig = {
+    schema,
+    storage: new SqliteServerStorage(':memory:'),
+    segments: new MemorySegmentStore(),
+    resolveScopes: () => ({ list_id: ['*'] }),
+  };
+  const app = createSyncularHono({
+    config,
+    authenticate: async () => ({ actorId: 'demo-user', partition: 'demo' }),
+  });
+  server = Bun.serve({ port: 0, fetch: app.fetch });
+  baseUrl = `http://localhost:${server.port}`;
+});
+
+afterAll(() => {
+  server.stop(true);
+});
+
+function makeClient(clientId: string): SyncClient {
+  return new SyncClient({
+    database: openBunDatabase(),
+    schema,
+    clientId,
+    transport: httpSyncTransport(`${baseUrl}/sync`),
+    segments: httpSegmentDownloader(`${baseUrl}/segments`),
+  });
+}
+
+test('two clients converge through the scaffolded server config', async () => {
+  const a = makeClient('client-a');
+  const b = makeClient('client-b');
+  await a.start();
+  await b.start();
+
+  const scopes = todoListSubscription.scopes({ listId: 'welcome' });
+  a.subscribe({ id: 'todos', table: 'todos', scopes });
+  b.subscribe({ id: 'todos', table: 'todos', scopes });
+
+  a.mutate([
+    {
+      table: 'todos',
+      op: 'upsert',
+      values: {
+        id: 'todo-1',
+        list_id: 'welcome',
+        title: 'Buy milk',
+        done: false,
+        position: 1,
+        updated_at_ms: Date.now(),
+      },
+    },
+  ]);
+  await a.syncUntilIdle();
+  await b.syncUntilIdle();
+
+  const rows = b.query('SELECT id, title, done FROM todos ORDER BY id');
+  expect(rows).toEqual([{ id: 'todo-1', title: 'Buy milk', done: 0 }]);
+
+  await a.close();
+  await b.close();
+});

package/template/tauri/src/syncular.generated.ts

@@ -0,0 +1,68 @@
+// Generated by @syncular/typegen — DO NOT EDIT.
+// irVersion: 1
+// irHash: sha256:2ffc5b70cb96cd546326de9c06868bd988c9fa3459fb3bac8428a81dcc85fca0
+
+/** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */
+export const schema = {
+  version: 1,
+  tables: [
+    {
+      name: 'todos',
+      columns: [
+        { name: 'id', type: 'string', nullable: false },
+        { name: 'list_id', type: 'string', nullable: false },
+        { name: 'title', type: 'string', nullable: false },
+        { name: 'done', type: 'boolean', nullable: false },
+        { name: 'position', type: 'integer', nullable: false },
+        { name: 'updated_at_ms', type: 'integer', nullable: false },
+      ],
+      primaryKey: 'id',
+      scopes: [
+        { pattern: 'list:{list_id}', column: 'list_id' },
+      ],
+    },
+  ],
+} as const;
+
+/** One todos row (§2.4 column order). */
+export interface TodosRow {
+  id: string;
+  listId: string;
+  title: string;
+  done: boolean;
+  position: number;
+  updatedAtMs: number;
+}
+
+/** Insert shape: nullable columns may be omitted. */
+export interface TodosInsert {
+  id: string;
+  listId: string;
+  title: string;
+  done: boolean;
+  position: number;
+  updatedAtMs: number;
+}
+
+/** Update shape: primary key required, all other columns optional. */
+export interface TodosUpdate {
+  id: string;
+  listId?: string;
+  title?: string;
+  done?: boolean;
+  position?: number;
+  updatedAtMs?: number;
+}
+
+export interface TodoListParams {
+  listId: string;
+}
+
+/** Requested-scope template for the 'todoList' subscription. */
+export const todoListSubscription = {
+  name: 'todoList',
+  table: 'todos',
+  scopes: (params: TodoListParams): Record<string, string[]> => ({
+    list_id: [params.listId],
+  }),
+} as const;

package/template/tauri/src-tauri/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "app"
+version = "0.1.0"
+edition = "2021"
+publish = false
+description = "The desktop host: a Tauri shell around the native syncular core"
+
+# Standalone crate on purpose: the scaffold is not part of any cargo
+# workspace, so a plain `cargo build` here never walks up into one.
+[workspace]
+
+[lib]
+name = "app_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+# The syncular plugin from crates.io. `native-transport` gives the core its
+# real HTTP + WebSocket transport (ureq + tungstenite) inside the host
+# process — the webview never talks to the sync server directly.
+tauri-plugin-syncular = { version = "0.4", features = ["native-transport"] }
+
+[features]
+default = []

package/template/tauri/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build();
+}

package/template/tauri/src-tauri/capabilities/syncular.json

@@ -0,0 +1,9 @@
+{
+  "identifier": "syncular",
+  "description": "Grants the main window the syncular plugin command surface.",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "syncular:default"
+  ]
+}

package/template/tauri/src-tauri/src/lib.rs

@@ -0,0 +1,40 @@
+//! The desktop host: registers `tauri-plugin-syncular`, which runs the
+//! NATIVE syncular core (real SQLite file + HTTP/WS transport) inside this
+//! process. The webview's `@syncular/tauri` bridge is a thin RPC client of
+//! it — the React tree in `src/frontend/` is byte-identical to the one the
+//! browser runs against the worker core.
+
+use tauri::Manager;
+use tauri_plugin_syncular::SyncularConfig;
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .setup(|app| {
+            // Persist the syncular database under the resolved app-data dir
+            // so it survives restarts.
+            let db_path = app
+                .path()
+                .app_data_dir()
+                .map(|dir| {
+                    let _ = std::fs::create_dir_all(&dir);
+                    dir.join("syncular.db").to_string_lossy().into_owned()
+                })
+                .ok();
+
+            // Points at this scaffold's own dev server (`bun run dev`,
+            // port 8787). Change it to your deployed sync endpoint.
+            let config = SyncularConfig {
+                base_url: Some("http://localhost:8787".to_owned()),
+                db_path,
+                // Host-loop cadence with a little jitter (§8.4).
+                wake_jitter_ms: 250,
+                auto_sync: true,
+                ..Default::default()
+            };
+            app.handle().plugin(tauri_plugin_syncular::init(config))?;
+            Ok(())
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running the tauri application");
+}

package/template/tauri/src-tauri/src/main.rs

@@ -0,0 +1,6 @@
+// Prevents an additional console window on Windows in release.
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    app_lib::run();
+}

package/template/tauri/src-tauri/tauri.conf.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "identifier": "com.example.__PROJECT_NAME__",
+  "build": {
+    "frontendDist": "../dist",
+    "beforeDevCommand": "bun run build-frontend",
+    "beforeBuildCommand": "bun run build-frontend"
+  },
+  "app": {
+    "windows": [
+      {
+        "title": "__PROJECT_NAME__",
+        "width": 900,
+        "height": 700
+      }
+    ],
+    "security": {
+      "csp": null,
+      "capabilities": ["syncular"]
+    }
+  },
+  "bundle": {
+    "active": false,
+    "targets": "all",
+    "icon": ["icons/icon.png"]
+  }
+}