@roster-lock/types 1.0.0

package/src/v1/lock/index.ts

@@ -0,0 +1,24 @@
+import { RosterLockIdentity } from "../shared";
+import { RosterLockEngineConfig } from "./engine";
+import { RosterLockPiece } from "./roster";
+import { RosterLockSelectionConfig } from "./selection";
+import { RosterLockPieceMeta } from "./piece-meta";
+
+export * from "./engine";
+export * from "./roster";
+export * from "./selection";
+export * from "./piece-meta";
+
+
+export type RosterLockV1Config = {
+  configIdentity: RosterLockIdentity<"lock", 1>,
+
+  author: string,
+  title: string,
+  version: string,
+  engine: RosterLockEngineConfig,
+  rosters: Record<string, Array<RosterLockPiece>>,
+  selection: RosterLockSelectionConfig,
+  pieceMeta: RosterLockPieceMeta,
+}
+

package/src/v1/lock/piece-meta.ts

@@ -0,0 +1,9 @@
+import { PieceType } from "../shared";
+import { JSONShallowObject, SelectionPieceMeta } from "./selection/meta";
+
+/*
+Custom fields (tier, difficulty, tags, etc) that selection configs can validate against
+and merge algorithms/scripts can read via PIECE_META.get(). Kept out of the selection
+config itself so the same selection config can be reused across different rosters.
+*/
+export type RosterLockPieceMeta = Record<PieceType, SelectionPieceMeta<JSONShallowObject>>;

package/src/v1/lock/roster.ts

@@ -0,0 +1,27 @@
+
+import { PieceId, Sha256 } from "../shared";
+
+type URLType = string;
+type DownloadableSource = string;
+
+export type RosterLockPiece = {
+  id: PieceId,
+  version: {
+    logic: Sha256,
+    media: Sha256,
+    docs: Sha256,
+  },
+  humanInfo: {
+    name: string,
+    author: string,
+    url: URLType,
+    image?: URLType,
+  }
+  downloadSources: Array<DownloadableSource>,
+  pathVariables: Record<string, string>,
+  requiredPieces: Record<string, {
+    expected: Array<PieceId>,
+    selectable: boolean,
+  }>,
+};
+

package/src/v1/lock/selection/index.ts

@@ -0,0 +1,34 @@
+
+import { PieceType } from "../../shared";
+import { UntrustedScriptRef } from "./script";
+import { SelectionGameControlledConfig } from "./selection-types/game-controlled";
+import { SelectionNormalConfig, UserSelectionValidation } from "./selection-types/normal";
+import { SelectionPreselectedConfig } from "./selection-types/preselected";
+import { SelectionUnselectableConfig } from "./selection-types/unselectable";
+
+export * from "./meta";
+
+export {
+  SelectionPreselectedConfig,
+  SelectionGameControlledConfig,
+  SelectionNormalConfig,
+  SelectionUnselectableConfig,
+  UserSelectionValidation,
+};
+
+export { UntrustedScriptRef };
+
+export type RosterLockSelectionConfig = {
+  piece: Record<PieceType, (
+    | SelectionGameControlledConfig
+    | SelectionNormalConfig
+    | SelectionPreselectedConfig
+    | SelectionUnselectableConfig
+  )>,
+
+  globalValidation: Array<UntrustedScriptRef>
+
+  scriptDictionary: Record<string, { content: string, }>
+};
+
+

package/src/v1/lock/selection/meta.ts

@@ -0,0 +1,17 @@
+import { PieceId } from "../../shared";
+
+export type JSONShallowObject = Record<string, (
+  | string | number | boolean
+  | Array<string> | Array<number> | Array<boolean>
+)>;
+
+type SimpleSchemaType = (
+  | "boolean" | "number" | "string"
+  | "boolean[]" | "number[]" | "string[]"
+)
+
+export type SelectionPieceMeta<Config extends JSONShallowObject> = {
+  schema: Record<string, SimpleSchemaType>,
+  defaultMeta: Config,
+  values: Record<PieceId, Partial<Config>>,
+}

package/src/v1/lock/selection/script.ts

@@ -0,0 +1,56 @@
+/*
+Global Variables accessible to the script
+
+// This is psuedo random number generator based on seeds from all players during the commit/reveal step
+// It returns a float between 0 and 1
+RANDOM()
+
+// This is a map of all the piece meta
+// Normally only includes the current piece type and any "on demand" piece types that are required by the current piece type
+// for globalValidation it includes all piece types after merging
+// This is a getter as it will merge default meta with a piece's custom meta
+PIECE_META.get(pieceType: string, pieceId: string): Meta
+
+// The pieces available to be selected
+// Normally only includes the current piece type and any "on demand" piece types that are required by the current piece type
+// for globalValidation it includes all piece types after merging
+PIECES_AVAILABLE: {
+  [pieceType: string]: Array<PieceId>
+}
+
+type SelectedPiece = {
+  // The id of the piece
+  id: pieceId,
+  // Whether the piece was selected or required by the piece config
+  selected: "selected" | "required",
+  // The "on demand" pieces that are required by this piece
+  // Includes both the selected and the pieces defined in the piece's config
+  required: Record<pieceType, Array<SelectedPiece>>,
+}
+
+
+// The pieces selected by the current player - only available during individual validation
+PLAYER_SELECTION: Array<SelectedPiece>
+
+
+// The pieces selected by each player - only available during merge algorithms
+EACH_PLAYER_SELECTION: {
+  [userId: string]: Array<SelectedPiece>
+}
+
+// The final merged selection - only available during globalValidation
+FINAL_SELECTION: {
+  // depending on the pieceType, it's either a list of pieces or a list of pieces per player
+  [pieceType: string]: Array<SelectedPiece> | Record<userId, Array<SelectedPiece>>
+}
+
+*/
+type RelativePath = string;
+export type UntrustedScriptRef = (
+  // I'm thinking a "published" config will be a tarball of all necessary files
+  // This allows users to write scripts in their preferred editor then add them as necessary
+  | {
+    src: RelativePath,
+    method?: string,
+  }
+);

package/src/v1/lock/selection/selection-types/game-controlled.ts

@@ -0,0 +1,9 @@
+
+
+// The game will handle the selection however it wants
+// The selection should be sent along side the match lock config when creating a room
+
+// Room will handle the selection as if it were a "preselected" config
+export type SelectionGameControlledConfig = {
+  type: "game-controlled",
+};

package/src/v1/lock/selection/selection-types/normal.ts

@@ -0,0 +1,32 @@
+import { UntrustedScriptRef } from "../script";
+import { PieceId, Count } from "../../../shared";
+
+export type UserSelectionValidation = {
+  count: Count,
+  unique: boolean,
+  banList: Array<PieceId>,
+  customValidation: Array<UntrustedScriptRef>
+};
+
+
+export type SelectionNormalConfig = {
+  type: "normal",
+
+  /*
+    The validation is used to validate the current user's and other player's choices
+    The validation does not validate the final choices after the merge algorithm is run
+  */
+  validation: UserSelectionValidation,
+
+  /*
+    A merge algorithm takes in each player's choices and returns a new set of choices
+    If the pieceType is "personal", the merge algorithm is expected to return a set of choices per player
+    If the pieceType is "shared", the merge algorithm is expected to return a single set of choices
+    - the mergeAlgorithm is mandatory for "shared" pieces
+    If the pieceType is "on demand", the merge algorithm is not allowed
+    
+    We validate the return type of the algorithm to ensure it matches the pieceType
+  */
+  mergeAlgorithm?: UntrustedScriptRef
+};
+

package/src/v1/lock/selection/selection-types/preselected.ts

@@ -0,0 +1,12 @@
+
+// Can select pieces as a part of the config
+// This is useful if players just want to play a specific stage without the chance of another being chosen
+// Final Destination Fox only
+
+import { SelectedPiece } from "../../../request/shared";
+
+// When selecting personal pieces, the array will be applied to all players
+export type SelectionPreselectedConfig = {
+  type: "preselected",
+  pieces: Array<SelectedPiece>
+};

package/src/v1/lock/selection/selection-types/unselectable.ts

@@ -0,0 +1,3 @@
+export type SelectionUnselectableConfig = {
+  type: "unselectable",
+};

package/src/v1/metadata.ts

@@ -0,0 +1,10 @@
+
+import { RosterLockPiece } from "./lock/roster";
+import { RosterLockIdentity } from "./shared";
+
+export type RosterLockV1PieceInfo = (
+  & {
+    configIdentity: RosterLockIdentity<"piece-info", 1>
+  }
+  & Pick<RosterLockPiece, "humanInfo" | "downloadSources" | "pathVariables">
+)

package/src/v1/relay/index.ts

@@ -0,0 +1,19 @@
+
+// Room Creation
+export type RoomConfig = {
+  matchmakerId: string;
+  coordinatorId: string;
+  roomId: string;
+  rosterConfigHash: string;
+  machines: RoomMachine[];
+}
+
+export type RoomMachine = {
+  machineId: string;
+  publicKey: string;
+  displayName: string;
+  // How many local players this machine is bringing to the room, declared to
+  // the matchmaker at queue time - match-agent validates each machine's
+  // submitted selections against this count.
+  playerCount: number;
+}

package/src/v1/request/index.ts

@@ -0,0 +1,4 @@
+
+export * from "./shared"
+export * from "./input"
+export * from "./output"

package/src/v1/request/input/agent-to-relay.ts

@@ -0,0 +1,6 @@
+import { UserSelection } from "../shared";
+
+export type UserInput = {
+  randomSeed: string,
+  userSelection: UserSelection
+};

package/src/v1/request/input/client-to-agent.ts

@@ -0,0 +1,19 @@
+import { RosterLockV1Config } from "../../lock";
+
+import { UserSelection } from "../shared";
+
+export type RosterLockV1SyncDLRequestClientToAgent = {
+  relay: {
+    url: string,
+    roomId: string,
+  },
+  machine: {
+    timestamp: number,
+    publicKey: string,
+    signature: string,
+  },
+  rosterConfig: RosterLockV1Config,
+  // Keyed by local player index on this machine (0-based) - a machine with
+  // multiple local players (e.g. 2 controllers) submits one entry per player.
+  playerSelections: Record<number, UserSelection>,
+};

package/src/v1/request/input/index.ts

@@ -0,0 +1,4 @@
+
+export * from "./user-to-client";
+export * from "./client-to-agent";
+export * from "./agent-to-relay";

package/src/v1/request/input/user-to-client.ts

@@ -0,0 +1,21 @@
+import { RosterLockV1Config } from "../../lock";
+
+import { UserSelection } from "../shared";
+
+export type RosterLockV1SyncDLRequestUserToClient = {
+  version: 1,
+  relay: {
+    url: string,
+    roomId: string,
+  },
+  machine: {
+    machineId: string;
+    keys: {
+      publicKey: string,
+      privateKey: string,
+    }
+  },
+  rosterConfig: RosterLockV1Config,
+  // Keyed by local player index on this machine (0-based).
+  playerSelections: Record<number, UserSelection>,
+};

package/src/v1/request/output/download-event.ts

@@ -0,0 +1,49 @@
+
+export enum ROSTERLOCK_DOWNLOAD_STATE {
+  downloadStart = "download-start",
+  downloadProgress = "download-progress",
+  downloadValidation = "download-validation",
+  downloadFinished = "download-finished",
+  downloadFailure = "download-failure",
+
+  downloadAllComplete = "download-all-complete",
+  downloadFullFailure = "download-full-fail",
+}
+
+export type RosterLockDownloadUpdate = (
+  | {
+    type: ROSTERLOCK_DOWNLOAD_STATE.downloadStart,
+    pieceType: string,
+    pieceVersions: { logic: string, media: string },
+  }
+  | {
+    type: ROSTERLOCK_DOWNLOAD_STATE.downloadProgress,
+    pieceType: string,
+    pieceVersions: { logic: string, media: string },
+    progress: number,
+  }
+  | {
+    type: ROSTERLOCK_DOWNLOAD_STATE.downloadValidation,
+    pieceType: string,
+    pieceVersions: { logic: string, media: string },
+  }
+  | {
+    type: ROSTERLOCK_DOWNLOAD_STATE.downloadFinished,
+    pieceType: string,
+    pieceVersions: { logic: string, media: string },
+  }
+  | {
+    type: ROSTERLOCK_DOWNLOAD_STATE.downloadFailure,
+    pieceType: string,
+    pieceVersions: { logic: string, media: string },
+    error: string,
+  }
+  | {
+    type: ROSTERLOCK_DOWNLOAD_STATE.downloadAllComplete,
+  }
+  | {
+    type: ROSTERLOCK_DOWNLOAD_STATE.downloadFullFailure,
+    error: string,
+  }
+)
+

package/src/v1/request/output/index.ts

@@ -0,0 +1,34 @@
+
+import { PlayerId, PieceType, PieceId } from "../../shared";
+import { SelectedPiece } from "../shared";
+
+export * from "./download-event";
+
+export type SharedSelection = {
+  type: "shared",
+  value: Array<SelectedPiece>,
+};
+export type PersonalSelection = {
+  type: "personal",
+  value: Record<PlayerId, Array<SelectedPiece>>,
+};
+
+export type FinalSelection = Record<PieceType, (
+  | SharedSelection
+  | PersonalSelection
+)>;
+
+export type DownloadResult = {
+  pieceType: PieceType,
+  pieceId: PieceId,
+  pieceVersions: { logic: string, media: string },
+  folder: string,
+}
+
+export type DownloadResultsMap = Record<PieceType, Record<PieceId, DownloadResult>>;
+
+export type RosterLockV1SyncDLResult = {
+  finalSelection: FinalSelection,
+  downloadResults: DownloadResultsMap,
+}
+

package/src/v1/request/shared.ts

@@ -0,0 +1,13 @@
+import { PieceId, PieceType } from "../shared";
+
+export type SelectedPiece = {
+  id: PieceId,
+  // selected: "selected" | "required",
+  required: Record<PieceType, {
+    mandatory: Array<SelectedPiece>,
+    selectable: Array<SelectedPiece>
+  }>
+};
+
+
+export type UserSelection = Record<PieceType, Array<SelectedPiece>>;

package/src/v1/runtime/download/Archive.ts

@@ -0,0 +1,13 @@
+
+
+export type ArchiveFile = {
+  path: string,
+  contents: AsyncIterable<Uint8Array>
+};
+
+export type ArchiveHandler = {
+  name: string;
+  extensions: Array<string>,
+  extractFiles: (input: AsyncIterable<Uint8Array>)=>AsyncIterable<ArchiveFile>;
+};
+

package/src/v1/runtime/download/Decompressor.ts

@@ -0,0 +1,6 @@
+
+export type Decompressor = {
+  name: string;
+  extensions: Array<string>,
+  decompress: (input: AsyncIterable<Uint8Array>) => AsyncIterable<Uint8Array>;
+};

package/src/v1/runtime/download/Protocol.ts

@@ -0,0 +1,15 @@
+
+import { ProcessHandlers } from "./types";
+
+export type ProtocolHandler = {
+  name: string,
+  validateURL: (url: string)=>boolean
+  download: (
+    url: string,
+    folderDestination: string,
+    processHandlers: ProcessHandlers
+  ) => Promise<{
+    finishPromise: Promise<any>,
+    metaData?: any
+  }>;
+};

package/src/v1/runtime/download/index.ts

@@ -0,0 +1,5 @@
+
+export * from "./types";
+export * from "./Archive";
+export * from "./Decompressor";
+export * from "./Protocol";

package/src/v1/runtime/download/types.ts

@@ -0,0 +1,18 @@
+import { Decompressor } from "./Decompressor";
+import { ArchiveHandler } from "./Archive";
+
+export type Processors = {
+  decompressors: Array<Decompressor>;
+  archiveHandler: ArchiveHandler;
+};
+
+export type ProcessHandlers = {
+  onProgress?: (progress: number, total?: number) => void;
+  abortSignal: AbortSignal;
+  getProcessors: (pathname: string) => Processors;
+};
+
+export type FileSignature = {
+  offset: number;
+  bytes: number[];
+};

package/src/v1/runtime/index.ts

@@ -0,0 +1,4 @@
+
+export * from "./download";
+export * from "./unstrusted-script";
+export * from "./piece-selection-sort";

package/src/v1/runtime/piece-selection-sort/index.ts

@@ -0,0 +1,34 @@
+
+import { RosterLockV1Config } from "../../lock";
+import { PieceType, PlayerId, LogicId } from "../../shared";
+import { UserSelection } from "../../request";
+
+export type SortPiecesArg = {
+  lockConfig: RosterLockV1Config,
+  pieceType: PieceType,
+  dataDir: string,
+};
+
+export type HandleFullSelectionArg = {
+  lockConfig: RosterLockV1Config,
+  // In case we only want to save local selections
+  localUsers: Array<PlayerId>,
+  // User Selections have all users
+  userSelections: Record<PlayerId, UserSelection>,
+  dataDir: string,
+};
+
+export type HandleGameCompleteArg = HandleFullSelectionArg & {
+  winners: Array<PlayerId>,
+};
+
+export type PieceSelectionSortPlugin = {
+  name: string,
+  publicInfo: {
+    title: string,
+    description: string,
+  },
+  sortPieces: (arg: SortPiecesArg) => Promise<Array<LogicId>>,
+  handleFullSelection: (arg: HandleFullSelectionArg) => Promise<void>,
+  handleGameComplete: (arg: HandleGameCompleteArg) => Promise<void>,
+};

package/src/v1/runtime/unstrusted-script/index.ts

@@ -0,0 +1,59 @@
+import { RosterLockV1Config, UntrustedScriptRef } from "../../lock";
+import { ScriptPurposeInput } from "./purpose-input";
+export * from "./purpose-input";
+
+export type ScriptStarter = {
+  config: RosterLockV1Config,
+  randomSeeds: string[],
+  purpose: ScriptPurposeInput,
+  entryScript: UntrustedScriptRef
+  debugLog?: Array<string>,
+};
+
+
+export type ScriptGlobals<ScriptModule> = {
+  randomFloat: ()=>number,
+  randomInt: (min: number, max: number)=>number,
+  shuffleIndexes: (length: number, startOffset?: number)=>Array<number>,
+  getPieceMeta: (pieceType: string, pieceId: string)=>any,
+  getAvailablePieces: (pieceType: string)=>Array<string>,
+  requireScript: (path: string, runCode: (newPath: string, content: string)=>Promise<ScriptModule>)=>Promise<ScriptModule>,
+  log: (...args: any)=>void
+};
+
+
+export type ScriptRunner<ScriptModule> = (
+  globals: ScriptGlobals<ScriptModule>,
+  input: ScriptPurposeInput,
+  script: string,
+  initialMethod: string
+)=>Promise<unknown>;
+
+export type UntrustedScript<ScriptModule> = {
+  name: string,
+  extensions: Array<string>,
+  directoryFile: Array<string>,
+  runScript: ScriptRunner<ScriptModule>,
+  exportConfig: (config: any)=>ScriptModule
+};
+
+export type UntrustedConfig = {
+  name: string,
+  extensions: Array<string>,
+  runConfig: (configString: string)=>Promise<unknown>
+};
+
+export type ScriptStackFrame = {
+  filename: string | null,
+  line: number | null,
+  name: string | null,
+};
+
+export type NormalizedScriptError = {
+  type: "UntrustedScriptError"
+  message: string,
+  filename: string | null,
+  line: number | null,
+  column: number | null,
+  stack: ScriptStackFrame[] | null,
+};

package/src/v1/runtime/unstrusted-script/purpose-input.ts

@@ -0,0 +1,34 @@
+
+import { PlayerId, PieceType } from "../../shared";
+import { SelectedPiece } from "../../request";
+
+export type PieceUserValidationInput = {
+  type: "piece-user-validation",
+  pieceType: string,
+  userId: string,
+  input: Array<SelectedPiece>,
+};
+
+export type PieceMergeInput = {
+  type: "piece-merge",
+  pieceType: string,
+  users: Array<PlayerId>,
+  input: Record<PlayerId, Array<SelectedPiece>>,
+};
+
+export type GlobalValidationInput = {
+  type: "global-validation",
+  pieceTypes: Array<string>,
+  users: Array<PlayerId>,
+  input: Record<PieceType, (
+    | Record<PlayerId, Array<SelectedPiece>>
+    | Array<SelectedPiece>
+  )> ,
+};
+
+
+export type ScriptPurposeInput = (
+  | PieceUserValidationInput
+  | PieceMergeInput
+  | GlobalValidationInput
+);

package/src/v1/shared.ts

@@ -0,0 +1,14 @@
+
+export type PlayerId = string;
+export type PieceType = string;
+export type PieceId = string;
+// RosterLockPiece["version"]["logic"] - the piece's real identity. A media/docs
+// update keeps the same LogicId; a logic update is a wholly new one.
+export type LogicId = string;
+export type Sha256 = string;
+
+export type RosterLockIdentity<P extends string, V extends number> = {
+  namespace: "roster-lock", purpose: P, version: V
+};
+
+export type Count = number | "*" | [number, number | "*"];

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "types": [],
+    "lib": ["es2022", "dom"],
+    "sourceMap": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "removeComments": true,
+    "noImplicitAny": true
+  },
+  "files": ["src/index.ts"],
+  "include": ["./typings", "./types", "**/*.test.ts"],
+  "exclude": ["node_modules", "**/*.spec.ts"]
+}