@roster-lock/match-agent 0.1.0

package/src/handle-room/version-0/piece-download/downloadPieceAssets/example.ts

@@ -0,0 +1,116 @@
+import { MatchLockPublishPiece } from "@match-lock/shared";
+import { downloadPieceAssets } from "./index";
+
+/**
+ * Example usage of the new asset-based download system
+ */
+export async function exampleDownload() {
+  // Example piece with individual assets
+  const examplePiece: MatchLockPublishPiece = {
+    name: "example-character",
+    author: "game-dev",
+    published: "2024-01-01T00:00:00Z",
+    sha256: "abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234",
+    signature: "example-signature",
+    signatureVerificationUrl: "https://example.com/verify",
+    preview: {
+      image: "https://example.com/preview.jpg",
+      url: "https://example.com/preview"
+    },
+    sources: [
+      {
+        type: "http",
+        url: "https://example.com/assets/"
+      }
+    ],
+    pieceDefinition: "character",
+    version: {
+      logic: "logic-sha256-hash-here",
+      media: "media-sha256-hash-here"
+    },
+    assets: {
+      "character.json": {
+        assetType: "json",
+        sha256: "file1-sha256-hash-here",
+        sizeBytes: 1024
+      },
+      "sprites/idle.png": {
+        assetType: "png", 
+        sha256: "file2-sha256-hash-here",
+        sizeBytes: 2048
+      },
+      "sounds/jump.wav": {
+        assetType: "wav",
+        sha256: "file3-sha256-hash-here", 
+        sizeBytes: 4096
+      }
+    }
+  };
+
+  const targetDirectory = "./downloaded-pieces";
+  
+  try {
+    const pieceFolder = await downloadPieceAssets(
+      examplePiece,
+      targetDirectory,
+      (progress) => {
+        console.log(`Download progress for ${progress.pieceId}:`);
+        console.log(`  Completed: ${progress.completedAssets}/${progress.totalAssets}`);
+        if (progress.currentAsset) {
+          console.log(`  Current: ${progress.currentAsset.filePath} (${Math.round(progress.currentAsset.progress * 100)}%)`);
+        }
+      }
+    );
+    
+    console.log(`Successfully downloaded piece to: ${pieceFolder}`);
+    
+    // The downloaded structure will be:
+    // ./downloaded-pieces/game-dev/example-character-logic-sh/
+    // ├── character.json
+    // ├── sprites/
+    // │   └── idle.png  
+    // ├── sounds/
+    // │   └── jump.wav
+    // └── piece.matchlock.json (metadata)
+    
+    return pieceFolder;
+    
+  } catch (error) {
+    console.error("Download failed:", error);
+    throw error;
+  }
+}
+
+/**
+ * Example of downloading a single asset
+ */
+export async function exampleSingleAssetDownload() {
+  const { downloadSingleAsset } = await import("./downloadSingleAsset");
+  
+  const examplePiece: MatchLockPublishPiece = {
+    // ... same as above
+  } as any;
+  
+  try {
+    const result = await downloadSingleAsset({
+      piece: examplePiece,
+      filePath: "character.json",
+      asset: {
+        assetType: "json",
+        sha256: "file1-sha256-hash-here",
+        sizeBytes: 1024
+      },
+      targetDirectory: "./single-asset-test",
+      onProgress: (progress) => {
+        console.log(`Downloading ${progress.filePath}: ${Math.round(progress.progress * 100)}%`);
+      }
+    });
+    
+    console.log(`Downloaded ${result.filePath} to ${result.localPath}`);
+    return result;
+    
+  } catch (error) {
+    console.error("Single asset download failed:", error);
+    throw error;
+  }
+}

package/src/handle-room/version-0/piece-download/downloadPieceAssets/index.ts

@@ -0,0 +1,144 @@
+import { join as pathJoin } from "node:path";
+import { mkdir as fsMkdir, writeFile as fsWriteFile } from "node:fs/promises";
+
+import { MatchLockPublishPiece } from "@match-lock/shared";
+import { downloadSingleAsset } from "./downloadSingleAsset";
+import { validateAssetFile } from "./validateAsset";
+import { 
+  ProgressListener, 
+  PieceDownloadProgress, 
+  AssetDownloadResult 
+} from "./types";
+
+export async function downloadPieceAssets(
+  piece: MatchLockPublishPiece,
+  targetDirectory: string,
+  onProgress?: ProgressListener
+): Promise<string> {
+  // Create piece-specific directory using author/name-logicSha pattern
+  const logicShaShort = piece.version.logic.substring(0, 8);
+  const pieceFolder = pathJoin(targetDirectory, piece.author, `${piece.name}-${logicShaShort}`);
+  
+  // Ensure piece directory exists
+  await fsMkdir(pieceFolder, { recursive: true });
+  
+  // Check if piece is already downloaded and up to date
+  if (await isPieceUpToDate(piece, pieceFolder)) {
+    return pieceFolder;
+  }
+  
+  const assetEntries = Object.entries(piece.assets);
+  const totalAssets = assetEntries.length;
+  let completedAssets = 0;
+  const downloadResults: AssetDownloadResult[] = [];
+  
+  // Download each asset
+  for (const [filePath, asset] of assetEntries) {
+    const targetFilePath = pathJoin(pieceFolder, filePath);
+    
+    // Check if this specific asset is already downloaded and valid
+    if (await validateAssetFile(targetFilePath, asset)) {
+      completedAssets++;
+      downloadResults.push({
+        filePath,
+        localPath: targetFilePath,
+        asset
+      });
+      
+      // Report progress
+      if (onProgress) {
+        onProgress({
+          pieceId: piece.name,
+          completedAssets,
+          totalAssets
+        });
+      }
+      continue;
+    }
+    
+    // Download the asset
+    try {
+      const result = await downloadSingleAsset({
+        piece,
+        filePath,
+        asset,
+        targetDirectory: pieceFolder,
+        onProgress: (assetProgress) => {
+          if (onProgress) {
+            onProgress({
+              pieceId: piece.name,
+              completedAssets,
+              totalAssets,
+              currentAsset: assetProgress
+            });
+          }
+        }
+      });
+      
+      downloadResults.push(result);
+      completedAssets++;
+      
+      // Report completion of this asset
+      if (onProgress) {
+        onProgress({
+          pieceId: piece.name,
+          completedAssets,
+          totalAssets
+        });
+      }
+      
+    } catch (error) {
+      throw new Error(`Failed to download piece ${piece.name}: ${error}`);
+    }
+  }
+  
+  // Create piece metadata file
+  await createPieceMetadata(piece, pieceFolder, downloadResults);
+  
+  return pieceFolder;
+}
+
+async function isPieceUpToDate(
+  piece: MatchLockPublishPiece,
+  pieceFolder: string
+): Promise<boolean> {
+  try {
+    // Check if all assets exist and are valid
+    for (const [filePath, asset] of Object.entries(piece.assets)) {
+      const targetFilePath = pathJoin(pieceFolder, filePath);
+      if (!(await validateAssetFile(targetFilePath, asset))) {
+        return false;
+      }
+    }
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+async function createPieceMetadata(
+  piece: MatchLockPublishPiece,
+  pieceFolder: string,
+  downloadResults: AssetDownloadResult[]
+): Promise<void> {
+  const metadata = {
+    pieceId: piece.name,
+    author: piece.author,
+    version: piece.version,
+    downloadedAt: new Date().toISOString(),
+    assets: downloadResults.map(result => ({
+      filePath: result.filePath,
+      localPath: result.localPath,
+      sha256: result.asset.sha256,
+      sizeBytes: result.asset.sizeBytes,
+      assetType: result.asset.assetType
+    }))
+  };
+  
+  const metadataPath = pathJoin(pieceFolder, "piece.matchlock.json");
+  await fsWriteFile(metadataPath, JSON.stringify(metadata, null, 2), "utf8");
+}
+
+export * from "./types";
+export { downloadSingleAsset } from "./downloadSingleAsset";
+export { validateAssetFile } from "./validateAsset";

package/src/handle-room/version-0/piece-download/downloadPieceAssets/types.ts

@@ -0,0 +1,32 @@
+import { MatchLockPublishPiece, MatchLockAsset } from "@match-lock/shared";
+
+export type AssetDownloadProgress = {
+  pieceId: string;
+  filePath: string;
+  bytesDownloaded: number;
+  totalBytes: number;
+  progress: number; // 0-1
+};
+
+export type AssetDownloadResult = {
+  filePath: string;
+  localPath: string;
+  asset: MatchLockAsset;
+};
+
+export type PieceDownloadProgress = {
+  pieceId: string;
+  completedAssets: number;
+  totalAssets: number;
+  currentAsset?: AssetDownloadProgress;
+};
+
+export type ProgressListener = (progress: PieceDownloadProgress) => void;
+
+export type AssetDownloadOptions = {
+  piece: MatchLockPublishPiece;
+  filePath: string;
+  asset: MatchLockAsset;
+  targetDirectory: string;
+  onProgress?: (progress: AssetDownloadProgress) => void;
+};

package/src/handle-room/version-0/piece-download/downloadPieceAssets/validateAssetFile.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { stat as fsStat, readFile as fsReadFile } from "node:fs/promises";
+import { MatchLockAsset } from "@match-lock/shared";
+
+
+export async function validateAssetFile(
+  filePath: string,
+  expectedAsset: MatchLockAsset
+): Promise<boolean> {
+  try {
+    const stats = await fsStat(filePath);
+    
+    // Check file size
+    if (stats.size !== expectedAsset.sizeBytes) {
+      return false;
+    }
+    
+    // Check SHA256 hash
+    const fileBuffer = await fsReadFile(filePath);
+    const hash = createHash("sha256").update(fileBuffer).digest("hex");
+    
+    return hash === expectedAsset.sha256;
+  } catch (error) {
+    return false;
+  }
+}
+
+export async function calculateFileHash(filePath: string): Promise<string> {
+  const fileBuffer = await fsReadFile(filePath);
+  return createHash("sha256").update(fileBuffer).digest("hex");
+}
+
+export async function getFileSize(filePath: string): Promise<number> {
+  const stats = await fsStat(filePath);
+  return stats.size;
+}
+
+export function validateAssetIntegrity(
+  actualSize: number,
+  actualHash: string,
+  expectedAsset: MatchLockAsset
+): void {
+  if (actualSize !== expectedAsset.sizeBytes) {
+    throw new Error(
+      `Asset size mismatch: expected ${expectedAsset.sizeBytes} bytes, got ${actualSize} bytes`
+    );
+  }
+  
+  if (actualHash !== expectedAsset.sha256) {
+    throw new Error(
+      `Asset hash mismatch: expected ${expectedAsset.sha256}, got ${actualHash}`
+    );
+  }
+}

package/src/handle-room/version-0/piece-download/index.ts

@@ -0,0 +1,5 @@
+// Export the new asset-based download system
+export * from "./downloadPieceAssets";
+
+// Export the legacy bundle-based download system for compatibility
+export * from "./availableGamePiece";

package/src/handle-room/version-0/piece-selection/constants.ts

@@ -0,0 +1,39 @@
+import { JSON_Unknown } from "@match-lock/shared";
+
+export enum MATCHLOCK_SELECTION_STATE {
+  failure = "failure",
+
+  hello = "hello",
+  restriction = "restriction",
+  selectionEncrypt = "selection-encrypt",
+  selectionDecrypt = "selection-decrypt",
+  selectionFinal = "selection-final",
+  goodbye = "goodbye",
+}
+
+export enum MATCHLOCK_DOWNLOAD_STATE {
+  failure = "failure",
+
+  hello = "hello",
+  selectionFinal = "selection-final",
+  downloadStart = "download-start",
+  downloadProgress = "download-progress",
+  downloadValidation = "download-validation",
+  downloadFinished = "download-finished",
+
+  downloadFailure = "download-failure",
+  downloadAllComplete = "download-all-complete",
+  goodbye = "goodbye",
+}
+
+export class ExternalUserError extends Error {
+  constructor(public userId: string, public rawError: JSON_Unknown){
+    super("External User Error");
+  }
+}
+
+export class UserMessegeError extends Error {
+  constructor(public userId: string, public message: string){
+    super(message);
+  }
+}

package/src/handle-room/version-0/piece-selection/handleRoomSelections.ts

@@ -0,0 +1,202 @@
+import { JSON_Unknown, RosterLockV1Config, UserInput } from "@match-lock/shared";
+import { MATCHLOCK_SELECTION_STATE, UserMessegeError } from "./constants";
+import {
+  encryptJSON, decryptJSON,
+  CastEncryptedMessage,
+} from "./steps/encrypton";
+import {
+  validatePlayerSelection, createRandomSeed,
+  PlayerSelectionWithSeed
+} from "./steps/player-selection";
+import {
+  finalizeSelection,
+  FinalSelection,
+  CastFinalSelection
+} from "./steps/final-selection";
+import { Room } from "../../../types/room";
+import { deepEqual } from "node:assert";
+
+const STATE_ORDER = [
+  MATCHLOCK_SELECTION_STATE.hello,
+  MATCHLOCK_SELECTION_STATE.restriction,
+  MATCHLOCK_SELECTION_STATE.selectionEncrypt,
+  MATCHLOCK_SELECTION_STATE.selectionDecrypt,
+  MATCHLOCK_SELECTION_STATE.selectionFinal,
+  MATCHLOCK_SELECTION_STATE.goodbye,
+];
+
+export async function handleRoomSelections(
+  room: Room,
+  abortSignal: AbortSignal,
+  restriction: RosterLockV1Config,
+  selection: UserInput["userSelection"],
+){
+
+  const rngSeed = createRandomSeed();
+  const [ownEncrypted] = await Promise.all([
+    // Prepare own Selections
+    encryptJSON({ selection, rngSeed }),
+    // Validate our own selection
+    validatePlayerSelection(restriction, { selection, rngSeed })
+  ])
+
+  if(abortSignal.aborted){
+    return Promise.reject(new Error("Aborted"));
+  }
+
+  const roomState = new RoomState(
+    room, restriction, ownEncrypted
+  );
+
+  const { promise, resolve, reject } = Promise.withResolvers<FinalSelection>();
+
+  // Send our "hello" after we start listening
+  Promise.resolve().then(async ()=>{
+    room.broadcast(MATCHLOCK_SELECTION_STATE.hello, "hello");
+  });
+  const stopListeningToRoom = room.listen(async (userId, event, data)=>{
+    try {
+      if(!(event in roomState.stateHandlers )){
+        return;
+      }
+      // ensure the message wasn't sent twice and event is in order
+      const count = roomState.validateMessageState(userId, event as MATCHLOCK_SELECTION_STATE);
+      const { message, finished } = roomState.stateHandlers[event];
+      // If there is a message handler, run it
+      await message?.(userId, data);
+      // If we haven't heard from everyone, exit
+      if(count < room.numberOfUsers) return;
+      // Update the room step
+      roomState.updateStep();
+      // Run the finished handler which includes broadcasting the next step
+      await finished();
+
+      // If we're in the goodbye state, we're done
+      if(event !== MATCHLOCK_SELECTION_STATE.goodbye) return;
+      if(!roomState.agreedSelection) throw new Error("Missing Agreed FInal Selection");
+      resolve(roomState.agreedSelection!);
+    }catch(e){
+      reject(e);
+    }
+  });
+
+  promise.finally(()=>{
+    stopListeningToRoom();
+  });
+
+  abortSignal.addEventListener("abort", ()=>(
+    reject(new Error("Aborted"))
+  ));
+
+  return promise;
+
+}
+
+class RoomState {
+  private state: MATCHLOCK_SELECTION_STATE = MATCHLOCK_SELECTION_STATE.hello;
+  private recievedMessages = new Map<MATCHLOCK_SELECTION_STATE, Set<string>>();
+
+  encryptedData = new Map<string, { iv: string, ciphertext: string }>();
+  userSelections = new Map<string, PlayerSelectionWithSeed>();
+  agreedSelection: FinalSelection | null = null;
+
+  constructor(
+    public room: Room,
+    public restriction: RosterLockV1Config,
+    public ownEncrypted: Awaited<ReturnType<typeof encryptJSON>>,
+  ){}
+
+  validateMessageState(
+    userId: string,
+    messageState: MATCHLOCK_SELECTION_STATE
+  ){
+    if(this.state !== messageState){
+      const currentIndex = STATE_ORDER.indexOf(this.state);
+      const messageIndex = STATE_ORDER.indexOf(messageState);
+      if(messageIndex === currentIndex + 1){
+        console.warn(`User Sent ${messageState} Early`, userId);
+        console.warn("We'll still process it as other messages may just be late");
+      } else {
+        throw new UserMessegeError(userId, `Expected ${this.state} message`);
+      }
+    }
+    if(!this.recievedMessages.has(messageState)){
+      this.recievedMessages.set(messageState, new Set());
+    }
+    if(this.recievedMessages.get(messageState)!.has(userId)){
+      throw new UserMessegeError(userId, "User Sent Message Twice");
+    }
+    this.recievedMessages.get(messageState)!.add(userId);
+    return this.recievedMessages.get(messageState)!.size;
+  }
+
+  updateStep(){
+    const currentIndex = STATE_ORDER.indexOf(this.state);
+    const nextIndex = currentIndex + 1;
+    if (nextIndex >= STATE_ORDER.length) {
+      throw new Error("No next phase after " + this.state);
+    }
+    this.state = STATE_ORDER[nextIndex];
+  }
+
+  stateHandlers: Record<string, {
+    message?(userId: string, data: JSON_Unknown):any,
+    finished():any
+  }> = {
+    [MATCHLOCK_SELECTION_STATE.hello]: {
+      finished: ()=>(
+        this.room.broadcast(MATCHLOCK_SELECTION_STATE.restriction, this.restriction)
+      ),
+    },
+    [MATCHLOCK_SELECTION_STATE.restriction]: {
+      message: (userId, data)=>{
+        deepEqual(data, this.restriction, "Restriction Mismatch")
+      },
+      finished: ()=>(
+        this.room.broadcast(MATCHLOCK_SELECTION_STATE.selectionEncrypt, this.ownEncrypted.encrypted)
+      )
+    },
+    [MATCHLOCK_SELECTION_STATE.selectionEncrypt]: {
+      message: (userId, data)=>{
+        const casted = CastEncryptedMessage.check(data);
+        this.encryptedData.set(userId, casted);
+      },
+      finished: ()=>(
+        this.room.broadcast(MATCHLOCK_SELECTION_STATE.selectionDecrypt, this.ownEncrypted.key)
+      )
+    },
+    [MATCHLOCK_SELECTION_STATE.selectionDecrypt]: {
+      message: async (userId, data)=>{
+        if(typeof data !== "string") throw new Error("Invalid Decryption Key");
+        const encrypted = this.encryptedData.get(userId);
+        if(!encrypted) throw new Error("Missing Encrypted Data");
+        const decrypted = await decryptJSON(data, encrypted);
+        const casted = await validatePlayerSelection(this.restriction, decrypted);
+        this.userSelections.set(userId, casted);
+      },
+      finished: async ()=>{
+        const ownFinalSelection = await finalizeSelection(
+          this.restriction, Object.fromEntries(this.userSelections)
+        );
+        this.room.broadcast(MATCHLOCK_SELECTION_STATE.selectionFinal, ownFinalSelection)
+      }
+    },
+    [MATCHLOCK_SELECTION_STATE.selectionFinal]: {
+      message: (userId, data)=>{
+        const casted: FinalSelection = CastFinalSelection.check(data);
+        if(this.agreedSelection === null){
+          this.agreedSelection = casted;
+        } else {
+          deepEqual(this.agreedSelection, casted, "Final Selection Mismatch");
+        }
+      },
+      finished: ()=>(
+        this.room.broadcast(MATCHLOCK_SELECTION_STATE.goodbye, "goodbye")
+      )
+    },
+    [MATCHLOCK_SELECTION_STATE.goodbye]: {
+      finished: ()=>{},
+    }
+  }
+}
+

package/src/handle-room/version-0/piece-selection/index.ts

@@ -0,0 +1,31 @@
+import { RosterLockV1Config, UserInput } from "@match-lock/shared";
+
+import { Room } from "../../../types/room";
+import { waitForExternalError, waitForStoppedRoomHeartbeat } from "./roomErrors";
+import { handleRoomSelections } from "./handleRoomSelections";
+import { ExternalUserError, MATCHLOCK_SELECTION_STATE } from "./constants";
+
+export async function handleSelection(
+  room: Room,
+  lockConfig: RosterLockV1Config,
+  selection: UserInput["userSelection"]
+){
+  const abortController = new AbortController();
+  try {
+    await Promise.race([
+      handleRoomSelections(room, abortController.signal, lockConfig, selection),
+      waitForExternalError(room, abortController.signal),
+      waitForStoppedRoomHeartbeat(room, 10_000, abortController.signal),
+    ])
+  }catch(e){
+    console.log("Match To Start Failed", e);
+    if(!(e instanceof ExternalUserError) && e instanceof Error){
+      room.broadcast(MATCHLOCK_SELECTION_STATE.failure, e.message);
+    }
+    room.disconnect();
+    throw e;
+  }finally{
+    abortController.abort();
+  }
+}
+

package/src/handle-room/version-0/piece-selection/roomErrors.ts

@@ -0,0 +1,25 @@
+
+import { Room } from "../../../types/room";
+import { ExternalUserError, MATCHLOCK_SELECTION_STATE } from "./constants";
+
+import { waitForEvent, waitForEventTimeout } from "@match-lock/shared";
+export async function waitForExternalError(room: Room, abortSignal: AbortSignal){
+  const [userId, event, message] = await waitForEvent(
+    room.listen.filter((userId, event, message)=>{
+      return event === MATCHLOCK_SELECTION_STATE.failure;
+    }),
+    abortSignal
+  )
+  throw new ExternalUserError(userId, message);
+}
+
+export async function waitForStoppedRoomHeartbeat(room: Room, timeout: number, abortSignal: AbortSignal){
+  await waitForEventTimeout(
+    room.listen.filter((userId, event, message)=>{
+      return event !== MATCHLOCK_SELECTION_STATE.failure;
+    }),
+    timeout,
+    abortSignal
+  );
+  throw new Error("Heartbeat Timeout");
+}