@volter/world-core 3.0.148 → 3.0.149

package/dist/src/resource-blob.d.ts

@@ -8,6 +8,13 @@ export declare function removeResourceBlob(service: string, key: string, root?:
 /** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
  *  what a listing that mints ids covers, so a branch serves bytes its parent received and never re-mints a parent's id. */
 export declare function resourceChain(service: string, root?: string): string[];
+/** Where a resource blob's key is kept under a resources directory. A key is a relative path, its parts joined by '/'.
+ *  On Windows a part may hold a character no file name can: a ':' there names an NTFS stream of the file before it, so
+ *  `asset:<id>` wrote into a stream of a file named `asset` and the store's rename failed (EINVAL). There each of
+ *  `<>:"|?*`, a control character and '%' itself is written as %XX, one name per key; elsewhere the key is the path. */
+export declare function resourceBlobFile(dir: string, key: string): string;
+/** The key a file under a resources directory holds: resourceBlobFile's inverse, its parts joined by '/'. */
+export declare function resourceBlobKey(dir: string, path: string): string;
 /** Size of a resource payload at this branch or its ancestors, or null. */
 export declare function resourceBlobSize(service: string, key: string, root?: string): Promise<number | null>;
 /** A byte range of a resource payload at this branch or its ancestors (a ranged read where the

package/dist/src/resource-blob.js

@@ -1,4 +1,4 @@
-import { isAbsolute, join } from 'node:path';
+import { isAbsolute, join, relative } from 'node:path';
 import { getActiveBlobStore, readBlobRange } from "./blob-store.js";
 import { readBranchMeta } from "./log.js";
 import { worldPaths } from "./storage.js";
@@ -6,7 +6,7 @@ import { worldPaths } from "./storage.js";
 export async function readResourceBlob(service, key, root) {
     assertResourceKey(key);
     for (const dir of resourceChain(service, root)) {
-        const bytes = await getActiveBlobStore().get(join(dir, key));
+        const bytes = await getActiveBlobStore().get(resourceBlobFile(dir, key));
         if (bytes !== null)
             return bytes;
     }
@@ -15,13 +15,13 @@ export async function readResourceBlob(service, key, root) {
 /** Write a resource payload on this branch (a stored object's bytes), where a read finds it first. */
 export async function writeResourceBlob(service, key, bytes, root) {
     assertResourceKey(key);
-    await getActiveBlobStore().put(join(worldPaths(service, root).resources, key), bytes);
+    await getActiveBlobStore().put(resourceBlobFile(worldPaths(service, root).resources, key), bytes);
 }
 /** Remove this branch's copy of a resource payload; an ancestor's stays its own (the row that named it is what a
  *  deletion ends). */
 export async function removeResourceBlob(service, key, root) {
     assertResourceKey(key);
-    await getActiveBlobStore().remove(join(worldPaths(service, root).resources, key));
+    await getActiveBlobStore().remove(resourceBlobFile(worldPaths(service, root).resources, key));
 }
 /** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
  *  what a listing that mints ids covers, so a branch serves bytes its parent received and never re-mints a parent's id. */
@@ -40,6 +40,18 @@ export function resourceChain(service, root) {
         current = parent.at;
     }
 }
+/** Where a resource blob's key is kept under a resources directory. A key is a relative path, its parts joined by '/'.
+ *  On Windows a part may hold a character no file name can: a ':' there names an NTFS stream of the file before it, so
+ *  `asset:<id>` wrote into a stream of a file named `asset` and the store's rename failed (EINVAL). There each of
+ *  `<>:"|?*`, a control character and '%' itself is written as %XX, one name per key; elsewhere the key is the path. */
+export function resourceBlobFile(dir, key) {
+    return join(dir, process.platform === 'win32' ? key.replace(/[%<>:"|?*\x00-\x1f]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`) : key);
+}
+/** The key a file under a resources directory holds: resourceBlobFile's inverse, its parts joined by '/'. */
+export function resourceBlobKey(dir, path) {
+    const key = relative(dir, path).split('\\').join('/');
+    return process.platform === 'win32' ? key.replace(/%([0-9A-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16))) : key;
+}
 function assertResourceKey(key) {
     if (isAbsolute(key) || key.includes('\0') || key.split(/[\\/]/).includes('..'))
         throw new Error('Invalid relative resource blob key');
@@ -48,7 +60,7 @@ function assertResourceKey(key) {
 async function resolveResourceBlob(service, key, root) {
     assertResourceKey(key);
     for (const dir of resourceChain(service, root)) {
-        const path = join(dir, key);
+        const path = resourceBlobFile(dir, key);
         if (await getActiveBlobStore().exists(path))
             return path;
     }

package/dist/src/runtime.d.ts

@@ -78,7 +78,7 @@ export { corsHeaders, withCors, type CorsDecl } from './cors.js';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.js';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.js';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.js';
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.js';
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from './ancestry.js';
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from './history.js';
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.js';

package/dist/src/runtime.js

@@ -98,7 +98,7 @@ export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBou
 export { corsHeaders, withCors } from "./cors.js";
 export { setInProcessTwins, vendorFetch, VendorUnreachableError } from "./vendor-call.js";
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver } from "./managed-database.js";
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from "./resource-blob.js";
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from "./resource-blob.js";
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from "./ancestry.js";
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from "./history.js";
 export { foldHistory } from "./log.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.148",
+  "version": "3.0.149",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/resource-blob.ts

@@ -1,4 +1,4 @@
-import { isAbsolute, join } from 'node:path';
+import { isAbsolute, join, relative } from 'node:path';
 import { getActiveBlobStore, readBlobRange } from './blob-store.ts';
 import { readBranchMeta } from './log.ts';
 import { worldPaths } from './storage.ts';
@@ -7,7 +7,7 @@ import { worldPaths } from './storage.ts';
 export async function readResourceBlob(service: string, key: string, root?: string): Promise<Uint8Array | null> {
   assertResourceKey(key);
   for (const dir of resourceChain(service, root)) {
-    const bytes = await getActiveBlobStore().get(join(dir, key));
+    const bytes = await getActiveBlobStore().get(resourceBlobFile(dir, key));
     if (bytes !== null) return bytes;
   }
   return null;
@@ -16,14 +16,14 @@ export async function readResourceBlob(service: string, key: string, root?: stri
 /** Write a resource payload on this branch (a stored object's bytes), where a read finds it first. */
 export async function writeResourceBlob(service: string, key: string, bytes: Uint8Array, root?: string): Promise<void> {
   assertResourceKey(key);
-  await getActiveBlobStore().put(join(worldPaths(service, root).resources, key), bytes);
+  await getActiveBlobStore().put(resourceBlobFile(worldPaths(service, root).resources, key), bytes);
 }
 
 /** Remove this branch's copy of a resource payload; an ancestor's stays its own (the row that named it is what a
  *  deletion ends). */
 export async function removeResourceBlob(service: string, key: string, root?: string): Promise<void> {
   assertResourceKey(key);
-  await getActiveBlobStore().remove(join(worldPaths(service, root).resources, key));
+  await getActiveBlobStore().remove(resourceBlobFile(worldPaths(service, root).resources, key));
 }
 
 /** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
@@ -42,6 +42,20 @@ export function resourceChain(service: string, root?: string): string[] {
   }
 }
 
+/** Where a resource blob's key is kept under a resources directory. A key is a relative path, its parts joined by '/'.
+ *  On Windows a part may hold a character no file name can: a ':' there names an NTFS stream of the file before it, so
+ *  `asset:<id>` wrote into a stream of a file named `asset` and the store's rename failed (EINVAL). There each of
+ *  `<>:"|?*`, a control character and '%' itself is written as %XX, one name per key; elsewhere the key is the path. */
+export function resourceBlobFile(dir: string, key: string): string {
+  return join(dir, process.platform === 'win32' ? key.replace(/[%<>:"|?*\x00-\x1f]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`) : key);
+}
+
+/** The key a file under a resources directory holds: resourceBlobFile's inverse, its parts joined by '/'. */
+export function resourceBlobKey(dir: string, path: string): string {
+  const key = relative(dir, path).split('\\').join('/');
+  return process.platform === 'win32' ? key.replace(/%([0-9A-F]{2})/g, (_, hex: string) => String.fromCharCode(parseInt(hex, 16))) : key;
+}
+
 function assertResourceKey(key: string): void {
   if (isAbsolute(key) || key.includes('\0') || key.split(/[\\/]/).includes('..')) throw new Error('Invalid relative resource blob key');
 }
@@ -50,7 +64,7 @@ function assertResourceKey(key: string): void {
 async function resolveResourceBlob(service: string, key: string, root?: string): Promise<string | null> {
   assertResourceKey(key);
   for (const dir of resourceChain(service, root)) {
-    const path = join(dir, key);
+    const path = resourceBlobFile(dir, key);
     if (await getActiveBlobStore().exists(path)) return path;
   }
   return null;

package/src/runtime.ts

@@ -335,7 +335,7 @@ export { corsHeaders, withCors, type CorsDecl } from './cors.ts';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.ts';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
-export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.ts';
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob } from './resource-blob.ts';
 
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from './ancestry.ts';