bunsane 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to bunsane are documented here.
 
+## 0.5.2 — 2026-06-19
+
+### Added
+
+- **`withLock(key, fn, options?)`** — public distributed-lock primitive,
+  exported from `bunsane/core`. Runs `fn` while holding a PostgreSQL advisory
+  lock and always releases it (even if `fn` throws); only one holder of a given
+  `key` runs `fn` at a time across every process pointed at the same database.
+  Returns `{ acquired: true, result }`, or `{ acquired: false }` when the lock
+  is held elsewhere (`fn` does not run). Wraps the same `DistributedLock`
+  singleton and PostgreSQL session the scheduler uses for task exclusion, now
+  surfaced for app-level "run once cluster-wide" work — reindex, migration,
+  cache rebuild. `options.wait` (ms, default `0` = try once) blocks for the lock
+  instead of skipping; `options.retryInterval` (default 100 ms) sets the poll
+  cadence. Layers an in-process guard over the advisory lock because PostgreSQL
+  advisory locks are reentrant per session — without it, two concurrent
+  same-key callers in one process would both win. Not reentrant; crash-safe
+  (session-scoped); honors `distributedLocking: false` (then always reports
+  `acquired: true` with no real lock). Also re-exported from
+  `bunsane/core/scheduler`. A new `core/index.ts` barrel establishes
+  `bunsane/core` as a public entry point.
+
 ## 0.5.1 — 2026-06-16
 
 ### Added

package/core/app/requestRouter.ts

@@ -198,16 +198,45 @@ export async function handleRequest(app: any, req: Request): Promise<Response> {
 
         for (const [route, folder] of app.staticAssets) {
             if (url.pathname.startsWith(route)) {
-                const relativePath = url.pathname.slice(route.length);
-                const filePath = path.join(folder, relativePath);
+                const rawRelative = url.pathname.slice(route.length);
+                // Decode percent-encoding first so encoded traversal sequences
+                // (e.g. %2e%2e%2f) can't slip past the containment check.
+                let decodedRelative: string;
                 try {
-                    const file = Bun.file(filePath);
+                    decodedRelative = decodeURIComponent(rawRelative);
+                } catch {
+                    clearTimeout(timeoutId);
+                    return wrap(new Response("Bad request", {
+                        status: 400,
+                        headers: { "Content-Type": "text/plain" },
+                    }));
+                }
+                // Resolve absolutely and confirm the target stays inside the
+                // served folder — blocks path traversal (../) out of the dir.
+                // Strip leading slashes so path.resolve treats the request as
+                // relative to the folder (an absolute-looking arg would reset
+                // to the filesystem root and bypass containment).
+                const relForResolve = decodedRelative.replace(/^[/\\]+/, "");
+                const resolvedBase = path.resolve(folder);
+                const resolvedFile = path.resolve(resolvedBase, relForResolve);
+                if (
+                    resolvedFile !== resolvedBase &&
+                    !resolvedFile.startsWith(resolvedBase + path.sep)
+                ) {
+                    clearTimeout(timeoutId);
+                    return wrap(new Response("Forbidden", {
+                        status: 403,
+                        headers: { "Content-Type": "text/plain" },
+                    }));
+                }
+                try {
+                    const file = Bun.file(resolvedFile);
                     if (await file.exists()) {
                         clearTimeout(timeoutId);
                         return wrap(new Response(file));
                     }
                 } catch (error) {
-                    logger.error(`Error serving static file ${filePath}:`, error as any);
+                    logger.error(`Error serving static file ${resolvedFile}:`, error as any);
                 }
             }
         }

package/core/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Public `bunsane/core` entry point.
+ *
+ * Subpath imports (`bunsane/core/App`, `bunsane/core/middleware`, …) remain the
+ * primary surface; this barrel re-exports cross-cutting primitives intended to
+ * be imported as `bunsane/core`.
+ */
+
+export {
+    withLock,
+    type WithLockOptions,
+    type LockOutcome,
+    DistributedLock,
+    getDistributedLock,
+    resetDistributedLock,
+    DEFAULT_LOCK_CONFIG,
+    type DistributedLockConfig,
+    type LockResult,
+} from "./scheduler";

package/core/scheduler/index.ts

@@ -13,3 +13,9 @@ export {
     type DistributedLockConfig,
     type LockResult,
 } from './DistributedLock';
+
+export {
+    withLock,
+    type WithLockOptions,
+    type LockOutcome,
+} from './withLock';

package/core/scheduler/withLock.ts

@@ -0,0 +1,98 @@
+/**
+ * withLock — run a function while holding a PostgreSQL advisory lock.
+ *
+ * Thin convenience wrapper over the shared {@link DistributedLock} singleton.
+ * Acquires the lock for `key`, runs `fn`, and always releases it — even if
+ * `fn` throws. Only one holder of a given `key` runs `fn` at a time, across
+ * every process pointed at the same database. When the lock is unavailable the
+ * call returns `{ acquired: false }` without running `fn` (unless `wait` is
+ * set, in which case it polls until the lock frees or the deadline passes).
+ *
+ * Two layers of exclusion:
+ *  - Across processes: PostgreSQL `pg_advisory_lock`, owned by the singleton's
+ *    pinned connection (one PG session per instance).
+ *  - Within a process: an in-memory `Set`. PostgreSQL advisory locks are
+ *    *reentrant per session*, so two concurrent callers sharing this instance's
+ *    session would both win the pg lock — the Set makes same-process contention
+ *    exclusive too.
+ *
+ * Notes:
+ *  - Not reentrant. Calling `withLock(key, …)` for a key already held by this
+ *    process returns `{ acquired: false }` (or waits, then gives up).
+ *  - Shares the scheduler's singleton + PG session. Keys live under the same
+ *    namespace prefix as scheduler task ids — pick keys unlikely to collide.
+ *  - Honors the singleton's `enabled` config: if distributed locking was
+ *    disabled (`getDistributedLock({ enabled: false })`), `tryAcquire` always
+ *    reports success and no real lock is taken.
+ *
+ * @example
+ * const res = await withLock("rebuild-search-index", async () => {
+ *   await rebuildIndex();
+ *   return "done";
+ * });
+ * if (!res.acquired) {
+ *   // another instance is already rebuilding — skip
+ * } else {
+ *   console.log(res.result); // "done"
+ * }
+ */
+import { getDistributedLock } from "./DistributedLock";
+
+export interface WithLockOptions {
+    /** Max ms to wait for the lock before giving up. 0 (default) = try once. */
+    wait?: number;
+    /** Poll interval while waiting, in ms. Default 100. */
+    retryInterval?: number;
+}
+
+export type LockOutcome<T> =
+    | { acquired: false; result?: undefined }
+    | { acquired: true; result: T };
+
+/** In-process holders, keyed by lock key (see "Within a process" above). */
+const localHeld = new Set<string>();
+
+const sleep = (ms: number): Promise<void> =>
+    new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function withLock<T>(
+    key: string,
+    fn: () => Promise<T> | T,
+    options: WithLockOptions = {}
+): Promise<LockOutcome<T>> {
+    const { wait = 0, retryInterval = 100 } = options;
+    const deadline = wait > 0 ? Date.now() + wait : 0;
+
+    // In-process gate. The has-check that exits the loop and the subsequent
+    // add() run without an await between them, so this is atomic on JS's single
+    // thread — concurrent same-key callers cannot both pass.
+    while (localHeld.has(key)) {
+        if (!deadline || Date.now() >= deadline) {
+            return { acquired: false };
+        }
+        await sleep(retryInterval);
+    }
+    localHeld.add(key);
+
+    try {
+        const lock = getDistributedLock();
+
+        let acquired = (await lock.tryAcquire(key)).acquired;
+        while (!acquired && deadline && Date.now() < deadline) {
+            await sleep(retryInterval);
+            acquired = (await lock.tryAcquire(key)).acquired;
+        }
+
+        if (!acquired) {
+            return { acquired: false };
+        }
+
+        try {
+            return { acquired: true, result: await fn() };
+        } finally {
+            await lock.release(key);
+        }
+    } finally {
+        localHeld.delete(key);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.5.2",
+    "version": "0.5.3",
     "author": {
         "name": "yaaruu"
     },

package/query/ComponentInclusionNode.ts

@@ -3,6 +3,7 @@ import type { QueryResult } from "./QueryNode";
 import { QueryContext } from "./QueryContext";
 import { shouldUseLateralJoins, shouldUseDirectPartition } from "../core/Config";
 import { FilterBuilderRegistry } from "./FilterBuilderRegistry";
+import { jsonbInListCast } from "./FilterBuilder";
 import { ComponentRegistry } from "../core/components";
 import { getMetadataStorage } from "../core/metadata";
 import { assertIdentifier } from "./SqlIdentifier";
@@ -95,8 +96,9 @@ export class ComponentInclusionNode extends QueryNode {
             return `${jsonPath} ${filter.operator} $${context.addParam(filter.value)}`;
         } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
             if (Array.isArray(filter.value) && filter.value.length > 0) {
-                const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}`).join(', ');
-                return `${jsonPath} ${filter.operator} (${placeholders})`;
+                const cast = jsonbInListCast(filter.value);
+                const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}${cast.param}`).join(', ');
+                return `${cast.lhs(jsonPath)} ${filter.operator} (${placeholders})`;
             } else if (Array.isArray(filter.value) && filter.value.length === 0) {
                 return filter.operator === 'IN' ? 'FALSE' : 'TRUE';
             }
@@ -665,8 +667,9 @@ export class ComponentInclusionNode extends QueryNode {
                 condition = `(${jsonPath})::boolean ${filter.operator} $${context.addParam(filter.value)}`;
             } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
                 if (Array.isArray(filter.value) && filter.value.length > 0) {
-                    const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}`).join(', ');
-                    condition = `${jsonPath} ${filter.operator} (${placeholders})`;
+                    const cast = jsonbInListCast(filter.value);
+                    const placeholders = filter.value.map((v: any) => `$${context.addParam(v)}${cast.param}`).join(', ');
+                    condition = `${cast.lhs(jsonPath)} ${filter.operator} (${placeholders})`;
                 } else {
                     return null; // Invalid or empty array - fall back to normal path
                 }
@@ -860,14 +863,17 @@ export class ComponentInclusionNode extends QueryNode {
                         // String LIKE/ILIKE comparison - no casting
                         condition = `${jsonPath} ${filter.operator} $${context.addParam(filter.value)}`;
                     } else if (filter.operator === 'IN' || filter.operator === 'NOT IN') {
-                        // IN/NOT IN comparison - handle arrays properly
+                        // IN/NOT IN comparison - handle arrays properly. Numeric/
+                        // boolean lists need a cast on both the JSONB text field
+                        // and each parameter, else `text IN (1, 2)` errors.
                         if (Array.isArray(filter.value) && filter.value.length > 0) {
+                            const cast = jsonbInListCast(filter.value);
                             let placeholders = '';
                             for (let i = 0; i < filter.value.length; i++) {
                                 if (i) placeholders += ', ';
-                                placeholders += '$' + context.addParam(filter.value[i]);
+                                placeholders += '$' + context.addParam(filter.value[i]) + cast.param;
                             }
-                            condition = `${jsonPath} ${filter.operator} (${placeholders})`;
+                            condition = `${cast.lhs(jsonPath)} ${filter.operator} (${placeholders})`;
                         } else if (Array.isArray(filter.value) && filter.value.length === 0) {
                             // Empty array: IN () is always false, NOT IN () is always true
                             condition = filter.operator === 'IN' ? 'FALSE' : 'TRUE';

package/query/FilterBuilder.ts

@@ -90,6 +90,25 @@ export function buildJSONBPath(field: string, alias: string): string {
     return `${alias}.data->'${field}'`;
 }
 
+/**
+ * Determine the type cast for an `IN` / `NOT IN` value list against a JSONB
+ * text-extracted field (`data->>'x'` always yields text). Without a cast a
+ * numeric/boolean list produces `text IN (1, 2)` → PostgreSQL "operator does
+ * not exist: text = integer". When every element is a number (or boolean) we
+ * cast both the field and each parameter, mirroring the scalar `=` path. Mixed
+ * or string lists stay as plain text comparison (the correct default).
+ *
+ * @returns `lhs(path)` wraps the field expression; `param` is the per-parameter
+ *          cast suffix (e.g. `::numeric`), `''` for text.
+ */
+export function jsonbInListCast(values: any[]): { lhs: (path: string) => string; param: string } {
+    const allNumbers = values.length > 0 && values.every(v => typeof v === 'number');
+    if (allNumbers) return { lhs: (p) => `(${p})::numeric`, param: '::numeric' };
+    const allBooleans = values.length > 0 && values.every(v => typeof v === 'boolean');
+    if (allBooleans) return { lhs: (p) => `(${p})::boolean`, param: '::boolean' };
+    return { lhs: (p) => p, param: '' };
+}
+
 /**
  * Compose multiple filter builders into a single builder that applies all conditions
  *

package/query/OrNode.ts

@@ -5,6 +5,7 @@ import { OrQuery } from "./OrQuery";
 import { ComponentRegistry } from "../core/components";
 import { shouldUseDirectPartition } from "../core/Config";
 import { getMembershipTable } from "./membershipSource";
+import { jsonbInListCast } from "./FilterBuilder";
 
 export class OrNode extends QueryNode {
     private orQuery: OrQuery;
@@ -111,15 +112,17 @@ export class OrNode extends QueryNode {
                             break;
                         case "IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                branchSql += ` AND ${jsonPath} IN (${placeholders})`;
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                branchSql += ` AND ${cast.lhs(jsonPath)} IN (${placeholders})`;
                                 context.params.push(...value);
                             }
                             break;
                         case "NOT IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                branchSql += ` AND ${jsonPath} NOT IN (${placeholders})`;
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                branchSql += ` AND ${cast.lhs(jsonPath)} NOT IN (${placeholders})`;
                                 context.params.push(...value);
                             }
                             break;
@@ -150,7 +153,7 @@ export class OrNode extends QueryNode {
         if (context.excludedComponentIds.size > 0) {
             const excludedTypes = Array.from(context.excludedComponentIds);
             const placeholders = excludedTypes.map(() => `$${paramIndex++}`).join(', ');
-            conditions.push(`NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = or_results.id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`);
+            conditions.push(`NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = or_results.entity_id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`);
             context.params.push(...excludedTypes);
         }
 
@@ -232,15 +235,17 @@ export class OrNode extends QueryNode {
                             break;
                         case "IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                conditions.push(`${jsonPath} IN (${placeholders})`);
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                conditions.push(`${cast.lhs(jsonPath)} IN (${placeholders})`);
                                 context.params.push(...value);
                             }
                             break;
                         case "NOT IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                conditions.push(`${jsonPath} NOT IN (${placeholders})`);
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                conditions.push(`${cast.lhs(jsonPath)} NOT IN (${placeholders})`);
                                 context.params.push(...value);
                             }
                             break;
@@ -329,10 +334,29 @@ export class OrNode extends QueryNode {
         let baseEntityQuery = "";
 
         if (hasComponentDependency) {
-            // Get base entities from ComponentInclusionNode
+            // Get base entities from ComponentInclusionNode.
+            //
+            // CRITICAL: the base set must be UNBOUNDED. OrNode embeds this SQL
+            // as `FROM (base) WHERE EXISTS (<or filter>)` and applies LIMIT/
+            // OFFSET to the *final* OR-filtered result below. If the base node
+            // bakes the caller's LIMIT/OFFSET into its own SQL, the EXISTS OR
+            // filter only ever sees the first page of base entities (ordered by
+            // entity_id), so any match beyond that page silently vanishes —
+            // e.g. a search whose only hits live on page 2+ returns 0 rows
+            // while count() (which strips pagination) reports them. Null out
+            // pagination around the base build, then restore so the final
+            // pagination below is unaffected. cursorId is left intact: it
+            // constrains the candidate set (entity_id > cursor) which composes
+            // correctly with the final LIMIT.
             const componentNode = this.dependencies[0];
             if (componentNode) {
+                const savedLimit = context.limit;
+                const savedOffset = context.offsetValue;
+                context.limit = null;
+                context.offsetValue = 0;
                 const baseResult = componentNode.execute(context);
+                context.limit = savedLimit;
+                context.offsetValue = savedOffset;
                 baseEntityQuery = baseResult.sql;
                 paramIndex = baseResult.context.paramIndex;
             }
@@ -408,15 +432,17 @@ export class OrNode extends QueryNode {
                             break;
                         case "IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                filterConditions.push(`${jsonPath} IN (${placeholders})`);
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                filterConditions.push(`${cast.lhs(jsonPath)} IN (${placeholders})`);
                                 context.params.push(...value);
                             }
                             break;
                         case "NOT IN":
                             if (Array.isArray(value)) {
-                                const placeholders = value.map(() => `$${paramIndex++}`).join(', ');
-                                filterConditions.push(`${jsonPath} NOT IN (${placeholders})`);
+                                const cast = jsonbInListCast(value);
+                                const placeholders = value.map(() => `$${paramIndex++}${cast.param}`).join(', ');
+                                filterConditions.push(`${cast.lhs(jsonPath)} NOT IN (${placeholders})`);
                                 context.params.push(...value);
                             }
                             break;
@@ -447,7 +473,7 @@ export class OrNode extends QueryNode {
             for (const componentType of allComponentTypes) {
                 const componentId = ComponentRegistry.getComponentId(componentType);
                 if (componentId) {
-                    componentConditions.push(`EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_all WHERE ec_all.entity_id = or_results.id AND ec_all.type_id = $${paramIndex} AND ec_all.deleted_at IS NULL)`);
+                    componentConditions.push(`EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_all WHERE ec_all.entity_id = or_results.entity_id AND ec_all.type_id = $${paramIndex} AND ec_all.deleted_at IS NULL)`);
                     context.params.push(componentId);
                     paramIndex++;
                 }
@@ -469,7 +495,7 @@ export class OrNode extends QueryNode {
         if (context.excludedComponentIds.size > 0) {
             const excludedTypes = Array.from(context.excludedComponentIds);
             const placeholders = excludedTypes.map(() => `$${paramIndex++}`).join(', ');
-            conditions.push(`NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = or_results.id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`);
+            conditions.push(`NOT EXISTS (SELECT 1 FROM ${getMembershipTable()} ec_ex WHERE ec_ex.entity_id = or_results.entity_id AND ec_ex.type_id IN (${placeholders}) AND ec_ex.deleted_at IS NULL)`);
             context.params.push(...excludedTypes);
         }