@effect/cluster 0.0.0-snapshot-d33d8b050b8e3c87dcde9587083e6c1cf733f72b

package/src/RecipientBehaviour.ts

@@ -0,0 +1,108 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Message from "@effect/cluster/Message"
+import type * as Duration from "effect/Duration"
+import type * as Effect from "effect/Effect"
+import type * as Option from "effect/Option"
+import type * as Queue from "effect/Queue"
+import type * as Ref from "effect/Ref"
+import type * as Scope from "effect/Scope"
+import * as internal from "./internal/recipientBehaviour.js"
+import type * as MessageState from "./MessageState.js"
+import type * as PoisonPill from "./PoisonPill.js"
+import type * as RecipientBehaviourContext from "./RecipientBehaviourContext.js"
+import type * as ShardingException from "./ShardingException.js"
+
+/**
+ * A RecipientBehaviour describes how a specific RecipientType should behave.
+ * This is the actual implementation of what an entity should do upon receiving a Msg,
+ * this could require additional context.
+ *
+ * The scope provided in the context is controlled by the cluster EntityManager,
+ * and is used to request the shoutdown of the entity,
+ * so you can safely scope whatever resource you want to use for your behaviour
+ *  and the EntityManager will close the scope for you when the entity is shoutdown.
+ *
+ * The function returned by the RecipientBehaviour effect is what we call "offer" effect.
+ * The offer effect is used by the EntityManager to give messages to the RecipientBehaviour.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface RecipientBehaviour<Msg, R> extends
+  Effect.Effect<
+    <A extends Msg>(
+      message: A
+    ) => Effect.Effect<
+      MessageState.MessageState<Message.Message.Exit<A>>,
+      ShardingException.ExceptionWhileOfferingMessageException
+    >,
+    never,
+    R | RecipientBehaviourContext.RecipientBehaviourContext | Scope.Scope
+  >
+{}
+
+/**
+ * This are the options for an EntityBehaviour. This controls the entityMaxIdleTime,
+ * check out more on that over the ShardingConfig.
+ * This allows to override the setting for a specific entity.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export type EntityBehaviourOptions = {
+  entityMaxIdleTime?: Option.Option<Duration.Duration>
+}
+
+/**
+ * This is the simplest behaviour you can have.
+ * You provide a function that given the entityId and the message, it will immediatly process it.
+ * You are then required to return a MessageState to tell the caller
+ * if the message has just arrived and will be later processed or it has been processed.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const fromFunctionEffect: <Msg extends Message.Message.Any, R>(
+  handler: (
+    entityId: string,
+    message: Msg
+  ) => Effect.Effect<MessageState.MessageState<Message.Message.Exit<Msg>>, never, R>
+) => RecipientBehaviour<Msg, R> = internal.fromFunctionEffect
+
+/**
+ * This is a stateful version of fromFunctionEffect.
+ * You can provide a function to get the initialState, and then it will be passed as Ref.
+ * Everything here is just stored in memory, so eventual persistence of the state is up to you!
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const fromFunctionEffectStateful: <S, R, Msg extends Message.Message.Any, R2>(
+  initialState: (entityId: string) => Effect.Effect<S, never, R>,
+  handler: (
+    entityId: string,
+    message: Msg,
+    stateRef: Ref.Ref<S>
+  ) => Effect.Effect<MessageState.MessageState<Message.Message.Exit<Msg>>, never, R2>
+) => RecipientBehaviour<Msg, R | R2> = internal.fromFunctionEffectStateful
+
+/**
+ * This behaviour uses a Queue where the entity will accumulate messages to be processed,
+ * and then you can use the Dequeue to take messages and process them.
+ * A PoisonPill is provided to request interruption of the entity behaviour.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const fromInMemoryQueue: <Msg extends Message.Message.Any, R>(
+  handler: (
+    entityId: string,
+    dequeue: Queue.Dequeue<Msg | PoisonPill.PoisonPill>,
+    processed: <A extends Msg>(
+      message: A,
+      value: Option.Option<Message.Message.Exit<A>>
+    ) => Effect.Effect<void, never, never>
+  ) => Effect.Effect<void, never, R>
+) => RecipientBehaviour<Msg, R> = internal.fromInMemoryQueue

package/src/RecipientBehaviourContext.ts

@@ -0,0 +1,101 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
+import * as internal from "./internal/recipientBehaviourContext.js"
+import type * as Message from "./Message.js"
+import type * as RecipientAddress from "./RecipientAddress.js"
+import type * as RecipientType from "./RecipientType.js"
+import type * as ShardId from "./ShardId.js"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const RecipientBehaviourContextTypeId: unique symbol = internal.RecipientBehaviourContextTypeId
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type RecipientBehaviourContextTypeId = typeof RecipientBehaviourContextTypeId
+
+/**
+ * This is the context information that is available to the RecipientBehaviour and has general informations
+ * about this specific entity, like the entityId or the recipientType.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface RecipientBehaviourContext {
+  readonly [RecipientBehaviourContextTypeId]: RecipientBehaviourContextTypeId
+  readonly recipientAddress: RecipientAddress.RecipientAddress
+  readonly shardId: ShardId.ShardId
+  readonly recipientType: RecipientType.RecipientType<Message.Message.Any>
+  readonly forkShutdown: Effect.Effect<void>
+}
+
+/**
+ * A tag to access current RecipientBehaviourContext
+ *
+ * @since 1.0.0
+ * @category context
+ */
+export const RecipientBehaviourContext: Context.Tag<RecipientBehaviourContext, RecipientBehaviourContext> =
+  internal.recipientBehaviourContextTag
+
+/**
+ * Creates a new RecipientBehaviourContext
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make: (
+  args: Omit<RecipientBehaviourContext, typeof RecipientBehaviourContextTypeId>
+) => RecipientBehaviourContext = internal.make
+
+/**
+ * Gets the current entityId
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const entityId: Effect.Effect<string, never, RecipientBehaviourContext> = internal.entityId
+
+/**
+ * Gets the current entityId
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const recipientAddress: Effect.Effect<RecipientAddress.RecipientAddress, never, RecipientBehaviourContext> =
+  internal.recipientAddress
+
+/**
+ * Gets the current shardId
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const shardId: Effect.Effect<ShardId.ShardId, never, RecipientBehaviourContext> = internal.shardId
+
+/**
+ * Gets the current recipientType
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const recipientType: Effect.Effect<
+  RecipientType.RecipientType<Message.Message.Any>,
+  never,
+  RecipientBehaviourContext
+> = internal.recipientType
+
+/**
+ * Forks the shutdown of the current recipient behaviour as soon as possible.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export const forkShutdown: Effect.Effect<void, never, RecipientBehaviourContext> = internal.forkShutdown

package/src/RecipientType.ts

@@ -0,0 +1,134 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Schema from "@effect/schema/Schema"
+import * as Data from "effect/Data"
+import * as Equal from "effect/Equal"
+import * as Hash from "effect/Hash"
+import type * as Message from "./Message.js"
+import * as ShardId from "./ShardId.js"
+
+const RecipientTypeSymbolKey = "@effect/cluster/RecipientType"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const RecipientTypeTypeId: unique symbol = Symbol.for(RecipientTypeSymbolKey)
+
+/**
+ * An EntityType is a RecipientType that is ensured to be alive only on a single Pod at a time.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class EntityType<Msg extends Message.Message.Any> extends Data.TaggedClass("EntityType")<{
+  readonly name: string
+  readonly schema: Schema.Schema<Msg, unknown>
+}> {
+  /**
+   * @since 1.0.0
+   */
+  readonly [RecipientTypeTypeId] = RecipientTypeTypeId;
+
+  /**
+   * @since 1.0.0
+   */
+  [Hash.symbol](): number {
+    return Hash.structure({ _tag: this._tag, name: this.name })
+  }
+
+  /**
+   * @since 1.0.0
+   */
+  [Equal.symbol](this: TopicType<Msg>, that: Equal.Equal): boolean {
+    if (isRecipientType(that)) {
+      return this._tag === that._tag && this.name === that.name
+    }
+    return false
+  }
+}
+
+/**
+ * A TopicType can live on multiple Pods at the same time.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class TopicType<Msg extends Message.Message.Any> extends Data.TaggedClass("TopicType")<{
+  readonly name: string
+  readonly schema: Schema.Schema<Msg, unknown>
+}> {
+  /**
+   * @since 1.0.0
+   */
+  readonly [RecipientTypeTypeId] = RecipientTypeTypeId;
+
+  /**
+   * @since 1.0.0
+   */
+  [Hash.symbol](): number {
+    return Hash.structure({ _tag: this._tag, name: this.name })
+  }
+
+  /**
+   * @since 1.0.0
+   */
+  [Equal.symbol](this: EntityType<Msg>, that: Equal.Equal): boolean {
+    if (isRecipientType(that)) {
+      return this._tag === that._tag && this.name === that.name
+    }
+    return false
+  }
+}
+
+/**
+ * A RecipientType is basically a pointer to a logical grouping of multiple enties having the same RecipientBehaviour.
+ * This value is required to be able to message with an entity/topic since it holds the Schema for the messages over the wire.
+ * Without the schema, you cannot ensure that the messages sent are what the receiver expects.
+ * Ideally, you can share this definition between the caller and the receiver.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export type RecipientType<Msg extends Message.Message.Any> = EntityType<Msg> | TopicType<Msg>
+
+/**
+ * Ensure that given value is a RecipientType
+ * @since 1.0.0
+ * @category constructors
+ */
+export function isRecipientType<A extends Message.Message.Any>(value: unknown): value is RecipientType<A> {
+  return typeof value === "object" && value !== null && RecipientTypeTypeId in value &&
+    value[RecipientTypeTypeId] === RecipientTypeTypeId
+}
+
+/**
+ * Given a name and a schema for the protocol, constructs an EntityType.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeEntityType<Msg extends Message.Message.Any, I>(
+  name: string,
+  schema: Schema.Schema<Msg, I>
+): EntityType<Msg> {
+  return new EntityType({ name, schema: schema as any })
+}
+
+/**
+ * Given a name and a schema for the protocol, constructs an TopicType.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function makeTopicType<Msg extends Message.Message.Any, I>(
+  name: string,
+  schema: Schema.Schema<Msg, I>
+): TopicType<Msg> {
+  return new TopicType({ name, schema: schema as any })
+}
+
+/** @internal */
+export const getShardId = (entityId: string, numberOfShards: number): ShardId.ShardId =>
+  ShardId.make(Math.abs(Hash.string(entityId) % numberOfShards) + 1)

package/src/Serialization.ts

@@ -0,0 +1,72 @@
+/**
+ * @since 1.0.0
+ */
+import type * as Schema from "@effect/schema/Schema"
+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/serialization.js"
+import type * as SerializedMessage from "./SerializedMessage.js"
+import type * as ShardingException from "./ShardingException.js"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const SerializationTypeId: unique symbol = internal.SerializationTypeId
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type SerializationTypeId = typeof SerializationTypeId
+
+/**
+ * An interface to serialize user messages that will be sent between pods.
+ * @since 1.0.0
+ * @category models
+ */
+export interface Serialization {
+  /**
+   * @since 1.0.0
+   */
+  readonly [SerializationTypeId]: SerializationTypeId
+
+  /**
+   * Transforms the given message into binary
+   * @since 1.0.0
+   */
+  readonly encode: <A, I>(
+    schema: Schema.Schema<A, I>,
+    message: A
+  ) => Effect.Effect<SerializedMessage.SerializedMessage, ShardingException.SerializationException>
+
+  /**
+   * Transform binary back into the given type
+   * @since 1.0.0
+   */
+  readonly decode: <A, I>(
+    schema: Schema.Schema<A, I>,
+    bytes: SerializedMessage.SerializedMessage
+  ) => Effect.Effect<A, ShardingException.SerializationException>
+}
+
+/**
+ * @since 1.0.0
+ * @category context
+ */
+export const Serialization: Context.Tag<Serialization, Serialization> = internal.serializationTag
+
+/**
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make: (args: Omit<Serialization, typeof SerializationTypeId>) => Serialization = internal.make
+
+/**
+ * A layer that uses JSON serialization for encoding and decoding messages.
+ * This is useful for testing and not recommended to use in production.
+ * @since 1.0.0
+ * @category layers
+ */
+export const json: Layer.Layer<Serialization> = internal.json

package/src/SerializedEnvelope.ts

@@ -0,0 +1,109 @@
+/**
+ * @since 1.0.0
+ */
+import * as Schema from "@effect/schema/Schema"
+import * as Serializable from "@effect/schema/Serializable"
+import * as PrimaryKey from "effect/PrimaryKey"
+import { TypeIdSchema } from "./internal/utils.js"
+import * as RecipientAddress from "./RecipientAddress.js"
+import * as SerializedMessage from "./SerializedMessage.js"
+
+/** @internal */
+const SerializedEnvelopeSymbolKey = "@effect/cluster/SerializedEnvelope"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const SerializedEnvelopeTypeId: unique symbol = Symbol.for(SerializedEnvelopeSymbolKey)
+
+/** @internal */
+const SerializedEnvelopeTypeIdSchema = TypeIdSchema(SerializedEnvelopeSymbolKey, SerializedEnvelopeTypeId)
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type SerializedEnvelopeTypeId = typeof SerializedEnvelopeTypeId
+
+/**
+ * A SerializedEnvelope is the message that goes over the wire between pods.
+ * Inside the Envelope, you have the encoded messages, plus some informations on where it should be routed to.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class SerializedEnvelope extends Schema.Class<SerializedEnvelope>(SerializedEnvelopeSymbolKey)({
+  [SerializedEnvelopeTypeId]: Schema.propertySignature(SerializedEnvelopeTypeIdSchema).pipe(
+    Schema.fromKey(SerializedEnvelopeSymbolKey)
+  ),
+  recipientAddress: RecipientAddress.RecipientAddress,
+  messageId: Schema.String,
+  body: SerializedMessage.schema
+}) {
+  get [Serializable.symbol]() {
+    return this.constructor
+  }
+  get [Serializable.symbolResult]() {
+    return { Success: Schema.Void, Failure: Schema.Never }
+  }
+  get [PrimaryKey.symbol]() {
+    return this.messageId + "@" + this.recipientAddress.recipientTypeName + "#" + this.recipientAddress.entityId
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export namespace SerializedEnvelope {
+  /**
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Encoded extends Schema.Schema.Encoded<typeof SerializedEnvelope> {}
+}
+
+/**
+ * Construct a new `SerializedEnvelope`
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function make(
+  recipientAddress: RecipientAddress.RecipientAddress,
+  messageId: string,
+  body: SerializedMessage.SerializedMessage
+): SerializedEnvelope {
+  return new SerializedEnvelope({
+    [SerializedEnvelopeTypeId]: SerializedEnvelopeTypeId,
+    messageId,
+    recipientAddress,
+    body
+  })
+}
+
+/**
+ * Ensures that the given value is a SerializedEnvelope.
+ *
+ * @since 1.0.0
+ * @category utils
+ */
+export function isSerializedEnvelope(value: unknown): value is SerializedEnvelope {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    SerializedEnvelopeTypeId in value &&
+    value[SerializedEnvelopeTypeId] === SerializedEnvelopeTypeId
+  )
+}
+
+/**
+ * This is the schema for a value.
+ *
+ * @since 1.0.0
+ * @category schema
+ */
+export const schema: Schema.Schema<SerializedEnvelope, SerializedEnvelope.Encoded, never> = Schema.asSchema(
+  SerializedEnvelope
+)

package/src/SerializedMessage.ts

@@ -0,0 +1,82 @@
+/**
+ * @since 1.0.0
+ */
+import * as Schema from "@effect/schema/Schema"
+import { TypeIdSchema } from "./internal/utils.js"
+
+/** @internal */
+const SerializedMessageSymbolKey = "@effect/cluster/SerializedMessage"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const SerializedMessageTypeId: unique symbol = Symbol.for(SerializedMessageSymbolKey)
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type SerializedMessageTypeId = typeof SerializedMessageTypeId
+
+/** @internal */
+const SerializedMessageTypeIdSchema = TypeIdSchema(SerializedMessageSymbolKey, SerializedMessageTypeId)
+
+/**
+ * Represents a Message that has been serialized.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class SerializedMessage extends Schema.Class<SerializedMessage>(SerializedMessageSymbolKey)({
+  [SerializedMessageTypeId]: Schema.propertySignature(SerializedMessageTypeIdSchema).pipe(
+    Schema.fromKey(SerializedMessageSymbolKey)
+  ),
+  value: Schema.String
+}) {}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export namespace SerializedMessage {
+  /**
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Encoded extends Schema.Schema.Encoded<typeof SerializedMessage> {}
+}
+
+/**
+ * Construct a new `SerializedMessage` from its internal string value.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function make(value: string): SerializedMessage {
+  return new SerializedMessage({ [SerializedMessageTypeId]: SerializedMessageTypeId, value })
+}
+
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export function isSerializedMessage(value: unknown): value is SerializedMessage {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    SerializedMessageTypeId in value &&
+    value[SerializedMessageTypeId] === SerializedMessageTypeId
+  )
+}
+
+/**
+ * This is the schema for a value.
+ *
+ * @since 1.0.0
+ * @category schema
+ */
+export const schema: Schema.Schema<
+  SerializedMessage,
+  SerializedMessage.Encoded
+> = Schema.asSchema(SerializedMessage)

package/src/ShardId.ts

@@ -0,0 +1,79 @@
+/**
+ * @since 1.0.0
+ */
+import * as Schema from "@effect/schema/Schema"
+import { TypeIdSchema } from "./internal/utils.js"
+
+/** @internal */
+const ShardIdSymbolKey = "@effect/cluster/ShardId"
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export const ShardIdTypeId: unique symbol = Symbol.for(ShardIdSymbolKey)
+
+/**
+ * @since 1.0.0
+ * @category symbols
+ */
+export type ShardIdTypeId = typeof ShardIdTypeId
+
+/** @internal */
+const ShardIdTypeIdSchema = TypeIdSchema(ShardIdSymbolKey, ShardIdTypeId)
+
+/**
+ * A shard is a logical grouping of multiple entities. There could be thousands of entities in your system,
+ * so instead of managing every single entity id, the shard manager group them by shard id, and when they are assigned
+ * or moved around, we always move all the entities with the same shard id.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export class ShardId extends Schema.Class<ShardId>(ShardIdSymbolKey)({
+  [ShardIdTypeId]: Schema.propertySignature(ShardIdTypeIdSchema).pipe(Schema.fromKey(ShardIdSymbolKey)),
+  value: Schema.Number
+}) {
+  /**
+   * @since 1.0.0
+   */
+  toString() {
+    return `ShardId(${this.value})`
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export namespace ShardId {
+  /**
+   * This is the shape that a shard id has over the wire.
+   *
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Encoded extends Schema.Schema.Encoded<typeof ShardId> {}
+}
+
+/**
+ * Constructs a shard id from its numerical value.
+ * The shard id is currently built up by making the hash of the entity id, and then modulo the max amount of shards configured in ManagerConfig.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export function make(value: number): ShardId {
+  return new ShardId({ [ShardIdTypeId]: ShardIdTypeId, value })
+}
+
+/**
+ * This is the schema for a ShardId.
+ *
+ * @since 1.0.0
+ * @category schema
+ */
+export const schema: Schema.Schema<
+  ShardId,
+  ShardId.Encoded
+> = Schema.asSchema(ShardId)