@effectstream/runtime 0.100.0

package/src/types.ts

@@ -0,0 +1,76 @@
+import type { Operation } from "effection";
+import type { SyncProtocolWithNetwork } from "@effectstream/config";
+import type { AppEvents, BaseStfInput, BaseStfOutput, Primitive } from "@effectstream/sm";
+import type { FastifyInstance } from "fastify";
+import type { Pool } from "pg";
+import type { SnapshotConfig } from "@effectstream/db";
+import type { SyncStateUpdateStream } from "@effectstream/coroutine";
+import type { GrammarDefinition } from "@effectstream/concise";
+// These are user type defined objects for launching the Effectstream Node.
+
+export type VERSION = `${number}.${number}.${number}`;
+
+/**
+ * Type for the game state transitions function.
+ * For each `prefix` it can return a list of state transitions and events.
+ */
+export type StartConfigGameStateTransitions = (
+  blockHeight: number,
+  input: BaseStfInput,
+) => SyncStateUpdateStream<void>;
+
+export type DBMigrations = {
+  versionDependency?: VERSION;
+  blockHeight?: number;
+  name: string;
+  sql: string;
+};
+
+/**
+ * Type for the API router function.
+ * It should return a valid Fastify instance.
+ */
+export type StartConfigApiRouter = (
+  server: FastifyInstance,
+  dbConn: Pool,
+) => Promise<void>;
+
+export type PrimitiveConstructor<T extends Primitive<any, any>> = new (config: any) => T;
+
+/**
+ * Main configuration object for the Effectstream Node.
+ *
+ * @param syncInfo - The Networks/Primitives Sync information.
+ * @param gameStateTransitions - (optional) Game State Transition Router.
+ * @param migrationRouter - (optional) SQL Migrations Router.
+ * @param apiRouter - (optional) API Router.
+ * @param snapshotConfig - (optional) Automated database snapshot configuration.
+ * @param dev - (optional) Development-only configuration.
+ * @param dev.resetPublicData - (optional) With this flag, the public schema tables data will be reset on sync process reset. This is useful for testing purposes.
+
+ */
+export type StartConfig = {
+  appName: string;
+  appVersion: VERSION;
+  syncInfo: SyncProtocolWithNetwork[];
+  gameStateTransitions?: StartConfigGameStateTransitions;
+  migrations?: DBMigrations[];
+  apiRouter?: StartConfigApiRouter;
+  grammar?: GrammarDefinition;
+  userDefinedPrimitives?: Record<string, PrimitiveConstructor<any>>;
+  /**
+   * Automated database snapshot configuration via `pg_dump`.
+   * An empty object `{}` enables snapshots with all defaults.
+   *
+   * Env overrides: `EFFECTSTREAM_SNAPSHOT_INTERVAL_SECONDS`, `EFFECTSTREAM_SNAPSHOT_PATH`,
+   * `EFFECTSTREAM_SNAPSHOT_LAST_DAY_HOURLY`, `EFFECTSTREAM_SNAPSHOT_LAST_3_DAYS_SIX_HOURLY`,
+   * `EFFECTSTREAM_SNAPSHOT_LAST_N_DAYS`.
+   * @see docs/home/1000-effectstream-engine/1003-database-snapshots.md
+   */
+  snapshotConfig?: SnapshotConfig;
+  /** Development-only options. Do not use in production. */
+  dev?: {
+    /** Reset public-schema tables on each sync reset. For local testing only. */
+    resetPublicData?: boolean;
+  };
+};

package/src/version-migrations.ts

@@ -0,0 +1,163 @@
+import type { Client } from "pg";
+import {
+  applyMigrations,
+  getMigrations,
+  EFFECTSTREAM_ENGINE_VERSION,
+  parseVersion,
+  type VersionInfo,
+} from "@effectstream/db/version";
+import type { Operation } from "effection";
+import { until } from "effection";
+import {
+  getMigrationsForBlockHeight,
+  insertPaimaEngineVersion,
+} from "@effectstream/db";
+import type { DBMigrations, VERSION } from "@effectstream/runtime";
+
+type SystemMigration = {
+  version: VERSION;
+  sql: string;
+};
+
+export function* applySystemMigrations(
+  appVersion: VERSION,
+  versionInfo: VersionInfo,
+  lastBlockHeight: number,
+  dbConn: Client,
+  migrationOrder: DBMigrations[] | undefined,
+): Operation<void> {
+  if (
+    versionInfo.engine_current_version === versionInfo.engine_previous_version
+  ) {
+    console.log("[MIGRATIONS] Nothing to apply.");
+    // Nothing to apply.
+    return;
+  }
+
+  const migrations = yield* getAllSystemMigrations(
+    versionInfo,
+    migrationOrder,
+    dbConn as any, // Client,
+  );
+
+  // Apply all missing System Migrations
+  for (const migration of migrations) {
+    yield* until(
+      applyMigrations(
+        dbConn,
+        lastBlockHeight,
+        migration.version,
+        migration.sql,
+        true,
+      ),
+    );
+  }
+
+  // Update Engine Version
+  const engineVersion = parseVersion(versionInfo.engine_current_version);
+  const appVersionParts = parseVersion(appVersion);
+  yield* until(
+    insertPaimaEngineVersion.run(
+      {
+        appVersionMajor: appVersionParts[0],
+        appVersionMinor: appVersionParts[1],
+        appVersionPatch: appVersionParts[2],
+        engineVersionMajor: engineVersion[0],
+        engineVersionMinor: engineVersion[1],
+        engineVersionPatch: engineVersion[2],
+        blockHeight: lastBlockHeight,
+      },
+      dbConn,
+    ),
+  );
+
+  return;
+}
+function* getAllSystemMigrations(
+  config: VersionInfo,
+  migrationOrder: DBMigrations[] | undefined,
+  blockHeight: number,
+): Operation<SystemMigration[]> {
+  const fromVersion = config.is_empty
+    ? undefined
+    : config.engine_previous_version;
+  const toVersion = config.engine_current_version;
+
+  // Get System Migrations
+  const systemMigrations = fromVersion !== toVersion
+    ? yield* until(getMigrations(fromVersion, toVersion))
+    : [];
+
+  return systemMigrations;
+}
+
+export function* applyUserMigrations(
+  currentBlockHeight: number,
+  dbConn: Client,
+  migrationOrder: DBMigrations[] | undefined,
+): Operation<void> {
+  const migrations = yield* getAllUserMigrations(
+    EFFECTSTREAM_ENGINE_VERSION,
+    migrationOrder,
+    currentBlockHeight,
+  );
+
+  // Apply all missing User Migrations
+  for (const migration of migrations) {
+    yield* until(
+      applyMigrations(
+        dbConn,
+        currentBlockHeight,
+        migration.name,
+        migration.sql,
+        false,
+      ),
+    );
+  }
+}
+
+function* getAllUserMigrations(
+  currentEngineVersion: VERSION,
+  migrationOrder: DBMigrations[] | undefined,
+  blockHeight: number,
+): Operation<DBMigrations[]> {
+  // Get User Migrations
+  const userMigrations = getMigrationsForBlockHeight(
+    migrationOrder,
+    blockHeight,
+    blockHeight,
+  );
+
+  // Check if User Migrations are compatible with the current version
+  for (const migration of userMigrations) {
+    // If a current version is provided we check if the migration have the correct version dependency
+    if (migration.versionDependency) {
+      if (
+        !isVersionGreaterOrEqual(
+          currentEngineVersion,
+          migration.versionDependency,
+        )
+      ) {
+        throw new Error(`[CRITICAL ERROR] Migration ${migration.name} failed.
+    Paima Engine Version ${migration.versionDependency} required.
+    Current version ${currentEngineVersion} is not compatible.
+    Please update your Paima Engine dependencies.`);
+      }
+    }
+  }
+
+  return userMigrations;
+}
+
+function isVersionGreaterOrEqual(
+  version: VERSION,
+  migrationVersion: VERSION,
+): boolean {
+  const versionParts = parseVersion(version);
+  const migrationVersionParts = parseVersion(migrationVersion);
+  return (
+    versionParts[0] > migrationVersionParts[0] ||
+    (versionParts[0] === migrationVersionParts[0] &&
+      versionParts[1] >= migrationVersionParts[1])
+  );
+}