@bod.ee/db 0.12.1 → 0.12.4

package/src/server/ReplicationEngine.ts

@@ -2,6 +2,7 @@ import type { BodDB } from './BodDB.ts';
 import { BodClient } from '../client/BodClient.ts';
 import type { ClientMessage } from '../shared/protocol.ts';
 import type { CompactOptions } from './StreamEngine.ts';
+import type { ComponentLogger } from '../shared/logger.ts';
 
 export interface ReplEvent {
   op: 'set' | 'delete' | 'push';
@@ -20,6 +21,94 @@ export interface WriteEvent {
   ttl?: number;
 }
 
+// --- Per-path topology types ---
+
+/**
+ * Per-path replication mode:
+ * - `primary`: local-authoritative, emits to _repl, not pulled from remote
+ * - `replica`: remote-authoritative, pulled from remote, client writes proxied to primary
+ * - `sync`: emits + pulls (one-directional pull — remote must also configure a source pointing back for true bidirectional)
+ * - `readonly`: pulled from remote, client writes rejected
+ * - `writeonly`: emits only, not pulled from remote, client writes allowed locally
+ */
+export type PathMode = 'primary' | 'replica' | 'sync' | 'readonly' | 'writeonly';
+
+export interface PathTopology {
+  path: string;
+  mode: PathMode;
+  /** Override write behavior: 'reject' rejects writes even on replica paths (default: proxy for replica, reject for readonly) */
+  writeProxy?: 'proxy' | 'optimistic' | 'reject';
+}
+
+/** Resolves per-path replication mode via longest-prefix match */
+export class PathTopologyRouter {
+  private entries: PathTopology[];
+  private fallbackMode: PathMode;
+
+  constructor(paths: Array<string | PathTopology>, fallbackRole: 'primary' | 'replica') {
+    this.fallbackMode = fallbackRole === 'primary' ? 'primary' : 'replica';
+    this.entries = paths.map(p =>
+      typeof p === 'string' ? { path: p, mode: 'sync' as PathMode } : p
+    );
+    // Sort longest-first for prefix matching
+    this.entries.sort((a, b) => b.path.length - a.path.length);
+  }
+
+  /** Longest-prefix match, falls back to role-based mode */
+  resolve(path: string): PathTopology {
+    for (const e of this.entries) {
+      if (path === e.path || path.startsWith(e.path + '/')) {
+        return e;
+      }
+    }
+    return { path: '', mode: this.fallbackMode };
+  }
+
+  /** Should this path's writes be emitted to _repl? */
+  shouldEmit(path: string): boolean {
+    const { mode } = this.resolve(path);
+    return mode === 'primary' || mode === 'sync' || mode === 'writeonly';
+  }
+
+  /** Should incoming repl events for this path be applied? */
+  shouldApply(path: string): boolean {
+    const { mode } = this.resolve(path);
+    return mode === 'replica' || mode === 'sync' || mode === 'readonly';
+  }
+
+  /** Should client writes to this path be proxied to primary? */
+  shouldProxy(path: string): boolean {
+    const { mode, writeProxy } = this.resolve(path);
+    if (writeProxy === 'reject') return false;
+    if (mode === 'readonly') return false; // readonly rejects, not proxies
+    return mode === 'replica';
+  }
+
+  /** Should client writes to this path be rejected? */
+  shouldReject(path: string): boolean {
+    const { mode, writeProxy } = this.resolve(path);
+    if (writeProxy === 'reject') return true;
+    return mode === 'readonly';
+  }
+
+  /** Get all configured entries */
+  getEntries(): readonly PathTopology[] { return this.entries; }
+
+  /** Get paths that need pulling from primary (ongoing stream subscription) */
+  getReplicaPaths(): string[] {
+    return this.entries
+      .filter(e => e.mode === 'replica' || e.mode === 'readonly' || e.mode === 'sync')
+      .map(e => e.path);
+  }
+
+  /** Get paths that need full bootstrap from primary (excludes sync — sync paths get ongoing events only, avoiding overwrite of local state) */
+  getBootstrapPaths(): string[] {
+    return this.entries
+      .filter(e => e.mode === 'replica' || e.mode === 'readonly')
+      .map(e => e.path);
+  }
+}
+
 export class ReplicationSource {
   url: string = '';
   auth?: () => string | Promise<string>;
@@ -34,17 +123,25 @@ export class ReplicationOptions {
   primaryUrl?: string;
   primaryAuth?: () => string | Promise<string>;
   replicaId?: string;
+  /** Paths excluded from replication. Note: when `paths` explicitly configures a prefix (e.g. `_auth`), it overrides this exclusion. */
   excludePrefixes: string[] = ['_repl', '_streams', '_mq', '_admin', '_auth'];
   /** Bootstrap replica from primary's full state before applying _repl stream */
   fullBootstrap: boolean = true;
   compact?: CompactOptions;
+  /** Auto-compact _repl after this many emitted writes (0 = disabled, default 500) */
+  autoCompactThreshold: number = 500;
   sources?: ReplicationSource[];
+  /** Per-path topology: strings default to 'sync', objects specify mode. When absent, role governs all paths. */
+  paths?: Array<string | PathTopology>;
 }
 
+const BOOTSTRAP_BATCH_SIZE = 200;
+
 type ProxyableMessage = Extract<ClientMessage, { op: 'set' | 'delete' | 'update' | 'push' | 'batch' }>;
 
 export class ReplicationEngine {
   readonly options: ReplicationOptions;
+  readonly router: PathTopologyRouter | null = null;
   private client: BodClient | null = null;
   private unsubWrite: (() => void) | null = null;
   private unsubStream: (() => void) | null = null;
@@ -52,10 +149,17 @@ export class ReplicationEngine {
   private _started = false;
   private _seq = 0;
   private _emitting = false;
+  private _emitCount = 0;
   private _pendingReplEvents: WriteEvent[] | null = null;
-
-  get isReplica(): boolean { return this.options.role === 'replica'; }
-  get isPrimary(): boolean { return this.options.role === 'primary'; }
+  private log: ComponentLogger;
+
+  /** When no router, falls back to role-based check. With router, both return false — use emitsToRepl/pullsFromPrimary instead. */
+  get isReplica(): boolean { return !this.router && this.options.role === 'replica'; }
+  get isPrimary(): boolean { return !this.router && this.options.role === 'primary'; }
+  /** True if this node emits write events to _repl (primary, router with emitting paths, or any node with startPrimary called) */
+  get emitsToRepl(): boolean { return this.isPrimary || !!this.router; }
+  /** True if this node pulls events from a primary */
+  get pullsFromPrimary(): boolean { return this.isReplica || (!!this.router && this.router.getReplicaPaths().length > 0); }
   get started(): boolean { return this._started; }
   get seq(): number { return this._seq; }
 
@@ -65,6 +169,7 @@ export class ReplicationEngine {
       role: this.options.role,
       started: this._started,
       seq: this._seq,
+      topology: this.router ? this.router.getEntries().map(e => ({ path: e.path, mode: e.mode })) : null,
       sources: (this.options.sources ?? []).map((s, i) => {
         const conn = this.sourceConns[i];
         return {
@@ -84,19 +189,62 @@ export class ReplicationEngine {
     options?: Partial<ReplicationOptions>,
   ) {
     this.options = { ...new ReplicationOptions(), ...options };
+    this.log = db.log.forComponent('repl');
+    if (this.options.paths?.length) {
+      this.router = new PathTopologyRouter(this.options.paths, this.options.role);
+    }
     if (!this.options.replicaId) {
-      this.options.replicaId = `replica_${Math.random().toString(36).slice(2, 10)}`;
+      // Derive stable ID from config when possible, fall back to random
+      if (this.options.primaryUrl) {
+        const seed = `${this.options.primaryUrl}:${(this.options.paths ?? []).map(p => typeof p === 'string' ? p : p.path).sort().join('+')}`;
+        // Simple hash for stability across restarts
+        let h = 0;
+        for (let i = 0; i < seed.length; i++) h = ((h << 5) - h + seed.charCodeAt(i)) | 0;
+        this.options.replicaId = `replica_${(h >>> 0).toString(36)}`;
+      } else {
+        this.options.replicaId = `replica_${Math.random().toString(36).slice(2, 10)}`;
+      }
     }
   }
 
+  /** Should client writes to this path be proxied to primary? */
+  shouldProxyPath(path: string): boolean {
+    if (this.router) {
+      // Only proxy if we have a client connection to proxy through
+      return this.router.shouldProxy(path) && !!this.client;
+    }
+    return this.options.role === 'replica';
+  }
+
+  /** Should client writes to this path be rejected? */
+  shouldRejectPath(path: string): boolean {
+    if (this.router) {
+      const shouldProxy = this.router.shouldProxy(path);
+      // If path wants proxy but no client → reject instead of crashing
+      if (shouldProxy && !this.client) return true;
+      return this.router.shouldReject(path);
+    }
+    return false;
+  }
+
   /** Start replication — primary listens for writes, replica connects and consumes */
   async start(): Promise<void> {
     if (this._started) return;
     this._started = true;
 
-    if (this.isPrimary) {
+    // Always hook writes for emit (router or primary will filter)
+    if (this.router || this.isPrimary) {
       this.startPrimary();
-    } else {
+    }
+
+    // Connect to primary for replica/readonly/sync paths
+    if (this.router) {
+      const pullPaths = this.router.getReplicaPaths();
+      if (pullPaths.length) {
+        if (!this.options.primaryUrl) throw new Error('primaryUrl is required when paths include replica/readonly/sync modes');
+        await this.startReplicaForPaths(pullPaths);
+      }
+    } else if (this.options.role === 'replica') {
       await this.startReplica();
     }
 
@@ -108,6 +256,7 @@ export class ReplicationEngine {
   /** Stop replication */
   stop(): void {
     this._started = false;
+    this._emitCount = 0;
     this.unsubWrite?.();
     this.unsubWrite = null;
     this.unsubStream?.();
@@ -123,7 +272,7 @@ export class ReplicationEngine {
 
   /** Proxy a write operation to the primary (replica mode) */
   async proxyWrite(msg: ProxyableMessage): Promise<unknown> {
-    if (!this.client) throw new Error('Replica not connected to primary');
+    if (!this.client) throw new Error('Replica not connected to primary — ensure primaryUrl is set and start() has been called');
     switch (msg.op) {
       case 'set':
         await this.client.set(msg.path, msg.value, msg.ttl ? { ttl: msg.ttl } : undefined);
@@ -149,16 +298,40 @@ export class ReplicationEngine {
     this.unsubWrite = this.db.onWrite((ev: WriteEvent) => {
       this.emit(ev);
     });
+
+    // Compact on startup
+    const compact = this.options.compact ?? { maxCount: 500, keepKey: 'path' };
+    if (compact.maxCount || compact.maxAge) {
+      try { this.db.stream.compact('_repl', compact); } catch {}
+    }
   }
 
   private isExcluded(path: string): boolean {
-    return this.options.excludePrefixes.some(p => path.startsWith(p));
+    if (this.options.excludePrefixes.some(p => path.startsWith(p))) {
+      // If router explicitly configures this path, don't exclude it
+      if (this.router) {
+        const resolved = this.router.resolve(path);
+        if (resolved.path !== '') return false; // explicitly configured → not excluded
+      }
+      return true;
+    }
+    return false;
   }
 
   /** Buffer replication events during transactions, emit immediately otherwise */
   private emit(ev: WriteEvent): void {
     if (this._emitting) return;
-    if (this.isExcluded(ev.path)) return;
+    if (this.router) {
+      // Single resolve: check exclusion override + shouldEmit together
+      const resolved = this.router.resolve(ev.path);
+      const isConfigured = resolved.path !== '';
+      // If in excludePrefixes but not explicitly configured, skip
+      if (!isConfigured && this.options.excludePrefixes.some(p => ev.path.startsWith(p))) return;
+      const mode = resolved.mode;
+      if (mode !== 'primary' && mode !== 'sync' && mode !== 'writeonly') return;
+    } else {
+      if (this.isExcluded(ev.path)) return;
+    }
 
     // If buffering (transaction in progress), collect events
     if (this._pendingReplEvents) {
@@ -176,9 +349,19 @@ export class ReplicationEngine {
       const seq = this._seq++;
       const idempotencyKey = `${replEvent.ts}:${seq}:${ev.path}`;
       this.db.push('_repl', replEvent, { idempotencyKey });
+
     } finally {
       this._emitting = false;
     }
+
+    // Auto-compact on write threshold (outside _emitting guard so notifications flow normally)
+    this._emitCount++;
+    const threshold = this.options.autoCompactThreshold;
+    if (threshold > 0 && this._emitCount >= threshold) {
+      this._emitCount = 0;
+      const compact = this.options.compact ?? { maxCount: 500, keepKey: 'path' };
+      try { this.db.stream.compact('_repl', compact); } catch {}
+    }
   }
 
   /** Start buffering replication events (call before transaction) */
@@ -202,42 +385,75 @@ export class ReplicationEngine {
 
   // --- Replica mode ---
 
-  private async startReplica(): Promise<void> {
-    if (!this.options.primaryUrl) throw new Error('primaryUrl required for replica mode');
+  /** Start replica for specific path prefixes (router-based) */
+  private async startReplicaForPaths(pathPrefixes: string[]): Promise<void> {
+    if (!this.options.primaryUrl) throw new Error('primaryUrl required for per-path replication');
 
     this.client = new BodClient({
       url: this.options.primaryUrl,
       auth: this.options.primaryAuth,
     });
-
     await this.client.connect();
-    console.log(`  [REPL] Connected to primary ${this.options.primaryUrl}`);
+    this.log.info(`Connected to primary ${this.options.primaryUrl} (paths: ${pathPrefixes.join(', ')})`);
 
-    // Full state bootstrap: fetch all data from primary (catches pre-replication data)
-    if (this.options.fullBootstrap) {
-      await this.bootstrapFullState();
+    // Bootstrap only replica/readonly paths (sync paths get ongoing events only — avoids overwriting local state)
+    const bootstrapPaths = this.router!.getBootstrapPaths();
+    if (this.options.fullBootstrap && bootstrapPaths.length) {
+      await this.bootstrapFullState(bootstrapPaths);
     }
 
-    // Stream bootstrap: apply _repl events on top (catches recent writes, deduped by idempotent set)
-    const snapshot = await this.client!.streamMaterialize('_repl', { keepKey: 'path' });
-    console.log(`  [REPL] Stream bootstrap: ${snapshot ? Object.keys(snapshot).length + ' events' : 'no events'}`);
-    if (snapshot) {
+    // Stream bootstrap filtered (cursor-based to avoid huge single response)
+    const applied = await this.bootstrapFromStream(this.client!, { filter: ev => this.matchesPathPrefixes(ev.path, pathPrefixes) });
+    this.log.info(`Stream bootstrap (paths): ${applied} events applied`);
+
+    // Subscribe to ongoing events, filter by paths
+    const groupId = this.options.replicaId!;
+    this.unsubStream = this.client.stream('_repl', groupId).on((events) => {
       this.db.setReplaying(true);
       try {
-        for (const [, event] of Object.entries(snapshot)) {
-          const ev = event as ReplEvent;
-          this.applyEvent(ev);
+        for (const e of events) {
+          const ev = e.val() as ReplEvent;
+          if (this.matchesPathPrefixes(ev.path, pathPrefixes)) {
+            this.applyEvent(ev);
+          }
+          this.client!.stream('_repl', groupId).ack(e.key).catch(() => {});
         }
       } finally {
         this.db.setReplaying(false);
       }
+    });
+  }
+
+  /** Check if path matches any of the given prefixes */
+  private matchesPathPrefixes(path: string, prefixes: string[]): boolean {
+    return prefixes.some(p => path === p || path.startsWith(p + '/'));
+  }
+
+  private async startReplica(): Promise<void> {
+    if (!this.options.primaryUrl) throw new Error('primaryUrl required for replica mode');
+
+    this.client = new BodClient({
+      url: this.options.primaryUrl,
+      auth: this.options.primaryAuth,
+    });
+
+    await this.client.connect();
+    this.log.info(`Connected to primary ${this.options.primaryUrl}`);
+
+    // Full state bootstrap: fetch all data from primary (catches pre-replication data)
+    if (this.options.fullBootstrap) {
+      await this.bootstrapFullState();
     }
 
+    // Stream bootstrap: cursor-based to avoid huge single response
+    const applied = await this.bootstrapFromStream(this.client!);
+    this.log.info(`Stream bootstrap: ${applied} events applied`);
+
     // Subscribe to ongoing events
     const groupId = this.options.replicaId!;
-    console.log(`  [REPL] Subscribing to stream as '${groupId}'`);
+    this.log.info(`Subscribing to stream as '${groupId}'`);
     this.unsubStream = this.client.stream('_repl', groupId).on((events) => {
-      console.log(`  [REPL] Received ${events.length} events`);
+      this.log.debug(`Received ${events.length} events`);
       this.db.setReplaying(true);
       try {
         for (const e of events) {
@@ -252,13 +468,16 @@ export class ReplicationEngine {
     });
   }
 
-  /** Fetch full DB state from primary and apply locally */
-  private async bootstrapFullState(): Promise<void> {
+  /** Fetch full DB state from primary and apply locally. Optional pathPrefixes filters which top-level keys to pull. */
+  private async bootstrapFullState(pathPrefixes?: string[]): Promise<void> {
     const topLevel = await this.client!.getShallow();
-    const keys = topLevel
+    let keys = topLevel
       .map(e => e.key)
       .filter(k => !this.isExcluded(k));
-    console.log(`  [REPL] Full bootstrap: ${keys.length} top-level keys [${keys.join(', ')}]`);
+    if (pathPrefixes) {
+      keys = keys.filter(k => this.matchesPathPrefixes(k, pathPrefixes));
+    }
+    this.log.info(`Full bootstrap: ${keys.length} top-level keys [${keys.join(', ')}]`);
     if (keys.length === 0) return;
 
     this.db.setReplaying(true);
@@ -283,7 +502,7 @@ export class ReplicationEngine {
     for (let i = 0; i < results.length; i++) {
       if (results[i].status === 'rejected') {
         const src = this.options.sources![i];
-        console.error(`[REPL] source ${src.url} paths=[${src.paths}] failed:`, (results[i] as PromiseRejectedResult).reason);
+        this.log.error(`source ${src.url} paths=[${src.paths}] failed:`, (results[i] as PromiseRejectedResult).reason);
       }
     }
   }
@@ -292,21 +511,11 @@ export class ReplicationEngine {
     const client = new BodClient({ url: source.url, auth: source.auth });
     await client.connect();
 
-    // Bootstrap: materialize _repl, filter by source paths
-    const snapshot = await client.streamMaterialize('_repl', { keepKey: 'path' });
-    if (snapshot) {
-      this.db.setReplaying(true);
-      try {
-        for (const [, event] of Object.entries(snapshot)) {
-          const ev = event as ReplEvent;
-          if (this.matchesSourcePaths(ev.path, source)) {
-            this.applyEvent(ev, source);
-          }
-        }
-      } finally {
-        this.db.setReplaying(false);
-      }
-    }
+    // Bootstrap: cursor-based materialize _repl, filter by source paths
+    await this.bootstrapFromStream(client, {
+      filter: ev => this.matchesSourcePaths(ev.path, source),
+      source,
+    });
 
     // Subscribe to ongoing events
     const groupId = source.id || `source_${source.url}_${source.paths.sort().join('+')}`;
@@ -343,8 +552,37 @@ export class ReplicationEngine {
     return source.localPrefix ? `${source.localPrefix}/${path}` : path;
   }
 
+  /** Cursor-based stream bootstrap: pages through _repl materialize to avoid huge single responses */
+  private async bootstrapFromStream(client: BodClient, opts?: { filter?: (ev: ReplEvent) => boolean; source?: ReplicationSource }): Promise<number> {
+    let cursor: string | undefined;
+    let applied = 0;
+    const filter = opts?.filter;
+    const source = opts?.source;
+    this.db.setReplaying(true);
+    try {
+      do {
+        const page = await client.streamMaterialize('_repl', { keepKey: 'path', batchSize: BOOTSTRAP_BATCH_SIZE, cursor });
+        if (page.data) {
+          for (const [, event] of Object.entries(page.data)) {
+            const ev = event as ReplEvent;
+            if (!filter || filter(ev)) {
+              this.applyEvent(ev, source);
+              applied++;
+            }
+          }
+        }
+        cursor = page.nextCursor;
+      } while (cursor);
+    } finally {
+      this.db.setReplaying(false);
+    }
+    return applied;
+  }
+
   private applyEvent(ev: ReplEvent, source?: ReplicationSource): void {
     const path = source ? this.remapPath(ev.path, source) : ev.path;
+    // Defense-in-depth: skip events for paths we shouldn't apply (primary/writeonly)
+    if (!source && this.router && !this.router.shouldApply(path)) return;
     switch (ev.op) {
       case 'set':
         this.db.set(path, ev.value, ev.ttl ? { ttl: ev.ttl } : undefined);

package/src/server/Transport.ts

@@ -159,7 +159,14 @@ export class Transport {
         if (this.options.keyAuth && path.startsWith(AUTH_PREFIX)) {
           return Response.json({ ok: false, error: `Write to ${AUTH_PREFIX} is reserved`, code: Errors.PERMISSION_DENIED }, { status: 403 });
         }
-        if (this.db.replication?.isReplica) {
+        const auth = await this.extractAuth(req);
+        if (this.rules && !this.rules.check('write', path, auth)) {
+          return Response.json({ ok: false, error: 'Permission denied', code: Errors.PERMISSION_DENIED }, { status: 403 });
+        }
+        if (this.db.replication?.shouldRejectPath(path)) {
+          return Response.json({ ok: false, error: 'Path is readonly', code: Errors.PERMISSION_DENIED }, { status: 403 });
+        }
+        if (this.db.replication?.shouldProxyPath(path)) {
           try {
             const body = await req.json();
             await this.db.replication.proxyWrite({ op: 'set', path, value: body });
@@ -168,10 +175,6 @@ export class Transport {
             return Response.json({ ok: false, error: e.message, code: Errors.INTERNAL }, { status: 500 });
           }
         }
-        const auth = await this.extractAuth(req);
-        if (this.rules && !this.rules.check('write', path, auth)) {
-          return Response.json({ ok: false, error: 'Permission denied', code: Errors.PERMISSION_DENIED }, { status: 403 });
-        }
         const body = await req.json();
         this.db.set(path, body);
         return Response.json({ ok: true });
@@ -185,7 +188,14 @@ export class Transport {
         if (this.options.keyAuth && path.startsWith(AUTH_PREFIX)) {
           return Response.json({ ok: false, error: `Write to ${AUTH_PREFIX} is reserved`, code: Errors.PERMISSION_DENIED }, { status: 403 });
         }
-        if (this.db.replication?.isReplica) {
+        const auth = await this.extractAuth(req);
+        if (this.rules && !this.rules.check('write', path, auth)) {
+          return Response.json({ ok: false, error: 'Permission denied', code: Errors.PERMISSION_DENIED }, { status: 403 });
+        }
+        if (this.db.replication?.shouldRejectPath(path)) {
+          return Response.json({ ok: false, error: 'Path is readonly', code: Errors.PERMISSION_DENIED }, { status: 403 });
+        }
+        if (this.db.replication?.shouldProxyPath(path)) {
           try {
             await this.db.replication.proxyWrite({ op: 'delete', path });
             return Response.json({ ok: true });
@@ -193,10 +203,6 @@ export class Transport {
             return Response.json({ ok: false, error: e.message, code: Errors.INTERNAL }, { status: 500 });
           }
         }
-        const auth = await this.extractAuth(req);
-        if (this.rules && !this.rules.check('write', path, auth)) {
-          return Response.json({ ok: false, error: 'Permission denied', code: Errors.PERMISSION_DENIED }, { status: 403 });
-        }
         this.db.delete(path);
         return Response.json({ ok: true });
       })();
@@ -418,13 +424,14 @@ export class Transport {
 
             case 'set': {
               if (guardAuthPrefix(msg.path)) return;
-              if (self.db.replication?.isReplica) {
-                try { return reply(await self.db.replication.proxyWrite(msg)); }
-                catch (e: any) { return error(e.message, Errors.INTERNAL); }
-              }
               if (self.rules && !self.rules.check('write', msg.path, ws.data.auth, self.db.get(msg.path), msg.value)) {
                 return error('Permission denied', Errors.PERMISSION_DENIED);
               }
+              if (self.db.replication?.shouldRejectPath(msg.path)) return error('Path is readonly', Errors.PERMISSION_DENIED);
+              if (self.db.replication?.shouldProxyPath(msg.path)) {
+                try { return reply(await self.db.replication.proxyWrite(msg)); }
+                catch (e: any) { return error(e.message, Errors.INTERNAL); }
+              }
               self.db.set(msg.path, msg.value, msg.ttl ? { ttl: msg.ttl } : undefined);
               return reply(null);
             }
@@ -433,28 +440,34 @@ export class Transport {
               for (const path of Object.keys(msg.updates)) {
                 if (guardAuthPrefix(path)) return;
               }
-              if (self.db.replication?.isReplica) {
-                try { return reply(await self.db.replication.proxyWrite(msg)); }
-                catch (e: any) { return error(e.message, Errors.INTERNAL); }
-              }
               for (const path of Object.keys(msg.updates)) {
                 if (self.rules && !self.rules.check('write', path, ws.data.auth)) {
                   return error(`Permission denied for ${path}`, Errors.PERMISSION_DENIED);
                 }
               }
+              // Per-path: if ANY path needs reject, reject; if ANY needs proxy, proxy all (known limitation: greedy)
+              if (self.db.replication) {
+                const paths = Object.keys(msg.updates);
+                if (paths.some(p => self.db.replication!.shouldRejectPath(p))) return error('Path is readonly', Errors.PERMISSION_DENIED);
+                if (paths.some(p => self.db.replication!.shouldProxyPath(p))) {
+                  try { return reply(await self.db.replication.proxyWrite(msg)); }
+                  catch (e: any) { return error(e.message, Errors.INTERNAL); }
+                }
+              }
               self.db.update(msg.updates);
               return reply(null);
             }
 
             case 'delete': {
               if (guardAuthPrefix(msg.path)) return;
-              if (self.db.replication?.isReplica) {
-                try { return reply(await self.db.replication.proxyWrite(msg)); }
-                catch (e: any) { return error(e.message, Errors.INTERNAL); }
-              }
               if (self.rules && !self.rules.check('write', msg.path, ws.data.auth)) {
                 return error('Permission denied', Errors.PERMISSION_DENIED);
               }
+              if (self.db.replication?.shouldRejectPath(msg.path)) return error('Path is readonly', Errors.PERMISSION_DENIED);
+              if (self.db.replication?.shouldProxyPath(msg.path)) {
+                try { return reply(await self.db.replication.proxyWrite(msg)); }
+                catch (e: any) { return error(e.message, Errors.INTERNAL); }
+              }
               self.db.delete(msg.path);
               return reply(null);
             }
@@ -502,9 +515,23 @@ export class Transport {
             }
 
             case 'batch': {
-              if (self.db.replication?.isReplica) {
-                try { return reply(await self.db.replication.proxyWrite(msg)); }
-                catch (e: any) { return error(e.message, Errors.INTERNAL); }
+              // Upfront rules check before proxy (defense-in-depth)
+              for (const batchOp of msg.operations) {
+                const opPaths = batchOp.op === 'update' ? Object.keys(batchOp.updates) : [batchOp.path];
+                for (const p of opPaths) {
+                  if (self.rules && !self.rules.check('write', p, ws.data.auth)) {
+                    return error(`Permission denied for ${p}`, Errors.PERMISSION_DENIED);
+                  }
+                }
+              }
+              // Per-path topology: if ANY path needs reject, reject; if ANY needs proxy, proxy all (known limitation: greedy)
+              if (self.db.replication) {
+                const batchPaths = msg.operations.map((o: any) => o.path != null ? [o.path] : (o.updates ? Object.keys(o.updates) : [])).flat();
+                if (batchPaths.some((p: string) => self.db.replication!.shouldRejectPath(p))) return error('Path is readonly', Errors.PERMISSION_DENIED);
+                if (batchPaths.some((p: string) => self.db.replication!.shouldProxyPath(p))) {
+                  try { return reply(await self.db.replication.proxyWrite(msg)); }
+                  catch (e: any) { return error(e.message, Errors.INTERNAL); }
+                }
               }
               const results: unknown[] = [];
               self.db.transaction((tx) => {
@@ -546,13 +573,14 @@ export class Transport {
 
             case 'push': {
               if (guardAuthPrefix(msg.path)) return;
-              if (self.db.replication?.isReplica) {
-                try { return reply(await self.db.replication.proxyWrite(msg)); }
-                catch (e: any) { return error(e.message, Errors.INTERNAL); }
-              }
               if (self.rules && !self.rules.check('write', msg.path, ws.data.auth)) {
                 return error('Permission denied', Errors.PERMISSION_DENIED);
               }
+              if (self.db.replication?.shouldRejectPath(msg.path)) return error('Path is readonly', Errors.PERMISSION_DENIED);
+              if (self.db.replication?.shouldProxyPath(msg.path)) {
+                try { return reply(await self.db.replication.proxyWrite(msg)); }
+                catch (e: any) { return error(e.message, Errors.INTERNAL); }
+              }
               const key = self.db.push(msg.path, msg.value, msg.idempotencyKey ? { idempotencyKey: msg.idempotencyKey } : undefined);
               return reply(key);
             }
@@ -678,7 +706,11 @@ export class Transport {
               if (self.rules && !self.rules.check('read', msg.path, ws.data.auth)) {
                 return error('Permission denied', Errors.PERMISSION_DENIED);
               }
-              return reply(self.db.stream.materialize(msg.path, msg.keepKey ? { keepKey: msg.keepKey } : undefined));
+              const matOpts: { keepKey?: string; batchSize?: number; cursor?: string } = {};
+              if (msg.keepKey) matOpts.keepKey = msg.keepKey;
+              if (msg.batchSize) matOpts.batchSize = msg.batchSize;
+              if (msg.cursor) matOpts.cursor = msg.cursor;
+              return reply(self.db.stream.materialize(msg.path, Object.keys(matOpts).length ? matOpts : undefined));
             }
             case 'stream-compact': {
               if (self.rules && !self.rules.check('write', msg.path, ws.data.auth)) {