@effect-vfs/core 0.2.0 → 0.3.1

package/dist/internal/image.js

@@ -1,42 +1,28 @@
-/**
- * Snapshot validation and serialization used by `VirtualFileSystem`.
- *
- * @internal
- */
+// Snapshot validation and serialization used by VirtualFileSystem.
 import * as ByteSize from "effect/ByteSize";
 import * as Effect from "effect/Effect";
-import * as Encoding from "effect/Encoding";
+import * as Match from "effect/Match";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import { DecodeLimits, ImageError, SnapshotTypeId } from "../Snapshot.js";
-import * as CanonicalBase64 from "./canonicalBase64.js";
-const natural = Schema.Finite.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+import { CanonicalBase64 } from "./canonicalBase64.js";
+import { StoredMetadata, WireStoredMetadata } from "./metadata.js";
 class SnapshotImpl {
     [SnapshotTypeId] = SnapshotTypeId;
 }
-const integer = Schema.String.check(Schema.isPattern(/^(?:0|-?[1-9][0-9]{0,127})(?![\s\S])/));
 /** @internal */
-export const StoredMetadata = Schema.Struct({
-    uid: natural,
-    gid: natural,
-    mode: natural.check(Schema.isLessThanOrEqualTo(0o7777)),
-    atimeNs: integer,
-    mtimeNs: integer,
-    ctimeNs: integer,
-    birthtimeNs: integer
-});
+export { StoredMetadata };
 const id = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128));
 /** @internal */
-export const Record = Schema.Union([
-    Schema.Struct({
+export const Record = Schema.TaggedUnion({
+    directory: {
         id,
-        kind: Schema.Literal("directory"),
         metadata: StoredMetadata,
-        entries: Schema.Array(Schema.Struct({ name: Schema.String, target: id }))
-    }),
-    Schema.Struct({ id, kind: Schema.Literal("file"), metadata: StoredMetadata, data: Schema.String }),
-    Schema.Struct({ id, kind: Schema.Literal("symlink"), metadata: StoredMetadata, target: Schema.String })
-]);
+        entries: Schema.Array(Schema.Struct({ name: CanonicalBase64.Encoded, target: id }))
+    },
+    file: { id, metadata: StoredMetadata, data: CanonicalBase64.Encoded },
+    symlink: { id, metadata: StoredMetadata, target: CanonicalBase64.Encoded }
+});
 /** @internal */
 export const Document = Schema.Struct({
     format: Schema.Literal("effect-vfs"),
@@ -44,97 +30,111 @@ export const Document = Schema.Struct({
     root: id,
     records: Schema.Array(Record)
 });
+const WireRecord = Schema.TaggedUnion({
+    directory: {
+        id,
+        metadata: WireStoredMetadata,
+        entries: Schema.Array(Schema.Struct({ name: Schema.String, target: id }))
+    },
+    file: { id, metadata: WireStoredMetadata, data: Schema.String },
+    symlink: { id, metadata: WireStoredMetadata, target: Schema.String }
+});
+const WireDocument = Schema.Struct({
+    format: Schema.Literal("effect-vfs"),
+    version: Schema.Literal(1),
+    root: id,
+    records: Schema.Array(WireRecord)
+});
+const VersionProbe = Schema.Struct({
+    format: Schema.Literal("effect-vfs"),
+    version: Schema.Unknown
+});
 const snapshots = new WeakMap();
 /** @internal */
-export const decodedLength = CanonicalBase64.decodedLength;
-/** @internal */
-export const base64 = (input) => {
-    // Effect's encoder concatenates individual characters. Join bounded chunks so snapshots
-    // retain flat strings instead of those intermediate string chains. A multiple of three
-    // keeps padding in the final chunk only, preserving canonical base64.
-    const chunkBytes = 12_288;
-    const chunks = [];
-    for (let offset = 0; offset < input.length; offset += chunkBytes) {
-        chunks.push(Encoding.encodeBase64(input.subarray(offset, offset + chunkBytes)));
-    }
-    return chunks.join("");
-};
-const error = (code, field) => new ImageError({ code, ...(field === undefined ? {} : { field }) });
-/** @internal */
-export const bytes = (value) => {
-    return CanonicalBase64.decodeTrusted(value);
-};
-/** @internal */
 export const inspect = (snapshot) => Effect.suspend(() => {
     const document = snapshots.get(snapshot);
-    return document === undefined ? Effect.fail(error("InvalidStructure", "snapshot")) : Effect.succeed(document);
+    return document === undefined
+        ? new ImageError({ code: "InvalidStructure", field: "snapshot" })
+        : Effect.succeed(document);
 });
 /** @internal */
-export const capture = Effect.fnUntraced(function* (input, limits) {
-    const decoded = Schema.decodeUnknownResult(Document, { onExcessProperty: "error" })(input);
-    if (Result.isFailure(decoded))
-        return yield* error("InvalidStructure");
-    const document = decoded.success;
+export const capture = Effect.fnUntraced(function* (input, limits, trusted = false) {
+    const wire = trusted ? undefined : Schema.decodeUnknownResult(WireDocument, { onExcessProperty: "error" })(input);
+    if (wire !== undefined && Result.isFailure(wire)) {
+        return yield* new ImageError({ code: "InvalidStructure", field: "document" });
+    }
+    const decoded = trusted ? undefined : Schema.decodeUnknownResult(Document, { onExcessProperty: "error" })(input);
+    if (decoded !== undefined && Result.isFailure(decoded)) {
+        return yield* new ImageError({ code: "InvalidEncoding", field: "document" });
+    }
+    // SAFETY: a trusted caller passes a Document it built; an untrusted one has just been decoded.
+    const document = decoded === undefined ? input : decoded.success;
     const records = new Map();
     let entries = 0;
     let payload = ByteSize.zero;
     if (limits !== undefined && document.records.length > limits.maxRecords) {
-        return yield* error("LimitExceeded", "records");
+        return yield* new ImageError({ code: "LimitExceeded", field: "records" });
     }
     for (const record of document.records) {
         if (records.has(record.id))
-            return yield* error("InvalidStructure", "id");
+            return yield* new ImageError({ code: "InvalidStructure", field: "id" });
         records.set(record.id, record);
-        if (record.kind === "directory")
+        Match.value(record).pipe(Match.tag("directory", (record) => {
             entries += record.entries.length;
+        }), Match.undefined);
     }
-    if (limits !== undefined && entries > limits.maxEntries)
-        return yield* error("LimitExceeded", "entries");
-    // Count every payload before allocating any decoded payload buffer.
-    for (const record of document.records) {
-        const values = record.kind === "directory"
-            ? record.entries.map((entry) => entry.name)
-            : [record.kind === "file" ? record.data : record.target];
-        for (const value of values) {
-            if (!CanonicalBase64.isCanonical(value))
-                return yield* error("InvalidEncoding", record.id);
-            payload = ByteSize.sum(payload, ByteSize.bytes(decodedLength(value)));
-            if (limits !== undefined && ByteSize.isGreaterThan(payload, limits.maxDecodedBytes)) {
-                return yield* error("LimitExceeded", "bytes");
+    if (limits !== undefined && entries > limits.maxEntries) {
+        return yield* new ImageError({ code: "LimitExceeded", field: "entries" });
+    }
+    // Count every payload before allocating any decoded payload buffer. Trusted records carry
+    // base64 this module produced, so the scan only runs when a limit depends on the tally.
+    if (!trusted || limits !== undefined) {
+        for (const record of document.records) {
+            const values = Match.value(record).pipe(Match.tag("directory", (record) => record.entries.map((entry) => entry.name)), Match.tag("file", (record) => [record.data]), Match.tag("symlink", (record) => [record.target]), Match.exhaustive);
+            for (const value of values) {
+                if (!CanonicalBase64.is(value)) {
+                    return yield* new ImageError({ code: "InvalidEncoding", field: record.id });
+                }
+                payload = ByteSize.sum(payload, ByteSize.bytes(CanonicalBase64.decodedLength(value)));
+                if (limits !== undefined && ByteSize.isGreaterThan(payload, limits.maxDecodedBytes)) {
+                    return yield* new ImageError({ code: "LimitExceeded", field: "bytes" });
+                }
             }
         }
     }
     const root = records.get(document.root);
-    if (root?.kind !== "directory")
-        return yield* error("InvalidStructure", "root");
+    if (root === undefined || !Record.guards.directory(root)) {
+        return yield* new ImageError({ code: "InvalidStructure", field: "root" });
+    }
     const parents = new Map();
     for (const record of document.records) {
-        if (record.kind === "directory") {
+        if (Record.guards.directory(record)) {
             const names = new Set();
             for (const entry of record.entries) {
-                if (names.has(entry.name) || decodedLength(entry.name) < 1 || decodedLength(entry.name) > 255) {
-                    return yield* error("InvalidStructure", "name");
-                }
+                if (names.has(entry.name) || CanonicalBase64.decodedLength(entry.name) < 1 ||
+                    CanonicalBase64.decodedLength(entry.name) > 255)
+                    return yield* new ImageError({ code: "InvalidStructure", field: "name" });
                 names.add(entry.name);
-                const name = bytes(entry.name);
+                const name = yield* CanonicalBase64.decode(entry.name);
                 if (name.includes(0) || name.includes(47) || (name.length === 1 && name[0] === 46) ||
                     (name.length === 2 && name[0] === 46 && name[1] === 46))
-                    return yield* error("InvalidStructure", "name");
+                    return yield* new ImageError({ code: "InvalidStructure", field: "name" });
                 const target = records.get(entry.target);
                 if (target === undefined)
-                    return yield* error("InvalidStructure", "target");
+                    return yield* new ImageError({ code: "InvalidStructure", field: "target" });
                 parents.set(target.id, (parents.get(target.id) ?? 0) + 1);
             }
         }
-        else if (record.kind === "symlink" && bytes(record.target).includes(0)) {
-            return yield* error("InvalidStructure", "symlink");
+        else if (Record.guards.symlink(record) && (yield* CanonicalBase64.decode(record.target)).includes(0)) {
+            return yield* new ImageError({ code: "InvalidStructure", field: "symlink" });
         }
     }
     if (parents.has(root.id))
-        return yield* error("InvalidStructure", "root");
+        return yield* new ImageError({ code: "InvalidStructure", field: "root" });
     for (const record of document.records) {
-        if (record !== root && (record.kind === "directory" ? parents.get(record.id) !== 1 : !parents.has(record.id))) {
-            return yield* error("InvalidStructure", "parent");
+        const invalidParent = Match.value(record).pipe(Match.tag("directory", (record) => parents.get(record.id) !== 1), Match.tag("file", (record) => !parents.has(record.id)), Match.tag("symlink", (record) => !parents.has(record.id)), Match.exhaustive);
+        if (record !== root && invalidParent) {
+            return yield* new ImageError({ code: "InvalidStructure", field: "parent" });
         }
     }
     const visited = new Set();
@@ -145,39 +145,43 @@ export const capture = Effect.fnUntraced(function* (input, limits) {
             continue;
         visited.add(next);
         const record = records.get(next);
-        if (record?.kind === "directory") {
-            for (const entry of record.entries)
-                pending.push(entry.target);
+        if (record !== undefined) {
+            Match.value(record).pipe(Match.tag("directory", (record) => {
+                for (const entry of record.entries)
+                    pending.push(entry.target);
+            }), Match.tag("file", () => undefined), Match.tag("symlink", () => undefined), Match.exhaustive);
         }
     }
     if (visited.size !== records.size)
-        return yield* error("InvalidStructure", "reachability");
+        return yield* new ImageError({ code: "InvalidStructure", field: "reachability" });
     const snapshot = Object.freeze(new SnapshotImpl());
     snapshots.set(snapshot, document);
     return snapshot;
 });
 /** @internal */
 export const encodeSnapshot = Effect.fn("VirtualFileSystem.encodeSnapshot")(function* (snapshot) {
-    const text = yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown))(yield* inspect(snapshot)).pipe(Effect.mapError(() => error("InvalidStructure")));
+    const text = yield* Schema.encodeEffect(Schema.fromJsonString(Document))(yield* inspect(snapshot)).pipe(Effect.mapError(() => new ImageError({ code: "InvalidStructure", field: "text" })));
     return new TextEncoder().encode(text);
 });
 /** @internal */
 export const decodeSnapshot = Effect.fn("VirtualFileSystem.decodeSnapshot")(function* (input, limits) {
     const checked = Schema.decodeResult(DecodeLimits, { onExcessProperty: "error" })(limits);
     if (Result.isFailure(checked))
-        return yield* error("InvalidStructure", "limits");
-    if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer))
-        return yield* error("InvalidEncoding");
+        return yield* new ImageError({ code: "InvalidStructure", field: "limits" });
+    if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer)) {
+        return yield* new ImageError({ code: "InvalidEncoding", field: "input" });
+    }
     if (ByteSize.isGreaterThan(ByteSize.bytes(input.byteLength), checked.success.maxEncodedBytes)) {
-        return yield* error("LimitExceeded", "encodedBytes");
+        return yield* new ImageError({ code: "LimitExceeded", field: "encodedBytes" });
     }
     const text = yield* Effect.try({
         try: () => new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(input)),
-        catch: () => error("InvalidEncoding")
+        catch: () => new ImageError({ code: "InvalidEncoding", field: "text" })
     });
-    const value = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe(Effect.mapError(() => error("InvalidEncoding")));
-    if (typeof value === "object" && value !== null && "format" in value && value.format === "effect-vfs" &&
-        "version" in value && value.version !== 1)
-        return yield* error("UnsupportedVersion");
+    const value = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe(Effect.mapError(() => new ImageError({ code: "InvalidEncoding", field: "text" })));
+    const version = Schema.decodeUnknownResult(VersionProbe)(value);
+    if (Result.isSuccess(version) && version.success.version !== 1) {
+        return yield* new ImageError({ code: "UnsupportedVersion", field: "version" });
+    }
     return yield* capture(value, checked.success);
 });

package/dist/internal/metadata.d.ts

@@ -0,0 +1,28 @@
+import * as Schema from "effect/Schema";
+/** @internal */
+export declare const Timestamp: Schema.BigInt;
+/** @internal */
+export declare const TimestampFromString: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+/** @internal */
+export declare const WireStoredMetadata: Schema.Struct<{
+    readonly uid: Schema.Natural;
+    readonly gid: Schema.Natural;
+    readonly mode: Schema.Natural;
+    readonly atimeNs: Schema.String;
+    readonly mtimeNs: Schema.String;
+    readonly ctimeNs: Schema.String;
+    readonly birthtimeNs: Schema.String;
+}>;
+/** @internal */
+export declare const StoredMetadata: Schema.Struct<{
+    readonly uid: Schema.Natural;
+    readonly gid: Schema.Natural;
+    readonly mode: Schema.Natural;
+    readonly atimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+    readonly mtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+    readonly ctimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+    readonly birthtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+}>;
+/** @internal */
+export type StoredMetadata = typeof StoredMetadata.Type;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/internal/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/internal/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAKvC,gBAAgB;AAChB,eAAO,MAAM,SAAS,eAGrB,CAAA;AAED,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,6DAE0C,CAAA;AAE1E,gBAAgB;AAChB,eAAO,MAAM,kBAAkB;;;;;;;;EAQ7B,CAAA;AAEF,gBAAgB;AAChB,eAAO,MAAM,cAAc;;;;;;;;EAQzB,CAAA;AAEF,gBAAgB;AAChB,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA"}

package/dist/internal/metadata.js

@@ -0,0 +1,29 @@
+import * as Schema from "effect/Schema";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+const MAX_TIMESTAMP = 10n ** 128n - 1n;
+/** @internal */
+export const Timestamp = Schema.BigInt.check(Schema.isGreaterThanOrEqualToBigInt(-MAX_TIMESTAMP), Schema.isLessThanOrEqualToBigInt(MAX_TIMESTAMP));
+/** @internal */
+export const TimestampFromString = Schema.String
+    .check(Schema.isPattern(/^-?[0-9]{1,128}$/))
+    .pipe(Schema.decodeTo(Timestamp, SchemaTransformation.bigintFromString));
+/** @internal */
+export const WireStoredMetadata = Schema.Struct({
+    uid: Schema.Natural,
+    gid: Schema.Natural,
+    mode: Schema.Natural.check(Schema.isLessThanOrEqualTo(0o7777)),
+    atimeNs: Schema.String,
+    mtimeNs: Schema.String,
+    ctimeNs: Schema.String,
+    birthtimeNs: Schema.String
+});
+/** @internal */
+export const StoredMetadata = Schema.Struct({
+    uid: Schema.Natural,
+    gid: Schema.Natural,
+    mode: Schema.Natural.check(Schema.isLessThanOrEqualTo(0o7777)),
+    atimeNs: TimestampFromString,
+    mtimeNs: TimestampFromString,
+    ctimeNs: TimestampFromString,
+    birthtimeNs: TimestampFromString
+});

package/dist/internal/snapshotDelta.d.ts

@@ -1,4 +1,3 @@
-/** Exact snapshot delta construction, inspection, serialization, and application. @internal */
 import * as ByteSize from "effect/ByteSize";
 import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";

package/dist/internal/snapshotDelta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshotDelta.d.ts","sourceRoot":"","sources":["../../src/internal/snapshotDelta.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAMvC,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC1D,OAAO,EAIL,KAAK,aAAa,EAClB,kBAAkB,EAKnB,MAAM,qBAAqB,CAAA;AA6d5B,gBAAgB;AAChB,eAAO,MAAM,aAAa;;;;;;;;;;;4GAgDzB,CAAA;AAwBD,gBAAgB;AAChB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;oGAgBhC,CAAA;AACD,gBAAgB;AAChB,eAAO,MAAM,mBAAmB;;;;;;;;;;;+DAS9B,CAAA;AACF,gBAAgB;AAChB,eAAO,MAAM,mBAAmB;;;;;;;;;;;qDAkB9B,CAAA;AACF,gBAAgB;AAChB,eAAO,MAAM,kBAAkB;;;;;;;;;;;4HAI9B,CAAA"}
+{"version":3,"file":"snapshotDelta.d.ts","sourceRoot":"","sources":["../../src/internal/snapshotDelta.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAOvC,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC1D,OAAO,EAGL,KAAK,aAAa,EAClB,kBAAkB,EAInB,MAAM,qBAAqB,CAAA;AAmuB5B,gBAAgB;AAChB,eAAO,MAAM,aAAa;;;;;;;;;;;4GAgDzB,CAAA;AAyBD,gBAAgB;AAChB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;oGAoBhC,CAAA;AAED,gBAAgB;AAChB,eAAO,MAAM,mBAAmB;;;;;;;;;;;+DAe9B,CAAA;AAEF,gBAAgB;AAChB,eAAO,MAAM,mBAAmB;;;;;;;;;;;qDAkC9B,CAAA;AAEF,gBAAgB;AAChB,eAAO,MAAM,kBAAkB;;;;;;;;;;;4HAI9B,CAAA"}