@forgeax/engine-assets-runtime 0.1.2

package/src/internal/load-asset.ts

@@ -0,0 +1,254 @@
+import type {
+  Asset,
+  AssetArtifactReader,
+  AssetDecoder,
+  AssetDecoderInput,
+  AssetDecoderLease,
+  AssetKind,
+  AssetLoadError,
+  BuiltinAssetKind,
+  BuiltinAssetPayload,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import type { CatalogSource } from '../catalog-source.js';
+import { ArtifactCache } from './artifact-cache.js';
+import { AssetGraph, type AssetGraphSnapshot } from './asset-graph.js';
+import { CatalogSession, type CatalogSessionOptions } from './catalog-session.js';
+import { DecoderRegistry } from './decoder-registry.js';
+import { freezeRuntimePayload } from './immutable-payload.js';
+import { PackReader } from './pack-reader.js';
+import { validateRuntimeRow } from './validate-runtime-row.js';
+
+export interface AssetRegistryOptions extends CatalogSessionOptions {
+  readonly catalog: CatalogSource;
+  readonly fetcher?: typeof globalThis.fetch;
+  readonly maxConcurrentReads?: number;
+}
+
+export interface AssetLoadOptions {
+  readonly signal?: AbortSignal;
+}
+
+export type AssetRegistrySnapshot = AssetGraphSnapshot;
+
+export type AssetRegistrySnapshotCounters = AssetRegistrySnapshot['counters'];
+
+export interface AssetRegistry {
+  installDecoder<P, K extends string>(
+    kind: AssetKind<P, K>,
+    decoder: AssetDecoder<P>,
+  ): AssetDecoderLease;
+  load<K extends BuiltinAssetKind>(
+    guid: string,
+    kind: K,
+    options?: AssetLoadOptions,
+  ): Promise<Result<BuiltinAssetPayload<K>, AssetLoadError>>;
+  load<P, K extends string>(
+    guid: string,
+    kind: AssetKind<P, K>,
+    options?: AssetLoadOptions,
+  ): Promise<Result<P, AssetLoadError>>;
+  snapshot(): AssetRegistrySnapshot;
+  subscribe(listener: (snapshot: AssetRegistrySnapshot) => void): () => void;
+  dispose(): void;
+}
+
+/** Internal render projection; the root Registry keeps only its five actions. */
+export interface AssetRegistryResolver {
+  readonly epoch: number;
+  lookup<T extends Asset>(guid: string): T | undefined;
+  guidOf(asset: Asset): string | undefined;
+}
+
+const REGISTRY_RESOLVER = Symbol.for('forgeax.assets-runtime.registry-resolver');
+type RegistryWithResolver = AssetRegistry & {
+  [REGISTRY_RESOLVER]?: AssetRegistryResolver;
+};
+
+export function getAssetRegistryResolver(registry: AssetRegistry): AssetRegistryResolver {
+  const resolver = (registry as RegistryWithResolver)[REGISTRY_RESOLVER];
+  if (resolver === undefined) {
+    throw new TypeError('AssetRegistry resolver is not owned by this asset runtime');
+  }
+  return resolver;
+}
+
+function missing(guid: string): AssetLoadError {
+  return {
+    code: 'asset-not-found',
+    expected: `the current Catalog to contain GUID "${guid}"`,
+    hint: 'inspect the producer Catalog and rebuild the missing publication',
+    detail: { guid },
+  };
+}
+
+function mismatch(guid: string, expectedKind: string, actualKind: string): AssetLoadError {
+  return {
+    code: 'asset-kind-mismatch',
+    expected: `Catalog kind "${actualKind}" to match "${expectedKind}"`,
+    hint: 'pass the Catalog kind or the matching custom AssetKind token',
+    detail: { guid, expectedKind, actualKind },
+  };
+}
+
+function artifactError(guid: string, reason: string): AssetLoadError {
+  return {
+    code: 'asset-integrity-failed',
+    expected: 'the verified artifact byte length and digest',
+    hint: 'verify the artifact digest and recook the Pack',
+    detail: {
+      guid,
+      artifactKey: reason,
+      expectedDigest: 'descriptor integrity',
+      actualDigest: reason,
+    },
+  };
+}
+
+const ASSET_GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function invalidGuid(guid: string): AssetLoadError {
+  return {
+    code: 'asset-guid-invalid',
+    expected: 'a 36-character dash-form asset GUID',
+    hint: 'pass the producer GUID from the current Catalog row',
+    detail: { guid },
+  };
+}
+
+export function createAssetRegistry(options: AssetRegistryOptions): AssetRegistry {
+  const session = new CatalogSession(options.catalog, options);
+  const reader = new PackReader(options.fetcher === undefined ? {} : { fetcher: options.fetcher });
+  const cache = new ArtifactCache();
+  const decoders = new DecoderRegistry(
+    options.scopeId === undefined ? {} : { scopeId: options.scopeId },
+  );
+  const graph = new AssetGraph<{ readonly value: unknown; readonly refs: readonly string[] }>({
+    ...(options.maxConcurrentReads === undefined
+      ? {}
+      : { maxConcurrentReads: options.maxConcurrentReads }),
+    read: async (guid, signal) => {
+      const row = session.current(guid);
+      if (row === undefined) return err(missing(guid));
+      const validated = validateRuntimeRow(row);
+      if (!validated.ok) return validated;
+      const publication = validated.value.publication;
+      const tuple = {
+        scopeId: session.snapshot().scopeId,
+        generation: publication.generation,
+        digest: publication.digest,
+        outputSetDigest: publication.outputSetDigest,
+      };
+      const pack = await reader.read(row.packageUrl, tuple, signal);
+      if (!pack.ok) return pack;
+      const envelope = pack.value.assets.find(
+        (asset) => asset.guid.toLowerCase() === guid.toLowerCase(),
+      );
+      if (envelope === undefined) return err(missing(guid));
+      const artifacts: AssetArtifactReader = {
+        read: (descriptor) => {
+          const integrity = descriptor.integrity;
+          if (integrity === undefined)
+            return Promise.resolve(err(artifactError(guid, descriptor.path)));
+          const key = `${tuple.scopeId}:${tuple.generation}:${tuple.outputSetDigest}:${integrity.digest}`;
+          return cache.read(key, async () => {
+            const url = resolveArtifactUrl(row.packageUrl, descriptor.path);
+            let response: Response;
+            try {
+              response = await (options.fetcher ?? globalThis.fetch)(url, { signal });
+            } catch {
+              return err(artifactError(guid, descriptor.path));
+            }
+            if (!response.ok) return err(artifactError(guid, descriptor.path));
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            if (descriptor.byteLength === undefined || bytes.byteLength !== descriptor.byteLength) {
+              return err(artifactError(guid, descriptor.path));
+            }
+            const actualDigest = await sha256(bytes);
+            if (actualDigest !== descriptor.integrity?.digest.toLowerCase()) {
+              return err(artifactError(guid, `${descriptor.path}:${actualDigest}`));
+            }
+            return ok(bytes);
+          });
+        },
+      };
+      const input: AssetDecoderInput<unknown> = { envelope, artifacts, signal };
+      const decoded = await decoders.loadByKind(envelope.kind, input);
+      if (!decoded.ok) return decoded;
+      return ok({ value: freezeRuntimePayload(decoded.value), refs: envelope.refs });
+    },
+  });
+
+  let catalogEpoch = session.snapshot().epoch;
+  const unsubscribeCatalog = session.subscribe((snapshot) => {
+    if (snapshot.epoch === catalogEpoch) return;
+    catalogEpoch = snapshot.epoch;
+    graph.invalidateForCatalogChange(
+      snapshot.stale ? undefined : [...snapshot.changed, ...snapshot.removed],
+    );
+  });
+
+  const registry: AssetRegistry = {
+    installDecoder: (kind, decoder) => decoders.install(kind, decoder),
+    load: (async (
+      guid: string,
+      kind: BuiltinAssetKind | AssetKind<unknown, string>,
+      loadOptions: AssetLoadOptions = {},
+    ): Promise<Result<unknown, AssetLoadError>> => {
+      if (!ASSET_GUID_PATTERN.test(guid)) return err(invalidGuid(guid));
+      const expectedKind = typeof kind === 'string' ? kind : kind.kind;
+      const started = await session.start();
+      if (!started.ok) return err(started.error);
+      if (session.snapshot().stale) {
+        const reconciled = await session.reconcile();
+        if (!reconciled.ok) return err(reconciled.error);
+        const discontinuity = session.discontinuity();
+        if (discontinuity !== undefined) return err(discontinuity);
+      }
+      const row = session.current(guid);
+      if (row === undefined) return err(missing(guid));
+      if (row.kind !== expectedKind) return err(mismatch(guid, expectedKind, row.kind));
+      const result = await graph.load(guid, loadOptions.signal);
+      return result.ok ? ok(result.value.value) : result;
+    }) as AssetRegistry['load'],
+    snapshot: () => graph.snapshot(),
+    subscribe: (listener) => graph.subscribe(listener),
+    dispose: () => {
+      graph.dispose();
+      unsubscribeCatalog();
+      decoders.dispose();
+      cache.clear();
+      session.dispose();
+    },
+  };
+  const resolver: AssetRegistryResolver = {
+    get epoch() {
+      return graph.snapshot().epoch;
+    },
+    lookup: <T extends Asset>(guid: string) => graph.lookup(guid) as T | undefined,
+    guidOf: (asset: Asset) => graph.guidOf(asset),
+  };
+  Object.defineProperty(registry, REGISTRY_RESOLVER, {
+    value: resolver,
+    enumerable: false,
+  });
+  return registry;
+}
+
+async function sha256(bytes: Uint8Array): Promise<string> {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes as unknown as BufferSource);
+  return `sha256:${Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('')}`;
+}
+
+function resolveArtifactUrl(packageUrl: string, path: string): string {
+  const separator = packageUrl.lastIndexOf('/');
+  const packageDirectory = separator < 0 ? '' : packageUrl.slice(0, separator + 1);
+  try {
+    return new URL(path, packageDirectory).toString();
+  } catch {
+    return `${packageDirectory}${path.replace(/^\//, '')}`;
+  }
+}

package/src/internal/pack-reader.ts

@@ -0,0 +1,183 @@
+import type {
+  AssetEnvelopeV2,
+  AssetLoadError,
+  AssetPublicationTuple,
+  PackV2,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+
+export interface PackReaderOptions {
+  readonly fetcher?: typeof globalThis.fetch;
+}
+
+export type VerifiedPack = PackV2<unknown>;
+
+function invalid(guid: string, reason: string): Result<never, AssetLoadError> {
+  return err({
+    code: 'asset-package-invalid',
+    expected: 'a verified Pack v2 envelope with complete runtime artifacts',
+    hint: 're-cook the Pack v2 publication and retry the current tuple',
+    detail: { guid, reason },
+  });
+}
+
+function frozen<T>(value: T): T {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value as Record<string, unknown>)) frozen(child);
+  }
+  return value;
+}
+
+function sameTuple(left: AssetPublicationTuple, right: AssetPublicationTuple): boolean {
+  return (
+    left.scopeId === right.scopeId &&
+    left.generation === right.generation &&
+    left.digest === right.digest &&
+    left.outputSetDigest === right.outputSetDigest
+  );
+}
+
+export class PackReader {
+  private readonly fetcher: typeof globalThis.fetch | undefined;
+  private readonly verified = new Map<string, VerifiedPack>();
+  private readonly pending = new Map<string, Promise<Result<VerifiedPack, AssetLoadError>>>();
+
+  constructor(options: PackReaderOptions = {}) {
+    // An injected fetcher is an explicit transport lease and is fixed for the
+    // reader lifetime. With no injection, resolve the host fetch at read time:
+    // App assembly can precede a dev/test host installing its transport.
+    this.fetcher = options.fetcher?.bind(globalThis);
+  }
+
+  async read(
+    packageUrl: string,
+    expected: AssetPublicationTuple,
+    signal: AbortSignal,
+  ): Promise<Result<VerifiedPack, AssetLoadError>> {
+    if (signal.aborted) return err(this.cancelled(packageUrl));
+    const key = this.key(packageUrl, expected);
+    const cached = this.verified.get(key);
+    if (cached !== undefined) return ok(cached);
+    const active = this.pending.get(key);
+    if (active !== undefined) return active;
+    const request = this.fetchAndVerify(packageUrl, expected, signal);
+    this.pending.set(key, request);
+    const result = await request;
+    this.pending.delete(key);
+    if (result.ok) this.verified.set(key, result.value);
+    return result;
+  }
+
+  private async fetchAndVerify(
+    packageUrl: string,
+    expected: AssetPublicationTuple,
+    signal: AbortSignal,
+  ): Promise<Result<VerifiedPack, AssetLoadError>> {
+    let response: Response;
+    try {
+      const fetcher = this.fetcher ?? globalThis.fetch.bind(globalThis);
+      response = await fetcher(packageUrl, { signal });
+    } catch (_cause) {
+      if (signal.aborted) return err(this.cancelled(packageUrl));
+      return err({
+        code: 'asset-fetch-failed',
+        expected: 'HTTP 200 for the current Pack URL',
+        hint: 'verify the package locator and republish the Pack',
+        detail: { guid: packageUrl, packageUrl },
+      });
+    }
+    if (!response.ok) {
+      return err({
+        code: 'asset-fetch-failed',
+        expected: 'HTTP 200 for the current Pack URL',
+        hint: 'verify the package locator and republish the Pack',
+        detail: { guid: packageUrl, packageUrl },
+      });
+    }
+    let value: unknown;
+    try {
+      value = await response.json();
+    } catch {
+      return invalid(packageUrl, 'invalid JSON');
+    }
+    return this.verify(value, expected);
+  }
+
+  private key(packageUrl: string, tuple: AssetPublicationTuple): string {
+    return `${packageUrl}\u0000${tuple.scopeId}\u0000${tuple.generation}\u0000${tuple.digest}\u0000${tuple.outputSetDigest}`;
+  }
+
+  verify(value: unknown, expected: AssetPublicationTuple): Result<VerifiedPack, AssetLoadError> {
+    if (value === null || typeof value !== 'object') return invalid('', 'Pack is not an object');
+    const pack = value as Partial<PackV2<unknown>>;
+    if (pack.schemaVersion !== '2.0.0' || pack.kind !== 'internal-text-package') {
+      return invalid('', 'schemaVersion or kind');
+    }
+    if (
+      typeof pack.scopeId !== 'string' ||
+      !Number.isSafeInteger(pack.generation) ||
+      typeof pack.digest !== 'string' ||
+      typeof pack.outputSetDigest !== 'string' ||
+      !sameTuple(pack as AssetPublicationTuple, expected)
+    ) {
+      return invalid('', 'publication tuple mismatch');
+    }
+    if (!Array.isArray(pack.assets)) return invalid('', 'assets');
+    const guids = new Set<string>();
+    for (const raw of pack.assets) {
+      const asset = raw as Partial<AssetEnvelopeV2<unknown>>;
+      const guid = typeof asset.guid === 'string' ? asset.guid : '';
+      if (guid.length === 0 || guids.has(guid.toLowerCase()))
+        return invalid(guid, 'duplicate guid');
+      guids.add(guid.toLowerCase());
+      if (
+        typeof asset.kind !== 'string' ||
+        asset.payload === undefined ||
+        !Array.isArray(asset.refs) ||
+        asset.refs.some((ref) => typeof ref !== 'string') ||
+        asset.artifacts === null ||
+        typeof asset.artifacts !== 'object'
+      ) {
+        return invalid(guid, 'asset envelope fields');
+      }
+      for (const [artifactKey, descriptor] of Object.entries(asset.artifacts)) {
+        if (!this.validArtifact(guid, artifactKey, descriptor)) {
+          return invalid(guid, `artifact ${artifactKey}`);
+        }
+      }
+    }
+    return ok(frozen(pack as VerifiedPack));
+  }
+
+  private validArtifact(_guid: string, key: string, value: unknown): boolean {
+    if (value === null || typeof value !== 'object') return false;
+    const descriptor = value as Record<string, unknown>;
+    const integrity = descriptor.integrity;
+    return (
+      key.length > 0 &&
+      typeof descriptor.path === 'string' &&
+      descriptor.path.length > 0 &&
+      typeof descriptor.mediaType === 'string' &&
+      descriptor.mediaType.length > 0 &&
+      (descriptor.contentEncoding === 'identity' || descriptor.contentEncoding === 'zstd') &&
+      Number.isSafeInteger(descriptor.byteLength) &&
+      Number(descriptor.byteLength) >= 0 &&
+      integrity !== null &&
+      typeof integrity === 'object' &&
+      (integrity as Record<string, unknown>).algorithm === 'sha256' &&
+      typeof (integrity as Record<string, unknown>).digest === 'string' &&
+      /^sha256:[0-9a-f]{64}$/i.test(String((integrity as Record<string, unknown>).digest))
+    );
+  }
+
+  private cancelled(guid: string): AssetLoadError {
+    return {
+      code: 'asset-load-cancelled',
+      expected: 'the request AbortSignal to remain live while reading the Pack',
+      hint: 'retry with a live AbortSignal when the request is still needed',
+      detail: { guid },
+    };
+  }
+}

package/src/internal/validate-runtime-row.ts

@@ -0,0 +1,51 @@
+import type { CatalogEntry } from '@forgeax/engine-types';
+import { type AssetLoadError, err, ok, type Result } from '@forgeax/engine-types';
+
+export interface RuntimeCatalogRow extends CatalogEntry {
+  readonly publication: NonNullable<CatalogEntry['publication']>;
+}
+
+function invalidRow(guid: string, reason: string): Result<never, AssetLoadError> {
+  return err({
+    code: 'asset-package-invalid',
+    expected: 'one complete current runtime Catalog row',
+    hint: 'rebuild the producer Catalog and publish one Pack v2 tuple',
+    detail: { guid, reason },
+  });
+}
+
+export function validateRuntimeRow(row: CatalogEntry): Result<RuntimeCatalogRow, AssetLoadError> {
+  if (row === null || typeof row !== 'object') return invalidRow('', 'row');
+  const candidate = row as Partial<CatalogEntry>;
+  const guid = typeof candidate.guid === 'string' ? candidate.guid : '';
+  if (guid.trim().length === 0) return invalidRow(guid, 'guid');
+  if (typeof candidate.kind !== 'string' || candidate.kind.trim().length === 0)
+    return invalidRow(guid, 'kind');
+  if (typeof candidate.packageUrl !== 'string' || candidate.packageUrl.trim().length === 0)
+    return invalidRow(guid, 'packageUrl');
+  if (typeof candidate.sourcePath !== 'string' || candidate.sourcePath.trim().length === 0)
+    return invalidRow(guid, 'sourcePath');
+  if (!Number.isSafeInteger(candidate.publication?.generation))
+    return invalidRow(guid, 'publication generation');
+  if (candidate.publication === undefined) return invalidRow(guid, 'publication');
+  const publication = candidate.publication;
+  if (
+    publication.schemaVersion !== 'asset-publication/1' ||
+    typeof publication.sourcePath !== 'string' ||
+    publication.sourcePath.trim().length === 0 ||
+    typeof publication.sourceRevision !== 'string' ||
+    publication.sourceRevision.trim().length === 0 ||
+    publication.generation < 0 ||
+    typeof publication.digest !== 'string' ||
+    publication.digest.trim().length === 0 ||
+    typeof publication.outputSetDigest !== 'string' ||
+    publication.outputSetDigest.trim().length === 0 ||
+    !Array.isArray(publication.outputs) ||
+    publication.receipt === null ||
+    typeof publication.receipt !== 'object' ||
+    !Array.isArray(publication.externalEvidence)
+  ) {
+    return invalidRow(guid, 'publication tuple');
+  }
+  return ok(Object.freeze({ ...candidate, guid, publication }) as RuntimeCatalogRow);
+}

package/src/internal.ts

@@ -0,0 +1,4 @@
+export {
+  type AssetRegistryResolver,
+  getAssetRegistryResolver,
+} from './internal/load-asset.js';