@aphrody/shenron-dbxv2 0.0.0-stage → 1.4.7

package/src/runtime.ts

@@ -0,0 +1,130 @@
+/**
+ * Runtime used by the modules the `dbxv2:` plugin generates. Resolves the private server from the
+ * environment on first use (so nothing about the game or the token is fixed at build time), and
+ * starts the loopback signing proxy lazily for URL imports.
+ */
+import { Dbxv2Client, type Dbxv2Binary } from "./client";
+import { currentEnv, dbxv2Status, describeDisabledReason, type Dbxv2EnvInput } from "./env";
+import { Dbxv2DisabledError } from "./errors";
+import { createDbxv2Proxy, type Dbxv2Proxy } from "./proxy";
+import {
+  parseRef,
+  type Dbxv2Ref,
+  type Dbxv2RefInput,
+  type Dbxv2ResourceKind,
+  type Dbxv2ResourceParams,
+} from "./refs";
+import type { Dbxv2ModelJson } from "./schemas";
+
+export interface Dbxv2Runtime {
+  readonly client: Dbxv2Client;
+  /** Started on first use. */
+  proxy(): Dbxv2Proxy;
+  stop(): void;
+}
+
+let current: { runtime: Dbxv2Runtime; key: string } | null = null;
+
+/** Client + proxy built from the environment; throws {@link Dbxv2DisabledError} when disabled. */
+export function getDbxv2Runtime(env: Dbxv2EnvInput = currentEnv()): Dbxv2Runtime {
+  const status = dbxv2Status(env);
+  if (!status.enabled) {
+    throw new Dbxv2DisabledError(
+      `DBXV2 is disabled: ${describeDisabledReason(status.reason)}. ` +
+        "Set DBXV2_SERVER_URL and DBXV2_TOKEN (see docs/products/dbxv2-plugin.md).",
+    );
+  }
+  const key = `${status.config.baseUrl}\n${status.config.token}`;
+  if (current?.key === key) return current.runtime;
+  current?.runtime.stop();
+  let proxy: Dbxv2Proxy | null = null;
+  const client = new Dbxv2Client(status.config);
+  const runtime: Dbxv2Runtime = {
+    client,
+    proxy: () => {
+      if (!status.config.token)
+        throw new Dbxv2DisabledError("Public clients do not create private signing proxies");
+      return (proxy ??= createDbxv2Proxy({
+        upstream: { baseUrl: status.config.baseUrl, token: status.config.token },
+        env,
+      }));
+    },
+    stop: () => {
+      proxy?.stop();
+      proxy = null;
+    },
+  };
+  current = { runtime, key };
+  return runtime;
+}
+
+/** Stops the proxy and forgets the cached runtime (tests, shutdown). */
+export function resetDbxv2Runtime(): void {
+  current?.runtime.stop();
+  current = null;
+}
+
+export interface Dbxv2Resource {
+  readonly ref: Dbxv2Ref;
+  readonly kind: Dbxv2ResourceKind;
+  /** Short-lived signed loopback URL, safe for `<img>`, `<audio>`, `<video>` or a native loader. */
+  url(): string;
+  blob(signal?: AbortSignal): Promise<Blob>;
+  arrayBuffer(signal?: AbortSignal): Promise<ArrayBuffer>;
+  /** `model.json` only. */
+  model(signal?: AbortSignal): Promise<Dbxv2ModelJson>;
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+/** Handle on one resource; nothing is fetched until a method is called. */
+export function resource(
+  input: Dbxv2RefInput,
+  kind: Dbxv2ResourceKind,
+  params: Dbxv2ResourceParams = {},
+): Dbxv2Resource {
+  const ref = parseRef(input);
+  const load = async (
+    signal?: AbortSignal,
+  ): Promise<Dbxv2Binary | { bytes: Uint8Array; contentType: string }> => {
+    const { client } = getDbxv2Runtime();
+    switch (kind) {
+      case "raw": {
+        const whole = await client.download(ref, { signal });
+        return { bytes: whole.bytes, contentType: "application/octet-stream" };
+      }
+      case "png":
+        return client.png(ref, { index: params.index, signal });
+      case "wav":
+        return client.wav(ref, { cue: params.cue, signal });
+      case "video":
+        return client.video(ref, { signal });
+      case "mp4":
+        return client.mp4(ref, { signal });
+      case "model.json":
+        return {
+          bytes: new TextEncoder().encode(
+            JSON.stringify(await client.modelJson(ref, { ...params, signal })),
+          ),
+          contentType: "application/json",
+        };
+      case "model.glb":
+        return client.modelGlb(ref, { ...params, signal });
+    }
+  };
+  return {
+    ref,
+    kind,
+    url: () => getDbxv2Runtime().proxy().sign(kind, ref, params),
+    async blob(signal) {
+      const res = await load(signal);
+      return new Blob([toArrayBuffer(res.bytes)], { type: res.contentType });
+    },
+    async arrayBuffer(signal) {
+      return toArrayBuffer((await load(signal)).bytes);
+    },
+    model: (signal) => getDbxv2Runtime().client.modelJson(ref, { ...params, signal }),
+  };
+}

package/src/schemas.ts

@@ -0,0 +1,60 @@
+/** zod v4 schemas of every JSON response of the private server. */
+import { z } from "zod";
+
+export const Dbxv2HealthSchema = z.object({ ok: z.literal(true) });
+export type Dbxv2Health = z.infer<typeof Dbxv2HealthSchema>;
+
+export const Dbxv2CpkInfoSchema = z.object({
+  name: z.string().regex(/^[A-Za-z0-9_]+$/),
+  size: z.number().int().nonnegative(),
+  mtime: z.string(),
+});
+export type Dbxv2CpkInfo = z.infer<typeof Dbxv2CpkInfoSchema>;
+export const Dbxv2CpkListSchema = z.array(Dbxv2CpkInfoSchema);
+
+export const Dbxv2IndexEntrySchema = z.object({
+  cpk: z.string(),
+  path: z.string(),
+  offset: z.number().int().nonnegative(),
+  size: z.number().int().nonnegative(),
+  extract_size: z.number().int().nonnegative(),
+  compressed: z.boolean(),
+});
+export type Dbxv2IndexEntry = z.infer<typeof Dbxv2IndexEntrySchema>;
+
+export const Dbxv2FindResponseSchema = z.object({
+  total: z.number().int().nonnegative(),
+  offset: z.number().int().nonnegative(),
+  limit: z.number().int().positive(),
+  entries: z.array(Dbxv2IndexEntrySchema),
+});
+export type Dbxv2FindResponse = z.infer<typeof Dbxv2FindResponseSchema>;
+
+export const Dbxv2ErrorBodySchema = z.object({ error: z.string() });
+
+const Vec3 = z.tuple([z.number(), z.number(), z.number()]);
+const Vec2 = z.tuple([z.number(), z.number()]);
+
+/** Geometry and texture metadata of an assembled EMD (no pixels; the skeleton stays opaque). */
+export const Dbxv2ModelPrimitiveSchema = z.looseObject({
+  name: z.string().default(""),
+  materialName: z.string().default(""),
+  positions: z.array(Vec3).default([]),
+  normals: z.array(Vec3).default([]),
+  uv: z.array(Vec2).default([]),
+  indices: z.array(z.number().int().nonnegative()).default([]),
+  textureIndex: z.number().int().nonnegative().nullish(),
+});
+export type Dbxv2ModelPrimitive = z.infer<typeof Dbxv2ModelPrimitiveSchema>;
+
+export const Dbxv2ModelJsonSchema = z.looseObject({
+  name: z.string().default(""),
+  primitives: z.array(Dbxv2ModelPrimitiveSchema).default([]),
+  textures: z
+    .array(
+      z.looseObject({ width: z.number().int().positive(), height: z.number().int().positive() }),
+    )
+    .default([]),
+  skeleton: z.unknown().optional(),
+});
+export type Dbxv2ModelJson = z.infer<typeof Dbxv2ModelJsonSchema>;

package/src/texture.ts

@@ -0,0 +1,83 @@
+/**
+ * Typed metadata of a texture served by `/png`. The server returns the decoded pixels as a
+ * lossless PNG at the native EMB dimensions; this module only reads the 33-byte PNG header (no
+ * pixel is decoded or resampled here), hashes the bytes, and refuses formats the server does not
+ * decode (GNF / PS4) instead of approximating them.
+ */
+import { Dbxv2Error, Dbxv2SchemaError } from "./errors";
+
+export type Dbxv2ColorSpace = "srgb" | "linear";
+export type Dbxv2AlphaMode = "straight" | "premultiplied";
+
+/** Declared, not measured: the PNG carries no such flag. Override per call when a source differs. */
+export interface Dbxv2TextureDeclaration {
+  readonly colorSpace?: Dbxv2ColorSpace;
+  readonly alpha?: Dbxv2AlphaMode;
+}
+
+export interface Dbxv2TextureInfo {
+  readonly format: "png";
+  /** Native dimensions, read from the PNG header (equal to the EMB entry dimensions). */
+  readonly width: number;
+  readonly height: number;
+  readonly bitDepth: number;
+  /** PNG colour type (6 = RGBA, 2 = RGB, ...). */
+  readonly pngColorType: number;
+  readonly colorSpace: Dbxv2ColorSpace;
+  readonly alpha: Dbxv2AlphaMode;
+  /** Lowercase hex SHA-256 of the exact PNG bytes. */
+  readonly sha256: string;
+  readonly byteLength: number;
+}
+
+export class Dbxv2UnsupportedFormatError extends Dbxv2Error {
+  constructor(message: string) {
+    super("schema", message);
+  }
+}
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+export function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  const copy = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  return toHex(new Uint8Array(await crypto.subtle.digest("SHA-256", copy as ArrayBuffer)));
+}
+
+/** True when the bytes start with the GNF (PlayStation 4) texture magic. */
+export function isGnf(bytes: Uint8Array): boolean {
+  return bytes.length >= 4 && bytes[0] === 0x47 && bytes[1] === 0x4e && bytes[2] === 0x46;
+}
+
+/** Reads the IHDR of a PNG; throws when the bytes are not a PNG. GNF is reported explicitly. */
+export async function describeTexture(
+  bytes: Uint8Array,
+  declaration: Dbxv2TextureDeclaration = {},
+): Promise<Dbxv2TextureInfo> {
+  if (isGnf(bytes))
+    throw new Dbxv2UnsupportedFormatError(
+      "GNF (PS4) textures are not decoded: refusing to approximate them",
+    );
+  if (bytes.length < 33 || PNG_SIGNATURE.some((b, i) => bytes[i] !== b))
+    throw new Dbxv2SchemaError("texture is not a PNG");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(12) !== 0x49484452)
+    throw new Dbxv2SchemaError("PNG header chunk (IHDR) missing");
+  const width = view.getUint32(16);
+  const height = view.getUint32(20);
+  if (width === 0 || height === 0) throw new Dbxv2SchemaError("PNG has an empty dimension");
+  return {
+    format: "png",
+    width,
+    height,
+    bitDepth: bytes[24]!,
+    pngColorType: bytes[25]!,
+    colorSpace: declaration.colorSpace ?? "srgb",
+    alpha: declaration.alpha ?? "straight",
+    sha256: await sha256Hex(bytes),
+    byteLength: bytes.byteLength,
+  };
+}