@effect/cluster 0.28.4 → 0.29.1

package/src/ShardingConfig.ts

@@ -1,76 +1,217 @@
 /**
  * @since 1.0.0
  */
-import type * as ConfigError from "effect/ConfigError"
-import type * as Context from "effect/Context"
-import type * as Duration from "effect/Duration"
-import type * as Layer from "effect/Layer"
-import * as internal from "./internal/shardingConfig.js"
+import * as Config from "effect/Config"
+import type { ConfigError } from "effect/ConfigError"
+import * as ConfigProvider from "effect/ConfigProvider"
+import * as Context from "effect/Context"
+import type { DurationInput } from "effect/Duration"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Option from "effect/Option"
+import { RunnerAddress } from "./RunnerAddress.js"
 
 /**
+ * Represents the configuration for the `Sharding` service on a given runner.
+ *
  * @since 1.0.0
- * @category symbols
+ * @category models
  */
-export const ShardingConfigTypeId: unique symbol = internal.ShardingConfigTypeId
+export class ShardingConfig extends Context.Tag("@effect/cluster/ShardingConfig")<ShardingConfig, {
+  /**
+   * The address for the current runner.
+   *
+   * If `None`, the runner is not part of the cluster and will be in a client-only
+   * mode.
+   */
+  readonly runnerAddress: Option.Option<RunnerAddress>
+  /**
+   * The version of the current runner.
+   */
+  readonly serverVersion: number
+  /**
+   * The number of shards to allocate to a runner.
+   *
+   * **Note**: this value should be consistent across all runners.
+   */
+  readonly numberOfShards: number
+  /**
+   * The address of the shard manager.
+   */
+  readonly shardManagerAddress: RunnerAddress
+  /**
+   * If the shard manager is unavailable for this duration, all the shard
+   * assignments will be reset.
+   */
+  readonly shardManagerUnavailableTimeout: DurationInput
+  /**
+   * The default capacity of the mailbox for entities.
+   */
+  readonly entityMailboxCapacity: number | "unbounded"
+  /**
+   * The maximum duration of inactivity (i.e. without receiving a message)
+   * after which an entity will be interrupted.
+   */
+  readonly entityMaxIdleTime: DurationInput
+  /**
+   * The maximum duration of time to wait for an entity to terminate.
+   *
+   * By default this is set to 15 seconds to stay within kubernetes defaults.
+   */
+  readonly entityTerminationTimeout: DurationInput
+  /**
+   * The interval at which to poll for unprocessed messages from storage.
+   */
+  readonly entityMessagePollInterval: DurationInput
+  /**
+   * The interval at which to poll for client replies from storage.
+   */
+  readonly entityReplyPollInterval: DurationInput
+  readonly refreshAssignmentsInterval: DurationInput
+  /**
+   * The interval to retry a send if EntityNotManagedByRunner is returned.
+   */
+  readonly sendRetryInterval: DurationInput
+  // readonly unhealthyRunnerReportInterval: Duration.Duration
+  /**
+   * Simulate serialization and deserialization to remote runners for local
+   * entities.
+   */
+  readonly simulateRemoteSerialization: boolean
+}>() {}
+
+const defaultRunnerAddress = RunnerAddress.make({ host: "localhost", port: 34431 })
 
 /**
  * @since 1.0.0
- * @category symbols
+ * @category defaults
  */
-export type ShardingConfigTypeId = typeof ShardingConfigTypeId
+export const defaults: ShardingConfig["Type"] = {
+  runnerAddress: Option.some(defaultRunnerAddress),
+  serverVersion: 1,
+  numberOfShards: 300,
+  shardManagerAddress: RunnerAddress.make({ host: "localhost", port: 8080 }),
+  shardManagerUnavailableTimeout: Duration.minutes(10),
+  entityMailboxCapacity: 4096,
+  entityMaxIdleTime: Duration.minutes(1),
+  entityTerminationTimeout: Duration.seconds(15),
+  entityMessagePollInterval: Duration.seconds(10),
+  entityReplyPollInterval: Duration.millis(200),
+  sendRetryInterval: Duration.millis(100),
+  refreshAssignmentsInterval: Duration.minutes(5),
+  simulateRemoteSerialization: true
+}
 
 /**
- * Sharding configuration
- * @param numberOfShards number of shards (see documentation on how to choose this), should be same on all nodes
- * @param selfHost hostname or IP address of the current pod
- * @param shardingPort port used for pods to communicate together
- * @param shardManagerUri url of the Shard Manager API
- * @param serverVersion version of the current pod
- * @param entityMaxIdleTime time of inactivity (without receiving any message) after which an entity will be interrupted
- * @param entityTerminationTimeout time we give to an entity to handle the termination message before interrupting it
- * @param refreshAssignmentsRetryInterval retry interval in case of failure getting shard assignments from storage
- * @param unhealthyPodReportInterval interval to report unhealthy pods to the Shard Manager (this exists to prevent calling the Shard Manager for each failed message)
  * @since 1.0.0
- * @category models
+ * @category Layers
  */
-export interface ShardingConfig {
-  readonly numberOfShards: number
-  readonly selfHost: string
-  readonly shardingPort: number
-  readonly shardManagerUri: string
-  readonly serverVersion: string
-  readonly entityMaxIdleTime: Duration.Duration
-  readonly entityTerminationTimeout: Duration.Duration
-  readonly refreshAssignmentsRetryInterval: Duration.Duration
-  readonly unhealthyPodReportInterval: Duration.Duration
-}
+export const layer = (options?: Partial<ShardingConfig["Type"]>): Layer.Layer<ShardingConfig> =>
+  Layer.succeed(ShardingConfig, { ...defaults, ...options })
 
 /**
  * @since 1.0.0
- * @category context
+ * @category defaults
  */
-export const ShardingConfig: Context.Tag<ShardingConfig, ShardingConfig> = internal.shardingConfigTag
+export const layerDefaults: Layer.Layer<ShardingConfig> = layer()
 
 /**
- * Provides the default values for the ShardingConfig.
- *
  * @since 1.0.0
- * @category layers
+ * @category Config
  */
-export const defaults: Layer.Layer<ShardingConfig> = internal.defaults
+export const config: Config.Config<ShardingConfig["Type"]> = Config.all({
+  runnerAddress: Config.all({
+    host: Config.string("host").pipe(
+      Config.withDefault(defaultRunnerAddress.host),
+      Config.withDescription("The hostname or IP address of the runner.")
+    ),
+    port: Config.integer("port").pipe(
+      Config.withDefault(defaultRunnerAddress.port),
+      Config.withDescription("The port used for inter-runner communication.")
+    )
+  }).pipe(Config.map((options) => RunnerAddress.make(options)), Config.option),
+  serverVersion: Config.integer("serverVersion").pipe(
+    Config.withDefault(defaults.serverVersion),
+    Config.withDescription("The version of the current runner.")
+  ),
+  numberOfShards: Config.integer("numberOfShards").pipe(
+    Config.withDefault(defaults.numberOfShards),
+    Config.withDescription("The number of shards to allocate to a runner.")
+  ),
+  shardManagerAddress: Config.all({
+    host: Config.string("shardManagerHost").pipe(
+      Config.withDefault(defaults.shardManagerAddress.host),
+      Config.withDescription("The host of the shard manager.")
+    ),
+    port: Config.integer("shardManagerPort").pipe(
+      Config.withDefault(defaults.shardManagerAddress.port),
+      Config.withDescription("The port of the shard manager.")
+    )
+  }).pipe(Config.map((options) => RunnerAddress.make(options))),
+  shardManagerUnavailableTimeout: Config.duration("shardManagerUnavailableTimeout").pipe(
+    Config.withDefault(defaults.shardManagerUnavailableTimeout),
+    Config.withDescription(
+      "If the shard is unavilable for this duration, all the shard assignments will be reset."
+    )
+  ),
+  entityMailboxCapacity: Config.integer("entityMailboxCapacity").pipe(
+    Config.withDefault(defaults.entityMailboxCapacity),
+    Config.withDescription("The default capacity of the mailbox for entities.")
+  ),
+  entityMaxIdleTime: Config.duration("entityMaxIdleTime").pipe(
+    Config.withDefault(defaults.entityMaxIdleTime),
+    Config.withDescription(
+      "The maximum duration of inactivity (i.e. without receiving a message) after which an entity will be interrupted."
+    )
+  ),
+  entityTerminationTimeout: Config.duration("entityTerminationTimeout").pipe(
+    Config.withDefault(defaults.entityTerminationTimeout),
+    Config.withDescription("The maximum duration of time to wait for an entity to terminate.")
+  ),
+  entityMessagePollInterval: Config.duration("entityMessagePollInterval").pipe(
+    Config.withDefault(defaults.entityMessagePollInterval),
+    Config.withDescription("The interval at which to poll for unprocessed messages from storage.")
+  ),
+  entityReplyPollInterval: Config.duration("entityReplyPollInterval").pipe(
+    Config.withDefault(defaults.entityReplyPollInterval),
+    Config.withDescription("The interval at which to poll for client replies from storage.")
+  ),
+  sendRetryInterval: Config.duration("sendRetryInterval").pipe(
+    Config.withDefault(defaults.sendRetryInterval),
+    Config.withDescription("The interval to retry a send if EntityNotManagedByRunner is returned.")
+  ),
+  refreshAssignmentsInterval: Config.duration("refreshAssignmentsInterval").pipe(
+    Config.withDefault(defaults.refreshAssignmentsInterval),
+    Config.withDescription("The interval at which to refresh shard assignments.")
+  ),
+  simulateRemoteSerialization: Config.boolean("simulateRemoteSerialization").pipe(
+    Config.withDefault(defaults.simulateRemoteSerialization),
+    Config.withDescription("Simulate serialization and deserialization to remote runners for local entities.")
+  )
+})
 
 /**
- * Provides the ShardingConfig, values that are omitted will be read from the defaults
- *
  * @since 1.0.0
- * @category layers
+ * @category Config
  */
-export const withDefaults: (customs: Partial<ShardingConfig>) => Layer.Layer<ShardingConfig> = internal.withDefaults
+export const configFromEnv = config.pipe(
+  Effect.withConfigProvider(
+    ConfigProvider.fromEnv().pipe(
+      ConfigProvider.constantCase
+    )
+  )
+)
 
 /**
- * Reads the ShardingConfig from the effect/ConfigProvider
- *
  * @since 1.0.0
- * @category layers
+ * @category Layers
  */
-export const fromConfig: Layer.Layer<ShardingConfig, ConfigError.ConfigError> = internal.fromConfig
+export const layerFromEnv = (options?: Partial<ShardingConfig["Type"]> | undefined): Layer.Layer<
+  ShardingConfig,
+  ConfigError
+> =>
+  Layer.effect(
+    ShardingConfig,
+    options ? Effect.map(configFromEnv, (config) => ({ ...config, ...options })) : configFromEnv
+  )

package/src/ShardingRegistrationEvent.ts

@@ -1,62 +1,61 @@
 /**
  * @since 1.0.0
  */
-import type * as Message from "./Message.js"
-import type * as RecipientType from "./RecipientType.js"
-
-interface EntityRegistered<Msg extends Message.Message.Any> {
-  _tag: "EntityRegistered"
-  entityType: RecipientType.EntityType<Msg>
-}
+import * as Data from "effect/Data"
+import type { Entity } from "./Entity.js"
+import type { SingletonAddress } from "./SingletonAddress.js"
 
 /**
- * Constructs and event that occurs when a new EntityType gets registered.
+ * Represents events that can occur when a runner registers entities or singletons.
  *
  * @since 1.0.0
- * @category constructors
+ * @category models
  */
-export function EntityRegistered<Msg extends Message.Message.Any>(
-  entityType: RecipientType.EntityType<Msg>
-): ShardingRegistrationEvent {
-  return ({ _tag: "EntityRegistered", entityType })
-}
-
-interface SingletonRegistered {
-  _tag: "SingletonRegistered"
-  name: string
-}
+export type ShardingRegistrationEvent =
+  | EntityRegistered
+  | SingletonRegistered
 
 /**
- * Constructs a new event that occurs when a new Singleton is registered.
+ * Represents an event that occurs when a new entity is registered with a runner.
  *
  * @since 1.0.0
- * @category constructors
+ * @category models
  */
-export function SingletonRegistered(name: string): ShardingRegistrationEvent {
-  return ({ _tag: "SingletonRegistered", name })
-}
-
-interface TopicRegistered<Msg extends Message.Message.Any> {
-  _tag: "TopicRegistered"
-  topicType: RecipientType.TopicType<Msg>
+export interface EntityRegistered {
+  readonly _tag: "EntityRegistered"
+  readonly entity: Entity<any>
 }
 
 /**
- * Constructs a new event that occurs when a topic is Registered.
+ * Represents an event that occurs when a new singleton is registered with a
+ * runner.
+ *
  * @since 1.0.0
- * @category constructors
+ * @category models
  */
-export function TopicRegistered<Msg extends Message.Message.Any>(
-  topicType: RecipientType.TopicType<Msg>
-): ShardingRegistrationEvent {
-  return ({ _tag: "TopicRegistered", topicType })
+export interface SingletonRegistered {
+  readonly _tag: "SingletonRegistered"
+  readonly address: SingletonAddress
 }
 
 /**
  * @since 1.0.0
- * @category models
+ * @category pattern matching
  */
-export type ShardingRegistrationEvent =
-  | EntityRegistered<any>
-  | SingletonRegistered
-  | TopicRegistered<any>
+export const {
+  /**
+   * @since 1.0.0
+   * @category pattern matching
+   */
+  $match: match,
+  /**
+   * @since 1.0.0
+   * @category constructors
+   */
+  EntityRegistered,
+  /**
+   * @since 1.0.0
+   * @category constructors
+   */
+  SingletonRegistered
+} = Data.taggedEnum<ShardingRegistrationEvent>()

package/src/Singleton.ts

@@ -0,0 +1,20 @@
+/**
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import type { Scope } from "effect/Scope"
+import { Sharding } from "./Sharding.js"
+
+/**
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make = <E, R>(
+  name: string,
+  run: Effect.Effect<void, E, R>
+): Layer.Layer<never, never, Sharding | Exclude<R, Scope>> =>
+  Layer.effectDiscard(Effect.gen(function*() {
+    const sharding = yield* Sharding
+    yield* sharding.registerSingleton(name, run)
+  }))

package/src/SingletonAddress.ts

@@ -0,0 +1,47 @@
+/**
+ * @since 1.0.0
+ */
+import * as Equal from "effect/Equal"
+import * as Hash from "effect/Hash"
+import * as Schema from "effect/Schema"
+import { ShardId } from "./ShardId.js"
+
+/**
+ * @since 1.0.0
+ * @category Address
+ */
+export const TypeId: unique symbol = Symbol.for("@effect/cluster/SingletonAddress")
+
+/**
+ * @since 1.0.0
+ * @category Address
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * Represents the unique address of an singleton within the cluster.
+ *
+ * @since 1.0.0
+ * @category Address
+ */
+export class SingletonAddress extends Schema.Class<SingletonAddress>("@effect/cluster/SingletonAddress")({
+  shardId: ShardId,
+  name: Schema.NonEmptyTrimmedString
+}) {
+  /**
+   * @since 1.0.0
+   */
+  readonly [TypeId] = TypeId;
+  /**
+   * @since 1.0.0
+   */
+  [Hash.symbol]() {
+    return Hash.cached(this)(Hash.string(`${this.shardId}:${this.name}`))
+  }
+  /**
+   * @since 1.0.0
+   */
+  [Equal.symbol](that: SingletonAddress): boolean {
+    return this.shardId === that.shardId && this.name === that.name
+  }
+}

package/src/Snowflake.ts

@@ -0,0 +1,194 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Brand from "effect/Brand"
+import * as Context from "effect/Context"
+import * as DateTime from "effect/DateTime"
+import * as Effect from "effect/Effect"
+import { identity } from "effect/Function"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import type { MachineId } from "./MachineId.js"
+
+/**
+ * @since 1.0.0
+ * @category Symbols
+ */
+export const TypeId: unique symbol = Symbol.for("@effect/cluster/Snowflake")
+
+/**
+ * @since 1.0.0
+ * @category Symbols
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export type Snowflake = Brand.Branded<bigint, TypeId>
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export const Snowflake = (input: string | bigint): Snowflake =>
+  typeof input === "string" ? BigInt(input) as Snowflake : input as Snowflake
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export declare namespace Snowflake {
+  /**
+   * @since 1.0.0
+   * @category Models
+   */
+  export interface Parts {
+    readonly timestamp: number
+    readonly machineId: MachineId
+    readonly sequence: number
+  }
+
+  /**
+   * @since 1.0.0
+   * @category Models
+   */
+  export interface Generator {
+    readonly unsafeNext: () => Snowflake
+    readonly setMachineId: (machineId: MachineId) => Effect.Effect<void>
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category Schemas
+ */
+export const SnowflakeFromBigInt: Schema.Schema<Snowflake, bigint> = Schema.BigIntFromSelf.pipe(
+  Schema.brand(TypeId)
+)
+
+/**
+ * @since 1.0.0
+ * @category Schemas
+ */
+export const SnowflakeFromString: Schema.Schema<Snowflake, string> = Schema.BigInt.pipe(
+  Schema.brand(TypeId)
+)
+
+/**
+ * @since 1.0.0
+ * @category Epoch
+ */
+export const constEpochMillis: number = Date.UTC(2025, 0, 1)
+
+const sinceUnixEpoch = constEpochMillis - Date.UTC(1970, 0, 1)
+const constBigInt12 = BigInt(12)
+const constBigInt22 = BigInt(22)
+const constBigInt1024 = BigInt(1024)
+const constBigInt4096 = BigInt(4096)
+
+/**
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make = (options: {
+  readonly machineId: MachineId
+  readonly sequence: number
+  readonly timestamp: number
+}): Snowflake =>
+  (BigInt(options.timestamp - constEpochMillis) << constBigInt22
+    | (BigInt(options.machineId % 1024) << constBigInt12)
+    | BigInt(options.sequence % 4096)) as Snowflake
+
+/**
+ * @since 1.0.0
+ * @category Parts
+ */
+export const timestamp = (snowflake: Snowflake): number => Number(snowflake >> constBigInt22) + sinceUnixEpoch
+
+/**
+ * @since 1.0.0
+ * @category Parts
+ */
+export const dateTime = (snowflake: Snowflake): DateTime.Utc => DateTime.unsafeMake(timestamp(snowflake))
+
+/**
+ * @since 1.0.0
+ * @category Parts
+ */
+export const machineId = (snowflake: Snowflake): MachineId =>
+  Number((snowflake >> constBigInt12) % constBigInt1024) as MachineId
+
+/**
+ * @since 1.0.0
+ * @category Parts
+ */
+export const sequence = (snowflake: Snowflake): number => Number(snowflake % constBigInt4096)
+
+/**
+ * @since 1.0.0
+ * @category Parts
+ */
+export const toParts = (snowflake: Snowflake): Snowflake.Parts => ({
+  timestamp: timestamp(snowflake),
+  machineId: machineId(snowflake),
+  sequence: sequence(snowflake)
+})
+
+/**
+ * @since 1.0.0
+ * @category Generator
+ */
+export const makeGenerator: Effect.Effect<Snowflake.Generator> = Effect.gen(function*() {
+  let machineId = Math.floor(Math.random() * 1024) as MachineId
+  const clock = yield* Effect.clock
+
+  let sequence = 0
+  let sequenceAt = clock.unsafeCurrentTimeMillis()
+
+  return identity<Snowflake.Generator>({
+    setMachineId: (newMachineId) =>
+      Effect.sync(() => {
+        machineId = newMachineId
+      }),
+    unsafeNext() {
+      let now = clock.unsafeCurrentTimeMillis()
+
+      // account for clock drift, only allow time to move forward
+      if (now < sequenceAt) {
+        now = sequenceAt
+      } else if (now > sequenceAt) {
+        // reset sequence if we're in a new millisecond
+        sequence = 0
+        sequenceAt = now
+      } else if (sequence >= 1024) {
+        // if we've hit the max sequence for this millisecond, go to the next
+        // millisecond
+        sequenceAt++
+        sequence = 0
+      }
+
+      return make({
+        machineId,
+        sequence: sequence++,
+        timestamp: sequenceAt
+      })
+    }
+  })
+})
+
+/**
+ * @since 1.0.0
+ * @category Generator
+ */
+export class Generator extends Context.Tag("@effect/cluster/Snowflake/Generator")<
+  Generator,
+  Snowflake.Generator
+>() {}
+
+/**
+ * @since 1.0.0
+ * @category Generator
+ */
+export const layerGenerator: Layer.Layer<Generator> = Layer.effect(Generator, makeGenerator)

package/src/SocketRunner.ts

@@ -0,0 +1,59 @@
+/**
+ * @since 1.0.0
+ */
+import { SocketServer } from "@effect/platform/SocketServer"
+import type * as RpcSerialization from "@effect/rpc/RpcSerialization"
+import * as RpcServer from "@effect/rpc/RpcServer"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import type { MessageStorage } from "./MessageStorage.js"
+import * as Runners from "./Runners.js"
+import * as RunnerServer from "./RunnerServer.js"
+import * as Sharding from "./Sharding.js"
+import type { ShardingConfig } from "./ShardingConfig.js"
+import * as ShardManager from "./ShardManager.js"
+import * as ShardStorage from "./ShardStorage.js"
+
+const withLogAddress = <A, E, R>(layer: Layer.Layer<A, E, R>): Layer.Layer<A, E, R | SocketServer> =>
+  Layer.effectDiscard(Effect.gen(function*() {
+    const server = yield* SocketServer
+    const address = server.address._tag === "UnixAddress"
+      ? server.address.path
+      : `${server.address.hostname}:${server.address.port}`
+    yield* Effect.annotateLogs(Effect.logInfo(`Listening on: ${address}`), {
+      package: "@effect/cluster",
+      service: "Runner"
+    })
+  })).pipe(Layer.provideMerge(layer))
+
+/**
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layer: Layer.Layer<
+  Sharding.Sharding | Runners.Runners,
+  never,
+  | Runners.RpcClientProtocol
+  | ShardingConfig
+  | RpcSerialization.RpcSerialization
+  | SocketServer
+  | MessageStorage
+  | ShardStorage.ShardStorage
+> = RunnerServer.layerWithClients.pipe(
+  withLogAddress,
+  Layer.provide(RpcServer.layerProtocolSocketServer)
+)
+
+/**
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layerClientOnly: Layer.Layer<
+  Sharding.Sharding | Runners.Runners,
+  never,
+  Runners.RpcClientProtocol | ShardingConfig | MessageStorage
+> = Sharding.layer.pipe(
+  Layer.provideMerge(Runners.layerRpc),
+  Layer.provide(ShardManager.layerClientRpc),
+  Layer.provide(ShardStorage.layerNoop)
+)