EntityProxy

Derives RPC and HTTP API surfaces from clustered entities.

The generated APIs let callers use ordinary RPC clients or HTTP routes while the cluster runtime still locates and delivers messages to the entity instance identified by entityId. Each generated operation keeps the original payload and success schema, adds cluster client errors, and creates a discard variant for fire-and-forget delivery.

4 exports Added in v4.0.0 Source

Constructors

toHttpApiGroup

Added in v4.0.0 Source

Derives an HttpApiGroup from an Entity.

Signature

declare function toHttpApiGroup<Name extends string, Type extends string, Rpcs extends Any>(name: Name, entity: Entity<Type, Rpcs>): HttpApiGroup<Name, ConvertHttpApi<Rpcs>>

Example

(Deriving HTTP API endpoints from an entity)

import { Layer, Schema } from "effect"
import { ClusterSchema, Entity, EntityProxy, EntityProxyServer } from "effect/unstable/cluster"
import { HttpApi, HttpApiBuilder } from "effect/unstable/httpapi"
import { Rpc } from "effect/unstable/rpc"

export const Counter = Entity.make("Counter", [
  Rpc.make("Increment", {
    payload: { id: Schema.String, amount: Schema.Number },
    primaryKey: ({ id }) => id,
    success: Schema.Number
  })
]).annotateRpcs(ClusterSchema.Persisted, true)

// Use EntityProxy.toHttpApiGroup to create a `HttpApiGroup` from the
// Counter entity
export class MyApi extends HttpApi.make("api")
  .add(
    EntityProxy.toHttpApiGroup("counter", Counter)
      .prefix("/counter")
  )
{}

// Use EntityProxyServer.layerHttpApi to create a layer that implements
// the handlers for the HttpApiGroup
const ApiLayer = HttpApiBuilder.layer(MyApi).pipe(
  Layer.provide(EntityProxyServer.layerHttpApi(MyApi, "counter", Counter))
)
const result = [Object.keys(MyApi.groups.counter.endpoints).length, Layer.isLayer(ApiLayer)] // => [2, true]

toRpcGroup

Added in v4.0.0 Source

Derives an RpcGroup from an Entity.

Signature

declare function toRpcGroup<Type extends string, Rpcs extends Any>(entity: Entity<Type, Rpcs>): RpcGroup<ConvertRpcs<Rpcs, Type>>

Example

(Deriving RPC endpoints from an entity)

import { Layer, Schema } from "effect"
import { ClusterSchema, Entity, EntityProxy, EntityProxyServer } from "effect/unstable/cluster"
import { Rpc, RpcServer } from "effect/unstable/rpc"

export const Counter = Entity.make("Counter", [
  Rpc.make("Increment", {
    payload: { id: Schema.String, amount: Schema.Number },
    primaryKey: ({ id }) => id,
    success: Schema.Number
  })
]).annotateRpcs(ClusterSchema.Persisted, true)

// Use EntityProxy.toRpcGroup to create a `RpcGroup` from the Counter entity
export class MyRpcs extends EntityProxy.toRpcGroup(Counter) {}

// Use EntityProxyServer.layerRpcHandlers to create a layer that implements
// the rpc handlers
const RpcServerLayer = RpcServer.layer(MyRpcs).pipe(
  Layer.provide(EntityProxyServer.layerRpcHandlers(Counter))
)
const result = [MyRpcs.requests.size, Layer.isLayer(RpcServerLayer)] // => [2, true]

Converting

ConvertHttpApi type

Added in v4.0.0 Source

Type-level conversion used by toHttpApiGroup.

Details

For each entity RPC, this creates a POST endpoint at /<tag>/:entityId and a discard endpoint at /<tag>/:entityId/discard, including cluster client errors.

Signature

type ConvertHttpApi<Rpcs extends Rpc.Any> = Rpcs extends Rpc.Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires> ? HttpApiEndpoint.HttpApiEndpoint<_Tag, "POST", `/${Lowercase<_Tag>}/:entityId`, Schema.Struct<{
  entityId: typeof EntityId;
}>, never, _Payload, never, _Success, _Error | typeof MailboxFull | typeof AlreadyProcessingMessage | typeof PersistenceError | typeof EntityNotAssignedToRunner> | HttpApiEndpoint.HttpApiEndpoint<`${_Tag}Discard`, "POST", `/${Lowercase<_Tag>}/:entityId/discard`, Schema.Struct<{
  entityId: typeof EntityId;
}>, never, _Payload, never, Schema.Void, typeof MailboxFull | typeof AlreadyProcessingMessage | typeof PersistenceError> : never

ConvertRpcs type

Added in v4.0.0 Source

Type-level conversion used by toRpcGroup.

Details

For each entity RPC, this creates a prefixed request RPC and a discard RPC whose payload includes entityId, and whose errors include cluster client errors.

Signature

type ConvertRpcs<Rpcs extends Rpc.Any, Prefix extends string> = Rpcs extends Rpc.Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires> ? Rpc.Rpc<`${Prefix}.${_Tag}`, Schema.Struct<{
  entityId: typeof Schema.String;
  payload: _Payload;
}>, _Success, Schema.Codec<_Error["Type"] | MailboxFull | AlreadyProcessingMessage | PersistenceError | EntityNotAssignedToRunner, _Error["Encoded"] | typeof MailboxFull["Encoded"] | typeof AlreadyProcessingMessage["Encoded"] | typeof PersistenceError["Encoded"] | typeof EntityNotAssignedToRunner["Encoded"], _Error["DecodingServices"], _Error["EncodingServices"]>> | Rpc.Rpc<`${Prefix}.${_Tag}Discard`, Schema.Struct<{
  entityId: typeof Schema.String;
  payload: _Payload;
}>, typeof Schema.Void, Schema.Union<[typeof MailboxFull, typeof AlreadyProcessingMessage, typeof PersistenceError]>> : never