@effect/cluster 0.53.5 → 0.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/cluster",
-  "version": "0.53.5",
+  "version": "0.54.0",
   "description": "Unified interfaces for common cluster-specific services",
   "license": "MIT",
   "repository": {
@@ -14,11 +14,11 @@
     "kubernetes-types": "^1.30.0"
   },
   "peerDependencies": {
-    "@effect/workflow": "^0.13.0",
+    "@effect/platform": "^0.93.5",
+    "@effect/sql": "^0.48.5",
     "@effect/rpc": "^0.72.2",
-    "@effect/sql": "^0.48.0",
-    "effect": "^3.19.6",
-    "@effect/platform": "^0.93.3"
+    "@effect/workflow": "^0.14.0",
+    "effect": "^3.19.8"
   },
   "publishConfig": {
     "provenance": true
@@ -183,6 +183,11 @@
       "import": "./dist/esm/ShardingRegistrationEvent.js",
       "default": "./dist/cjs/ShardingRegistrationEvent.js"
     },
+    "./SingleRunner": {
+      "types": "./dist/dts/SingleRunner.d.ts",
+      "import": "./dist/esm/SingleRunner.js",
+      "default": "./dist/cjs/SingleRunner.js"
+    },
     "./Singleton": {
       "types": "./dist/dts/Singleton.d.ts",
       "import": "./dist/esm/Singleton.js",
@@ -213,6 +218,11 @@
       "import": "./dist/esm/SqlRunnerStorage.js",
       "default": "./dist/cjs/SqlRunnerStorage.js"
     },
+    "./TestRunner": {
+      "types": "./dist/dts/TestRunner.d.ts",
+      "import": "./dist/esm/TestRunner.js",
+      "default": "./dist/cjs/TestRunner.js"
+    },
     "./index": {
       "types": "./dist/dts/index.d.ts",
       "import": "./dist/esm/index.js",
@@ -311,6 +321,9 @@
       "ShardingRegistrationEvent": [
         "./dist/dts/ShardingRegistrationEvent.d.ts"
       ],
+      "SingleRunner": [
+        "./dist/dts/SingleRunner.d.ts"
+      ],
       "Singleton": [
         "./dist/dts/Singleton.d.ts"
       ],
@@ -329,6 +342,9 @@
       "SqlRunnerStorage": [
         "./dist/dts/SqlRunnerStorage.d.ts"
       ],
+      "TestRunner": [
+        "./dist/dts/TestRunner.d.ts"
+      ],
       "index": [
         "./dist/dts/index.d.ts"
       ]

package/src/ShardingConfig.ts

@@ -63,6 +63,10 @@ export class ShardingConfig extends Context.Tag("@effect/cluster/ShardingConfig"
    * Shard lock expiration duration.
    */
   readonly shardLockExpiration: DurationInput
+  /**
+   * Disable the use of advisory locks for shard locking.
+   */
+  readonly shardLockDisableAdvisory: boolean
   /**
    * Start shutting down as soon as an Entity has started shutting down.
    *
@@ -134,6 +138,7 @@ export const defaults: ShardingConfig["Type"] = {
   preemptiveShutdown: true,
   shardLockRefreshInterval: Duration.seconds(10),
   shardLockExpiration: Duration.seconds(35),
+  shardLockDisableAdvisory: false,
   entityMailboxCapacity: 4096,
   entityMaxIdleTime: Duration.minutes(1),
   entityRegistrationTimeout: Duration.minutes(1),
@@ -206,6 +211,10 @@ export const config: Config.Config<ShardingConfig["Type"]> = Config.all({
     Config.withDefault(defaults.shardLockExpiration),
     Config.withDescription("Shard lock expiration duration.")
   ),
+  shardLockDisableAdvisory: Config.boolean("shardLockDisableAdvisory").pipe(
+    Config.withDefault(defaults.shardLockDisableAdvisory),
+    Config.withDescription("Disable the use of advisory locks for shard locking.")
+  ),
   entityMailboxCapacity: Config.integer("entityMailboxCapacity").pipe(
     Config.withDefault(defaults.entityMailboxCapacity),
     Config.withDescription("The default capacity of the mailbox for entities.")

package/src/SingleRunner.ts

@@ -0,0 +1,41 @@
+/**
+ * @since 1.0.0
+ */
+import type * as SqlClient from "@effect/sql/SqlClient"
+import type * as ConfigError from "effect/ConfigError"
+import * as Layer from "effect/Layer"
+import type * as MessageStorage from "./MessageStorage.js"
+import * as RunnerHealth from "./RunnerHealth.js"
+import * as Runners from "./Runners.js"
+import * as RunnerStorage from "./RunnerStorage.js"
+import * as Sharding from "./Sharding.js"
+import * as ShardingConfig from "./ShardingConfig.js"
+import * as SqlMessageStorage from "./SqlMessageStorage.js"
+import * as SqlRunnerStorage from "./SqlRunnerStorage.js"
+
+/**
+ * A sql backed single-node cluster, that can be used for running durable
+ * entities and workflows.
+ *
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layer = (options?: {
+  readonly shardingConfig?: Partial<ShardingConfig.ShardingConfig["Type"]> | undefined
+  readonly runnerStorage?: "memory" | "sql" | undefined
+}): Layer.Layer<
+  | Sharding.Sharding
+  | Runners.Runners
+  | MessageStorage.MessageStorage,
+  ConfigError.ConfigError,
+  SqlClient.SqlClient
+> =>
+  Sharding.layer.pipe(
+    Layer.provideMerge(Runners.layerNoop),
+    Layer.provideMerge(SqlMessageStorage.layer),
+    Layer.provide([
+      options?.runnerStorage === "memory" ? RunnerStorage.layerMemory : Layer.orDie(SqlRunnerStorage.layer),
+      RunnerHealth.layerNoop
+    ]),
+    Layer.provide(ShardingConfig.layerFromEnv(options?.shardingConfig))
+  )

package/src/SqlRunnerStorage.ts

@@ -25,6 +25,7 @@ export const make = Effect.fnUntraced(function*(options: {
   readonly prefix?: string | undefined
 }) {
   const config = yield* ShardingConfig.ShardingConfig
+  const disableAdvisoryLocks = config.shardLockDisableAdvisory
   const sql = (yield* SqlClient.SqlClient).withoutTransforms()
   const prefix = options?.prefix ?? "cluster"
   const table = (name: string) => `${prefix}_${name}`
@@ -138,8 +139,22 @@ export const make = Effect.fnUntraced(function*(options: {
           acquired_at DATETIME NOT NULL
         )
       `,
-    mysql: () => Effect.void,
-    pg: () => Effect.void,
+    mysql: () =>
+      sql`
+        CREATE TABLE IF NOT EXISTS ${locksTableSql} (
+          shard_id VARCHAR(50) PRIMARY KEY,
+          address VARCHAR(255) NOT NULL,
+          acquired_at DATETIME NOT NULL
+        )
+      `,
+    pg: () =>
+      sql`
+        CREATE TABLE IF NOT EXISTS ${locksTableSql} (
+          shard_id VARCHAR(50) PRIMARY KEY,
+          address VARCHAR(255) NOT NULL,
+          acquired_at TIMESTAMP NOT NULL
+        )
+      `,
     orElse: () =>
       // sqlite
       sql`
@@ -232,6 +247,16 @@ export const make = Effect.fnUntraced(function*(options: {
       Effect.onError(() => lockConn.unsafeRebuild())
     )
   }
+  const execWithLockConnUnprepared = <A>(
+    effect: Statement.Statement<A>
+  ): Effect.Effect<ReadonlyArray<ReadonlyArray<any>>, SqlError> => {
+    if (!lockConn) return effect.values
+    const [query, params] = effect.compile()
+    return lockConn.await.pipe(
+      Effect.flatMap(([conn]) => conn.executeUnprepared(query, params, undefined)),
+      Effect.onError(() => lockConn.unsafeRebuild())
+    )
+  }
   const execWithLockConnValues = <A>(
     effect: Statement.Statement<A>
   ): Effect.Effect<ReadonlyArray<ReadonlyArray<any>>, SqlError> => {
@@ -244,8 +269,24 @@ export const make = Effect.fnUntraced(function*(options: {
   }
 
   const acquireLock = sql.onDialectOrElse({
-    pg: () =>
-      Effect.fnUntraced(function*(_address: string, shardIds: ReadonlyArray<string>) {
+    pg: () => {
+      if (disableAdvisoryLocks) {
+        return (address: string, shardIds: ReadonlyArray<string>) => {
+          const values = shardIds.map((shardId) =>
+            sql`(${stringLiteral(shardId)}, ${stringLiteral(address)}, ${sqlNow})`
+          )
+          return sql`
+            INSERT INTO ${locksTableSql} (shard_id, address, acquired_at) VALUES ${sql.csv(values)}
+            ON CONFLICT (shard_id) DO UPDATE
+            SET address = ${address}, acquired_at = ${sqlNow}
+            WHERE ${locksTableSql}.address = ${address}
+              OR ${locksTableSql}.acquired_at < ${lockExpiresAt}
+`.pipe(
+            Effect.andThen(acquiredLocks(address, shardIds))
+          )
+        }
+      }
+      return Effect.fnUntraced(function*(_address: string, shardIds: ReadonlyArray<string>) {
         const [conn, pid] = yield* lockConn!.await
         const acquiredShardIds: Array<string> = []
         const toAcquire = new Map(shardIds.map((shardId) => [lockNumbers.get(shardId)!, shardId]))
@@ -269,10 +310,26 @@ export const make = Effect.fnUntraced(function*(options: {
           }
         }
         return acquiredShardIds
-      }, Effect.onError(() => lockConn!.unsafeRebuild())),
+      }, Effect.onError(() => lockConn!.unsafeRebuild()))
+    },
 
-    mysql: () =>
-      Effect.fnUntraced(function*(_address: string, shardIds: ReadonlyArray<string>) {
+    mysql: () => {
+      if (disableAdvisoryLocks) {
+        return (address: string, shardIds: ReadonlyArray<string>) => {
+          const values = shardIds.map((shardId) =>
+            sql`(${stringLiteral(shardId)}, ${stringLiteral(address)}, ${sqlNow})`
+          )
+          return sql`
+            INSERT INTO ${locksTableSql} (shard_id, address, acquired_at) VALUES ${sql.csv(values)}
+            ON DUPLICATE KEY UPDATE
+            address = IF(address = VALUES(address) OR acquired_at < ${lockExpiresAt}, VALUES(address), address),
+            acquired_at = IF(address = VALUES(address) OR acquired_at < ${lockExpiresAt}, VALUES(acquired_at), acquired_at)
+`.unprepared.pipe(
+            Effect.andThen(acquiredLocks(address, shardIds))
+          )
+        }
+      }
+      return Effect.fnUntraced(function*(_address: string, shardIds: ReadonlyArray<string>) {
         const [conn, pid] = yield* lockConn!.await
         const takenLocks = (yield* conn.executeValues(`SELECT ${allMySqlTakenLocks}`, []))[0] as Array<number | null>
         const acquiredShardIds: Array<string> = []
@@ -296,7 +353,8 @@ export const make = Effect.fnUntraced(function*(options: {
           }
         }
         return acquiredShardIds
-      }, Effect.onError(() => lockConn!.unsafeRebuild())),
+      }, Effect.onError(() => lockConn!.unsafeRebuild()))
+    },
 
     mssql: () => (address: string, shardIds: ReadonlyArray<string>) => {
       const values = shardIds.map((shardId) => sql`(${stringLiteral(shardId)}, ${stringLiteral(address)}, ${sqlNow})`)
@@ -399,8 +457,34 @@ export const make = Effect.fnUntraced(function*(options: {
   const stringLiteralArr = (arr: ReadonlyArray<string>) => sql.literal(`(${arr.map(wrapString).join(",")})`)
 
   const refreshShards = sql.onDialectOrElse({
-    pg: () => acquireLock,
-    mysql: () => acquireLock,
+    pg: () => {
+      if (!disableAdvisoryLocks) return acquireLock
+      return (address: string, shardIds: ReadonlyArray<string>) =>
+        sql`
+          UPDATE ${locksTableSql}
+          SET acquired_at = ${sqlNow}
+          WHERE address = ${address} AND shard_id IN ${stringLiteralArr(shardIds)}
+          RETURNING shard_id
+        `.pipe(
+          execWithLockConnValues,
+          Effect.map((rows) => rows.map((row) => row[0] as string))
+        )
+    },
+    mysql: () => {
+      if (!disableAdvisoryLocks) return acquireLock
+      return (address: string, shardIds: ReadonlyArray<string>) => {
+        const shardIdsStr = stringLiteralArr(shardIds)
+        return sql<Array<{ shard_id: string }>>`
+          UPDATE ${locksTableSql}
+          SET acquired_at = ${sqlNow}
+          WHERE address = ${address} AND shard_id IN ${shardIdsStr};
+          SELECT shard_id FROM ${locksTableSql} WHERE address = ${address} AND shard_id IN ${shardIdsStr}
+        `.pipe(
+          execWithLockConnUnprepared,
+          Effect.map((rows) => rows[1].map((row) => row.shard_id))
+        )
+      }
+    },
     mssql: () => (address: string, shardIds: ReadonlyArray<string>) =>
       sql`
         UPDATE ${locksTableSql}
@@ -462,8 +546,14 @@ export const make = Effect.fnUntraced(function*(options: {
       ),
 
     release: sql.onDialectOrElse({
-      pg: () =>
-        Effect.fnUntraced(
+      pg: () => {
+        if (disableAdvisoryLocks) {
+          return (address: string, shardId: string) =>
+            sql`DELETE FROM ${locksTableSql} WHERE address = ${address} AND shard_id = ${shardId}`.pipe(
+              PersistenceError.refail
+            )
+        }
+        return Effect.fnUntraced(
           function*(_address, shardId) {
             const lockNum = lockNumbers.get(shardId)!
             for (let i = 0; i < 5; i++) {
@@ -481,9 +571,16 @@ export const make = Effect.fnUntraced(function*(options: {
           Effect.onError(() => lockConn!.unsafeRebuild()),
           Effect.asVoid,
           PersistenceError.refail
-        ),
-      mysql: () =>
-        Effect.fnUntraced(
+        )
+      },
+      mysql: () => {
+        if (disableAdvisoryLocks) {
+          return (address: string, shardId: string) =>
+            sql`DELETE FROM ${locksTableSql} WHERE address = ${address} AND shard_id = ${shardId}`.pipe(
+              PersistenceError.refail
+            )
+        }
+        return Effect.fnUntraced(
           function*(_address, shardId) {
             const lockName = lockNames.get(shardId)!
             while (true) {
@@ -499,7 +596,8 @@ export const make = Effect.fnUntraced(function*(options: {
           Effect.onError(() => lockConn!.unsafeRebuild()),
           Effect.asVoid,
           PersistenceError.refail
-        ),
+        )
+      },
       orElse: () => (address, shardId) =>
         sql`DELETE FROM ${locksTableSql} WHERE address = ${address} AND shard_id = ${shardId}`.pipe(
           PersistenceError.refail
@@ -507,20 +605,34 @@ export const make = Effect.fnUntraced(function*(options: {
     }),
 
     releaseAll: sql.onDialectOrElse({
-      pg: () => (_address) =>
-        sql`SELECT pg_advisory_unlock_all()`.pipe(
+      pg: () => (address) => {
+        if (disableAdvisoryLocks) {
+          return sql`DELETE FROM ${locksTableSql} WHERE address = ${address}`.pipe(
+            PersistenceError.refail,
+            withTracerDisabled
+          )
+        }
+        return sql`SELECT pg_advisory_unlock_all()`.pipe(
           execWithLockConn,
           Effect.asVoid,
           PersistenceError.refail,
           withTracerDisabled
-        ),
-      mysql: () => (_address) =>
-        sql`SELECT RELEASE_ALL_LOCKS()`.pipe(
+        )
+      },
+      mysql: () => (address) => {
+        if (disableAdvisoryLocks) {
+          return sql`DELETE FROM ${locksTableSql} WHERE address = ${address}`.pipe(
+            PersistenceError.refail,
+            withTracerDisabled
+          )
+        }
+        return sql`SELECT RELEASE_ALL_LOCKS()`.pipe(
           execWithLockConn,
           Effect.asVoid,
           PersistenceError.refail,
           withTracerDisabled
-        ),
+        )
+      },
       orElse: () => (address) =>
         sql`DELETE FROM ${locksTableSql} WHERE address = ${address}`.pipe(
           PersistenceError.refail,

package/src/TestRunner.ts

@@ -0,0 +1,28 @@
+/**
+ * @since 1.0.0
+ */
+import * as Layer from "effect/Layer"
+import * as MessageStorage from "./MessageStorage.js"
+import * as RunnerHealth from "./RunnerHealth.js"
+import * as Runners from "./Runners.js"
+import * as RunnerStorage from "./RunnerStorage.js"
+import * as Sharding from "./Sharding.js"
+import * as ShardingConfig from "./ShardingConfig.js"
+
+/**
+ * An in-memory cluster that can be used for testing purposes.
+ *
+ * MessageStorage is backed by an in-memory driver, and RunnerStorage is backed
+ * by an in-memory driver.
+ *
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layer: Layer.Layer<
+  Sharding.Sharding | Runners.Runners | MessageStorage.MessageStorage | MessageStorage.MemoryDriver
+> = Sharding.layer.pipe(
+  Layer.provideMerge(Runners.layerNoop),
+  Layer.provideMerge(MessageStorage.layerMemory),
+  Layer.provide([RunnerStorage.layerMemory, RunnerHealth.layerNoop]),
+  Layer.provide(ShardingConfig.layer())
+)

package/src/index.ts

@@ -148,6 +148,11 @@ export * as ShardingConfig from "./ShardingConfig.js"
  */
 export * as ShardingRegistrationEvent from "./ShardingRegistrationEvent.js"
 
+/**
+ * @since 1.0.0
+ */
+export * as SingleRunner from "./SingleRunner.js"
+
 /**
  * @since 1.0.0
  */
@@ -177,3 +182,8 @@ export * as SqlMessageStorage from "./SqlMessageStorage.js"
  * @since 1.0.0
  */
 export * as SqlRunnerStorage from "./SqlRunnerStorage.js"
+
+/**
+ * @since 1.0.0
+ */
+export * as TestRunner from "./TestRunner.js"