@effect/cluster 0.0.0-snapshot-d33d8b050b8e3c87dcde9587083e6c1cf733f72b

package/src/MessageState.ts

@@ -0,0 +1,126 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Schema from "@effect/schema/Schema"
+import type * as Effect from "effect/Effect"
+import * as internal from "./internal/messageState.js"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const MessageStateTypeId: unique symbol = internal.MessageStateTypeId
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type MessageStateTypeId = typeof MessageStateTypeId
+
+/**
+ * A message state given to just acknowledged messages.
+ * This state tells the sender that the receiver has received the message and will eventually process it later.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface MessageStateAcknowledged {
+  readonly [MessageStateTypeId]: MessageStateTypeId
+  readonly _tag: "@effect/cluster/MessageState/Acknowledged"
+}
+
+/**
+ * A message state given to processed messages.
+ * This state tells the sender that the receiver has already received and processed the message.
+ * This will also tell the sender the result for this message.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface MessageStateProcessed<A> {
+  readonly [MessageStateTypeId]: MessageStateTypeId
+  readonly _tag: "@effect/cluster/MessageState/Processed"
+  readonly result: A
+}
+
+/**
+ * Once a Message is sent to an entity to be processed,
+ * the state of that message over that entity is either Acknoledged (not yet processed) or Processed.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type MessageState<A> = MessageStateAcknowledged | MessageStateProcessed<A>
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export namespace MessageState {
+  /**
+   * @since 1.0.0
+   * @category models
+   */
+  export type Encoded<I> = {
+    readonly "@effect/cluster/MessageState": "@effect/cluster/MessageState"
+    readonly _tag: "@effect/cluster/MessageState/Acknowledged"
+  } | {
+    readonly result: I
+    readonly "@effect/cluster/MessageState": "@effect/cluster/MessageState"
+    readonly _tag: "@effect/cluster/MessageState/Processed"
+  }
+}
+
+/**
+ * Ensures that the given value is a MessageState
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const isMessageState = internal.isMessageState
+
+/**
+ * Match over the possible states of a MessageState
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const match = internal.match
+
+/**
+ * Constructs an AcknowledgedMessageState.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const Acknowledged: MessageStateAcknowledged = internal.Acknowledged
+
+/**
+ * Constructs a ProcessedMessageState from the result of the message being processed.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const Processed: <A>(result: A) => MessageStateProcessed<A> = internal.Processed
+
+/**
+ * Effectfully transform the <A> type of the MessageState<A>.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const mapEffect: <A, B, R, E>(
+  value: MessageState<A>,
+  fn: (value: A) => Effect.Effect<B, E, R>
+) => Effect.Effect<MessageState<B>, E, R> = internal.mapEffect
+
+/**
+ * @since 1.0.0
+ * @category schema
+ */
+export const schema: <A, I>(
+  result: Schema.Schema<A, I>
+) => Schema.Schema<
+  MessageState<A>,
+  MessageState.Encoded<I>
+> = internal.schema

package/src/Messenger.ts

@@ -0,0 +1,40 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Effect from "effect/Effect"
+import type * as Message from "./Message.js"
+import type * as ShardingException from "./ShardingException.js"
+
+/**
+ * An interface to communicate with a remote entity.
+ *
+ * @tparam Msg the type of message that can be sent to this entity type
+ * @since 1.0.0
+ * @category models
+ */
+export interface Messenger<Msg extends Message.Message.Any> {
+  /**
+   * Send a message without waiting for a response (fire and forget)
+   *
+   * You can use Effect timeout to get send timeouts. The default behaviour is to send the message indifinetely
+   *
+   * @since 1.0.0
+   */
+  sendDiscard(entityId: string): (message: Msg) => Effect.Effect<void, ShardingException.ShardingException>
+
+  /**
+   * Send a message and wait for a response.
+   *
+   * You can use Effect timeout to get send timeouts. The default behaviour is to send the message indifinetely
+   *
+   * @since 1.0.0
+   */
+  send(
+    entityId: string
+  ): <A extends Msg>(
+    message: A
+  ) => Effect.Effect<
+    Message.Message.Success<A>,
+    ShardingException.ShardingException | Message.Message.Error<A>
+  >
+}

package/src/Pod.ts

@@ -0,0 +1,95 @@
+/**
+ * @since 1.0.0
+ */
+import * as Schema from "@effect/schema/Schema"
+import { TypeIdSchema } from "./internal/utils.js"
+import * as PodAddress from "./PodAddress.js"
+
+/** @internal */
+const PodSymbolKey = "@effect/cluster/Pod"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const PodTypeId: unique symbol = Symbol.for(PodSymbolKey)
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type PodTypeId = typeof PodTypeId
+
+/** @internal */
+const PodTypeIdSchema = TypeIdSchema(PodSymbolKey, PodTypeId)
+
+/**
+ * A pod is an application server that is able to run entities. A pod can run multiple entities,
+ * but a single entity will live on a given pod at a time.
+ * Since this is an application server, it needs to have an unique identifier where it's addressed (PodAddress),
+ * and has a version of the application that's running on it.
+ * Version is used during the rebalance phase to give priority to newer application servers and slowly kill older ones.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class Pod extends Schema.Class<Pod>(PodSymbolKey)({
+  [PodTypeId]: Schema.propertySignature(PodTypeIdSchema).pipe(Schema.fromKey(PodSymbolKey)),
+  address: PodAddress.schema,
+  version: Schema.String
+}) {
+  /**
+   * @since 1.0.0
+   */
+  toString() {
+    return `Pod(${this.address}, ${this.version})`
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export namespace Pod {
+  /**
+   * This is the shape that a Pod is represented over the wire.
+   *
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Encoded extends Schema.Schema.Encoded<typeof Pod> {}
+}
+
+/**
+ * Given a value, ensures that it's a valid Pod.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export function isPod(value: unknown): value is Pod {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    PodTypeId in value &&
+    value[PodTypeId] === PodTypeId
+  )
+}
+
+/**
+ * Constructs a Pod from it's identifing PodAddress and application server version.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function make(address: PodAddress.PodAddress, version: string): Pod {
+  return new Pod({ [PodTypeId]: PodTypeId, address, version })
+}
+
+/**
+ * @since 1.0.0
+ * @category schema
+ */
+export const schema: Schema.Schema<
+  Pod,
+  Pod.Encoded
+> = Schema.asSchema(Pod)

package/src/PodAddress.ts

@@ -0,0 +1,94 @@
+/**
+ * @since 1.0.0
+ */
+import * as Schema from "@effect/schema/Schema"
+import { TypeIdSchema } from "./internal/utils.js"
+
+/** @internal */
+const PodAddressSymbolKey = "@effect/cluster/PodAddress"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const PodAddressTypeId: unique symbol = Symbol.for(PodAddressSymbolKey)
+
+/** @internal */
+export const PodAddressTypeIdSchema = TypeIdSchema(PodAddressSymbolKey, PodAddressTypeId)
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type PodAddressTypeId = typeof PodAddressTypeId
+
+/**
+ * A PodAddress is a unique identifier of a Pod (application server).
+ * It is conventially built by using an address and a port, so that messaging implementations may use directly the
+ * PodAddress to know how to connect to the specific Pod.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class PodAddress extends Schema.Class<PodAddress>(PodAddressSymbolKey)({
+  [PodAddressTypeId]: Schema.propertySignature(PodAddressTypeIdSchema).pipe(Schema.fromKey(PodAddressSymbolKey)),
+  host: Schema.String,
+  port: Schema.Number
+}) {
+  /**
+   * @since 1.0.0
+   */
+  toString() {
+    return `PodAddress(${this.host}:${this.port})`
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export namespace PodAddress {
+  /**
+   * This is the shape one PodAddress has over the wire.
+   *
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Encoded extends Schema.Schema.Encoded<typeof PodAddress> {}
+}
+
+/**
+ * Constructs a PodAddress from an host and a port.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function make(host: string, port: number): PodAddress {
+  return new PodAddress({ [PodAddressTypeId]: PodAddressTypeId, host, port })
+}
+
+/**
+ * Ensures that the given value is a valid PodAddress.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export function isPodAddress(value: unknown): value is PodAddress {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    PodAddressTypeId in value &&
+    value[PodAddressTypeId] === PodAddressTypeId
+  )
+}
+
+/**
+ * This is the schema for a PodAddress.
+ *
+ * @since 1.0.0
+ * @category schema
+ */
+export const schema: Schema.Schema<
+  PodAddress,
+  PodAddress.Encoded
+> = Schema.asSchema(PodAddress)

package/src/Pods.ts

@@ -0,0 +1,100 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as HashSet from "effect/HashSet"
+import type * as Layer from "effect/Layer"
+import * as internal from "./internal/pods.js"
+import type * as MessageState from "./MessageState.js"
+import type * as PodAddress from "./PodAddress.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"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const PodsTypeId: unique symbol = internal.PodsTypeId
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type PodsTypeId = typeof PodsTypeId
+
+/**
+ * An interface to communicate with remote pods.
+ * This is used by the Shard Manager for assigning and unassigning shards.
+ * This is also used by pods for internal communication (forward messages to each other).
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Pods {
+  /**
+   * @since 1.0.0
+   */
+  readonly [PodsTypeId]: PodsTypeId
+
+  /**
+   * Notify a pod that it was assigned a list of shards
+   * @since 1.0.0
+   */
+  readonly assignShards: (
+    pod: PodAddress.PodAddress,
+    shards: HashSet.HashSet<ShardId.ShardId>
+  ) => Effect.Effect<void, ShardingException.PodUnavailableException>
+
+  /**
+   * Notify a pod that it was unassigned a list of shards
+   * @since 1.0.0
+   */
+  readonly unassignShards: (
+    pod: PodAddress.PodAddress,
+    shards: HashSet.HashSet<ShardId.ShardId>
+  ) => Effect.Effect<void, ShardingException.PodUnavailableException>
+
+  /**
+   * Check that a pod is responsive
+   * @since 1.0.0
+   */
+  readonly ping: (pod: PodAddress.PodAddress) => Effect.Effect<void, ShardingException.PodUnavailableException>
+
+  /**
+   * Send a message to a pod and receive its message state
+   * @since 1.0.0
+   */
+  readonly sendAndGetState: (
+    pod: PodAddress.PodAddress,
+    envelope: SerializedEnvelope.SerializedEnvelope
+  ) => Effect.Effect<
+    MessageState.MessageState<SerializedMessage.SerializedMessage>,
+    ShardingException.ShardingException
+  >
+}
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export const Pods: Context.Tag<Pods, Pods> = internal.podsTag
+
+/**
+ * Constructs a Pods service from its implementation
+ *
+ * @since 1.0.0
+ * @category context
+ */
+export const make: (args: Omit<Pods, typeof PodsTypeId>) => Pods = internal.make
+
+/**
+ * A layer that creates a service that does nothing when called.
+ * Useful for testing ShardManager or when using Sharding.local.
+ *
+ * @since 1.0.0
+ * @category layers
+ */
+export const noop: Layer.Layer<Pods> = internal.noop

package/src/PodsHealth.ts

@@ -0,0 +1,74 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import type * as Layer from "effect/Layer"
+import * as internal from "./internal/podsHealth.js"
+import type * as PodAddress from "./PodAddress.js"
+import type * as Pods from "./Pods.js"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const PodsHealthTypeId: unique symbol = internal.PodsHealthTypeId
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type PodsHealthTypeId = typeof PodsHealthTypeId
+
+/**
+ * An interface to check a pod's health.
+ * This is used when a pod is unresponsive, to check if it should be unassigned all its shards or not.
+ * If the pod is alive, shards will not be unassigned because the pods might still be processing messages and might be responsive again.
+ * If the pod is not alive, shards can be safely reassigned somewhere else.
+ * A typical implementation for this is using k8s to check if the pod still exists.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface PodsHealth {
+  /**
+   * @since 1.0.0
+   */
+  readonly [PodsHealthTypeId]: PodsHealthTypeId
+
+  /**
+   * Check if a pod is still alive.
+   * @since 1.0.0
+   */
+  readonly isAlive: (podAddress: PodAddress.PodAddress) => Effect.Effect<boolean>
+}
+
+/**
+ * Constructs a PodsHealth from its implementation
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make: (args: Omit<PodsHealth, typeof PodsHealthTypeId>) => PodsHealth = internal.make
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export const PodsHealth: Context.Tag<PodsHealth, PodsHealth> = internal.podsHealthTag
+
+/**
+ * A layer that considers pods as always alive.
+ * This is useful for testing only.
+ * @since 1.0.0
+ * @category layers
+ */
+export const noop: Layer.Layer<PodsHealth> = internal.noop
+
+/**
+ * A layer that pings the pod directly to check if it's alive.
+ * This is useful for developing and testing but not reliable in production.
+ * @since 1.0.0
+ * @category layers
+ */
+export const local: Layer.Layer<PodsHealth, never, Pods.Pods> = internal.local

package/src/PoisonPill.ts

@@ -0,0 +1,105 @@
+/**
+ * @since 1.0.0
+ */
+import * as Schema from "@effect/schema/Schema"
+import * as Effect from "effect/Effect"
+import { pipe } from "effect/Function"
+import * as Queue from "effect/Queue"
+import { TypeIdSchema } from "./internal/utils.js"
+
+/** @internal */
+const PoisonPillSymbolKey = "@effect/cluster/PoisonPill"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const PoisonPillTypeId: unique symbol = Symbol.for(PoisonPillSymbolKey)
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type PoisonPillTypeId = typeof PoisonPillTypeId
+
+/** @internal */
+const PoisonPillTypeIdSchema = TypeIdSchema(PoisonPillSymbolKey, PoisonPillTypeId)
+
+/**
+ * @since 1.0.0
+ */
+export namespace PoisonPill {
+  /**
+   * This is the shape that a PoisonPill takes over the wire.
+   *
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Encoded extends Schema.Schema.Encoded<typeof PoisonPill> {}
+}
+
+/**
+ * A PoisonPill is a special value that tells a behaviour entity to shut itself down.
+ * PoisonPill is handled only when you are using a Queue-based RecipientBehaviour.
+ * Other RecipientBehaviour such as fromFunctionEffect would not care about PoisonPill.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class PoisonPill extends Schema.Class<PoisonPill>(PoisonPillSymbolKey)({
+  [PoisonPillTypeId]: Schema.propertySignature(PoisonPillTypeIdSchema).pipe(Schema.fromKey(PoisonPillSymbolKey))
+}) {
+}
+
+/**
+ * Constructs a new PosionPill
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make: Effect.Effect<PoisonPill> = Effect.succeed(
+  new PoisonPill({ [PoisonPillTypeId]: PoisonPillTypeId })
+)
+
+/**
+ * Checks if the given value is a PoisonPill.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export function isPoisonPill(value: unknown): value is PoisonPill {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    PoisonPillTypeId in value &&
+    value[PoisonPillTypeId] === PoisonPillTypeId
+  )
+}
+
+/**
+ * This is the schema for a PoisonPill that is used to encode the value over the wire.
+ * This is useful if you want a behavior that can be shut down from an external message.
+ *
+ * @since 1.0.0
+ * @category schema
+ */
+export const schema: Schema.Schema<
+  PoisonPill,
+  PoisonPill.Encoded
+> = Schema.asSchema(PoisonPill)
+
+/**
+ * Attempts to take a message from the queue in the same way Queue.take does.
+ * If the result is a PoisonPill, it will interrupt the effect.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export function takeOrInterrupt<Req>(
+  dequeue: Queue.Dequeue<Req | PoisonPill>
+): Effect.Effect<Req> {
+  return pipe(
+    Queue.take(dequeue),
+    Effect.flatMap((msg) => isPoisonPill(msg) ? Effect.interrupt : Effect.succeed(msg))
+  )
+}

package/src/RecipientAddress.ts

@@ -0,0 +1,72 @@
+/**
+ * @since 1.0.0
+ */
+import * as Schema from "@effect/schema/Schema"
+import * as Equal from "effect/Equal"
+import * as Hash from "effect/Hash"
+import { TypeIdSchema } from "./internal/utils.js"
+
+const RecipientAddressSymbolKey = "@effect/cluster/RecipientAddress"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const RecipientAddressTypeId: unique symbol = Symbol.for(RecipientAddressSymbolKey)
+
+/** @internal */
+const RecipientAddressTypeIdSchema = TypeIdSchema(RecipientAddressSymbolKey, RecipientAddressTypeId)
+
+/**
+ * A RecipientAddress uniquely identifies a RecipientType + EntityId instance.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class RecipientAddress extends Schema.Class<RecipientAddress>(RecipientAddressSymbolKey)({
+  [RecipientAddressTypeId]: Schema.propertySignature(RecipientAddressTypeIdSchema).pipe(
+    Schema.fromKey(RecipientAddressSymbolKey)
+  ),
+  recipientTypeName: Schema.String,
+  entityId: Schema.String
+}) {
+  /**
+   * @since 1.0.0
+   */
+  [Hash.symbol](): number {
+    return Hash.structure({ recipientTypeName: this.recipientTypeName, entityId: this.entityId })
+  }
+
+  /**
+   * @since 1.0.0
+   */
+  [Equal.symbol](this: RecipientAddress, that: Equal.Equal): boolean {
+    if (isRecipientAddress(that)) {
+      return this.recipientTypeName === that.recipientTypeName && this.entityId === that.entityId
+    }
+    return false
+  }
+}
+
+/**
+ * Ensure that given value is a RecipientAddress
+ * @since 1.0.0
+ * @category constructors
+ */
+export function isRecipientAddress(value: unknown): value is RecipientAddress {
+  return typeof value === "object" && value !== null && RecipientAddressTypeId in value &&
+    value[RecipientAddressTypeId] === RecipientAddressTypeId
+}
+
+/**
+ * Given a name and a schema for the protocol, constructs an EntityType.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeRecipientAddress(
+  recipientTypeName: string,
+  entityId: string
+): RecipientAddress {
+  return new RecipientAddress({ [RecipientAddressTypeId]: RecipientAddressTypeId, recipientTypeName, entityId })
+}