@effect/cluster 0.0.0-snapshot-d33d8b050b8e3c87dcde9587083e6c1cf733f72b

package/src/ShardManager.ts

@@ -0,0 +1,53 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Effect from "effect/Effect"
+import type * as HashMap from "effect/HashMap"
+import type * as Option from "effect/Option"
+import type * as Stream from "effect/Stream"
+import * as internal from "./internal/shardManager.js"
+import type * as Pod from "./Pod.js"
+import type * as PodAddress from "./PodAddress.js"
+import type * as ShardId from "./ShardId.js"
+import type * as ShardingEvent from "./ShardingEvent.js"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const ShardManagerTypeId: unique symbol = internal.ShardManagerTypeId
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type ShardManagerTypeId = typeof ShardManagerTypeId
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export const ShardManager = internal.shardManagerTag
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface ShardManager {
+  readonly getShardingEvents: Stream.Stream<ShardingEvent.ShardingEvent>
+  readonly register: (pod: Pod.Pod) => Effect.Effect<void>
+  readonly unregister: (podAddress: PodAddress.PodAddress) => Effect.Effect<void>
+  readonly notifyUnhealthyPod: (podAddress: PodAddress.PodAddress) => Effect.Effect<void>
+  readonly checkAllPodsHealth: Effect.Effect<void>
+  readonly getAssignments: Effect.Effect<HashMap.HashMap<ShardId.ShardId, Option.Option<PodAddress.PodAddress>>>
+  /* @internal */
+  readonly rebalance: (rebalanceImmediately: boolean) => Effect.Effect<void>
+  /* @internal */
+  readonly persistPods: Effect.Effect<void>
+}
+
+/**
+ * @since 1.0.0
+ * @category layers
+ */
+export const live = internal.live

package/src/ShardManagerClient.ts

@@ -0,0 +1,57 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as HashMap from "effect/HashMap"
+import type * as Layer from "effect/Layer"
+import type * as Option from "effect/Option"
+import * as internal from "./internal/shardManagerClient.js"
+import type * as PodAddress from "./PodAddress.js"
+import type * as ShardId from "./ShardId.js"
+import type * as ShardingConfig from "./ShardingConfig.js"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const ShardManagerClientTypeId: unique symbol = internal.ShardManagerClientTypeId
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export type ShardManagerClientTypeId = typeof ShardManagerClientTypeId
+
+/**
+ * ShardManagerClient provides the methods exposed by the ShardManager and called by the Pod.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface ShardManagerClient {
+  readonly [ShardManagerClientTypeId]: ShardManagerClientTypeId
+  readonly register: (podAddress: PodAddress.PodAddress) => Effect.Effect<void>
+  readonly unregister: (podAddress: PodAddress.PodAddress) => Effect.Effect<void>
+  readonly notifyUnhealthyPod: (podAddress: PodAddress.PodAddress) => Effect.Effect<void>
+  readonly getAssignments: Effect.Effect<HashMap.HashMap<ShardId.ShardId, Option.Option<PodAddress.PodAddress>>>
+}
+
+/**
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make: (args: Omit<ShardManagerClient, typeof ShardManagerClientTypeId>) => ShardManagerClient =
+  internal.make
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export const ShardManagerClient: Context.Tag<ShardManagerClient, ShardManagerClient> = internal.shardManagerClientTag
+
+/**
+ * @since 1.0.0
+ * @category layers
+ */
+export const local: Layer.Layer<ShardManagerClient, never, ShardingConfig.ShardingConfig> = internal.local

package/src/Sharding.ts

@@ -0,0 +1,214 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Effect from "effect/Effect"
+import type * as HashSet from "effect/HashSet"
+import type * as Scope from "effect/Scope"
+import type * as Stream from "effect/Stream"
+import type { Broadcaster } from "./Broadcaster.js"
+import * as internal from "./internal/sharding.js"
+import type * as Message from "./Message.js"
+import type * as MessageState from "./MessageState.js"
+import type { Messenger } from "./Messenger.js"
+import type * as PodAddress from "./PodAddress.js"
+import type * as RecipientAddress from "./RecipientAddress.js"
+import type * as RecipientBehaviour from "./RecipientBehaviour.js"
+import type * as RecipientBehaviourContext from "./RecipientBehaviourContext.js"
+import type * as RecipentType from "./RecipientType.js"
+import type * as SerializedEnvelope from "./SerializedEnvelope.js"
+import type * as SerializedMessage from "./SerializedMessage.js"
+import type * as ShardId from "./ShardId.js"
+import type * as ShardingException from "./ShardingException.js"
+import type * as ShardingRegistrationEvent from "./ShardingRegistrationEvent.js"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const ShardingTypeId: unique symbol = internal.ShardingTypeId
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type ShardingTypeId = typeof ShardingTypeId
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface Sharding {
+  readonly [ShardingTypeId]: ShardingTypeId
+  readonly register: Effect.Effect<void>
+  readonly unregister: Effect.Effect<void>
+  readonly messenger: <Msg extends Message.Message.Any>(
+    entityType: RecipentType.EntityType<Msg>
+  ) => Messenger<Msg>
+  readonly broadcaster: <Msg extends Message.Message.Any>(
+    topicType: RecipentType.TopicType<Msg>
+  ) => Broadcaster<Msg>
+  readonly isEntityOnLocalShards: (
+    recipientAddress: RecipientAddress.RecipientAddress
+  ) => Effect.Effect<boolean>
+  readonly isShuttingDown: Effect.Effect<boolean>
+
+  readonly registerScoped: Effect.Effect<void, never, Scope.Scope>
+  readonly registerEntity: <Msg extends Message.Message.Any>(
+    entityType: RecipentType.EntityType<Msg>
+  ) => <R>(
+    behaviour: RecipientBehaviour.RecipientBehaviour<Msg, R>,
+    options?: RecipientBehaviour.EntityBehaviourOptions
+  ) => Effect.Effect<void, never, Exclude<R, RecipientBehaviourContext.RecipientBehaviourContext>>
+  readonly registerTopic: <Msg extends Message.Message.Any>(
+    topicType: RecipentType.TopicType<Msg>
+  ) => <R>(
+    behaviour: RecipientBehaviour.RecipientBehaviour<Msg, R>,
+    options?: RecipientBehaviour.EntityBehaviourOptions
+  ) => Effect.Effect<void, never, Exclude<R, RecipientBehaviourContext.RecipientBehaviourContext>>
+  readonly getShardingRegistrationEvents: Stream.Stream<ShardingRegistrationEvent.ShardingRegistrationEvent>
+  readonly registerSingleton: <R>(name: string, run: Effect.Effect<void, never, R>) => Effect.Effect<void, never, R>
+  readonly assign: (shards: HashSet.HashSet<ShardId.ShardId>) => Effect.Effect<void>
+  readonly unassign: (shards: HashSet.HashSet<ShardId.ShardId>) => Effect.Effect<void>
+  readonly sendMessageToLocalEntityManagerWithoutRetries: (
+    message: SerializedEnvelope.SerializedEnvelope
+  ) => Effect.Effect<
+    MessageState.MessageState<SerializedMessage.SerializedMessage>,
+    ShardingException.ShardingException
+  >
+  readonly getPods: Effect.Effect<HashSet.HashSet<PodAddress.PodAddress>>
+  readonly getAssignedShardIds: Effect.Effect<HashSet.HashSet<ShardId.ShardId>>
+  /** @internal */
+  readonly refreshAssignments: Effect.Effect<void, never, Scope.Scope>
+  /** @internal */
+  readonly getShardId: (recipientAddress: RecipientAddress.RecipientAddress) => ShardId.ShardId
+}
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export const Tag = internal.shardingTag
+
+/**
+ * @since 1.0.0
+ * @category layers
+ */
+export const live = internal.live
+
+/**
+ * Notify the shard manager that shards can now be assigned to this pod.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const register: Effect.Effect<void, never, Sharding> = internal.register
+
+/**
+ * Notify the shard manager that shards must be unassigned from this pod.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const unregister: Effect.Effect<void, never, Sharding> = internal.unregister
+
+/**
+ * Same as `register`, but will automatically call `unregister` when the `Scope` is terminated.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const registerScoped: Effect.Effect<void, never, Scope.Scope | Sharding> = internal.registerScoped
+
+/**
+ * Start a computation that is guaranteed to run only on a single pod.
+ * Each pod should call `registerSingleton` but only a single pod will actually run it at any given time.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const registerSingleton: <R>(
+  name: string,
+  run: Effect.Effect<void, never, R>
+) => Effect.Effect<void, never, Sharding | R> = internal.registerSingleton
+
+/**
+ * Register a new entity type, allowing pods to send messages to entities of this type.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const registerEntity: <Msg extends Message.Message.Any>(
+  entityType: RecipentType.EntityType<Msg>
+) => <R>(
+  behavior: RecipientBehaviour.RecipientBehaviour<Msg, R>,
+  options?: RecipientBehaviour.EntityBehaviourOptions | undefined
+) => Effect.Effect<void, never, Sharding | Exclude<R, RecipientBehaviourContext.RecipientBehaviourContext>> =
+  internal.registerEntity
+
+/**
+ * Register a new topic type, allowing pods to broadcast messages to subscribers.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const registerTopic: <Msg extends Message.Message.Any>(
+  topicType: RecipentType.TopicType<Msg>
+) => <R>(
+  behavior: RecipientBehaviour.RecipientBehaviour<Msg, R>,
+  options?: RecipientBehaviour.EntityBehaviourOptions | undefined
+) => Effect.Effect<void, never, Sharding | Exclude<R, RecipientBehaviourContext.RecipientBehaviourContext>> =
+  internal.registerTopic
+
+/**
+ * Get an object that allows sending messages to a given entity type.
+ * You can provide a custom send timeout to override the one globally defined.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const messenger: <Msg extends Message.Message.Any>(
+  entityType: RecipentType.EntityType<Msg>
+) => Effect.Effect<Messenger<Msg>, never, Sharding> = internal.messenger
+
+/**
+ * Get an object that allows broadcasting messages to a given topic type.
+ * You can provide a custom send timeout to override the one globally defined.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const broadcaster: <Msg extends Message.Message.Any>(
+  topicType: RecipentType.TopicType<Msg>
+) => Effect.Effect<Broadcaster<Msg>, never, Sharding> = internal.broadcaster
+
+/**
+ * Get the list of pods currently registered to the Shard Manager
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const getPods: Effect.Effect<HashSet.HashSet<PodAddress.PodAddress>, never, Sharding> = internal.getPods
+
+/**
+ * Sends a raw message to the local entity manager without performing reties.
+ * Those are up to the caller.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const sendMessageToLocalEntityManagerWithoutRetries: (
+  message: SerializedEnvelope.SerializedEnvelope
+) => Effect.Effect<
+  MessageState.MessageState<SerializedMessage.SerializedMessage>,
+  ShardingException.ShardingException,
+  Sharding
+> = internal.sendMessageToLocalEntityManagerWithoutRetries
+
+/**
+ * Gets the list of shardIds assigned to the current Pod
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const getAssignedShardIds: Effect.Effect<HashSet.HashSet<ShardId.ShardId>, never, Sharding> =
+  internal.getAssignedShardIds

package/src/ShardingConfig.ts

@@ -0,0 +1,76 @@
+/**
+ * @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"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const ShardingConfigTypeId: unique symbol = internal.ShardingConfigTypeId
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type ShardingConfigTypeId = typeof ShardingConfigTypeId
+
+/**
+ * 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
+ */
+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
+}
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export const ShardingConfig: Context.Tag<ShardingConfig, ShardingConfig> = internal.shardingConfigTag
+
+/**
+ * Provides the default values for the ShardingConfig.
+ *
+ * @since 1.0.0
+ * @category layers
+ */
+export const defaults: Layer.Layer<ShardingConfig> = internal.defaults
+
+/**
+ * Provides the ShardingConfig, values that are omitted will be read from the defaults
+ *
+ * @since 1.0.0
+ * @category layers
+ */
+export const withDefaults: (customs: Partial<ShardingConfig>) => Layer.Layer<ShardingConfig> = internal.withDefaults
+
+/**
+ * Reads the ShardingConfig from the effect/ConfigProvider
+ *
+ * @since 1.0.0
+ * @category layers
+ */
+export const fromConfig: Layer.Layer<ShardingConfig, ConfigError.ConfigError> = internal.fromConfig

package/src/ShardingEvent.ts

@@ -0,0 +1,121 @@
+/**
+ * @since 1.0.0
+ */
+import type * as HashSet from "effect/HashSet"
+import type * as PodAddress from "./PodAddress.js"
+import type * as ShardId from "./ShardId.js"
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface ShardsAssigned {
+  readonly _tag: "ShardsAssigned"
+  readonly pod: PodAddress.PodAddress
+  readonly shards: HashSet.HashSet<ShardId.ShardId>
+}
+
+/**
+ * Constructs the event that occurs when new shards are assigned to Pod.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function ShardsAssigned(
+  pod: PodAddress.PodAddress,
+  shards: HashSet.HashSet<ShardId.ShardId>
+): ShardsAssigned {
+  return { _tag: "ShardsAssigned", pod, shards }
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface ShardsUnassigned {
+  readonly _tag: "ShardsUnassigned"
+  readonly pod: PodAddress.PodAddress
+  readonly shards: HashSet.HashSet<ShardId.ShardId>
+}
+
+/**
+ * Constructs the event that occurs when shards are unassigned to a Pod
+ * @since 1.0.0
+ * @category constructors
+ */
+export function ShardsUnassigned(
+  pod: PodAddress.PodAddress,
+  shards: HashSet.HashSet<ShardId.ShardId>
+): ShardsUnassigned {
+  return { _tag: "ShardsUnassigned", pod, shards }
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface PodHealthChecked {
+  readonly _tag: "PodHealthChecked"
+  readonly pod: PodAddress.PodAddress
+}
+
+/**
+ * Constructs the event that occurs when the health of a Pod has been checked
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function PodHealthChecked(pod: PodAddress.PodAddress): PodHealthChecked {
+  return { _tag: "PodHealthChecked", pod }
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface PodRegistered {
+  readonly _tag: "PodRegistered"
+  readonly pod: PodAddress.PodAddress
+}
+
+/**
+ * Constructs the event that occurs when a new Pod has registered
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function PodRegistered(pod: PodAddress.PodAddress): PodRegistered {
+  return { _tag: "PodRegistered", pod }
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface PodUnregistered {
+  readonly _tag: "PodUnregistered"
+  readonly pod: PodAddress.PodAddress
+}
+
+/**
+ * Constructs the event that occurs when a pod has unregistered
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function PodUnregistered(pod: PodAddress.PodAddress): PodUnregistered {
+  return { _tag: "PodUnregistered", pod }
+}
+
+/**
+ * This are the events that may occur over the ShardManager during its lifetime.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type ShardingEvent =
+  | ShardsAssigned
+  | ShardsUnassigned
+  | PodHealthChecked
+  | PodRegistered
+  | PodUnregistered

package/src/ShardingException.ts

@@ -0,0 +1,151 @@
+/**
+ * @since 1.0.0
+ */
+import * as Schema from "@effect/schema/Schema"
+import * as PodAddress from "./PodAddress.js"
+import * as RecipientAddress from "./RecipientAddress.js"
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export class EntityNotManagedByThisPodException extends Schema.TaggedError<EntityNotManagedByThisPodException>()(
+  "@effect/cluster/EntityNotManagedByThisPodException",
+  {
+    recipientAddress: RecipientAddress.RecipientAddress
+  }
+) {
+}
+
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export const isEntityNotManagedByThisPodException = Schema.is(EntityNotManagedByThisPodException)
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export class EntityTypeNotRegisteredException extends Schema.TaggedError<EntityTypeNotRegisteredException>()(
+  "@effect/cluster/EntityTypeNotRegisteredException",
+  {
+    entityType: Schema.String,
+    podAddress: PodAddress.schema
+  }
+) {
+}
+
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export const isEntityTypeNotRegisteredException = Schema.is(EntityTypeNotRegisteredException)
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export class NoResultInProcessedMessageStateException
+  extends Schema.TaggedError<NoResultInProcessedMessageStateException>()(
+    "@effect/cluster/NoResultInProcessedMessageStateException",
+    {}
+  )
+{
+}
+
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export const isNoResultInProcessedMessageStateException = Schema.is(NoResultInProcessedMessageStateException)
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export class PodNoLongerRegisteredException extends Schema.TaggedError<PodNoLongerRegisteredException>()(
+  "@effect/cluster/PodNoLongerRegisteredException",
+  {
+    podAddress: PodAddress.schema
+  }
+) {
+}
+
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export const isPodNoLongerRegisteredException = Schema.is(PodNoLongerRegisteredException)
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export class PodUnavailableException extends Schema.TaggedError<PodUnavailableException>()(
+  "@effect/cluster/PodUnavailableException",
+  {
+    podAddress: PodAddress.schema
+  }
+) {
+}
+
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export const isPodUnavailableException = Schema.is(PodUnavailableException)
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export class SerializationException extends Schema.TaggedError<SerializationException>()(
+  "@effect/cluster/SerializationException",
+  {}
+) {
+}
+
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export const isSerializationException = Schema.is(SerializationException)
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export class ExceptionWhileOfferingMessageException
+  extends Schema.TaggedError<ExceptionWhileOfferingMessageException>()(
+    "@effect/cluster/ExceptionWhileOfferingMessageException",
+    {}
+  )
+{
+}
+
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export const isExceptionWhileOfferingMessageException = Schema.is(ExceptionWhileOfferingMessageException)
+
+/**
+ * @since 1.0.0
+ * @category schema
+ */
+export const schema = Schema.Union(
+  SerializationException,
+  EntityNotManagedByThisPodException,
+  EntityTypeNotRegisteredException,
+  PodNoLongerRegisteredException,
+  PodUnavailableException,
+  NoResultInProcessedMessageStateException,
+  ExceptionWhileOfferingMessageException
+)
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export type ShardingException = Schema.Schema.Type<typeof schema>