pyfect-dev 0.1.0__py3-none-any.whl

pyfect/cluster/entity/_handlers.py

@@ -0,0 +1,168 @@
+"""An entity's handlers, built one RPC at a time, and the options it is
+registered with."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, Never, Protocol, overload
+
+from pyfect._core import Effect
+from pyfect.cluster.entity._request import Request
+from pyfect.deferred import Deferred
+from pyfect.duration import Duration, Seconds, to_seconds
+from pyfect.errors import Done
+from pyfect.queue import Dequeue
+from pyfect.rpc._rpc import AnyRpc, Rpc, StreamRpc
+from pyfect.rpc.middleware import RpcMiddleware
+from pyfect.schedule import Schedule
+from pyfect.scope import Scope
+from pyfect.stream import Stream
+
+if TYPE_CHECKING:
+    from pyfect.cluster.entity._entity import Entity
+
+type Concurrency = int | Literal["unbounded"]
+type EntityHandlerFn = Callable[[Request[Any]], Any]
+
+
+class EntityHandlers[G, R = Never]:
+    """The handlers of the entity ``G`` so far, needing ``R``. Immutable:
+    ``handle`` gives a new one."""
+
+    __slots__ = ("_by_tag", "entity")
+
+    def __init__(self, entity: type[Entity], by_tag: Mapping[str, EntityHandlerFn]) -> None:
+        self.entity = entity
+        self._by_tag = dict(by_tag)
+
+    @property
+    def by_tag(self) -> Mapping[str, EntityHandlerFn]:
+        return self._by_tag
+
+    @overload
+    def handle[P, S, E](
+        self, rpc: Rpc[P, S, E, Never], /
+    ) -> Bound[G, Request[P], S, E, Never, R]: ...
+    @overload
+    def handle[P, S, E, MP, ME, MT](
+        self, rpc: Rpc[P, S, E, RpcMiddleware[MP, ME, Any], MT], /
+    ) -> Bound[G, Request[P], S, E | ME, MP, R | MT]: ...
+    @overload
+    def handle[P, A, E](
+        self, rpc: StreamRpc[P, A, E, Never], /
+    ) -> StreamBound[G, Request[P], A, E, Never, R]: ...
+    @overload
+    def handle[P, A, E, MP, ME, MT](
+        self, rpc: StreamRpc[P, A, E, RpcMiddleware[MP, ME, Any], MT], /
+    ) -> StreamBound[G, Request[P], A, E | ME, MP, R | MT]: ...
+    def handle(self, rpc: AnyRpc, /) -> Any:
+        """The slot of ``rpc``'s handler: call it with the handler, which
+        gets the entity ``Request`` and returns the effect to run (for a
+        stream RPC, a stream or a scoped queue)."""
+        if rpc.tag not in self.entity.rpcs:
+            raise ValueError(f"{rpc.tag!r} is not an RPC of the entity {self.entity.type}")
+        return _Slot(self, rpc.tag)
+
+    def missing(self) -> list[str]:
+        """The tags of the entity's RPCs without a handler."""
+        return [tag for tag in self.entity.rpcs if tag not in self._by_tag]
+
+
+class Bound[G, X, S, E, MP, RR](Protocol):
+    """The handler slot of a unary RPC of the entity ``G``: request ``X``,
+    success ``S``, errors ``E``; its middleware provides ``MP``; ``RR`` is
+    what the handlers need so far."""
+
+    @overload
+    def __call__(
+        self, handler: Callable[[X], Effect[S | Deferred[S, E], E, MP]], /
+    ) -> EntityHandlers[G, RR]: ...
+    @overload
+    def __call__[R1](
+        self, handler: Callable[[X], Effect[S | Deferred[S, E], E, R1 | MP]], /
+    ) -> EntityHandlers[G, RR | R1]: ...
+
+
+class StreamBound[G, X, A, E, MP, RR](Protocol):
+    """The handler slot of a stream RPC of the entity ``G`` (see
+    ``Bound``): the handler gives a stream, or a scoped queue that ends
+    with ``Done``."""
+
+    @overload
+    def __call__(self, handler: Callable[[X], Stream[A, E, MP]], /) -> EntityHandlers[G, RR]: ...
+    @overload
+    def __call__[R1](
+        self, handler: Callable[[X], Stream[A, E, R1 | MP]], /
+    ) -> EntityHandlers[G, RR | R1]: ...
+    @overload
+    def __call__(
+        self, handler: Callable[[X], Effect[Dequeue[A, E | Done], E, MP | Scope]], /
+    ) -> EntityHandlers[G, RR]: ...
+    @overload
+    def __call__[R1](
+        self, handler: Callable[[X], Effect[Dequeue[A, E | Done], E, R1 | MP | Scope]], /
+    ) -> EntityHandlers[G, RR | R1]: ...
+
+
+class _Slot:
+    __slots__ = ("handlers", "tag")
+
+    def __init__(self, handlers: EntityHandlers[Any, Any], tag: str) -> None:
+        self.handlers = handlers
+        self.tag = tag
+
+    def __call__(self, handler: EntityHandlerFn, /) -> EntityHandlers[Any, Any]:
+        handlers = self.handlers
+        return EntityHandlers(handlers.entity, {**handlers.by_tag, self.tag: handler})
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class EntityOptions:
+    """How an entity runs: an idle entity stops after ``max_idle_time``
+    (the sharding default when ``None``), at most ``concurrency`` requests
+    at once, ``mailbox_capacity`` requests waiting (the sharding default
+    when ``None``); a defect ends every request of the entity unless
+    ``disable_fatal_defects``, and the entity restarts on the
+    ``defect_retry_policy``."""
+
+    max_idle_time: Seconds | None = None
+    concurrency: Concurrency = 1
+    mailbox_capacity: Concurrency | None = None
+    mailbox_metrics: bool | None = None
+    disable_fatal_defects: bool = False
+    defect_retry_policy: Schedule[Any, Any, Any, Any] | None = None
+    span_attributes: Mapping[str, str] = field(default_factory=dict[str, str])
+
+
+def parse_options(
+    *,
+    max_idle_time: Duration | None,
+    concurrency: Concurrency,
+    mailbox_capacity: Concurrency | None,
+    mailbox_metrics: bool | None,
+    disable_fatal_defects: bool,
+    defect_retry_policy: Schedule[Any, Any, Any, Any] | None,
+    span_attributes: Mapping[str, str] | None,
+) -> EntityOptions:
+    """The options of ``to_layer``, checked and parsed once."""
+    return EntityOptions(
+        max_idle_time=None if max_idle_time is None else to_seconds(max_idle_time),
+        concurrency=concurrency,
+        mailbox_capacity=mailbox_capacity,
+        mailbox_metrics=mailbox_metrics,
+        disable_fatal_defects=disable_fatal_defects,
+        defect_retry_policy=defect_retry_policy,
+        span_attributes=dict(span_attributes or {}),
+    )
+
+
+__all__ = [
+    "Bound",
+    "Concurrency",
+    "EntityHandlerFn",
+    "EntityHandlers",
+    "EntityOptions",
+    "StreamBound",
+    "parse_options",
+]

pyfect/cluster/entity/_keep_alive.py

@@ -0,0 +1,74 @@
+"""Keeping an entity alive while it holds a resource (Effect's
+``Entity.keepAlive``)."""
+
+from __future__ import annotations
+
+from typing import Never
+
+from pyfect._core import Effect
+from pyfect.cluster.cluster_schema import Persisted, Uninterruptible
+from pyfect.cluster.entity._services import CurrentAddress, KeepAliveLatch
+from pyfect.cluster.envelope import make_request
+from pyfect.cluster.message import OutgoingRequest
+from pyfect.cluster.reply import Reply
+from pyfect.cluster.sharding import Sharding
+from pyfect.context import Context
+from pyfect.effect import gen, service_option, succeed
+from pyfect.rpc import make as make_rpc
+from pyfect.tracer import current_span
+
+KeepAliveRpc = (
+    make_rpc("Cluster/Entity/keepAlive").annotate(Persisted, True).annotate(Uninterruptible, True)
+)
+"""The persisted, uninterruptible RPC an entity sends itself to stay
+alive."""
+
+_VOID: Effect[None] = succeed(None)
+
+
+def _ignore(_: Reply) -> Effect[None]:
+    return _VOID
+
+
+def keep_alive(enabled: bool) -> Effect[None, Never, Sharding | CurrentAddress]:
+    """Keep the current entity alive (``True``) until called with
+    ``False``; outside an entity that can be kept alive it does nothing."""
+
+    @gen
+    def run():
+        found = yield from service_option(KeepAliveLatch)
+        if found is None:
+            return
+        latch = found.value
+        if not enabled:
+            yield from latch.open()
+            return
+        sharding = yield from Sharding()
+        address = yield from CurrentAddress()
+        request_id = yield from sharding.get_snowflake
+        span = yield from current_span().or_die()
+        latch.close_unsafe()
+        message = OutgoingRequest(
+            annotations=KeepAliveRpc.annotations,
+            rpc=KeepAliveRpc,
+            context=Context.empty(),
+            envelope=make_request(
+                request_id=request_id,
+                address=address,
+                tag=KeepAliveRpc.tag,
+                payload=None,
+                trace_id=span.trace_id,
+                span_id=span.span_id,
+                sampled=span.sampled,
+            ),
+            last_received_reply=None,
+            respond=_ignore,
+        )
+        yield from sharding.send_outgoing(message, True).or_die()
+
+    return run.with_span(
+        "Entity/keepAlive", attributes={"enabled": enabled}, capture_stack_trace=False
+    )
+
+
+__all__ = ["KeepAliveRpc", "keep_alive"]

pyfect/cluster/entity/_queue.py

@@ -0,0 +1,103 @@
+"""An entity served from a mailbox queue (Effect's ``toLayerQueue``): its
+behaviour takes requests from the queue and answers them with a
+``Replier``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Never, cast
+
+from pyfect import exit as Exit
+from pyfect._core import Effect
+from pyfect.cause import Cause
+from pyfect.cluster.entity._handlers import EntityHandlers
+from pyfect.cluster.entity._request import Request
+from pyfect.effect import callback, from_exit, gen, sync
+from pyfect.queue import Dequeue, Queue
+from pyfect.scope import Scope, fork_scoped
+from pyfect.stream import Stream, from_queue, unwrap
+
+if TYPE_CHECKING:
+    from pyfect.cluster.entity._entity import Entity
+
+type _Resume = Callable[[Effect[Any, Any]], None]
+
+
+class Replier:
+    """Answers the requests a queue-based entity takes. A streamed RPC is
+    answered with a ``Stream`` or a ``Dequeue`` of its items."""
+
+    __slots__ = ("_resumes",)
+
+    def __init__(self, resumes: dict[int, tuple[Request[Any], _Resume]]) -> None:
+        self._resumes = resumes
+
+    def complete(self, request: Request[Any], exit: Exit.Exit[Any, Any]) -> Effect[None]:
+        def run() -> None:
+            found = self._resumes.pop(id(request), None)
+            if found is not None:
+                found[1](from_exit(exit))
+
+        return sync(run)
+
+    def succeed(self, request: Request[Any], value: object) -> Effect[None]:
+        return self.complete(request, Exit.succeed(value))
+
+    def fail(self, request: Request[Any], error: object) -> Effect[None]:
+        return self.complete(request, Exit.fail(error))
+
+    def fail_cause(self, request: Request[Any], cause: Cause[Any]) -> Effect[None]:
+        return self.complete(request, Exit.Failure(cause))
+
+
+type Behaviour[R] = Callable[[Dequeue[Request[Any], Never], Replier], Effect[Never, Never, R]]
+
+
+def queue_handlers[R](
+    entity: type[Entity], behaviour: Behaviour[R]
+) -> Effect[EntityHandlers[Any, Any], Never, R | Scope]:
+    """Handlers putting each request in a mailbox, with ``behaviour``
+    forked into the current scope to answer them."""
+
+    @gen
+    def make():
+        mailbox = yield from Queue[Request[Any], Never].unbounded()
+        resumes: dict[int, tuple[Request[Any], _Resume]] = {}
+
+        def enqueue(request: Request[Any]) -> Effect[Any, Any]:
+            def register(resume: _Resume) -> None:
+                mailbox.offer_unsafe(request)
+                resumes[id(request)] = (request, resume)
+
+            return callback(register)
+
+        def stream_of(value: Any) -> Stream[Any, Any, Any]:
+            if isinstance(value, Stream):
+                return cast("Stream[Any, Any, Any]", value)
+            return from_queue(cast("Dequeue[Any, Any]", value))
+
+        def enqueue_stream(request: Request[Any]) -> Stream[Any, Any, Any]:
+            return unwrap(enqueue(request).map(stream_of))
+
+        by_tag = {
+            tag: enqueue_stream if rpc.is_stream else enqueue for tag, rpc in entity.rpcs.items()
+        }
+
+        def fail_all(cause: Cause[Any]) -> Effect[None]:
+            def run() -> None:
+                waiting = list(resumes.values())
+                resumes.clear()
+                for _, resume in waiting:
+                    resume(from_exit(Exit.Failure(cause)))
+
+            return sync(run)
+
+        yield from fork_scoped(
+            behaviour(mailbox, Replier(resumes)).catch_cause(fail_all).interruptible()
+        )
+        return EntityHandlers[Any, Any](entity, by_tag)
+
+    return make
+
+
+__all__ = ["Behaviour", "Replier", "queue_handlers"]

pyfect/cluster/entity/_request.py

@@ -0,0 +1,34 @@
+"""What an entity handler receives (Effect's ``Entity.Request``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pyfect.cluster import envelope as envelope_
+from pyfect.cluster.reply import Chunk
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Request[P](envelope_.Request[P]):
+    """A request for one of the entity's RPCs, with its decoded ``payload``
+    and the last chunk of a streamed reply already sent
+    (``last_sent_chunk``), so a restarted handler can resume its
+    sequence."""
+
+    last_sent_chunk: Chunk[Any] | None = None
+
+    @property
+    def last_sent_chunk_value(self) -> Any | None:
+        """The last item of the last chunk sent, if a chunk was sent."""
+        chunk = self.last_sent_chunk
+        return None if chunk is None else chunk.values[-1]
+
+    @property
+    def next_sequence(self) -> int:
+        """The sequence number of the next chunk to send."""
+        chunk = self.last_sent_chunk
+        return 0 if chunk is None else chunk.sequence + 1
+
+
+__all__ = ["Request"]

pyfect/cluster/entity/_services.py

@@ -0,0 +1,23 @@
+"""The services an entity handler can read."""
+
+from __future__ import annotations
+
+from pyfect.cluster.entity_address import EntityAddress
+from pyfect.cluster.runner_address import RunnerAddress
+from pyfect.context import Tag
+from pyfect.latch import Latch
+
+
+class CurrentAddress(Tag[EntityAddress], key="effect/cluster/Entity/EntityAddress"):
+    """The address of the entity handling the current request."""
+
+
+class CurrentRunnerAddress(Tag[RunnerAddress], key="effect/cluster/Entity/RunnerAddress"):
+    """The address of the runner the entity runs on."""
+
+
+class KeepAliveLatch(Tag[Latch], key="effect/cluster/Entity/KeepAliveLatch"):
+    """Closed while ``keep_alive(True)`` keeps the entity alive."""
+
+
+__all__ = ["CurrentAddress", "CurrentRunnerAddress", "KeepAliveLatch"]

pyfect/cluster/entity/_test_client.py

@@ -0,0 +1,237 @@
+"""In-memory clients of an entity layer (Effect's
+``Entity.makeTestClient``): no sharding, no serialization, one server per
+entity id."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Any, Never, overload
+
+from pyfect import layer as layer_
+from pyfect._core import Effect, _Locally
+from pyfect._layer_core import require_layer
+from pyfect.cluster._entity_activation import CurrentActivationScope
+from pyfect.cluster._hash import shard_number
+from pyfect.cluster._resource_map import ResourceMap
+from pyfect.cluster.entity._request import Request
+from pyfect.cluster.entity._services import CurrentAddress, CurrentRunnerAddress
+from pyfect.cluster.entity_address import EntityAddress
+from pyfect.cluster.entity_id import EntityId
+from pyfect.cluster.message import Incoming, Outgoing
+from pyfect.cluster.runner_address import RunnerAddress
+from pyfect.cluster.shard_id import ShardId
+from pyfect.cluster.sharding import Sharding
+from pyfect.cluster.sharding_config import ShardingConfig
+from pyfect.cluster.snowflake import Snowflake, make_generator
+from pyfect.context import Context
+from pyfect.effect import context, die, fn_untraced, gen
+from pyfect.layer import Layer
+from pyfect.rpc import message as rpc_message
+from pyfect.rpc.client._core import ClientCore, ClientOptions, OnFromClient
+from pyfect.rpc.client._core import make_no_serialization as make_client_core
+from pyfect.rpc.message import FromServer
+from pyfect.rpc.server._core import ServerOptions
+from pyfect.rpc.server._core import make_no_serialization as make_server_core
+from pyfect.scope import Scope
+from pyfect.stream import Stream
+from pyfect.stream import die as stream_die
+
+if TYPE_CHECKING:
+    from pyfect.cluster.entity._entity import Entity
+    from pyfect.cluster.entity._handlers import Concurrency, EntityHandlers, EntityOptions
+    from pyfect.cluster.sharding_registration_event import ShardingRegistrationEvent
+
+
+@dataclass(frozen=True, slots=True)
+class _Registered:
+    context: Context[Any]
+    concurrency: Concurrency
+    disable_fatal_defects: bool
+    build: Effect[Context[Any], Never, Any]
+
+
+def _not_in_test(name: str) -> Effect[Never]:
+    return die(RuntimeError(f"Sharding.{name} is not available to Entity.make_test_client"))
+
+
+class _TestSharding:
+    """A sharding that only records entity registrations."""
+
+    __slots__ = ("registered",)
+
+    def __init__(self) -> None:
+        self.registered: dict[str, _Registered] = {}
+
+    def register_entity(
+        self,
+        entity: type[Entity],
+        build: Effect[EntityHandlers[Any, Any], Never, Any],
+        options: EntityOptions,
+        /,
+    ) -> Effect[None, Never, Any]:
+        def record(services: Context[Any]) -> None:
+            self.registered[entity.type] = _Registered(
+                services,
+                options.concurrency,
+                options.disable_fatal_defects,
+                entity.to_handlers(build),
+            )
+
+        return context().map(record)
+
+    def get_shard_id(self, entity_id: EntityId, group: str, /) -> ShardId:
+        raise RuntimeError("Sharding.get_shard_id is not available to Entity.make_test_client")
+
+    def has_shard_id(self, shard_id: ShardId, /) -> bool:
+        return True
+
+    @property
+    def get_registration_events(self) -> Stream[ShardingRegistrationEvent]:
+        return stream_die(
+            RuntimeError(
+                "Sharding.get_registration_events is not available to Entity.make_test_client"
+            )
+        )
+
+    @property
+    def get_snowflake(self) -> Effect[Snowflake]:
+        return _not_in_test("get_snowflake")
+
+    @property
+    def is_shutdown(self) -> Effect[bool]:
+        return _not_in_test("is_shutdown")
+
+    def make_client[T: Entity](self, entity: type[T], /) -> Effect[Callable[[str], T]]:
+        return _not_in_test("make_client")
+
+    def register_singleton(
+        self, name: str, run: Effect[None, Any, Any], shard_group: str | None, /
+    ) -> Effect[None, Never, Any]:
+        return _not_in_test("register_singleton")
+
+    def send(self, message: Incoming, /) -> Effect[None, Any]:
+        return _not_in_test("send")
+
+    def send_outgoing(self, message: Outgoing, discard: bool, /) -> Effect[None, Any]:
+        return _not_in_test("send_outgoing")
+
+    def notify(self, message: Incoming, /, *, wait_until_read: bool = False) -> Effect[None, Any]:
+        return _not_in_test("notify")
+
+    def reset(
+        self, request_id: Snowflake, /, *, expected_reply_id: Snowflake | None = None
+    ) -> Effect[bool]:
+        return _not_in_test("reset")
+
+    @property
+    def poll_storage(self) -> Effect[None]:
+        return _not_in_test("poll_storage")
+
+    @property
+    def active_entity_count(self) -> Effect[int]:
+        return _not_in_test("active_entity_count")
+
+
+_RUNNER_ADDRESS = RunnerAddress(host="localhost", port=3000)
+
+
+@overload
+def make_test_client[T: Entity, E](
+    entity: type[T], layer: Layer[Any, E, Sharding], /
+) -> Effect[Callable[[str], Effect[T]], E, Scope | ShardingConfig]: ...
+@overload
+def make_test_client[T: Entity, E, R](
+    entity: type[T], layer: Layer[Any, E, R | Sharding], /
+) -> Effect[Callable[[str], Effect[T]], E, Scope | ShardingConfig | R]: ...
+def make_test_client(entity: type[Entity], layer: Layer[Any, Any, Any], /) -> Effect[Any, Any, Any]:
+    """Build ``layer`` against a sharding that records the entity's
+    registration, and give a function making the client of an entity id:
+    each id gets its own entity, started on first use and stopped when the
+    current scope closes."""
+    require_layer(layer, "layer")
+
+    @gen
+    def make():
+        config = yield from ShardingConfig()
+        snowflakes = yield from make_generator()
+        sharding = _TestSharding()
+        yield from layer.pipe(layer_.provide(layer_.succeed(Sharding, sharding))).build()
+        entry = sharding.registered.get(entity.type)
+        if entry is None:
+            yield from die(
+                RuntimeError(f"Entity.make_test_client: {entity.type} was not registered by layer")
+            )
+            return None
+        registered = entry
+
+        @fn_untraced
+        def lookup(entity_id: str):
+            id = EntityId(entity_id)
+            address = EntityAddress(
+                entity_type=entity.type,
+                entity_id=id,
+                shard_id=ShardId(
+                    group=entity.get_shard_group(id),
+                    id=shard_number(entity_id, config.shards_per_group),
+                ),
+            )
+            scope = yield from Scope()
+            handler_context = (
+                registered.context.add(CurrentRunnerAddress, _RUNNER_ADDRESS)
+                .add(CurrentAddress, address)
+                .add(CurrentActivationScope, scope)
+                .add(Scope, scope)
+            )
+            handlers = yield from _Locally(registered.build, lambda _: handler_context)
+            cores: list[ClientCore] = []
+
+            def on_from_server(response: FromServer) -> Effect[None]:
+                return cores[0].write(response)
+
+            server = yield from _Locally(
+                make_server_core(
+                    entity.protocol,
+                    on_from_server,
+                    ServerOptions(
+                        concurrency=registered.concurrency,
+                        disable_fatal_defects=registered.disable_fatal_defects,
+                    ),
+                ),
+                lambda _: handler_context.merge(handlers),
+            )
+
+            def on_from_client(sent: OnFromClient) -> Effect[None, Any]:
+                message = sent.message
+                if isinstance(message, rpc_message.Request):
+                    request = Request[Any](
+                        request_id=Snowflake(int(message.id)),
+                        address=address,
+                        tag=message.tag,
+                        payload=message.payload,
+                        headers=message.headers,
+                        trace_id=message.trace_id,
+                        span_id=message.span_id,
+                        sampled=message.sampled,
+                    )
+                    return server.write(0, replace(message, payload=request))
+                return server.write(0, message)
+
+            _, core = yield from make_client_core(
+                entity.protocol,
+                on_from_client,
+                ClientOptions(supports_ack=True, generate_request_id=snowflakes.next_unsafe),
+            )
+            cores.append(core)
+            client = entity()
+            client._rpc_methods = core.methods(entity.protocol)
+            return client
+
+        clients = yield from ResourceMap.make(lookup)
+        return clients.get
+
+    return make
+
+
+__all__ = ["make_test_client"]

pyfect/cluster/entity_address.py

@@ -0,0 +1,25 @@
+"""``EntityAddress``: an entity's type, id and shard (Effect's
+``EntityAddress``)."""
+
+from __future__ import annotations
+
+from pyfect import schema as S
+from pyfect.cluster.entity_id import EntityId, EntityIdSchema
+from pyfect.cluster.entity_type import EntityType, EntityTypeSchema
+from pyfect.cluster.shard_id import ShardId
+
+
+class EntityAddress(S.Class, identifier="~effect/cluster/EntityAddress"):
+    shard_id: ShardId = S.field(ShardId, key="shardId")
+    entity_type: EntityType = S.field(EntityTypeSchema, key="entityType")
+    entity_id: EntityId = S.field(EntityIdSchema, key="entityId")
+
+    def __str__(self) -> str:
+        return f"EntityAddress({self.entity_type}, {self.entity_id}, {self.shard_id})"
+
+
+def make(*, shard_id: ShardId, entity_type: EntityType, entity_id: EntityId) -> EntityAddress:
+    return EntityAddress(shard_id=shard_id, entity_type=entity_type, entity_id=entity_id)
+
+
+__all__ = ["EntityAddress", "make"]

pyfect/cluster/entity_id.py

@@ -0,0 +1,20 @@
+"""``EntityId``: the id of one entity of a type (Effect's ``EntityId``)."""
+
+from __future__ import annotations
+
+from typing import NewType
+
+from pyfect import schema as S
+from pyfect.brand import Brand
+
+EntityId = NewType("EntityId", str)
+
+EntityIdSchema = S.String.pipe(S.from_brand(Brand[str, EntityId].nominal()))
+"""Entity ids (Effect's ``EntityId`` schema)."""
+
+
+def make(id: str) -> EntityId:
+    return EntityId(id)
+
+
+__all__ = ["EntityId", "EntityIdSchema", "make"]