@rocicorp/zero 1.2.0 → 1.3.0-canary.0

package/out/zero-cache/src/custom-queries/transform-query.js

@@ -1,14 +1,17 @@
 import { getErrorMessage } from "../../../shared/src/error.js";
-import { must } from "../../../shared/src/must.js";
 import { TransformFailed } from "../../../zero-protocol/src/error-kind-enum.js";
 import { ZeroCache } from "../../../zero-protocol/src/error-origin-enum.js";
 import { Internal } from "../../../zero-protocol/src/error-reason-enum.js";
 import { isProtocolError } from "../../../zero-protocol/src/error.js";
 import { transformResponseMessageSchema } from "../../../zero-protocol/src/custom-queries.js";
 import { hashOfAST } from "../../../zero-protocol/src/query-hash.js";
+import { startAsyncSpan } from "../../../otel/src/span.js";
 import { TimedCache } from "../../../shared/src/cache.js";
-import { compileUrlPattern, fetchFromAPIServer } from "../custom/fetch.js";
+import { sortedEntries } from "../../../shared/src/sorted-entries.js";
+import { fetchFromAPIServer } from "../custom/fetch.js";
+import { trace } from "@opentelemetry/api";
 //#region ../zero-cache/src/custom-queries/transform-query.ts
+var tracer = trace.getTracer("custom-query-transformer");
 /**
 * Transforms a custom query by calling the user's API server.
 * Caches the transformed queries for 5 seconds to avoid unnecessary API calls.
@@ -26,32 +29,37 @@ import { compileUrlPattern, fetchFromAPIServer } from "../custom/fetch.js";
 * The ViewSyncer will call the API server 3-4 times with the exact same queries
 * if we do not cache requests.
 *
-* Caching is safe here because the cache key encodes both
-* the user's cookies and auth token. A user cannot see another user's
-* transformed queries unless they share the same token and cookies.
+* Caching is safe here because the cache key encodes the effective request
+* identity used for `/query`: auth, userID, forwarded cookies, origin,
+* custom headers, target URL, and the query hash itself.
 */
 var CustomQueryTransformer = class {
 	#shard;
 	#cache;
-	#config;
-	#urlPatterns;
 	#lc;
-	constructor(lc, config, shard) {
-		this.#config = config;
+	constructor(lc, shard) {
 		this.#shard = shard;
 		this.#lc = lc;
-		this.#urlPatterns = config.url.map(compileUrlPattern);
 		this.#cache = new TimedCache(5e3);
 	}
-	async transform(headerOptions, queries, userQueryURL) {
+	/**
+	* Forces the empty `/query` validation request used by auth maintenance.
+	*
+	* This stays separate from `transform()` because `transform([], ...)`
+	* short-circuits locally and never hits the API server, while validation
+	* still needs to make the request so auth failures are surfaced.
+	* Successful validation is intentionally opaque because callers only care
+	* whether the request succeeded or failed.
+	*/
+	async validate(ctx) {
+		const response = await this.#requestTransform(ctx, [], "validate");
+		return Array.isArray(response) ? void 0 : response;
+	}
+	async transform(ctx, queries) {
 		const request = [];
 		const cachedResponses = [];
-		if (!this.#config.forwardCookies && headerOptions.cookie) headerOptions = {
-			...headerOptions,
-			cookie: void 0
-		};
 		for (const query of queries) {
-			const cacheKey = getCacheKey(headerOptions, query.id);
+			const cacheKey = getCacheKey(ctx, query.id);
 			const cached = this.#cache.get(cacheKey);
 			if (cached) cachedResponses.push(cached);
 			else request.push({
@@ -60,25 +68,39 @@ var CustomQueryTransformer = class {
 				args: query.args
 			});
 		}
-		if (request.length === 0) return cachedResponses;
-		const queryIDs = request.map((r) => r.id);
+		let cached = true;
+		if (request.length === 0) return {
+			result: cachedResponses,
+			cached: true
+		};
+		else cached = false;
+		const response = await this.#requestTransform(ctx, request, "transform");
+		if (!Array.isArray(response)) return {
+			result: response,
+			cached
+		};
+		const newResponses = response.map((transformed) => {
+			if ("error" in transformed) return transformed;
+			return {
+				id: transformed.id,
+				transformedAst: transformed.ast,
+				transformationHash: hashOfAST(transformed.ast)
+			};
+		});
+		for (const transformed of newResponses) {
+			if ("error" in transformed) continue;
+			const cacheKey = getCacheKey(ctx, transformed.id);
+			this.#cache.set(cacheKey, transformed);
+		}
+		return {
+			result: [...newResponses, ...cachedResponses],
+			cached
+		};
+	}
+	async #requestTransform(ctx, request, operation) {
+		const queryIDs = request.map(({ id }) => id);
 		try {
-			const transformResponse = await fetchFromAPIServer(transformResponseMessageSchema, "transform", this.#lc, userQueryURL ?? must(this.#config.url[0], "A ZERO_QUERY_URL must be configured for custom queries"), this.#urlPatterns, this.#shard, headerOptions, ["transform", request]);
-			if (transformResponse[0] === "transformFailed") return transformResponse[1];
-			const newResponses = transformResponse[1].map((transformed) => {
-				if ("error" in transformed) return transformed;
-				return {
-					id: transformed.id,
-					transformedAst: transformed.ast,
-					transformationHash: hashOfAST(transformed.ast)
-				};
-			});
-			for (const transformed of newResponses) {
-				if ("error" in transformed) continue;
-				const cacheKey = getCacheKey(headerOptions, transformed.id);
-				this.#cache.set(cacheKey, transformed);
-			}
-			return newResponses.concat(cachedResponses);
+			return (await startAsyncSpan(tracer, "customQueryTransformer.fetchFromAPIServer", () => fetchFromAPIServer(transformResponseMessageSchema, "transform", this.#lc, ctx, this.#shard, ["transform", request])))[1];
 		} catch (e) {
 			if (isProtocolError(e) && e.errorBody.kind === "TransformFailed") return {
 				...e.errorBody,
@@ -88,14 +110,29 @@ var CustomQueryTransformer = class {
 				kind: TransformFailed,
 				origin: ZeroCache,
 				reason: Internal,
-				message: `Failed to transform queries: ${getErrorMessage(e)}`,
+				message: `Failed to ${operation} queries: ${getErrorMessage(e)}`,
 				queryIDs
 			};
 		}
 	}
 };
-function getCacheKey(headerOptions, queryID) {
-	return `${headerOptions.token}:${headerOptions.cookie}:${queryID}`;
+function getCacheKey(ctx, queryID) {
+	return JSON.stringify({
+		queryID,
+		token: ctx.auth?.raw,
+		cookie: ctx.queryContext.headerOptions.cookie,
+		origin: ctx.queryContext.headerOptions.origin,
+		userID: ctx.userID,
+		url: ctx.queryContext.url,
+		customHeaders: normalizedForwardedHeaders(ctx.queryContext.headerOptions)
+	});
+}
+function normalizedForwardedHeaders(headerOptions) {
+	const { allowedClientHeaders, customHeaders } = headerOptions;
+	if (!customHeaders || !allowedClientHeaders || allowedClientHeaders.length === 0) return;
+	const allowedHeaders = new Set(allowedClientHeaders.map((header) => header.toLowerCase()));
+	const forwardedHeaders = sortedEntries(customHeaders).filter(([header]) => allowedHeaders.has(header.toLowerCase()));
+	return forwardedHeaders.length === 0 ? void 0 : JSON.stringify(forwardedHeaders);
 }
 //#endregion
 export { CustomQueryTransformer };

package/out/zero-cache/src/custom-queries/transform-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"transform-query.js","names":["#shard","#cache","#config","#urlPatterns","#lc"],"sources":["../../../../../zero-cache/src/custom-queries/transform-query.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {TimedCache} from '../../../shared/src/cache.ts';\nimport {getErrorMessage} from '../../../shared/src/error.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport {\n  transformResponseMessageSchema,\n  type ErroredQuery,\n  type TransformRequestBody,\n  type TransformRequestMessage,\n} from '../../../zero-protocol/src/custom-queries.ts';\nimport {ErrorKind} from '../../../zero-protocol/src/error-kind.ts';\nimport {ErrorOrigin} from '../../../zero-protocol/src/error-origin.ts';\nimport {ErrorReason} from '../../../zero-protocol/src/error-reason.ts';\nimport {\n  isProtocolError,\n  type TransformFailedBody,\n} from '../../../zero-protocol/src/error.ts';\nimport {hashOfAST} from '../../../zero-protocol/src/query-hash.ts';\nimport type {TransformedAndHashed} from '../auth/read-authorizer.ts';\nimport {\n  compileUrlPattern,\n  fetchFromAPIServer,\n  type HeaderOptions,\n} from '../custom/fetch.ts';\nimport type {CustomQueryRecord} from '../services/view-syncer/schema/types.ts';\nimport type {ShardID} from '../types/shards.ts';\n\n/**\n * Transforms a custom query by calling the user's API server.\n * Caches the transformed queries for 5 seconds to avoid unnecessary API calls.\n *\n * Error responses are not cached as the user may want to retry the query\n * and the error may be transient.\n *\n * The TTL was chosen to be 5 seconds since custom query requests come with\n * a token which itself may have a short TTL (e.g., 10 seconds).\n *\n * Token expiration isn't expected to be exact so this 5 second\n * caching shouldn't cause unexpected behavior. E.g., many JWT libraries\n * implement leeway for expiration checks: https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md#clocktolerance\n *\n * The ViewSyncer will call the API server 3-4 times with the exact same queries\n * if we do not cache requests.\n *\n * Caching is safe here because the cache key encodes both\n * the user's cookies and auth token. A user cannot see another user's\n * transformed queries unless they share the same token and cookies.\n */\nexport class CustomQueryTransformer {\n  readonly #shard: ShardID;\n  readonly #cache: TimedCache<TransformedAndHashed>;\n  readonly #config: {\n    url: string[];\n    forwardCookies: boolean;\n  };\n  readonly #urlPatterns: URLPattern[];\n  readonly #lc: LogContext;\n\n  constructor(\n    lc: LogContext,\n    config: {\n      url: string[];\n      forwardCookies: boolean;\n    },\n    shard: ShardID,\n  ) {\n    this.#config = config;\n    this.#shard = shard;\n    this.#lc = lc;\n    this.#urlPatterns = config.url.map(compileUrlPattern);\n    this.#cache = new TimedCache(5000); // 5 seconds cache TTL\n  }\n\n  async transform(\n    headerOptions: HeaderOptions,\n    queries: Iterable<CustomQueryRecord>,\n    userQueryURL: string | undefined,\n  ): Promise<(TransformedAndHashed | ErroredQuery)[] | TransformFailedBody> {\n    const request: TransformRequestBody = [];\n    const cachedResponses: TransformedAndHashed[] = [];\n\n    if (!this.#config.forwardCookies && headerOptions.cookie) {\n      headerOptions = {\n        ...headerOptions,\n        cookie: undefined, // remove cookies if not forwarded\n      };\n    }\n\n    // split queries into cached and uncached\n    for (const query of queries) {\n      const cacheKey = getCacheKey(headerOptions, query.id);\n      const cached = this.#cache.get(cacheKey);\n      if (cached) {\n        cachedResponses.push(cached);\n      } else {\n        request.push({\n          id: query.id,\n          name: query.name,\n          args: query.args,\n        });\n      }\n    }\n\n    if (request.length === 0) {\n      return cachedResponses;\n    }\n\n    const queryIDs = request.map(r => r.id);\n\n    try {\n      const transformResponse = await fetchFromAPIServer(\n        transformResponseMessageSchema,\n        'transform',\n        this.#lc,\n        userQueryURL ??\n          must(\n            this.#config.url[0],\n            'A ZERO_QUERY_URL must be configured for custom queries',\n          ),\n        this.#urlPatterns,\n        this.#shard,\n        headerOptions,\n        ['transform', request] satisfies TransformRequestMessage,\n      );\n\n      if (transformResponse[0] === 'transformFailed') {\n        return transformResponse[1];\n      }\n\n      const newResponses = transformResponse[1].map(transformed => {\n        if ('error' in transformed) {\n          return transformed;\n        }\n        return {\n          id: transformed.id,\n          transformedAst: transformed.ast,\n          transformationHash: hashOfAST(transformed.ast),\n        } satisfies TransformedAndHashed;\n      });\n\n      for (const transformed of newResponses) {\n        if ('error' in transformed) {\n          // do not cache error responses\n          continue;\n        }\n        const cacheKey = getCacheKey(headerOptions, transformed.id);\n        this.#cache.set(cacheKey, transformed);\n      }\n\n      return newResponses.concat(cachedResponses);\n    } catch (e) {\n      if (\n        isProtocolError(e) &&\n        e.errorBody.kind === ErrorKind.TransformFailed\n      ) {\n        return {\n          ...e.errorBody,\n          queryIDs,\n        } as const satisfies TransformFailedBody;\n      }\n\n      return {\n        kind: ErrorKind.TransformFailed,\n        origin: ErrorOrigin.ZeroCache,\n        reason: ErrorReason.Internal,\n        message: `Failed to transform queries: ${getErrorMessage(e)}`,\n        queryIDs,\n      } as const satisfies TransformFailedBody;\n    }\n  }\n}\n\nfunction getCacheKey(headerOptions: HeaderOptions, queryID: string) {\n  // For custom queries, queryID is a hash of the name + args.\n  // the APIKey from headerOptions is static. Not needed for the cache key.\n  // The token is used to identify the user and should be included in the cache key.\n  return `${headerOptions.token}:${headerOptions.cookie}:${queryID}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,IAAa,yBAAb,MAAoC;CAClC;CACA;CACA;CAIA;CACA;CAEA,YACE,IACA,QAIA,OACA;AACA,QAAA,SAAe;AACf,QAAA,QAAc;AACd,QAAA,KAAW;AACX,QAAA,cAAoB,OAAO,IAAI,IAAI,kBAAkB;AACrD,QAAA,QAAc,IAAI,WAAW,IAAK;;CAGpC,MAAM,UACJ,eACA,SACA,cACwE;EACxE,MAAM,UAAgC,EAAE;EACxC,MAAM,kBAA0C,EAAE;AAElD,MAAI,CAAC,MAAA,OAAa,kBAAkB,cAAc,OAChD,iBAAgB;GACd,GAAG;GACH,QAAQ,KAAA;GACT;AAIH,OAAK,MAAM,SAAS,SAAS;GAC3B,MAAM,WAAW,YAAY,eAAe,MAAM,GAAG;GACrD,MAAM,SAAS,MAAA,MAAY,IAAI,SAAS;AACxC,OAAI,OACF,iBAAgB,KAAK,OAAO;OAE5B,SAAQ,KAAK;IACX,IAAI,MAAM;IACV,MAAM,MAAM;IACZ,MAAM,MAAM;IACb,CAAC;;AAIN,MAAI,QAAQ,WAAW,EACrB,QAAO;EAGT,MAAM,WAAW,QAAQ,KAAI,MAAK,EAAE,GAAG;AAEvC,MAAI;GACF,MAAM,oBAAoB,MAAM,mBAC9B,gCACA,aACA,MAAA,IACA,gBACE,KACE,MAAA,OAAa,IAAI,IACjB,yDACD,EACH,MAAA,aACA,MAAA,OACA,eACA,CAAC,aAAa,QAAQ,CACvB;AAED,OAAI,kBAAkB,OAAO,kBAC3B,QAAO,kBAAkB;GAG3B,MAAM,eAAe,kBAAkB,GAAG,KAAI,gBAAe;AAC3D,QAAI,WAAW,YACb,QAAO;AAET,WAAO;KACL,IAAI,YAAY;KAChB,gBAAgB,YAAY;KAC5B,oBAAoB,UAAU,YAAY,IAAI;KAC/C;KACD;AAEF,QAAK,MAAM,eAAe,cAAc;AACtC,QAAI,WAAW,YAEb;IAEF,MAAM,WAAW,YAAY,eAAe,YAAY,GAAG;AAC3D,UAAA,MAAY,IAAI,UAAU,YAAY;;AAGxC,UAAO,aAAa,OAAO,gBAAgB;WACpC,GAAG;AACV,OACE,gBAAgB,EAAE,IAClB,EAAE,UAAU,SAAS,kBAErB,QAAO;IACL,GAAG,EAAE;IACL;IACD;AAGH,UAAO;IACL,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,SAAS,gCAAgC,gBAAgB,EAAE;IAC3D;IACD;;;;AAKP,SAAS,YAAY,eAA8B,SAAiB;AAIlE,QAAO,GAAG,cAAc,MAAM,GAAG,cAAc,OAAO,GAAG"}
+{"version":3,"file":"transform-query.js","names":["#shard","#cache","#lc","#requestTransform"],"sources":["../../../../../zero-cache/src/custom-queries/transform-query.ts"],"sourcesContent":["import {trace} from '@opentelemetry/api';\nimport type {LogContext} from '@rocicorp/logger';\nimport {startAsyncSpan} from '../../../otel/src/span.ts';\nimport {TimedCache} from '../../../shared/src/cache.ts';\nimport {getErrorMessage} from '../../../shared/src/error.ts';\nimport {sortedEntries} from '../../../shared/src/sorted-entries.ts';\nimport {\n  transformResponseMessageSchema,\n  type ErroredQuery,\n  type TransformRequestBody,\n  type TransformRequestMessage,\n  type TransformResponseBody,\n} from '../../../zero-protocol/src/custom-queries.ts';\nimport {ErrorKind} from '../../../zero-protocol/src/error-kind.ts';\nimport {ErrorOrigin} from '../../../zero-protocol/src/error-origin.ts';\nimport {ErrorReason} from '../../../zero-protocol/src/error-reason.ts';\nimport {\n  isProtocolError,\n  type TransformFailedBody,\n} from '../../../zero-protocol/src/error.ts';\nimport {hashOfAST} from '../../../zero-protocol/src/query-hash.ts';\nimport type {TransformedAndHashed} from '../auth/read-authorizer.ts';\nimport {fetchFromAPIServer} from '../custom/fetch.ts';\nimport type {\n  ConnectionContext,\n  HeaderOptions,\n} from '../services/view-syncer/connection-context-manager.ts';\nimport type {CustomQueryRecord} from '../services/view-syncer/schema/types.ts';\nimport type {ShardID} from '../types/shards.ts';\n\nconst tracer = trace.getTracer('custom-query-transformer');\n\ntype TransformResponse = TransformResponseBody | TransformFailedBody;\nexport type TransformAttempt = {\n  result: (TransformedAndHashed | ErroredQuery)[] | TransformFailedBody;\n  cached: boolean;\n};\n\n/**\n * Transforms a custom query by calling the user's API server.\n * Caches the transformed queries for 5 seconds to avoid unnecessary API calls.\n *\n * Error responses are not cached as the user may want to retry the query\n * and the error may be transient.\n *\n * The TTL was chosen to be 5 seconds since custom query requests come with\n * a token which itself may have a short TTL (e.g., 10 seconds).\n *\n * Token expiration isn't expected to be exact so this 5 second\n * caching shouldn't cause unexpected behavior. E.g., many JWT libraries\n * implement leeway for expiration checks: https://github.com/panva/jose/blob/main/docs/jwt/verify/interfaces/JWTVerifyOptions.md#clocktolerance\n *\n * The ViewSyncer will call the API server 3-4 times with the exact same queries\n * if we do not cache requests.\n *\n * Caching is safe here because the cache key encodes the effective request\n * identity used for `/query`: auth, userID, forwarded cookies, origin,\n * custom headers, target URL, and the query hash itself.\n */\nexport class CustomQueryTransformer {\n  readonly #shard: ShardID;\n  readonly #cache: TimedCache<TransformedAndHashed>;\n  readonly #lc: LogContext;\n\n  constructor(lc: LogContext, shard: ShardID) {\n    this.#shard = shard;\n    this.#lc = lc;\n    this.#cache = new TimedCache(5000); // 5 seconds cache TTL\n  }\n\n  /**\n   * Forces the empty `/query` validation request used by auth maintenance.\n   *\n   * This stays separate from `transform()` because `transform([], ...)`\n   * short-circuits locally and never hits the API server, while validation\n   * still needs to make the request so auth failures are surfaced.\n   * Successful validation is intentionally opaque because callers only care\n   * whether the request succeeded or failed.\n   */\n  async validate(\n    ctx: ConnectionContext,\n  ): Promise<TransformFailedBody | undefined> {\n    const response = await this.#requestTransform(ctx, [], 'validate');\n\n    return Array.isArray(response) ? undefined : response;\n  }\n\n  async transform(\n    ctx: ConnectionContext,\n    queries: Iterable<CustomQueryRecord>,\n  ): Promise<TransformAttempt> {\n    const request: TransformRequestBody = [];\n    const cachedResponses: TransformedAndHashed[] = [];\n\n    // split queries into cached and uncached\n    for (const query of queries) {\n      const cacheKey = getCacheKey(ctx, query.id);\n      const cached = this.#cache.get(cacheKey);\n      if (cached) {\n        cachedResponses.push(cached);\n      } else {\n        request.push({\n          id: query.id,\n          name: query.name,\n          args: query.args,\n        });\n      }\n    }\n\n    let cached = true;\n\n    if (request.length === 0) {\n      return {\n        result: cachedResponses,\n        cached: true,\n      };\n    } else {\n      // we are hitting the server with at least one uncached query\n      cached = false;\n    }\n\n    const response = await this.#requestTransform(ctx, request, 'transform');\n    if (!Array.isArray(response)) {\n      return {\n        result: response,\n        cached,\n      };\n    }\n\n    const newResponses = response.map(transformed => {\n      if ('error' in transformed) {\n        return transformed;\n      }\n      return {\n        id: transformed.id,\n        transformedAst: transformed.ast,\n        transformationHash: hashOfAST(transformed.ast),\n      } satisfies TransformedAndHashed;\n    });\n\n    for (const transformed of newResponses) {\n      if ('error' in transformed) {\n        // do not cache error responses\n        continue;\n      }\n      const cacheKey = getCacheKey(ctx, transformed.id);\n      this.#cache.set(cacheKey, transformed);\n    }\n\n    return {\n      result: [...newResponses, ...cachedResponses],\n      cached,\n    };\n  }\n\n  async #requestTransform(\n    ctx: ConnectionContext,\n    request: TransformRequestBody,\n    operation: 'validate' | 'transform',\n  ): Promise<TransformResponse> {\n    const queryIDs = request.map(({id}) => id);\n\n    try {\n      const transformResponse = await startAsyncSpan(\n        tracer,\n        'customQueryTransformer.fetchFromAPIServer',\n        () =>\n          fetchFromAPIServer(\n            transformResponseMessageSchema,\n            'transform',\n            this.#lc,\n            ctx,\n            this.#shard,\n            ['transform', request] satisfies TransformRequestMessage,\n          ),\n      );\n\n      return transformResponse[1];\n    } catch (e) {\n      if (\n        isProtocolError(e) &&\n        e.errorBody.kind === ErrorKind.TransformFailed\n      ) {\n        return {\n          ...e.errorBody,\n          queryIDs,\n        } as const satisfies TransformFailedBody;\n      }\n\n      return {\n        kind: ErrorKind.TransformFailed,\n        origin: ErrorOrigin.ZeroCache,\n        reason: ErrorReason.Internal,\n        message: `Failed to ${operation} queries: ${getErrorMessage(e)}`,\n        queryIDs,\n      } as const satisfies TransformFailedBody;\n    }\n  }\n}\n\nfunction getCacheKey(ctx: ConnectionContext, queryID: string) {\n  // For custom queries, queryID is a hash of the name + args.\n  // The apiKey is static for a given transformer instance.\n  return JSON.stringify({\n    queryID,\n    token: ctx.auth?.raw,\n    cookie: ctx.queryContext.headerOptions.cookie,\n    origin: ctx.queryContext.headerOptions.origin,\n    userID: ctx.userID,\n    url: ctx.queryContext.url,\n    customHeaders: normalizedForwardedHeaders(ctx.queryContext.headerOptions),\n  });\n}\n\nfunction normalizedForwardedHeaders(headerOptions: HeaderOptions) {\n  const {allowedClientHeaders, customHeaders} = headerOptions;\n  if (\n    !customHeaders ||\n    !allowedClientHeaders ||\n    allowedClientHeaders.length === 0\n  ) {\n    return undefined;\n  }\n\n  const allowedHeaders = new Set(\n    allowedClientHeaders.map(header => header.toLowerCase()),\n  );\n  const forwardedHeaders = sortedEntries(customHeaders).filter(([header]) =>\n    allowedHeaders.has(header.toLowerCase()),\n  );\n\n  return forwardedHeaders.length === 0\n    ? undefined\n    : JSON.stringify(forwardedHeaders);\n}\n"],"mappings":";;;;;;;;;;;;;AA8BA,IAAM,SAAS,MAAM,UAAU,2BAA2B;;;;;;;;;;;;;;;;;;;;;;AA6B1D,IAAa,yBAAb,MAAoC;CAClC;CACA;CACA;CAEA,YAAY,IAAgB,OAAgB;AAC1C,QAAA,QAAc;AACd,QAAA,KAAW;AACX,QAAA,QAAc,IAAI,WAAW,IAAK;;;;;;;;;;;CAYpC,MAAM,SACJ,KAC0C;EAC1C,MAAM,WAAW,MAAM,MAAA,iBAAuB,KAAK,EAAE,EAAE,WAAW;AAElE,SAAO,MAAM,QAAQ,SAAS,GAAG,KAAA,IAAY;;CAG/C,MAAM,UACJ,KACA,SAC2B;EAC3B,MAAM,UAAgC,EAAE;EACxC,MAAM,kBAA0C,EAAE;AAGlD,OAAK,MAAM,SAAS,SAAS;GAC3B,MAAM,WAAW,YAAY,KAAK,MAAM,GAAG;GAC3C,MAAM,SAAS,MAAA,MAAY,IAAI,SAAS;AACxC,OAAI,OACF,iBAAgB,KAAK,OAAO;OAE5B,SAAQ,KAAK;IACX,IAAI,MAAM;IACV,MAAM,MAAM;IACZ,MAAM,MAAM;IACb,CAAC;;EAIN,IAAI,SAAS;AAEb,MAAI,QAAQ,WAAW,EACrB,QAAO;GACL,QAAQ;GACR,QAAQ;GACT;MAGD,UAAS;EAGX,MAAM,WAAW,MAAM,MAAA,iBAAuB,KAAK,SAAS,YAAY;AACxE,MAAI,CAAC,MAAM,QAAQ,SAAS,CAC1B,QAAO;GACL,QAAQ;GACR;GACD;EAGH,MAAM,eAAe,SAAS,KAAI,gBAAe;AAC/C,OAAI,WAAW,YACb,QAAO;AAET,UAAO;IACL,IAAI,YAAY;IAChB,gBAAgB,YAAY;IAC5B,oBAAoB,UAAU,YAAY,IAAI;IAC/C;IACD;AAEF,OAAK,MAAM,eAAe,cAAc;AACtC,OAAI,WAAW,YAEb;GAEF,MAAM,WAAW,YAAY,KAAK,YAAY,GAAG;AACjD,SAAA,MAAY,IAAI,UAAU,YAAY;;AAGxC,SAAO;GACL,QAAQ,CAAC,GAAG,cAAc,GAAG,gBAAgB;GAC7C;GACD;;CAGH,OAAA,iBACE,KACA,SACA,WAC4B;EAC5B,MAAM,WAAW,QAAQ,KAAK,EAAC,SAAQ,GAAG;AAE1C,MAAI;AAeF,WAd0B,MAAM,eAC9B,QACA,mDAEE,mBACE,gCACA,aACA,MAAA,IACA,KACA,MAAA,OACA,CAAC,aAAa,QAAQ,CACvB,CACJ,EAEwB;WAClB,GAAG;AACV,OACE,gBAAgB,EAAE,IAClB,EAAE,UAAU,SAAS,kBAErB,QAAO;IACL,GAAG,EAAE;IACL;IACD;AAGH,UAAO;IACL,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,SAAS,aAAa,UAAU,YAAY,gBAAgB,EAAE;IAC9D;IACD;;;;AAKP,SAAS,YAAY,KAAwB,SAAiB;AAG5D,QAAO,KAAK,UAAU;EACpB;EACA,OAAO,IAAI,MAAM;EACjB,QAAQ,IAAI,aAAa,cAAc;EACvC,QAAQ,IAAI,aAAa,cAAc;EACvC,QAAQ,IAAI;EACZ,KAAK,IAAI,aAAa;EACtB,eAAe,2BAA2B,IAAI,aAAa,cAAc;EAC1E,CAAC;;AAGJ,SAAS,2BAA2B,eAA8B;CAChE,MAAM,EAAC,sBAAsB,kBAAiB;AAC9C,KACE,CAAC,iBACD,CAAC,wBACD,qBAAqB,WAAW,EAEhC;CAGF,MAAM,iBAAiB,IAAI,IACzB,qBAAqB,KAAI,WAAU,OAAO,aAAa,CAAC,CACzD;CACD,MAAM,mBAAmB,cAAc,cAAc,CAAC,QAAQ,CAAC,YAC7D,eAAe,IAAI,OAAO,aAAa,CAAC,CACzC;AAED,QAAO,iBAAiB,WAAW,IAC/B,KAAA,IACA,KAAK,UAAU,iBAAiB"}

package/out/zero-cache/src/db/migration-lite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-lite.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration-lite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AACnD,OAAO,KAAK,EAAC,QAAQ,IAAI,EAAE,EAAC,MAAM,2BAA2B,CAAC;AAG9D,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEpE;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,SAAS,EACzB,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,IAAI,CAAC,CAoHf;AAaD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;OAIG;;aAEH,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAG5D,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,EAAE,GAAG,cAAc,CAmBxD"}
+{"version":3,"file":"migration-lite.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration-lite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AACnD,OAAO,KAAK,EAAC,QAAQ,IAAI,EAAE,EAAC,MAAM,2BAA2B,CAAC;AAG9D,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEpE;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,SAAS,EACzB,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,IAAI,CAAC,CAqHf;AAaD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;OAIG;;aAEH,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAG5D,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,EAAE,GAAG,cAAc,CAmBxD"}

package/out/zero-cache/src/db/migration-lite.js

@@ -15,7 +15,7 @@ async function runSchemaMigrations(log, debugName, dbPath, setupMigration, incre
 		const versionMigrations = sorted(incrementalMigrationMap);
 		assert(versionMigrations.length, `Must specify a at least one version migration`);
 		assert(versionMigrations[0][0] > 0, `Versions must be non-zero positive numbers`);
-		const codeVersion = versionMigrations[versionMigrations.length - 1][0];
+		const codeVersion = versionMigrations.at(-1)[0];
 		log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeVersion}`);
 		let versions = await runTransaction(log, db, (tx) => {
 			const versions = getVersionHistory(tx);

package/out/zero-cache/src/db/migration-lite.js.map

@@ -1 +1 @@
-{"version":3,"file":"migration-lite.js","names":[],"sources":["../../../../../zero-cache/src/db/migration-lite.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {randInt} from '../../../shared/src/rand.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport type {Database as Db} from '../../../zqlite/src/db.ts';\nimport {Database} from '../../../zqlite/src/db.ts';\n\ntype Operations = (log: LogContext, tx: Db) => Promise<void> | void;\n\n/**\n * Encapsulates the logic for setting up or upgrading to a new schema. After the\n * Migration code successfully completes, {@link runSchemaMigrations}\n * will update the schema version and commit the transaction.\n */\nexport type Migration = {\n  /**\n   * Perform database operations that create or alter table structure. This is\n   * called at most once during lifetime of the application. If a `migrateData()`\n   * operation is defined, that will be performed after `migrateSchema()` succeeds.\n   */\n  migrateSchema?: Operations;\n\n  /**\n   * Perform database operations to migrate data to the new schema. This is\n   * called after `migrateSchema()` (if defined), and may be called again\n   * to re-migrate data after the server was rolled back to an earlier version,\n   * and rolled forward again.\n   *\n   * Consequently, the logic in `migrateData()` must be idempotent.\n   */\n  migrateData?: Operations;\n\n  /**\n   * Sets the `minSafeVersion` to the specified value, prohibiting running\n   * any earlier code versions.\n   */\n  minSafeVersion?: number;\n};\n\n/**\n * Mapping of incremental migrations to move from the previous old code\n * version to next one. Versions must be non-zero.\n *\n * The schema resulting from performing incremental migrations should be\n * equivalent to that of the `setupMigration` on a blank database.\n *\n * The highest destinationVersion of this map denotes the current\n * \"code version\", and is also used as the destination version when\n * running the initial setup migration on a blank database.\n */\nexport type IncrementalMigrationMap = {\n  [destinationVersion: number]: Migration;\n};\n\n/**\n * Ensures that the schema is compatible with the current code, updating and\n * migrating the schema if necessary.\n */\nexport async function runSchemaMigrations(\n  log: LogContext,\n  debugName: string,\n  dbPath: string,\n  setupMigration: Migration,\n  incrementalMigrationMap: IncrementalMigrationMap,\n): Promise<void> {\n  const start = Date.now();\n  log = log.withContext(\n    'initSchema',\n    randInt(0, Number.MAX_SAFE_INTEGER).toString(36),\n  );\n  const db = new Database(log, dbPath);\n\n  try {\n    const versionMigrations = sorted(incrementalMigrationMap);\n    assert(\n      versionMigrations.length,\n      `Must specify a at least one version migration`,\n    );\n    assert(\n      versionMigrations[0][0] > 0,\n      `Versions must be non-zero positive numbers`,\n    );\n    const codeVersion = versionMigrations[versionMigrations.length - 1][0];\n    log.info?.(\n      `Checking schema for compatibility with ${debugName} at schema v${codeVersion}`,\n    );\n\n    let versions = await runTransaction(log, db, tx => {\n      const versions = getVersionHistory(tx);\n      if (codeVersion < versions.minSafeVersion) {\n        throw new Error(\n          `Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`,\n        );\n      }\n\n      if (versions.dataVersion > codeVersion) {\n        log.info?.(\n          `Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`,\n        );\n        return updateVersionHistory(log, tx, versions, codeVersion);\n      }\n      return versions;\n    });\n\n    if (versions.dataVersion < codeVersion) {\n      db.unsafeMode(true); // Enables journal_mode = OFF\n      db.pragma('locking_mode = EXCLUSIVE');\n      db.pragma('foreign_keys = OFF');\n      db.pragma('journal_mode = OFF');\n      db.pragma('synchronous = OFF');\n      // Unfortunately, AUTO_VACUUM is not compatible with BEGIN CONCURRENT,\n      // so it is not an option for the replica file.\n      // https://sqlite.org/forum/forumpost/25f183416a\n      // db.pragma('auto_vacuum = INCREMENTAL');\n\n      const migrations =\n        versions.dataVersion === 0\n          ? // For the empty database v0, only run the setup migration.\n            ([[codeVersion, setupMigration]] as const)\n          : versionMigrations;\n\n      for (const [dest, migration] of migrations) {\n        if (versions.dataVersion < dest) {\n          log.info?.(\n            `Migrating schema from v${versions.dataVersion} to v${dest}`,\n          );\n          void log.flush(); // Flush logs before each migration to help debug crash-y migrations.\n\n          versions = await runTransaction(log, db, async tx => {\n            // Fetch meta from within the transaction to make the migration atomic.\n            let versions = getVersionHistory(tx);\n            if (versions.dataVersion < dest) {\n              versions = await runMigration(log, tx, versions, dest, migration);\n              assert(\n                versions.dataVersion === dest,\n                () =>\n                  `Migration did not reach target version: expected ${dest}, got ${versions.dataVersion}`,\n              );\n            }\n            return versions;\n          });\n        }\n      }\n\n      db.exec('ANALYZE main');\n      log.info?.('ANALYZE completed');\n    } else {\n      // Run optimize whenever opening an sqlite db file as recommended in\n      // https://www.sqlite.org/pragma.html#pragma_optimize\n      // It is important to run the same initialization steps as is done\n      // in the view-syncer (i.e. when preparing database for serving\n      // replication) so that any corruption detected in the view-syncer is\n      // similarly detected in the change-streamer, facilitating an eventual\n      // recovery by resyncing the replica anew.\n      db.pragma('optimize = 0x10002');\n\n      // TODO: Investigate running `integrity_check` or `quick_check` as well,\n      // provided that they are not inordinately expensive on large databases.\n    }\n\n    db.pragma('synchronous = NORMAL');\n    db.unsafeMode(false);\n\n    assert(\n      versions.dataVersion === codeVersion,\n      () =>\n        `Final dataVersion (${versions.dataVersion}) does not match codeVersion (${codeVersion})`,\n    );\n    log.info?.(\n      `Running ${debugName} at schema v${codeVersion} (${\n        Date.now() - start\n      } ms)`,\n    );\n  } catch (e) {\n    log.error?.('Error in ensureSchemaMigrated', e);\n    throw e;\n  } finally {\n    db.close();\n    void log.flush(); // Flush the logs but do not block server progress on it.\n  }\n}\n\nfunction sorted(\n  incrementalMigrationMap: IncrementalMigrationMap,\n): [number, Migration][] {\n  const versionMigrations: [number, Migration][] = [];\n  for (const [v, m] of Object.entries(incrementalMigrationMap)) {\n    versionMigrations.push([Number(v), m]);\n  }\n  return versionMigrations.sort(([a], [b]) => a - b);\n}\n\n// Exposed for tests.\nexport const versionHistory = v.object({\n  /**\n   * The `schemaVersion` is highest code version that has ever been run\n   * on the database, and is used to delineate the structure of the tables\n   * in the database. A schemaVersion only moves forward; rolling back to\n   * an earlier (safe) code version does not revert schema changes that\n   * have already been applied.\n   */\n  schemaVersion: v.number(),\n\n  /**\n   * The data version is the code version of the latest server that ran.\n   * Note that this may be less than the schemaVersion in the case that\n   * a server is rolled back to an earlier version after a schema change.\n   * In such a case, data (but not schema), may need to be re-migrated\n   * when rolling forward again.\n   */\n  dataVersion: v.number(),\n\n  /**\n   * The minimum code version that is safe to run. This is used when\n   * a schema migration is not backwards compatible with an older version\n   * of the code.\n   */\n  minSafeVersion: v.number(),\n});\n\n// Exposed for tests.\nexport type VersionHistory = v.Infer<typeof versionHistory>;\n\n// Exposed for tests\nexport function getVersionHistory(db: Db): VersionHistory {\n  // Note: The `lock` column transparently ensures that at most one row exists.\n  db.prepare(\n    `\n    CREATE TABLE IF NOT EXISTS \"_zero.versionHistory\" (\n      dataVersion INTEGER NOT NULL,\n      schemaVersion INTEGER NOT NULL,\n      minSafeVersion INTEGER NOT NULL,\n\n      lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n    );\n  `,\n  ).run();\n  const result = db\n    .prepare(\n      'SELECT dataVersion, schemaVersion, minSafeVersion FROM \"_zero.versionHistory\"',\n    )\n    .get() as VersionHistory;\n  return result ?? {dataVersion: 0, schemaVersion: 0, minSafeVersion: 0};\n}\n\nfunction updateVersionHistory(\n  log: LogContext,\n  db: Db,\n  prev: VersionHistory,\n  newVersion: number,\n  minSafeVersion?: number,\n): VersionHistory {\n  assert(newVersion > 0, 'newVersion must be positive');\n  const meta = {\n    ...prev,\n    dataVersion: newVersion,\n    // The schemaVersion never moves backwards.\n    schemaVersion: Math.max(newVersion, prev.schemaVersion),\n    minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),\n  } satisfies VersionHistory;\n\n  db.prepare(\n    `\n    INSERT INTO \"_zero.versionHistory\" (dataVersion, schemaVersion, minSafeVersion, lock)\n    VALUES (@dataVersion, @schemaVersion, @minSafeVersion, 1)\n    ON CONFLICT (lock) DO UPDATE\n    SET dataVersion=@dataVersion,\n        schemaVersion=@schemaVersion,\n        minSafeVersion=@minSafeVersion\n  `,\n  ).run(meta);\n\n  return meta;\n}\n\nasync function runMigration(\n  log: LogContext,\n  tx: Db,\n  versions: VersionHistory,\n  destinationVersion: number,\n  migration: Migration,\n): Promise<VersionHistory> {\n  if (versions.schemaVersion < destinationVersion) {\n    await migration.migrateSchema?.(log, tx);\n  }\n  if (versions.dataVersion < destinationVersion) {\n    await migration.migrateData?.(log, tx);\n  }\n  return updateVersionHistory(\n    log,\n    tx,\n    versions,\n    destinationVersion,\n    migration.minSafeVersion,\n  );\n}\n\n/**\n * Bumps the rollback limit [[toAtLeast]] the specified version.\n * Leaves the rollback limit unchanged if it is equal or greater.\n */\nfunction getMinSafeVersion(\n  log: LogContext,\n  current: VersionHistory,\n  proposedSafeVersion?: number,\n): number {\n  if (proposedSafeVersion === undefined) {\n    return current.minSafeVersion;\n  }\n  if (current.minSafeVersion >= proposedSafeVersion) {\n    // The rollback limit must never move backwards.\n    log.debug?.(\n      `rollback limit is already at ${current.minSafeVersion}, ` +\n        `don't need to bump to ${proposedSafeVersion}`,\n    );\n    return current.minSafeVersion;\n  }\n  log.info?.(\n    `bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`,\n  );\n  return proposedSafeVersion;\n}\n\n// Note: We use a custom transaction wrapper (instead of db.begin(...)) in order\n// to support async operations within the transaction.\nasync function runTransaction<T>(\n  log: LogContext,\n  db: Db,\n  tx: (db: Db) => Promise<T> | T,\n): Promise<T> {\n  db.prepare('BEGIN EXCLUSIVE').run();\n  try {\n    const result = await tx(db);\n    db.prepare('COMMIT').run();\n    return result;\n  } catch (e) {\n    log.error?.('Aborted transaction due to error', e);\n    db.prepare('ROLLBACK').run();\n    throw e;\n  }\n}\n"],"mappings":";;;;;;;;;AA0DA,eAAsB,oBACpB,KACA,WACA,QACA,gBACA,yBACe;CACf,MAAM,QAAQ,KAAK,KAAK;AACxB,OAAM,IAAI,YACR,cACA,QAAQ,GAAG,OAAO,iBAAiB,CAAC,SAAS,GAAG,CACjD;CACD,MAAM,KAAK,IAAI,SAAS,KAAK,OAAO;AAEpC,KAAI;EACF,MAAM,oBAAoB,OAAO,wBAAwB;AACzD,SACE,kBAAkB,QAClB,gDACD;AACD,SACE,kBAAkB,GAAG,KAAK,GAC1B,6CACD;EACD,MAAM,cAAc,kBAAkB,kBAAkB,SAAS,GAAG;AACpE,MAAI,OACF,0CAA0C,UAAU,cAAc,cACnE;EAED,IAAI,WAAW,MAAM,eAAe,KAAK,KAAI,OAAM;GACjD,MAAM,WAAW,kBAAkB,GAAG;AACtC,OAAI,cAAc,SAAS,eACzB,OAAM,IAAI,MACR,cAAc,UAAU,cAAc,YAAY,8BAA8B,SAAS,iBAC1F;AAGH,OAAI,SAAS,cAAc,aAAa;AACtC,QAAI,OACF,eAAe,SAAS,YAAY,kBAAkB,cACvD;AACD,WAAO,qBAAqB,KAAK,IAAI,UAAU,YAAY;;AAE7D,UAAO;IACP;AAEF,MAAI,SAAS,cAAc,aAAa;AACtC,MAAG,WAAW,KAAK;AACnB,MAAG,OAAO,2BAA2B;AACrC,MAAG,OAAO,qBAAqB;AAC/B,MAAG,OAAO,qBAAqB;AAC/B,MAAG,OAAO,oBAAoB;GAM9B,MAAM,aACJ,SAAS,gBAAgB,IAEpB,CAAC,CAAC,aAAa,eAAe,CAAC,GAChC;AAEN,QAAK,MAAM,CAAC,MAAM,cAAc,WAC9B,KAAI,SAAS,cAAc,MAAM;AAC/B,QAAI,OACF,0BAA0B,SAAS,YAAY,OAAO,OACvD;AACI,QAAI,OAAO;AAEhB,eAAW,MAAM,eAAe,KAAK,IAAI,OAAM,OAAM;KAEnD,IAAI,WAAW,kBAAkB,GAAG;AACpC,SAAI,SAAS,cAAc,MAAM;AAC/B,iBAAW,MAAM,aAAa,KAAK,IAAI,UAAU,MAAM,UAAU;AACjE,aACE,SAAS,gBAAgB,YAEvB,oDAAoD,KAAK,QAAQ,SAAS,cAC7E;;AAEH,YAAO;MACP;;AAIN,MAAG,KAAK,eAAe;AACvB,OAAI,OAAO,oBAAoB;QAS/B,IAAG,OAAO,qBAAqB;AAMjC,KAAG,OAAO,uBAAuB;AACjC,KAAG,WAAW,MAAM;AAEpB,SACE,SAAS,gBAAgB,mBAEvB,sBAAsB,SAAS,YAAY,gCAAgC,YAAY,GAC1F;AACD,MAAI,OACF,WAAW,UAAU,cAAc,YAAY,IAC7C,KAAK,KAAK,GAAG,MACd,MACF;UACM,GAAG;AACV,MAAI,QAAQ,iCAAiC,EAAE;AAC/C,QAAM;WACE;AACR,KAAG,OAAO;AACL,MAAI,OAAO;;;AAIpB,SAAS,OACP,yBACuB;CACvB,MAAM,oBAA2C,EAAE;AACnD,MAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,wBAAwB,CAC1D,mBAAkB,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC;AAExC,QAAO,kBAAkB,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE;;AAItB,eAAE,OAAO;CAQrC,eAAe,eAAE,QAAQ;CASzB,aAAa,eAAE,QAAQ;CAOvB,gBAAgB,eAAE,QAAQ;CAC3B,CAAC;AAMF,SAAgB,kBAAkB,IAAwB;AAExD,IAAG,QACD;;;;;;;;IASD,CAAC,KAAK;AAMP,QALe,GACZ,QACC,kFACD,CACA,KAAK,IACS;EAAC,aAAa;EAAG,eAAe;EAAG,gBAAgB;EAAE;;AAGxE,SAAS,qBACP,KACA,IACA,MACA,YACA,gBACgB;AAChB,QAAO,aAAa,GAAG,8BAA8B;CACrD,MAAM,OAAO;EACX,GAAG;EACH,aAAa;EAEb,eAAe,KAAK,IAAI,YAAY,KAAK,cAAc;EACvD,gBAAgB,kBAAkB,KAAK,MAAM,eAAe;EAC7D;AAED,IAAG,QACD;;;;;;;IAQD,CAAC,IAAI,KAAK;AAEX,QAAO;;AAGT,eAAe,aACb,KACA,IACA,UACA,oBACA,WACyB;AACzB,KAAI,SAAS,gBAAgB,mBAC3B,OAAM,UAAU,gBAAgB,KAAK,GAAG;AAE1C,KAAI,SAAS,cAAc,mBACzB,OAAM,UAAU,cAAc,KAAK,GAAG;AAExC,QAAO,qBACL,KACA,IACA,UACA,oBACA,UAAU,eACX;;;;;;AAOH,SAAS,kBACP,KACA,SACA,qBACQ;AACR,KAAI,wBAAwB,KAAA,EAC1B,QAAO,QAAQ;AAEjB,KAAI,QAAQ,kBAAkB,qBAAqB;AAEjD,MAAI,QACF,gCAAgC,QAAQ,eAAe,0BAC5B,sBAC5B;AACD,SAAO,QAAQ;;AAEjB,KAAI,OACF,+BAA+B,QAAQ,eAAe,MAAM,sBAC7D;AACD,QAAO;;AAKT,eAAe,eACb,KACA,IACA,IACY;AACZ,IAAG,QAAQ,kBAAkB,CAAC,KAAK;AACnC,KAAI;EACF,MAAM,SAAS,MAAM,GAAG,GAAG;AAC3B,KAAG,QAAQ,SAAS,CAAC,KAAK;AAC1B,SAAO;UACA,GAAG;AACV,MAAI,QAAQ,oCAAoC,EAAE;AAClD,KAAG,QAAQ,WAAW,CAAC,KAAK;AAC5B,QAAM"}
+{"version":3,"file":"migration-lite.js","names":[],"sources":["../../../../../zero-cache/src/db/migration-lite.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {randInt} from '../../../shared/src/rand.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport type {Database as Db} from '../../../zqlite/src/db.ts';\nimport {Database} from '../../../zqlite/src/db.ts';\n\ntype Operations = (log: LogContext, tx: Db) => Promise<void> | void;\n\n/**\n * Encapsulates the logic for setting up or upgrading to a new schema. After the\n * Migration code successfully completes, {@link runSchemaMigrations}\n * will update the schema version and commit the transaction.\n */\nexport type Migration = {\n  /**\n   * Perform database operations that create or alter table structure. This is\n   * called at most once during lifetime of the application. If a `migrateData()`\n   * operation is defined, that will be performed after `migrateSchema()` succeeds.\n   */\n  migrateSchema?: Operations;\n\n  /**\n   * Perform database operations to migrate data to the new schema. This is\n   * called after `migrateSchema()` (if defined), and may be called again\n   * to re-migrate data after the server was rolled back to an earlier version,\n   * and rolled forward again.\n   *\n   * Consequently, the logic in `migrateData()` must be idempotent.\n   */\n  migrateData?: Operations;\n\n  /**\n   * Sets the `minSafeVersion` to the specified value, prohibiting running\n   * any earlier code versions.\n   */\n  minSafeVersion?: number;\n};\n\n/**\n * Mapping of incremental migrations to move from the previous old code\n * version to next one. Versions must be non-zero.\n *\n * The schema resulting from performing incremental migrations should be\n * equivalent to that of the `setupMigration` on a blank database.\n *\n * The highest destinationVersion of this map denotes the current\n * \"code version\", and is also used as the destination version when\n * running the initial setup migration on a blank database.\n */\nexport type IncrementalMigrationMap = {\n  [destinationVersion: number]: Migration;\n};\n\n/**\n * Ensures that the schema is compatible with the current code, updating and\n * migrating the schema if necessary.\n */\nexport async function runSchemaMigrations(\n  log: LogContext,\n  debugName: string,\n  dbPath: string,\n  setupMigration: Migration,\n  incrementalMigrationMap: IncrementalMigrationMap,\n): Promise<void> {\n  const start = Date.now();\n  log = log.withContext(\n    'initSchema',\n    randInt(0, Number.MAX_SAFE_INTEGER).toString(36),\n  );\n  const db = new Database(log, dbPath);\n\n  try {\n    const versionMigrations = sorted(incrementalMigrationMap);\n    assert(\n      versionMigrations.length,\n      `Must specify a at least one version migration`,\n    );\n    assert(\n      versionMigrations[0][0] > 0,\n      `Versions must be non-zero positive numbers`,\n    );\n    // oxlint-disable-next-line typescript/no-non-null-assertion\n    const codeVersion = versionMigrations.at(-1)![0];\n    log.info?.(\n      `Checking schema for compatibility with ${debugName} at schema v${codeVersion}`,\n    );\n\n    let versions = await runTransaction(log, db, tx => {\n      const versions = getVersionHistory(tx);\n      if (codeVersion < versions.minSafeVersion) {\n        throw new Error(\n          `Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`,\n        );\n      }\n\n      if (versions.dataVersion > codeVersion) {\n        log.info?.(\n          `Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`,\n        );\n        return updateVersionHistory(log, tx, versions, codeVersion);\n      }\n      return versions;\n    });\n\n    if (versions.dataVersion < codeVersion) {\n      db.unsafeMode(true); // Enables journal_mode = OFF\n      db.pragma('locking_mode = EXCLUSIVE');\n      db.pragma('foreign_keys = OFF');\n      db.pragma('journal_mode = OFF');\n      db.pragma('synchronous = OFF');\n      // Unfortunately, AUTO_VACUUM is not compatible with BEGIN CONCURRENT,\n      // so it is not an option for the replica file.\n      // https://sqlite.org/forum/forumpost/25f183416a\n      // db.pragma('auto_vacuum = INCREMENTAL');\n\n      const migrations =\n        versions.dataVersion === 0\n          ? // For the empty database v0, only run the setup migration.\n            ([[codeVersion, setupMigration]] as const)\n          : versionMigrations;\n\n      for (const [dest, migration] of migrations) {\n        if (versions.dataVersion < dest) {\n          log.info?.(\n            `Migrating schema from v${versions.dataVersion} to v${dest}`,\n          );\n          void log.flush(); // Flush logs before each migration to help debug crash-y migrations.\n\n          versions = await runTransaction(log, db, async tx => {\n            // Fetch meta from within the transaction to make the migration atomic.\n            let versions = getVersionHistory(tx);\n            if (versions.dataVersion < dest) {\n              versions = await runMigration(log, tx, versions, dest, migration);\n              assert(\n                versions.dataVersion === dest,\n                () =>\n                  `Migration did not reach target version: expected ${dest}, got ${versions.dataVersion}`,\n              );\n            }\n            return versions;\n          });\n        }\n      }\n\n      db.exec('ANALYZE main');\n      log.info?.('ANALYZE completed');\n    } else {\n      // Run optimize whenever opening an sqlite db file as recommended in\n      // https://www.sqlite.org/pragma.html#pragma_optimize\n      // It is important to run the same initialization steps as is done\n      // in the view-syncer (i.e. when preparing database for serving\n      // replication) so that any corruption detected in the view-syncer is\n      // similarly detected in the change-streamer, facilitating an eventual\n      // recovery by resyncing the replica anew.\n      db.pragma('optimize = 0x10002');\n\n      // TODO: Investigate running `integrity_check` or `quick_check` as well,\n      // provided that they are not inordinately expensive on large databases.\n    }\n\n    db.pragma('synchronous = NORMAL');\n    db.unsafeMode(false);\n\n    assert(\n      versions.dataVersion === codeVersion,\n      () =>\n        `Final dataVersion (${versions.dataVersion}) does not match codeVersion (${codeVersion})`,\n    );\n    log.info?.(\n      `Running ${debugName} at schema v${codeVersion} (${\n        Date.now() - start\n      } ms)`,\n    );\n  } catch (e) {\n    log.error?.('Error in ensureSchemaMigrated', e);\n    throw e;\n  } finally {\n    db.close();\n    void log.flush(); // Flush the logs but do not block server progress on it.\n  }\n}\n\nfunction sorted(\n  incrementalMigrationMap: IncrementalMigrationMap,\n): [number, Migration][] {\n  const versionMigrations: [number, Migration][] = [];\n  for (const [v, m] of Object.entries(incrementalMigrationMap)) {\n    versionMigrations.push([Number(v), m]);\n  }\n  return versionMigrations.sort(([a], [b]) => a - b);\n}\n\n// Exposed for tests.\nexport const versionHistory = v.object({\n  /**\n   * The `schemaVersion` is highest code version that has ever been run\n   * on the database, and is used to delineate the structure of the tables\n   * in the database. A schemaVersion only moves forward; rolling back to\n   * an earlier (safe) code version does not revert schema changes that\n   * have already been applied.\n   */\n  schemaVersion: v.number(),\n\n  /**\n   * The data version is the code version of the latest server that ran.\n   * Note that this may be less than the schemaVersion in the case that\n   * a server is rolled back to an earlier version after a schema change.\n   * In such a case, data (but not schema), may need to be re-migrated\n   * when rolling forward again.\n   */\n  dataVersion: v.number(),\n\n  /**\n   * The minimum code version that is safe to run. This is used when\n   * a schema migration is not backwards compatible with an older version\n   * of the code.\n   */\n  minSafeVersion: v.number(),\n});\n\n// Exposed for tests.\nexport type VersionHistory = v.Infer<typeof versionHistory>;\n\n// Exposed for tests\nexport function getVersionHistory(db: Db): VersionHistory {\n  // Note: The `lock` column transparently ensures that at most one row exists.\n  db.prepare(\n    `\n    CREATE TABLE IF NOT EXISTS \"_zero.versionHistory\" (\n      dataVersion INTEGER NOT NULL,\n      schemaVersion INTEGER NOT NULL,\n      minSafeVersion INTEGER NOT NULL,\n\n      lock INTEGER PRIMARY KEY DEFAULT 1 CHECK (lock=1)\n    );\n  `,\n  ).run();\n  const result = db\n    .prepare(\n      'SELECT dataVersion, schemaVersion, minSafeVersion FROM \"_zero.versionHistory\"',\n    )\n    .get() as VersionHistory;\n  return result ?? {dataVersion: 0, schemaVersion: 0, minSafeVersion: 0};\n}\n\nfunction updateVersionHistory(\n  log: LogContext,\n  db: Db,\n  prev: VersionHistory,\n  newVersion: number,\n  minSafeVersion?: number,\n): VersionHistory {\n  assert(newVersion > 0, 'newVersion must be positive');\n  const meta = {\n    ...prev,\n    dataVersion: newVersion,\n    // The schemaVersion never moves backwards.\n    schemaVersion: Math.max(newVersion, prev.schemaVersion),\n    minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),\n  } satisfies VersionHistory;\n\n  db.prepare(\n    `\n    INSERT INTO \"_zero.versionHistory\" (dataVersion, schemaVersion, minSafeVersion, lock)\n    VALUES (@dataVersion, @schemaVersion, @minSafeVersion, 1)\n    ON CONFLICT (lock) DO UPDATE\n    SET dataVersion=@dataVersion,\n        schemaVersion=@schemaVersion,\n        minSafeVersion=@minSafeVersion\n  `,\n  ).run(meta);\n\n  return meta;\n}\n\nasync function runMigration(\n  log: LogContext,\n  tx: Db,\n  versions: VersionHistory,\n  destinationVersion: number,\n  migration: Migration,\n): Promise<VersionHistory> {\n  if (versions.schemaVersion < destinationVersion) {\n    await migration.migrateSchema?.(log, tx);\n  }\n  if (versions.dataVersion < destinationVersion) {\n    await migration.migrateData?.(log, tx);\n  }\n  return updateVersionHistory(\n    log,\n    tx,\n    versions,\n    destinationVersion,\n    migration.minSafeVersion,\n  );\n}\n\n/**\n * Bumps the rollback limit [[toAtLeast]] the specified version.\n * Leaves the rollback limit unchanged if it is equal or greater.\n */\nfunction getMinSafeVersion(\n  log: LogContext,\n  current: VersionHistory,\n  proposedSafeVersion?: number,\n): number {\n  if (proposedSafeVersion === undefined) {\n    return current.minSafeVersion;\n  }\n  if (current.minSafeVersion >= proposedSafeVersion) {\n    // The rollback limit must never move backwards.\n    log.debug?.(\n      `rollback limit is already at ${current.minSafeVersion}, ` +\n        `don't need to bump to ${proposedSafeVersion}`,\n    );\n    return current.minSafeVersion;\n  }\n  log.info?.(\n    `bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`,\n  );\n  return proposedSafeVersion;\n}\n\n// Note: We use a custom transaction wrapper (instead of db.begin(...)) in order\n// to support async operations within the transaction.\nasync function runTransaction<T>(\n  log: LogContext,\n  db: Db,\n  tx: (db: Db) => Promise<T> | T,\n): Promise<T> {\n  db.prepare('BEGIN EXCLUSIVE').run();\n  try {\n    const result = await tx(db);\n    db.prepare('COMMIT').run();\n    return result;\n  } catch (e) {\n    log.error?.('Aborted transaction due to error', e);\n    db.prepare('ROLLBACK').run();\n    throw e;\n  }\n}\n"],"mappings":"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"}

package/out/zero-cache/src/db/migration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAGrC,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AACnD,OAAO,EAAC,KAAK,UAAU,EAAE,KAAK,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAGzE,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,UAAU,EACd,cAAc,EAAE,SAAS,EACzB,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,IAAI,CAAC,CA6Ef;AAaD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;OAIG;;aAEH,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAG5D,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,QAAQ,CAAC,GAAG,EACjB,UAAU,EAAE,MAAM,iBAcnB;AASD,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,CAAC,GAAG,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,UAAQ,GACb,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAuBhC"}
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAGrC,OAAO,KAAK,CAAC,MAAM,+BAA+B,CAAC;AACnD,OAAO,EAAC,KAAK,UAAU,EAAE,KAAK,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAGzE,KAAK,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9E;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,CAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC,CAAC;AAEF;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,UAAU,EACd,cAAc,EAAE,SAAS,EACzB,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAaD,eAAO,MAAM,cAAc;IACzB;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;OAIG;;aAEH,CAAC;AAGH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAG5D,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,QAAQ,CAAC,GAAG,EACjB,UAAU,EAAE,MAAM,iBAcnB;AASD,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,CAAC,GAAG,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,UAAQ,GACb,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAuBhC"}

package/out/zero-cache/src/db/migration.js

@@ -13,7 +13,7 @@ async function runSchemaMigrations(log, debugName, schemaName, db, setupMigratio
 	const versionMigrations = sorted(incrementalMigrationMap);
 	assert(versionMigrations.length, `Must specify at least one version migration`);
 	assert(versionMigrations[0][0] > 0, `Versions must be non-zero positive numbers`);
-	const codeVersion = versionMigrations[versionMigrations.length - 1][0];
+	const codeVersion = versionMigrations.at(-1)[0];
 	log.info?.(`Checking schema for compatibility with ${debugName} at schema v${codeVersion}`);
 	try {
 		await runTx(db, async (tx) => {

package/out/zero-cache/src/db/migration.js.map

@@ -1 +1 @@
-{"version":3,"file":"migration.js","names":[],"sources":["../../../../../zero-cache/src/db/migration.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport type postgres from 'postgres';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport {type PostgresDB, type PostgresTransaction} from '../types/pg.ts';\nimport {runTx} from './run-transaction.ts';\n\ntype Operations = (log: LogContext, tx: PostgresTransaction) => Promise<void>;\n\n/**\n * Encapsulates the logic for setting up or upgrading to a new schema. After the\n * Migration code successfully completes, {@link runSchemaMigrations}\n * will update the schema version and commit the transaction.\n */\nexport type Migration = {\n  /**\n   * Perform database operations that create or alter table structure. This is\n   * called at most once during lifetime of the application. If a `migrateData()`\n   * operation is defined, that will be performed after `migrateSchema()` succeeds.\n   */\n  migrateSchema?: Operations;\n\n  /**\n   * Perform database operations to migrate data to the new schema. This is\n   * called after `migrateSchema()` (if defined), and may be called again\n   * to re-migrate data after the server was rolled back to an earlier version,\n   * and rolled forward again.\n   *\n   * Consequently, the logic in `migrateData()` must be idempotent.\n   */\n  migrateData?: Operations;\n\n  /**\n   * Sets the `minSafeVersion` to the specified value, prohibiting running\n   * any earlier code versions.\n   */\n  minSafeVersion?: number;\n};\n\n/**\n * Mapping of incremental migrations to move from the previous old code\n * version to next one. Versions must be non-zero.\n *\n * The schema resulting from performing incremental migrations should be\n * equivalent to that of the `setupMigration` on a blank database.\n *\n * The highest destinationVersion of this map denotes the current\n * \"code version\", and is also used as the destination version when\n * running the initial setup migration on a blank database.\n */\nexport type IncrementalMigrationMap = {\n  [destinationVersion: number]: Migration;\n};\n\n/**\n * Ensures that the schema is compatible with the current code, updating and\n * migrating the schema if necessary.\n */\nexport async function runSchemaMigrations(\n  log: LogContext,\n  debugName: string,\n  schemaName: string,\n  db: PostgresDB,\n  setupMigration: Migration,\n  incrementalMigrationMap: IncrementalMigrationMap,\n): Promise<void> {\n  log = log.withContext('initSchema', schemaName);\n\n  const versionMigrations = sorted(incrementalMigrationMap);\n  assert(\n    versionMigrations.length,\n    `Must specify at least one version migration`,\n  );\n  assert(\n    versionMigrations[0][0] > 0,\n    `Versions must be non-zero positive numbers`,\n  );\n  const codeVersion = versionMigrations[versionMigrations.length - 1][0];\n\n  log.info?.(\n    `Checking schema for compatibility with ${debugName} at schema v${codeVersion}`,\n  );\n\n  try {\n    await runTx(db, async tx => {\n      // Acquire advisory lock to prevent concurrent migrations from racing.\n      // This can happen during rolling deployments when multiple pods start\n      // up simultaneously. The lock auto-releases when the transaction ends.\n      const lockName = `migrate-schema:${schemaName}`;\n      await tx`SELECT pg_advisory_xact_lock(hashtext(${lockName}))`;\n\n      let versions = await ensureVersionHistory(tx, schemaName);\n\n      if (codeVersion < versions.minSafeVersion) {\n        throw new Error(\n          `Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`,\n        );\n      }\n\n      if (versions.dataVersion > codeVersion) {\n        log.info?.(\n          `Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`,\n        );\n        await updateVersionHistory(log, tx, schemaName, versions, codeVersion);\n        return;\n      }\n\n      if (versions.dataVersion === codeVersion) {\n        return;\n      }\n\n      const migrations =\n        versions.dataVersion === 0\n          ? // For an empty database (v0), only run the setup migration.\n            ([[codeVersion, setupMigration]] as const)\n          : versionMigrations;\n\n      for (const [dest, migration] of migrations) {\n        if (versions.dataVersion < dest) {\n          log.info?.(\n            `Migrating schema from v${versions.dataVersion} to v${dest}`,\n          );\n          void log.flush();\n          versions = await runMigration(\n            log,\n            schemaName,\n            tx,\n            versions,\n            dest,\n            migration,\n          );\n        }\n      }\n    });\n\n    log.info?.(`Running ${debugName} at schema v${codeVersion}`);\n  } catch (e) {\n    log.error?.('Error in ensureSchemaMigrated', e);\n    throw e;\n  } finally {\n    void log.flush();\n  }\n}\n\nfunction sorted(\n  incrementalMigrationMap: IncrementalMigrationMap,\n): [number, Migration][] {\n  const versionMigrations: [number, Migration][] = [];\n  for (const [v, m] of Object.entries(incrementalMigrationMap)) {\n    versionMigrations.push([Number(v), m]);\n  }\n  return versionMigrations.sort(([a], [b]) => a - b);\n}\n\n// Exposed for tests.\nexport const versionHistory = v.object({\n  /**\n   * The `schemaVersion` is highest code version that has ever been run\n   * on the database, and is used to delineate the structure of the tables\n   * in the database. A schemaVersion only moves forward; rolling back to\n   * an earlier (safe) code version does not revert schema changes that\n   * have already been applied.\n   */\n  schemaVersion: v.number(),\n\n  /**\n   * The data version is the code version of the latest server that ran.\n   * Note that this may be less than the schemaVersion in the case that\n   * a server is rolled back to an earlier version after a schema change.\n   * In such a case, data (but not schema), may need to be re-migrated\n   * when rolling forward again.\n   */\n  dataVersion: v.number(),\n\n  /**\n   * The minimum code version that is safe to run. This is used when\n   * a schema migration is not backwards compatible with an older version\n   * of the code.\n   */\n  minSafeVersion: v.number(),\n});\n\n// Exposed for tests.\nexport type VersionHistory = v.Infer<typeof versionHistory>;\n\n// Exposed for tests.\nexport async function createVersionHistoryTable(\n  sql: postgres.Sql,\n  schemaName: string,\n) {\n  // Note: The `lock` column transparently ensures that at most one row exists.\n  await sql`\n    CREATE SCHEMA IF NOT EXISTS ${sql(schemaName)};\n    CREATE TABLE IF NOT EXISTS ${sql(schemaName)}.\"versionHistory\" (\n      \"dataVersion\" int NOT NULL,\n      \"schemaVersion\" int NOT NULL,\n      \"minSafeVersion\" int NOT NULL,\n\n      lock char(1) NOT NULL CONSTRAINT DF_schema_meta_lock DEFAULT 'v',\n      CONSTRAINT PK_schema_meta_lock PRIMARY KEY (lock),\n      CONSTRAINT CK_schema_meta_lock CHECK (lock='v')\n    );`.simple();\n}\n\nasync function ensureVersionHistory(\n  sql: postgres.Sql,\n  schemaName: string,\n): Promise<VersionHistory> {\n  return must(await getVersionHistory(sql, schemaName, true));\n}\n\nexport async function getVersionHistory(\n  sql: postgres.Sql,\n  schemaName: string,\n  create = false,\n): Promise<VersionHistory | null> {\n  const exists = await sql`\n  SELECT nspname, relname FROM pg_class\n    JOIN pg_namespace ON relnamespace = pg_namespace.oid\n    WHERE nspname = ${schemaName} AND relname = ${'versionHistory'}`;\n\n  if (exists.length === 0) {\n    if (create) {\n      await createVersionHistoryTable(sql, schemaName);\n    } else {\n      return null;\n    }\n  }\n  const rows = await sql`\n    SELECT \"dataVersion\", \"schemaVersion\", \"minSafeVersion\"\n       FROM ${sql(schemaName)}.\"versionHistory\"`;\n\n  if (rows.length === 0) {\n    return create\n      ? {schemaVersion: 0, dataVersion: 0, minSafeVersion: 0}\n      : null;\n  }\n  return v.parse(rows[0], versionHistory);\n}\n\nasync function updateVersionHistory(\n  log: LogContext,\n  sql: postgres.Sql,\n  schemaName: string,\n  prev: VersionHistory,\n  newVersion: number,\n  minSafeVersion?: number,\n): Promise<VersionHistory> {\n  assert(newVersion > 0, 'newVersion must be positive');\n  const versions = {\n    dataVersion: newVersion,\n    // The schemaVersion never moves backwards.\n    schemaVersion: Math.max(newVersion, prev.schemaVersion),\n    minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),\n  } satisfies VersionHistory;\n\n  await sql`\n    INSERT INTO ${sql(schemaName)}.\"versionHistory\" ${sql(versions)}\n      ON CONFLICT (lock) DO UPDATE SET ${sql(versions)}\n  `;\n  return versions;\n}\n\nasync function runMigration(\n  log: LogContext,\n  schemaName: string,\n  tx: PostgresTransaction,\n  versions: VersionHistory,\n  destinationVersion: number,\n  migration: Migration,\n): Promise<VersionHistory> {\n  if (versions.schemaVersion < destinationVersion) {\n    await migration.migrateSchema?.(log, tx);\n  }\n  if (versions.dataVersion < destinationVersion) {\n    await migration.migrateData?.(log, tx);\n  }\n  return updateVersionHistory(\n    log,\n    tx,\n    schemaName,\n    versions,\n    destinationVersion,\n    migration.minSafeVersion,\n  );\n}\n\n/**\n * Bumps the rollback limit [[toAtLeast]] the specified version.\n * Leaves the rollback limit unchanged if it is equal or greater.\n */\nfunction getMinSafeVersion(\n  log: LogContext,\n  current: VersionHistory,\n  proposedSafeVersion?: number,\n): number {\n  if (proposedSafeVersion === undefined) {\n    return current.minSafeVersion;\n  }\n  if (current.minSafeVersion >= proposedSafeVersion) {\n    // The rollback limit must never move backwards.\n    log.debug?.(\n      `rollback limit is already at ${current.minSafeVersion}, ` +\n        `don't need to bump to ${proposedSafeVersion}`,\n    );\n    return current.minSafeVersion;\n  }\n  log.info?.(\n    `bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`,\n  );\n  return proposedSafeVersion;\n}\n"],"mappings":"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"}
+{"version":3,"file":"migration.js","names":[],"sources":["../../../../../zero-cache/src/db/migration.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport type postgres from 'postgres';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {must} from '../../../shared/src/must.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport {type PostgresDB, type PostgresTransaction} from '../types/pg.ts';\nimport {runTx} from './run-transaction.ts';\n\ntype Operations = (log: LogContext, tx: PostgresTransaction) => Promise<void>;\n\n/**\n * Encapsulates the logic for setting up or upgrading to a new schema. After the\n * Migration code successfully completes, {@link runSchemaMigrations}\n * will update the schema version and commit the transaction.\n */\nexport type Migration = {\n  /**\n   * Perform database operations that create or alter table structure. This is\n   * called at most once during lifetime of the application. If a `migrateData()`\n   * operation is defined, that will be performed after `migrateSchema()` succeeds.\n   */\n  migrateSchema?: Operations;\n\n  /**\n   * Perform database operations to migrate data to the new schema. This is\n   * called after `migrateSchema()` (if defined), and may be called again\n   * to re-migrate data after the server was rolled back to an earlier version,\n   * and rolled forward again.\n   *\n   * Consequently, the logic in `migrateData()` must be idempotent.\n   */\n  migrateData?: Operations;\n\n  /**\n   * Sets the `minSafeVersion` to the specified value, prohibiting running\n   * any earlier code versions.\n   */\n  minSafeVersion?: number;\n};\n\n/**\n * Mapping of incremental migrations to move from the previous old code\n * version to next one. Versions must be non-zero.\n *\n * The schema resulting from performing incremental migrations should be\n * equivalent to that of the `setupMigration` on a blank database.\n *\n * The highest destinationVersion of this map denotes the current\n * \"code version\", and is also used as the destination version when\n * running the initial setup migration on a blank database.\n */\nexport type IncrementalMigrationMap = {\n  [destinationVersion: number]: Migration;\n};\n\n/**\n * Ensures that the schema is compatible with the current code, updating and\n * migrating the schema if necessary.\n */\nexport async function runSchemaMigrations(\n  log: LogContext,\n  debugName: string,\n  schemaName: string,\n  db: PostgresDB,\n  setupMigration: Migration,\n  incrementalMigrationMap: IncrementalMigrationMap,\n): Promise<void> {\n  log = log.withContext('initSchema', schemaName);\n\n  const versionMigrations = sorted(incrementalMigrationMap);\n  assert(\n    versionMigrations.length,\n    `Must specify at least one version migration`,\n  );\n  assert(\n    versionMigrations[0][0] > 0,\n    `Versions must be non-zero positive numbers`,\n  );\n  // oxlint-disable-next-line typescript/no-non-null-assertion\n  const codeVersion = versionMigrations.at(-1)![0];\n\n  log.info?.(\n    `Checking schema for compatibility with ${debugName} at schema v${codeVersion}`,\n  );\n\n  try {\n    await runTx(db, async tx => {\n      // Acquire advisory lock to prevent concurrent migrations from racing.\n      // This can happen during rolling deployments when multiple pods start\n      // up simultaneously. The lock auto-releases when the transaction ends.\n      const lockName = `migrate-schema:${schemaName}`;\n      await tx`SELECT pg_advisory_xact_lock(hashtext(${lockName}))`;\n\n      let versions = await ensureVersionHistory(tx, schemaName);\n\n      if (codeVersion < versions.minSafeVersion) {\n        throw new Error(\n          `Cannot run ${debugName} at schema v${codeVersion} because rollback limit is v${versions.minSafeVersion}`,\n        );\n      }\n\n      if (versions.dataVersion > codeVersion) {\n        log.info?.(\n          `Data is at v${versions.dataVersion}. Resetting to v${codeVersion}`,\n        );\n        await updateVersionHistory(log, tx, schemaName, versions, codeVersion);\n        return;\n      }\n\n      if (versions.dataVersion === codeVersion) {\n        return;\n      }\n\n      const migrations =\n        versions.dataVersion === 0\n          ? // For an empty database (v0), only run the setup migration.\n            ([[codeVersion, setupMigration]] as const)\n          : versionMigrations;\n\n      for (const [dest, migration] of migrations) {\n        if (versions.dataVersion < dest) {\n          log.info?.(\n            `Migrating schema from v${versions.dataVersion} to v${dest}`,\n          );\n          void log.flush();\n          versions = await runMigration(\n            log,\n            schemaName,\n            tx,\n            versions,\n            dest,\n            migration,\n          );\n        }\n      }\n    });\n\n    log.info?.(`Running ${debugName} at schema v${codeVersion}`);\n  } catch (e) {\n    log.error?.('Error in ensureSchemaMigrated', e);\n    throw e;\n  } finally {\n    void log.flush();\n  }\n}\n\nfunction sorted(\n  incrementalMigrationMap: IncrementalMigrationMap,\n): [number, Migration][] {\n  const versionMigrations: [number, Migration][] = [];\n  for (const [v, m] of Object.entries(incrementalMigrationMap)) {\n    versionMigrations.push([Number(v), m]);\n  }\n  return versionMigrations.sort(([a], [b]) => a - b);\n}\n\n// Exposed for tests.\nexport const versionHistory = v.object({\n  /**\n   * The `schemaVersion` is highest code version that has ever been run\n   * on the database, and is used to delineate the structure of the tables\n   * in the database. A schemaVersion only moves forward; rolling back to\n   * an earlier (safe) code version does not revert schema changes that\n   * have already been applied.\n   */\n  schemaVersion: v.number(),\n\n  /**\n   * The data version is the code version of the latest server that ran.\n   * Note that this may be less than the schemaVersion in the case that\n   * a server is rolled back to an earlier version after a schema change.\n   * In such a case, data (but not schema), may need to be re-migrated\n   * when rolling forward again.\n   */\n  dataVersion: v.number(),\n\n  /**\n   * The minimum code version that is safe to run. This is used when\n   * a schema migration is not backwards compatible with an older version\n   * of the code.\n   */\n  minSafeVersion: v.number(),\n});\n\n// Exposed for tests.\nexport type VersionHistory = v.Infer<typeof versionHistory>;\n\n// Exposed for tests.\nexport async function createVersionHistoryTable(\n  sql: postgres.Sql,\n  schemaName: string,\n) {\n  // Note: The `lock` column transparently ensures that at most one row exists.\n  await sql`\n    CREATE SCHEMA IF NOT EXISTS ${sql(schemaName)};\n    CREATE TABLE IF NOT EXISTS ${sql(schemaName)}.\"versionHistory\" (\n      \"dataVersion\" int NOT NULL,\n      \"schemaVersion\" int NOT NULL,\n      \"minSafeVersion\" int NOT NULL,\n\n      lock char(1) NOT NULL CONSTRAINT DF_schema_meta_lock DEFAULT 'v',\n      CONSTRAINT PK_schema_meta_lock PRIMARY KEY (lock),\n      CONSTRAINT CK_schema_meta_lock CHECK (lock='v')\n    );`.simple();\n}\n\nasync function ensureVersionHistory(\n  sql: postgres.Sql,\n  schemaName: string,\n): Promise<VersionHistory> {\n  return must(await getVersionHistory(sql, schemaName, true));\n}\n\nexport async function getVersionHistory(\n  sql: postgres.Sql,\n  schemaName: string,\n  create = false,\n): Promise<VersionHistory | null> {\n  const exists = await sql`\n  SELECT nspname, relname FROM pg_class\n    JOIN pg_namespace ON relnamespace = pg_namespace.oid\n    WHERE nspname = ${schemaName} AND relname = ${'versionHistory'}`;\n\n  if (exists.length === 0) {\n    if (create) {\n      await createVersionHistoryTable(sql, schemaName);\n    } else {\n      return null;\n    }\n  }\n  const rows = await sql`\n    SELECT \"dataVersion\", \"schemaVersion\", \"minSafeVersion\"\n       FROM ${sql(schemaName)}.\"versionHistory\"`;\n\n  if (rows.length === 0) {\n    return create\n      ? {schemaVersion: 0, dataVersion: 0, minSafeVersion: 0}\n      : null;\n  }\n  return v.parse(rows[0], versionHistory);\n}\n\nasync function updateVersionHistory(\n  log: LogContext,\n  sql: postgres.Sql,\n  schemaName: string,\n  prev: VersionHistory,\n  newVersion: number,\n  minSafeVersion?: number,\n): Promise<VersionHistory> {\n  assert(newVersion > 0, 'newVersion must be positive');\n  const versions = {\n    dataVersion: newVersion,\n    // The schemaVersion never moves backwards.\n    schemaVersion: Math.max(newVersion, prev.schemaVersion),\n    minSafeVersion: getMinSafeVersion(log, prev, minSafeVersion),\n  } satisfies VersionHistory;\n\n  await sql`\n    INSERT INTO ${sql(schemaName)}.\"versionHistory\" ${sql(versions)}\n      ON CONFLICT (lock) DO UPDATE SET ${sql(versions)}\n  `;\n  return versions;\n}\n\nasync function runMigration(\n  log: LogContext,\n  schemaName: string,\n  tx: PostgresTransaction,\n  versions: VersionHistory,\n  destinationVersion: number,\n  migration: Migration,\n): Promise<VersionHistory> {\n  if (versions.schemaVersion < destinationVersion) {\n    await migration.migrateSchema?.(log, tx);\n  }\n  if (versions.dataVersion < destinationVersion) {\n    await migration.migrateData?.(log, tx);\n  }\n  return updateVersionHistory(\n    log,\n    tx,\n    schemaName,\n    versions,\n    destinationVersion,\n    migration.minSafeVersion,\n  );\n}\n\n/**\n * Bumps the rollback limit [[toAtLeast]] the specified version.\n * Leaves the rollback limit unchanged if it is equal or greater.\n */\nfunction getMinSafeVersion(\n  log: LogContext,\n  current: VersionHistory,\n  proposedSafeVersion?: number,\n): number {\n  if (proposedSafeVersion === undefined) {\n    return current.minSafeVersion;\n  }\n  if (current.minSafeVersion >= proposedSafeVersion) {\n    // The rollback limit must never move backwards.\n    log.debug?.(\n      `rollback limit is already at ${current.minSafeVersion}, ` +\n        `don't need to bump to ${proposedSafeVersion}`,\n    );\n    return current.minSafeVersion;\n  }\n  log.info?.(\n    `bumping rollback limit from ${current.minSafeVersion} to ${proposedSafeVersion}`,\n  );\n  return proposedSafeVersion;\n}\n"],"mappings":"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"}

package/out/zero-cache/src/db/pg-copy-binary.d.ts

@@ -0,0 +1,101 @@
+import type { LiteValueType } from '../types/lite.ts';
+import type { ColumnSpec } from './specs.ts';
+/**
+ * Streaming parser for PostgreSQL `COPY ... TO STDOUT WITH (FORMAT binary)`.
+ *
+ * Analogous to {@link import('./pg-copy.ts').TsvParser} but for binary format.
+ * Yields `Buffer | null` per field (null = SQL NULL).
+ *
+ * The caller tracks column position the same way as with TsvParser.
+ */
+export declare class BinaryCopyParser {
+    #private;
+    parse(chunk: Buffer): Iterable<Buffer | null>;
+}
+export type BinaryDecoder = (buf: Buffer) => LiteValueType;
+type BinaryColumnSpec = Pick<ColumnSpec, 'dataType' | 'pgTypeClass' | 'elemPgTypeClass'> & {
+    typeOID: number;
+};
+/**
+ * Returns true if the column's binary format is known and can be decoded
+ * natively. For columns where this returns false, the COPY SELECT should
+ * cast the column to `::text` so PG sends the text representation inside
+ * the binary frame.
+ */
+export declare function hasBinaryDecoder(spec: BinaryColumnSpec): boolean;
+/** Decoder for columns cast to `::text` in the COPY SELECT. */
+export declare const textCastDecoder: BinaryDecoder;
+/**
+ * Creates a specialized binary decoder for the given column spec.
+ * The returned function converts a raw COPY binary field `Buffer`
+ * directly to a `LiteValueType`, bypassing text parsing entirely.
+ *
+ * Only call this for columns where {@link hasBinaryDecoder} returns true.
+ * For other columns, cast to `::text` in the SELECT and use
+ * {@link textCastDecoder}.
+ */
+export declare function makeBinaryDecoder(spec: BinaryColumnSpec): BinaryDecoder;
+/**
+ * UUID: 16 bytes → "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ */
+export declare function decodeUUID(buf: Buffer): string;
+/**
+ * TIMESTAMP / TIMESTAMPTZ: int64 microseconds since PG epoch (2000-01-01 UTC)
+ * → floating-point milliseconds since Unix epoch.
+ *
+ * Matches the output of `timestampToFpMillis()` in `types/pg.ts`.
+ *
+ * Uses Number arithmetic (avoiding BigInt) for speed. The microsecond value
+ * fits safely in a Number for all practical dates (up to ~year 285,000).
+ */
+export declare function decodeTimestamp(buf: Buffer): number;
+/**
+ * DATE: int32 days since PG epoch (2000-01-01) → millis since Unix epoch at
+ * UTC midnight. Matches `dateToUTCMidnight()` in `types/pg.ts`.
+ */
+export declare function decodeDate(buf: Buffer): number;
+/**
+ * TIME: int64 microseconds since midnight → milliseconds since midnight.
+ * Matches `postgresTimeToMilliseconds()` in `types/pg.ts`.
+ *
+ * Max value is 86,400,000,000 (~8.6e10), well within Number.MAX_SAFE_INTEGER.
+ */
+export declare function decodeTime(buf: Buffer): number;
+/**
+ * TIMETZ: int64 microseconds since midnight + int32 timezone offset in seconds.
+ * PG stores the offset with inverted sign from ISO (POSIX convention):
+ * positive = west of UTC, negative = east of UTC.
+ * UTC = local_time + pg_offset.
+ * → UTC milliseconds since midnight.
+ *
+ * Max value ~1.3e11 microseconds, well within Number.MAX_SAFE_INTEGER.
+ */
+export declare function decodeTimeTZ(buf: Buffer): number;
+/**
+ * NUMERIC: variable-length binary format.
+ * Header: {ndigits: int16, weight: int16, sign: int16, dscale: int16}
+ * Followed by ndigits x int16 base-10000 digits.
+ *
+ * Converts to a JS `number` (matching the text path's `Number(x)` behavior).
+ */
+export declare function decodeNumeric(buf: Buffer): number;
+/**
+ * Array: binary format.
+ *
+ * Header:
+ *   int32 ndim       — number of dimensions (0 for empty array)
+ *   int32 flags      — 0 or 1 (has-nulls)
+ *   int32 elem_oid   — OID of element type
+ *   Per dimension:
+ *     int32 dim_size  — number of elements in this dimension
+ *     int32 dim_lb    — lower bound (usually 1)
+ *
+ * Then for each element (in row-major order):
+ *   int32 length     — -1 for NULL, otherwise byte length
+ *   bytes            — element data
+ *
+ * Result is JSON.stringify'd for storage in SQLite (matching text path behavior).
+ */
+export declare function decodeArray(buf: Buffer): string;
+export {};
+//# sourceMappingURL=pg-copy-binary.d.ts.map

package/out/zero-cache/src/db/pg-copy-binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-copy-binary.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/db/pg-copy-binary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAwBpD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,YAAY,CAAC;AA0B3C;;;;;;;GAOG;AACH,qBAAa,gBAAgB;;IAM1B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC;CAuH/C;AAID,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC;AAE3D,KAAK,gBAAgB,GAAG,IAAI,CAC1B,UAAU,EACV,UAAU,GAAG,aAAa,GAAG,iBAAiB,CAC/C,GAAG;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC;AAyBtB;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAQhE;AAED,+DAA+D;AAC/D,eAAO,MAAM,eAAe,EAAE,aAA2C,CAAC;AAE1E;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa,CAyDvE;AAID;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAa9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASnD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYhD;AASD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiDjD;AAkCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiD/C"}