querysub 0.93.0 → 0.95.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "querysub",
-  "version": "0.93.0",
+  "version": "0.95.0",
   "main": "index.js",
   "license": "MIT",
   "note1": "note on node-forge fork, see https://github.com/digitalbazaar/forge/issues/744 for details",

package/src/-0-hooks/hooks.ts

@@ -37,6 +37,23 @@ function createHookFunction<Fnc extends (...args: any[]) => void>(debugName: str
     return fnc;
 }
 
+function createHookFunctionReturn<Fnc extends (...args: any[]) => any>(debugName: string): {
+    (...args: Parameters<Fnc>): ReturnType<Fnc>;
+    declare: (fnc: Fnc) => void;
+} {
+    let declaration: Fnc | undefined;
+    function fnc(...args: Parameters<Fnc>): ReturnType<Fnc> {
+        if (!declaration) {
+            throw new Error(`Hook function ${debugName} not declared`);
+        }
+        return declaration(...args);
+    };
+    fnc.declare = (fnc: Fnc) => {
+        declaration = fnc;
+    };
+    return fnc;
+}
+
 export const addStatPeriodic = createHookFunction<
     (
         config: {
@@ -94,3 +111,8 @@ export const logNodeStateStats = createHookFunction<
         value: number,
     ) => void
 >("logNodeStateStats");
+
+
+export const isManagementUser = createHookFunctionReturn<
+    () => Promise<boolean>
+>("isManagementUser");

package/src/-c-identity/IdentityController.ts

@@ -11,10 +11,11 @@ import { cache, lazy } from "socket-function/src/caching";
 import { getClientNodeId, getNodeId, getNodeIdDomain, getNodeIdIP, getNodeIdLocation, isClientNodeId } from "socket-function/src/nodeCache";
 import { getCommonName, getIdentityCA, getMachineId, getPublicIdentifier, getThreadKeyCert, parseCert, sign, validateCertificate, verify } from "../-a-auth/certs";
 import { getShortNumber } from "../bits";
-import { measureFnc, measureWrap } from "socket-function/src/profiling/measure";
+import { measureBlock, measureFnc, measureWrap } from "socket-function/src/profiling/measure";
 import { timeoutToError } from "../errors";
 import { delay } from "socket-function/src/batching";
 import { formatTime } from "socket-function/src/formatting/format";
+import { waitForFirstTimeSync } from "socket-function/time/trueTimeShim";
 
 let callerInfo = new Map<CallerContext, {
     reconnectNodeId: string | undefined;
@@ -175,6 +176,11 @@ const IdentityController = SocketFunction.register(
 );
 
 const changeIdentityOnce = cache(async function changeIdentityOnce(connectionId: { nodeId: string }) {
+    // Wait for time sync, otherwise the time in our change identity might be rejected.
+    await measureBlock(async () => {
+        await waitForFirstTimeSync();
+    }, "waitForFirstTimeSync");
+
     let nodeId = connectionId.nodeId;
     let threadKeyCert = getThreadKeyCert();
     let issuer = getIdentityCA();

package/src/0-path-value-core/NodePathAuthorities.ts

@@ -1,5 +1,5 @@
 import { SocketFunction } from "socket-function/SocketFunction";
-import { measureFnc, measureWrap } from "socket-function/src/profiling/measure";
+import { measureBlock, measureFnc, measureWrap } from "socket-function/src/profiling/measure";
 import { errorToUndefined, errorToUndefinedSilent, ignoreErrors, logErrors, timeoutToUndefined, timeoutToUndefinedSilent } from "../errors";
 import { PromiseObj } from "../promise";
 import { getAllNodeIds, getBrowserUrlNode, getOwnNodeId, isNodeDiscoveryLogging, isOwnNodeId, onNodeDiscoveryReady, triggerNodeChange, watchDeltaNodeIds, watchNodeIds } from "../-f-node-discovery/NodeDiscovery";
@@ -22,6 +22,7 @@ import { IdentityController_getCurrentReconnectNodeIdAssert, IdentityController_
 import { getBufferFraction, getBufferInt, getShortNumber } from "../bits";
 import { devDebugbreak, isDevDebugbreak } from "../config";
 import { diskLog } from "../diagnostics/logs/diskLogger";
+import { waitForFirstTimeSync } from "socket-function/time/trueTimeShim";
 
 export const LOCAL_DOMAIN = "LOCAL";
 export const LOCAL_DOMAIN_PATH = getPathStr1(LOCAL_DOMAIN);

package/src/3-path-functions/PathFunctionHelpers.ts

@@ -2,7 +2,7 @@ import { getOwnMachineId } from "../-a-auth/certs";
 import { atomicObjectWrite, proxyWatcher, specialObjectWriteSymbol } from "../2-proxy/PathValueProxyWatcher";
 import { pathValueCommitter } from "../0-path-value-core/PathValueController";
 import { getNextTime } from "../0-path-value-core/pathValueCore";
-import { FunctionSpec, functionSchema, CallSpec } from "./PathFunctionRunner";
+import { FunctionSpec, functionSchema, CallSpec, commitCall } from "./PathFunctionRunner";
 import { logErrors } from "../errors";
 import { FunctionMetadata } from "./syncSchema";
 import debugbreak from "debugbreak";
@@ -12,8 +12,9 @@ import { secureRandom } from "../misc/random";
 import { isDefined } from "../misc";
 import { blue, green, red } from "socket-function/src/formatting/logColors";
 import { getPathStr2 } from "../path";
-import { sort } from "socket-function/src/misc";
+import { isNode, sort } from "socket-function/src/misc";
 import { decodeCborx, encodeCborx } from "../misc/cloneHelpers";
+import { parseFilterable } from "../misc/filterable";
 const cborxInstance = lazy(() => new cborx.Encoder({ structuredClone: true }));
 
 
@@ -93,19 +94,7 @@ export async function replaceFunctions(config: {
 
 export const writeCall = {
     value: async (callSpec: CallSpec, metadata: FunctionMetadata) => {
-        let domainName = callSpec.DomainName;
-        let moduleId = callSpec.ModuleId;
-        let callId = callSpec.CallId;
-        proxyWatcher.writeOnly({
-            canWrite: true,
-            eventWrite: true,
-            doNotStoreWritesAsPredictions: true,
-            // NOTE: We write the call in the present, it is callSpec.runAtTime that is in the past. No one cares
-            //  when the call was added, only when it wants to run at.
-            watchFunction: function writeCall() {
-                functionSchema()[domainName].PathFunctionRunner[moduleId].Calls[callId] = atomicObjectWrite(callSpec);
-            },
-        });
+        commitCall(callSpec);
         await pathValueCommitter.waitForValuesToCommit();
     }
 };
@@ -164,6 +153,14 @@ export function writeFunctionCall(config: {
         //  this is fine).
         callerIP: "127.0.0.1",
     };
+    if (!isNode()) {
+        // Get the "setfncfilter" querystring parameter
+        let url = new URL(window.location.href);
+        let setfncfilter = url.searchParams.get("setfncfilter");
+        if (setfncfilter) {
+            callSpec.filterable = parseFilterable(setfncfilter);
+        }
+    }
 
     if (curInterceptor) {
         curInterceptor.onCall(callSpec, metadata);

package/src/3-path-functions/PathFunctionRunner.ts

@@ -19,6 +19,7 @@ import { PERMISSIONS_FUNCTION_ID, getExportPath } from "./syncSchema";
 import { formatTime } from "socket-function/src/formatting/format";
 import { set_debug_getFunctionRunnerShards } from "../-g-core-values/NodeCapabilities";
 import { diskLog } from "../diagnostics/logs/diskLogger";
+import { FilterSelector, Filterable, doesMatch } from "../misc/filterable";
 
 export const functionSchema = rawSchema<{
     [domainName: string]: {
@@ -33,6 +34,22 @@ export const functionSchema = rawSchema<{
     };
 }>();
 
+export function commitCall(call: CallSpec) {
+    let domainName = call.DomainName;
+    let moduleId = call.ModuleId;
+    let callId = call.CallId;
+    proxyWatcher.writeOnly({
+        canWrite: true,
+        eventWrite: true,
+        doNotStoreWritesAsPredictions: true,
+        // NOTE: We write the call in the present, it is callSpec.runAtTime that is in the past. No one cares
+        //  when the call was added, only when it wants to run at.
+        watchFunction: function writeCall() {
+            functionSchema()[domainName].PathFunctionRunner[moduleId].Calls[callId] = atomicObjectWrite(call);
+        },
+    });
+}
+
 export const DEPTH_TO_DATA = 4;
 export const DOMAIN_INDEX = 0;
 export const MODULE_INDEX = 2;
@@ -66,6 +83,8 @@ export interface CallSpec {
     callerMachineId: string;
     callerIP: string;
     runAtTime: Time;
+
+    filterable?: Filterable;
 }
 export function debugCallSpec(spec: CallSpec): string {
     return `${spec.DomainName}/${spec.ModuleId}/${spec.FunctionId}`;
@@ -155,6 +174,7 @@ export class PathFunctionRunner {
         shardRange: { startFraction: number, endFraction: number };
         secondaryShardRange?: { startFraction: number, endFraction: number };
         PermissionsChecker: PermissionsCheckType | undefined;
+        filterSelector?: FilterSelector;
     }) {
         debugFunctionRunnerShards.push({
             domainName: config.domainName,
@@ -402,6 +422,10 @@ export class PathFunctionRunner {
             skipPermissions = PermissionsChecker.skipPermissionsChecks.bind(PermissionsChecker);
         }
 
+        if (!doesMatch(callPath.filterable, this.config.filterSelector)) {
+            return;
+        }
+
         await this.letIOClear();
 
         let secondaryDelay = this.getSecondaryShardDelay(callPath);

package/src/3-path-functions/PathFunctionRunnerMain.ts

@@ -7,6 +7,7 @@ let yargObj = yargs(process.argv)
     .option("shardcenter", { type: "number", default: 0.5, desc: "Center of sharding fraction from 0 to 1" })
     .option("shardsize", { type: "number", default: 1, desc: "Size of sharding fraction from 0 to 1 (ex, shardsize = 0.35 and shardcenter = 0.5 results in sharding from 0.15 to 0.85)" })
     .option("secondarysize", { type: "number", default: 0, desc: "Also shards this size HOWEVER, any values in this range (which are not matched in shardsize) are delayed." })
+    .option("filter", { type: "string", default: "", desc: `Filter to only include handle specific function calls (shardsize is still applied). For example, "a&b|c", using regular boolean rules.` })
     .argv
     ;
 
@@ -24,6 +25,7 @@ import { timeInMinute } from "socket-function/src/misc";
 import { getDomain, isPublic } from "../config";
 import { publishMachineARecords } from "../-e-certs/EdgeCertController";
 import { green } from "socket-function/src/formatting/logColors";
+import { parseFilterSelector } from "../misc/filterable";
 
 async function main() {
 
@@ -56,12 +58,15 @@ async function main() {
 
     console.log(green(`Sharding from ${shardStart} to ${shardEnd}. Fallback sharding (dead function recovery) from ${secondaryStart} to ${secondaryEnd}`));
 
+    let filterSelector = parseFilterSelector(yargObj.filter);
+
     new PathFunctionRunner({
         domainName: getDomain(),
         shardRange: { startFraction: shardStart, endFraction: shardEnd },
         secondaryShardRange: yargObj.secondarysize ? { startFraction: secondaryStart, endFraction: secondaryEnd } : undefined,
         // TODO: Maybe abstract this out even more, so anything can plug in permissions checks?
         PermissionsChecker: PermissionsCheck,
+        filterSelector,
     });
 }
 logErrors(main());

package/src/4-querysub/QuerysubController.ts

@@ -5,7 +5,7 @@ import { CHILD_CHECK_PREFIX, FunctionMetadata } from "../3-path-functions/syncSc
 import { RemoteWatcher, remoteWatcher } from "../1-path-client/RemoteWatcher";
 import { getProxyPath } from "../2-proxy/pathValueProxy";
 import { atomic, atomicObjectWrite, proxyWatcher } from "../2-proxy/PathValueProxyWatcher";
-import { CallSpec, DEPTH_TO_DATA, FunctionSpec, debugCallSpec, functionSchema } from "../3-path-functions/PathFunctionRunner";
+import { CallSpec, DEPTH_TO_DATA, FunctionSpec, commitCall, debugCallSpec, functionSchema } from "../3-path-functions/PathFunctionRunner";
 import { PathValueController } from "../0-path-value-core/PathValueController";
 import { epochTime, MAX_ACCEPTED_CHANGE_AGE, PathValue, pathWatcher, Time, WatchConfig, compareTime, debugTime, getNextTime, MAX_CHANGE_AGE } from "../0-path-value-core/pathValueCore";
 import { IdentityController_getMachineId, IdentityController_getPubKeyShort, IdentityController_getSecureIP } from "../-c-identity/IdentityController";
@@ -16,7 +16,7 @@ import { blue, green, magenta, red } from "socket-function/src/formatting/logCol
 import { PermissionsCheck } from "./permissions";
 import { parseArgs, writeCall } from "../3-path-functions/PathFunctionHelpers";
 import { delay } from "socket-function/src/batching";
-import { isNode, timeInMinute, timeInSecond } from "socket-function/src/misc";
+import { isNode, isNodeTrue, timeInMinute, timeInSecond } from "socket-function/src/misc";
 import { registerResource } from "../diagnostics/trackResources";
 
 // Always whitelist preact, as most of the time we want it clientside
@@ -40,6 +40,17 @@ import { assertIsManagementUser } from "../diagnostics/managementPages";
 import { getBrowserUrlNode } from "../-f-node-discovery/NodeDiscovery";
 setFlag(require, "preact", "allowclient", true);
 
+import yargs from "yargs";
+import { mergeFilterables, parseFilterable, serializeFilterable } from "../misc/filterable";
+import { isManagementUser } from "../-0-hooks/hooks";
+
+let yargObj = isNodeTrue() && yargs(process.argv)
+    .option("fncfilter", { type: "string", default: "", desc: `Sets the filterable state for function calls, causing them to target specific FunctionRunners. If no FunctionRunner matches, all functions will fail to run. For example: "devtestserver" will match a FunctionRunner that uses the "devtestserver" filter. Merges with the existing filterable state if a client sets it explicitly.` })
+    .argv
+    ;
+
+const getFncFilter = lazy(() => parseFilterable(yargObj.fncfilter));
+
 export { Querysub, id };
 
 
@@ -501,6 +512,11 @@ export class QuerysubControllerBase {
         let callerCreatorId = IdentityController_getPubKeyShort(caller);
         call.callerIP = IdentityController_getSecureIP(caller);
 
+        if (call.filterable && !await isManagementUser()) {
+            throw new Error(`Caller is not a management user, and so does not have permissions to set filterable on calls. Call ${debugCallSpec(call)}, filter was "${serializeFilterable(call.filterable)}"`);
+        }
+        call.filterable = mergeFilterables([getFncFilter(), call.filterable]);
+
         if (Querysub.SIMULATE_LAG) {
             await delay(Querysub.SIMULATE_LAG * 2);
         }
@@ -558,16 +574,9 @@ export class QuerysubControllerBase {
             throw new Error(`Caller does not have permission to call ${call.DomainName}.${call.ModuleId}`);
         }
 
+        commitCall(call);
         // NOTE: We don't wait for our writes to actually commit, because... there isn't any reason they shouldn't
-        //  except the server being down, in which case, the client can figure that out anyways?
-        proxyWatcher.writeOnly({
-            canWrite: true,
-            eventWrite: true,
-            doNotStoreWritesAsPredictions: true,
-            watchFunction: function writeCall() {
-                functionSchema()[call.DomainName].PathFunctionRunner[call.ModuleId].Calls[call.CallId] = atomicObjectWrite(call);
-            },
-        });
+        //  except the server being down, in which case, the client will gracefully timeout when it doesn't receive the confirmation
     }
 
     public async getModulePath(config: {

package/src/4-querysub/querysubPrediction.ts

@@ -92,6 +92,11 @@ export const addCall = runInSerial(async function addCall(call: CallSpec, metada
     if (metadata.nopredict) {
         predict = false;
     }
+
+    // NOTE: We predict when call.filterable, as filterable usually just means we are testing
+    //  new functions in development (instead of targeting specific hardware). If we find this
+    //  is annoying, we could add a flag in filterable that explicitly screens out prediction?
+
     let cancel = () => { };
 
     if (predict) {

package/src/diagnostics/managementPages.tsx

@@ -23,6 +23,7 @@ import { isTrusted } from "../-d-trust/NetworkTrust2";
 import { devDebugbreak, getDomain } from "../config";
 import { getCallWrites } from "../4-querysub/querysubPrediction";
 import { SchemaObject } from "../3-path-functions/syncSchema";
+import * as hooks from "../-0-hooks/hooks";
 
 
 export const managementPageURL = new URLParam("managementpage", "");
@@ -134,7 +135,7 @@ export async function registerManagementPages2(config: {
     }
 }
 
-
+hooks.isManagementUser.declare(isManagementUser);
 export async function isManagementUser() {
     let caller = SocketFunction.getCaller();
     let callerMachineId = IdentityController_getMachineId(caller);

package/src/misc/filterable.ts

@@ -0,0 +1,391 @@
+import { devDebugbreak } from "../config";
+import debugbreak from "debugbreak";
+
+export type Filterable = {
+    values: string[];
+} | undefined;
+// undefined FilterSelector only matches empty Filterables.
+export type FilterSelector = {
+    expression: ASTNode;
+} | undefined;
+
+type ASTNode = {
+    type: "orList";
+    parts: ASTNode[];
+} | {
+    type: "andList";
+    parts: ASTNode[];
+} | {
+    type: "not";
+    part: ASTNode;
+} | {
+    type: "leaf";
+    matcher: FilterMatcher;
+};
+
+export type FilterMatcher = {
+    type: "includes";
+    value: string;
+} | {
+    type: "regex";
+    value: string;
+};
+
+export function doesMatch(filterable: Filterable, filterSelector: FilterSelector): boolean {
+    if (!filterSelector) {
+        return !!filterable;
+    }
+    return evaluateASTNode(filterSelector.expression, filterable);
+}
+function evaluateASTNode(node: ASTNode, filterable: Filterable): boolean {
+    if (node.type === "orList") {
+        return node.parts.some(part => evaluateASTNode(part, filterable));
+    } else if (node.type === "andList") {
+        return node.parts.every(part => evaluateASTNode(part, filterable));
+    } else if (node.type === "not") {
+        return !evaluateASTNode(node.part, filterable);
+    } else if (node.type === "leaf") {
+        return evaluateLeaf(node.matcher, filterable);
+    } else {
+        let unhandled: never = node;
+    }
+    return false;
+}
+function evaluateLeaf(matcher: FilterMatcher, filterable: Filterable): boolean {
+    if (!filterable) return false;
+    if (matcher.type === "includes") {
+        return filterable.values.some(value => value.includes(matcher.value));
+    } else if (matcher.type === "regex") {
+        return filterable.values.some(value => new RegExp(matcher.value).test(value));
+    } else {
+        let unhandled: never = matcher;
+    }
+    return false;
+}
+
+export function mergeSelectors(selectors: FilterSelector[]): FilterSelector {
+    if (selectors.length === 0) return undefined;
+    if (selectors.length === 1) return selectors[0];
+    let nodes: ASTNode[] = [];
+    for (let selector of selectors) {
+        if (!selector) continue;
+        // Flatten orLists
+        if (selector.expression.type === "orList") {
+            nodes.push(...selector.expression.parts);
+        } else {
+            nodes.push(selector.expression);
+        }
+    }
+    return {
+        expression: {
+            type: "orList",
+            parts: nodes,
+        },
+    };
+}
+export function mergeFilterables(filterables: Filterable[]): Filterable {
+    if (filterables.length === 0) return undefined;
+    if (filterables.length === 1) return filterables[0];
+    let values = Array.from(new Set(filterables.flatMap(filterable => filterable?.values ?? [])));
+    return {
+        values,
+    };
+}
+
+// apple | b & "cats are | funny" | !(d | elephant)
+// " at the start and end allows using special characters in a value
+// "" inside of " is parsed as a single "
+// The values are trimmed
+export function parseFilterSelector(filterSelector: string): FilterSelector {
+    if (!filterSelector.trim()) return undefined;
+
+    let pos = 0;
+    const input = filterSelector;
+
+    function parseValue(): string {
+        let value = "";
+        if (input[pos] === "\"") {
+            pos++; // Skip opening quote
+            while (pos < input.length) {
+                if (input[pos] === "\"") {
+                    if (input[pos + 1] === "\"") {
+                        value += "\"";
+                        pos += 2;
+                        continue;
+                    }
+                    pos++; // Skip closing quote
+                    break;
+                }
+                value += input[pos];
+                pos++;
+            }
+        } else {
+            while (pos < input.length && !/[\s|&!()]/.test(input[pos])) {
+                value += input[pos];
+                pos++;
+            }
+        }
+        return value.trim();
+    }
+
+    function skipWhitespace() {
+        while (pos < input.length && /\s/.test(input[pos])) pos++;
+    }
+
+    function parseExpression(): ASTNode {
+        skipWhitespace();
+
+        if (pos >= input.length) {
+            throw new Error(`Expected expression at position ${pos} but reached end of input`);
+        }
+
+        // Handle NOT
+        if (input[pos] === "!") {
+            pos++;
+            skipWhitespace();
+
+            // Support both (!x) and !(x) forms
+            const needsClosingParen = input[pos] === "(";
+            if (needsClosingParen) {
+                pos++;
+            }
+
+            const expr = parseOrExpression();
+            skipWhitespace();
+
+            if (needsClosingParen) {
+                if (input[pos] !== ")") {
+                    throw new Error(`Expected ")" at position ${pos}, found "${input[pos]}"`);
+                }
+                pos++;
+            }
+
+            return { type: "not", part: expr };
+        }
+
+        // Handle parentheses
+        if (input[pos] === "(") {
+            pos++;
+            const expr = parseOrExpression();
+            skipWhitespace();
+            if (input[pos] !== ")") {
+                throw new Error(`Expected ")" at position ${pos}, found "${input[pos]}"`);
+            }
+            pos++;
+            return expr;
+        }
+
+        // Handle leaf node (simple value)
+        const value = parseValue();
+        if (!value) {
+            throw new Error(`Expected value at position ${pos}`);
+        }
+        return {
+            type: "leaf",
+            matcher: { type: "includes", value }
+        };
+    }
+
+    function parseAndExpression(): ASTNode {
+        let left = parseExpression();
+        skipWhitespace();
+
+        const parts: ASTNode[] = [left];
+
+        while (pos < input.length && input[pos] === "&") {
+            pos++;
+            skipWhitespace();
+            parts.push(parseExpression());
+            skipWhitespace();
+        }
+
+        if (parts.length === 1) return parts[0];
+        return { type: "andList", parts };
+    }
+
+    function parseOrExpression(): ASTNode {
+        let left = parseAndExpression();
+        skipWhitespace();
+
+        const parts: ASTNode[] = [left];
+
+        while (pos < input.length && input[pos] === "|") {
+            pos++;
+            skipWhitespace();
+            parts.push(parseAndExpression());
+            skipWhitespace();
+        }
+
+        if (parts.length === 1) return parts[0];
+        return { type: "orList", parts };
+    }
+
+    try {
+        const expression = parseOrExpression();
+        skipWhitespace();
+
+        if (pos < input.length) {
+            throw new Error(`Unexpected character "${input[pos]}" at position ${pos}`);
+        }
+
+        return { expression };
+    } catch (error: any) {
+        throw new Error(`Failed to parse filter selector "${filterSelector}": ${error.message}`);
+    }
+}
+export function serializeFilterSelector(filterSelector: FilterSelector): string {
+    if (!filterSelector) return "";
+
+    function serializeASTNode(node: ASTNode, parentPrecedence = 0): string {
+        // Precedence: OR = 1, AND = 2, NOT = 3, LEAF = 4
+        let result: string;
+        let currentPrecedence: number;
+
+        if (node.type === "orList") {
+            currentPrecedence = 1;
+            result = node.parts.map(part => serializeASTNode(part, currentPrecedence)).join(" | ");
+        } else if (node.type === "andList") {
+            currentPrecedence = 2;
+            result = node.parts.map(part => serializeASTNode(part, currentPrecedence)).join(" & ");
+        } else if (node.type === "not") {
+            currentPrecedence = 3;
+            if (
+                (node.part.type === "andList" || node.part.type === "orList") && node.part.parts.length === 1
+                || node.part.type === "leaf"
+            ) {
+                result = `!${serializeASTNode(node.part, 0)}`;
+            } else {
+                result = `!(${serializeASTNode(node.part, 0)})`;
+            }
+        } else if (node.type === "leaf") {
+            currentPrecedence = 4;
+            const value = node.matcher.value;
+            // If the value contains special characters, wrap it in quotes
+            if (/[\s|&!()]/.test(value)) {
+                // Escape quotes by doubling them
+                result = `"${value.replace(/"/g, "\"\"")}"`;
+            } else {
+                result = value;
+            }
+        } else {
+            let unhandled: never = node;
+            return "";
+        }
+
+        // Add parentheses if our precedence is lower than parent's
+        if (currentPrecedence < parentPrecedence) {
+            result = `(${result})`;
+        }
+        return result;
+    }
+
+    return serializeASTNode(filterSelector.expression);
+}
+
+// a | b => { values: ["a", "b"] }
+export function parseFilterable(filterable: string): Filterable {
+    if (!filterable.trim()) return undefined;
+    let values = filterable.split("|").map(value => value.trim());
+    return {
+        values,
+    };
+}
+export function serializeFilterable(filterable: Filterable): string {
+    if (!filterable) return "";
+    return filterable.values.join("|");
+}
+
+async function main() {
+    function assert(cond: () => boolean, message?: string) {
+        if (!cond()) throw new Error(`Failed for ${cond.toString()}${message ? `: ${message}` : ""}`);
+    }
+
+    function testFilter(input: string, matches: string[][], nonMatches: string[][]) {
+        console.log(`\nTesting filter: ${input}`);
+        const filter = parseFilterSelector(input);
+        const serialized = serializeFilterSelector(filter);
+        console.log("Serialized:", serialized);
+
+        // Test that parsing the serialized version gives same result
+        const reparsed = parseFilterSelector(serialized);
+        assert(() => JSON.stringify(filter) === JSON.stringify(reparsed),
+            "Serialized form should parse to equivalent AST");
+
+        // Test positive matches
+        for (const values of matches) {
+            assert(() => doesMatch({ values }, filter),
+                `Should match values: [${values.join(", ")}]`);
+        }
+
+        // Test negative matches
+        for (const values of nonMatches) {
+            assert(() => !doesMatch({ values }, filter),
+                `Should NOT match values: [${values.join(", ")}]`);
+        }
+    }
+
+    // Test basic operators
+    testFilter("a",
+        [["a"], ["ab"], ["a", "b"]],
+        [["b"], ["c"], []]);
+
+    testFilter("a & b",
+        [["a", "b"], ["ab", "b"], ["a", "ab"]],
+        [["a"], ["b"], ["c", "d"], []]);
+
+    testFilter("a | b",
+        [["a"], ["b"], ["a", "b"], ["ab"]],
+        [["c"], ["d"], []]);
+
+    // Test NOT operator
+    testFilter("!a",
+        [["b"], ["c"], ["b", "c"]],
+        [["a"], ["a", "b"]]);
+
+    testFilter("!(a | b)",
+        [["c"], ["d"], ["c", "d"]],
+        [["a"], ["b"], ["a", "c"], ["b", "d"]]);
+
+    // Test operator precedence
+    testFilter("a & b | c",
+        [["a", "b"], ["c"], ["a", "b", "c"]],
+        [["a"], ["b"]]);
+
+    testFilter("a | b & c",
+        [["a"], ["b", "c"], ["a", "b", "c"]],
+        [["b"], ["c"], ["b"]]);
+
+    // Test complex expressions
+    testFilter("(a | b & c) & !d",
+        [["a"], ["b", "c"], ["a", "b", "c"]],
+        [["a", "d"], ["b", "c", "d"], ["d"]]);
+
+    // Test quoted strings and special characters
+    testFilter("\"hello world\" & !\"good bye\"",
+        [["hello world"], ["hello world", "hi"]],
+        [["good bye"], ["hello world", "good bye"]]);
+
+    testFilter("\"a & b\" | \"c | d\"",
+        [["a & b"], ["c | d"], ["a & b", "e"]],
+        [["a"], ["b"], ["c"], ["d"]]);
+
+    // Test empty and undefined cases
+    assert(() => !doesMatch(undefined, undefined), "undefined should not match undefined");
+    assert(() => !doesMatch(undefined, parseFilterSelector("a")), "undefined should not match filter");
+    assert(() => doesMatch({ values: ["a"] }, undefined), "non-empty values should match undefined");
+
+    // Test mergeSelectors
+    const merged = mergeSelectors([
+        parseFilterSelector("a & b"),
+        parseFilterSelector("c | d"),
+        undefined,
+        parseFilterSelector("!e")
+    ]);
+    assert(() => doesMatch({ values: ["a", "b"] }, merged), "should match first selector");
+    assert(() => doesMatch({ values: ["c"] }, merged), "should match second selector");
+    assert(() => doesMatch({ values: ["d"] }, merged), "should match second selector alternative");
+    assert(() => !doesMatch({ values: ["e"] }, merged), "should respect NOT in merged selectors");
+
+    console.log("All tests passed!");
+}
+//main().catch(console.error).finally(() => process.exit(0));