GitHub

MessageStorageService

API reference for MessageStorageService.

Where messages to entities and their replies are kept (Effect's MessageStorage), with the reply handlers of this runner.

unprocessed_messages claims the messages it returns for ten minutes; reset_* release claims early.

Attributes

AttributeTypeDescription
baseStorageBase

Functions

__init__

__init__(base, _handlers=dict[Snowflake, list[_ReplyHandler]](), _handlers_by_shard=dict[str, set[_ReplyHandler]]()) -> None
ParameterTypeDescription
baseStorageBase
_handlersdict[Snowflake, list[_ReplyHandler]] = dict[Snowflake, list[_ReplyHandler]]()
_handlers_by_sharddict[str, set[_ReplyHandler]] = dict[str, set[_ReplyHandler]]()

save_request

save_request(message) -> Effect[SaveResult, PersistenceError | MalformedMessage]

Saves the request message, or gives SaveDuplicate (with the original's id and its last reply) when a request of the same primary key is already stored. Fails with PersistenceError when the storage cannot be written, MalformedMessage when the message (or the stored reply) does not encode (or decode).

ParameterTypeDescription
messageOutgoingRequest

Returns Effect[SaveResult, PersistenceError | MalformedMessage]

def save_request(
    self, message: OutgoingRequest, /
) -> Effect[SaveResult, PersistenceError | MalformedMessage]:
    """Saves the request ``message``, or gives ``SaveDuplicate`` (with
    the original's id and its last reply) when a request of the same
    primary key is already stored. Fails with ``PersistenceError``
    when the storage cannot be written, ``MalformedMessage`` when the
    message (or the stored reply) does not encode (or decode)."""
    return self.base.save_request(message)

save_envelope

save_envelope(message) -> Effect[None, PersistenceError | MalformedMessage]

Saves the envelope message (an AckChunk or an Interrupt). Fails with PersistenceError when the storage cannot be written, MalformedMessage when it does not encode.

ParameterTypeDescription
messageOutgoingEnvelope

Returns Effect[None, PersistenceError | MalformedMessage]

def save_envelope(
    self, message: OutgoingEnvelope, /
) -> Effect[None, PersistenceError | MalformedMessage]:
    """Saves the envelope ``message`` (an ``AckChunk`` or an
    ``Interrupt``). Fails with ``PersistenceError`` when the storage
    cannot be written, ``MalformedMessage`` when it does not encode."""
    return self.base.save_envelope(message)

clear_replies

clear_replies(request_id, /, *, expected_reply_id=None) -> Effect[None, PersistenceError]

Deletes the replies of request_id; with expected_reply_id, only while that is still its latest reply (so a stale resume cannot clear a newer one). Fails with PersistenceError when the storage cannot be written.

ParameterTypeDescription
request_idSnowflake
expected_reply_idSnowflake | None = None

Returns Effect[None, PersistenceError]

def clear_replies(
    self, request_id: Snowflake, /, *, expected_reply_id: Snowflake | None = None
) -> Effect[None, PersistenceError]:
    """Deletes the replies of ``request_id``; with
    ``expected_reply_id``, only while that is still its latest reply
    (so a stale resume cannot clear a newer one). Fails with
    ``PersistenceError`` when the storage cannot be written."""
    return self.base.clear_replies(request_id, expected_reply_id=expected_reply_id)

replies_for

replies_for(requests) -> Effect[list[Reply], PersistenceError | MalformedMessage]

The stored replies of requests that are still to be delivered: their unacknowledged chunks and their WithExit. Fails with PersistenceError when the storage cannot be read, MalformedMessage when a reply does not decode.

ParameterTypeDescription
requestsIterable[OutgoingRequest]

Returns Effect[list[Reply], PersistenceError | MalformedMessage]

def replies_for(
    self, requests: Iterable[OutgoingRequest], /
) -> Effect[list[Reply], PersistenceError | MalformedMessage]:
    """The stored replies of ``requests`` that are still to be
    delivered: their unacknowledged chunks and their ``WithExit``.
    Fails with ``PersistenceError`` when the storage cannot be read,
    ``MalformedMessage`` when a reply does not decode."""
    return self.base.replies_for(requests)

replies_for_unfiltered

replies_for_unfiltered(request_ids) -> Effect[list[Any], PersistenceError | MalformedMessage]

Every stored reply of request_ids, encoded. Fails with PersistenceError when the storage cannot be read.

ParameterTypeDescription
request_idsIterable[Snowflake]

Returns Effect[list[Any], PersistenceError | MalformedMessage]

def replies_for_unfiltered(
    self, request_ids: Iterable[Snowflake], /
) -> Effect[list[Any], PersistenceError | MalformedMessage]:
    """Every stored reply of ``request_ids``, encoded. Fails with
    ``PersistenceError`` when the storage cannot be read."""
    return self.base.replies_for_unfiltered(request_ids)

request_id_for_primary_key

request_id_for_primary_key(*, address, tag, id) -> Effect[Snowflake | None, PersistenceError]

The id of the stored request to address with RPC tag and primary key id, None when there is none. Fails with PersistenceError when the storage cannot be read.

ParameterTypeDescription
addressEntityAddress
tagstr
idstr

Returns Effect[Snowflake | None, PersistenceError]

def request_id_for_primary_key(
    self, *, address: EntityAddress, tag: str, id: str
) -> Effect[Snowflake | None, PersistenceError]:
    """The id of the stored request to ``address`` with RPC ``tag``
    and primary key ``id``, ``None`` when there is none. Fails with
    ``PersistenceError`` when the storage cannot be read."""
    return self.base.request_id_for_primary_key(address=address, tag=tag, id=id)

unprocessed_messages

unprocessed_messages(shard_ids, /, *, limit=None, addresses=None) -> Effect[list[Incoming], PersistenceError]

Claims, for ten minutes, the unprocessed messages of shard_ids and gives them: requests without a WithExit or with unacknowledged chunks, the latest AckChunk and the Interrupt envelopes of unprocessed requests. limit bounds how many one read gives, addresses restricts it to those entities. A message that does not decode gets a defect reply instead. Fails with PersistenceError when the storage cannot be read.

ParameterTypeDescription
shard_idsIterable[ShardId]
limitint | None = None
addressesSequence[EntityAddress] | None = None

Returns Effect[list[Incoming], PersistenceError]

def unprocessed_messages(
    self,
    shard_ids: Iterable[ShardId],
    /,
    *,
    limit: int | None = None,
    addresses: Sequence[EntityAddress] | None = None,
) -> Effect[list[Incoming], PersistenceError]:
    """Claims, for ten minutes, the unprocessed messages of
    ``shard_ids`` and gives them: requests without a ``WithExit`` or
    with unacknowledged chunks, the latest ``AckChunk`` and the
    ``Interrupt`` envelopes of unprocessed requests. ``limit`` bounds
    how many one read gives, ``addresses`` restricts it to those
    entities. A message that does not decode gets a defect reply
    instead. Fails with ``PersistenceError`` when the storage cannot
    be read."""
    return self.base.unprocessed_messages(
        shard_ids, responder=self, limit=limit, addresses=addresses
    )

unprocessed_messages_by_id

unprocessed_messages_by_id(message_ids) -> Effect[list[Incoming], PersistenceError]

The unprocessed messages among message_ids, claimed as unprocessed_messages claims them. Fails with PersistenceError when the storage cannot be read.

ParameterTypeDescription
message_idsIterable[Snowflake]

Returns Effect[list[Incoming], PersistenceError]

def unprocessed_messages_by_id(
    self, message_ids: Iterable[Snowflake], /
) -> Effect[list[Incoming], PersistenceError]:
    """The unprocessed messages among ``message_ids``, claimed as
    ``unprocessed_messages`` claims them. Fails with
    ``PersistenceError`` when the storage cannot be read."""
    return self.base.unprocessed_messages_by_id(message_ids, responder=self)

reset_shards

reset_shards(shard_ids) -> Effect[None, PersistenceError]

Releases the claims on the messages of shard_ids, so the next read gives them again. Fails with PersistenceError when the storage cannot be written.

ParameterTypeDescription
shard_idsIterable[ShardId]

Returns Effect[None, PersistenceError]

def reset_shards(self, shard_ids: Iterable[ShardId], /) -> Effect[None, PersistenceError]:
    """Releases the claims on the messages of ``shard_ids``, so the
    next read gives them again. Fails with ``PersistenceError`` when
    the storage cannot be written."""
    return self.base.reset_shards(shard_ids)

reset_address

reset_address(address) -> Effect[None, PersistenceError]

Releases the claims on the messages to address. Fails with PersistenceError when the storage cannot be written.

ParameterTypeDescription
addressEntityAddress

Returns Effect[None, PersistenceError]

def reset_address(self, address: EntityAddress, /) -> Effect[None, PersistenceError]:
    """Releases the claims on the messages to ``address``. Fails with
    ``PersistenceError`` when the storage cannot be written."""
    return self.base.reset_address(address)

reset_requests

reset_requests(request_ids) -> Effect[None, PersistenceError]

Releases the claims on request_ids, leaving their replies and processed state as they are. Fails with PersistenceError when the storage cannot be written.

ParameterTypeDescription
request_idsSequence[Snowflake]

Returns Effect[None, PersistenceError]

def reset_requests(self, request_ids: Sequence[Snowflake], /) -> Effect[None, PersistenceError]:
    """Releases the claims on ``request_ids``, leaving their replies
    and processed state as they are. Fails with ``PersistenceError``
    when the storage cannot be written."""
    return self.base.reset_requests(request_ids)

reset_addresses

reset_addresses(addresses) -> Effect[None, PersistenceError]

Releases the claims on the messages to addresses. Fails with PersistenceError when the storage cannot be written.

ParameterTypeDescription
addressesSequence[EntityAddress]

Returns Effect[None, PersistenceError]

def reset_addresses(
    self, addresses: Sequence[EntityAddress], /
) -> Effect[None, PersistenceError]:
    """Releases the claims on the messages to ``addresses``. Fails
    with ``PersistenceError`` when the storage cannot be written."""
    return self.base.reset_addresses(addresses)

clear_address

clear_address(address) -> Effect[None, PersistenceError]

Deletes every message to address and their replies. Fails with PersistenceError when the storage cannot be written.

ParameterTypeDescription
addressEntityAddress

Returns Effect[None, PersistenceError]

def clear_address(self, address: EntityAddress, /) -> Effect[None, PersistenceError]:
    """Deletes every message to ``address`` and their replies. Fails
    with ``PersistenceError`` when the storage cannot be written."""
    return self.base.clear_address(address)

with_transaction

with_transaction[A, E, R](effect) -> Effect[A, E, R]

effect in one storage transaction; reply notifications wait for the outermost commit.

ParameterTypeDescription
effectEffect[A, E, R]

Returns Effect[A, E, R]

def with_transaction[A, E, R](self, effect: Effect[A, E, R], /) -> Effect[A, E, R]:
    """``effect`` in one storage transaction; reply notifications wait
    for the outermost commit."""
    require_effect(effect, "effect")

    def run(outer: list[Notification] | None) -> Effect[A, E, R]:
        notifications: list[Notification] = []

        def committed(_: A) -> Effect[None]:
            if outer is not None:
                pending = outer
                return sync(lambda: pending.extend(notifications))
            return for_each(notifications, lambda n: n).as_void().or_die()

        inner = effect.pipe(provide_service(TransactionNotifications, notifications))
        return self.base.with_transaction(inner).tap(committed)

    return TransactionNotifications().flat_map(run)

register_reply_handler

register_reply_handler(message) -> Effect[None, EntityNotAssignedToRunner]

Wait for the exit of message's request, sending every reply saved meanwhile to it. Fails with EntityNotAssignedToRunner when its shard's handlers are dropped.

ParameterTypeDescription
messageOutgoingRequest | IncomingRequest

Returns Effect[None, EntityNotAssignedToRunner]

def register_reply_handler(
    self, message: OutgoingRequest | IncomingRequest, /
) -> Effect[None, EntityNotAssignedToRunner]:
    """Wait for the exit of ``message``'s request, sending every reply
    saved meanwhile to it. Fails with ``EntityNotAssignedToRunner``
    when its shard's handlers are dropped."""
    request_id = message.envelope.request_id
    handlers_by_id = self._handlers
    by_shard = self._handlers_by_shard

    def register(resume: _Resume) -> Effect[None]:
        shard = str(message.envelope.address.shard_id)
        handlers = handlers_by_id.setdefault(request_id, [])
        shard_set = by_shard.setdefault(shard, set())
        entry = _ReplyHandler(message, shard_set, resume)
        handlers.append(entry)
        shard_set.add(entry)

        def unregister() -> None:
            if entry in handlers:
                handlers.remove(entry)
            shard_set.discard(entry)

        return sync(unregister)

    return callback(register)

unregister_reply_handler

unregister_reply_handler(request_id, /, *, interrupt=False) -> Effect[None]

Drop the handlers of request_id: they fail with EntityNotAssignedToRunner, or are interrupted as abandoned.

ParameterTypeDescription
request_idSnowflake
interruptbool = False

Returns Effect[None]

def unregister_reply_handler(
    self, request_id: Snowflake, /, *, interrupt: bool = False
) -> Effect[None]:
    """Drop the handlers of ``request_id``: they fail with
    ``EntityNotAssignedToRunner``, or are interrupted as abandoned."""

    def run() -> None:
        handlers = self._handlers.pop(request_id, None)
        for handler in handlers or ():
            handler.shard_set.discard(handler)
            self._resume_unregistered(handler, interrupt)

    return sync(run)

unregister_shard_reply_handlers

unregister_shard_reply_handlers(shard_id, /, *, interrupt=False) -> Effect[None]

Drop the handlers of every request to shard_id.

ParameterTypeDescription
shard_idShardId
interruptbool = False

Returns Effect[None]

def unregister_shard_reply_handlers(
    self, shard_id: ShardId, /, *, interrupt: bool = False
) -> Effect[None]:
    """Drop the handlers of every request to ``shard_id``."""

    def run() -> None:
        shard_set = self._handlers_by_shard.pop(str(shard_id), None)
        for handler in list(shard_set or ()):
            self._handlers.pop(handler.message.envelope.request_id, None)
            self._resume_unregistered(handler, interrupt)

    return sync(run)

save_reply

save_reply(reply) -> Effect[None, PersistenceError | MalformedMessage]

Persist reply and send it to the request's handlers; an exit resumes them (after the outermost commit, in a transaction).

ParameterTypeDescription
replyReplyWithContext

Returns Effect[None, PersistenceError | MalformedMessage]

def save_reply(
    self, reply: ReplyWithContext, /
) -> Effect[None, PersistenceError | MalformedMessage]:
    """Persist ``reply`` and send it to the request's handlers; an exit
    resumes them (after the outermost commit, in a transaction)."""
    request_id = reply.reply.request_id

    def persisted(saved: ReplyWithContext) -> Effect[None, PersistenceError | MalformedMessage]:
        def notify_now() -> Notification:
            handlers = self._handlers.get(request_id)
            if handlers is None:
                return void
            if isinstance(saved.reply, WithExit):
                del self._handlers[request_id]
                for handler in handlers:
                    handler.shard_set.discard(handler)
                    handler.resume(void)
            if len(handlers) == 1:
                return handlers[0].respond(saved)
            return for_each(list(handlers), lambda h: h.respond(saved)).as_void()

        notify = suspend(notify_now)
        if not isinstance(saved.reply, WithExit):
            return notify

        def defer(notifications: list[Notification] | None) -> Notification:
            if notifications is None:
                return notify
            return sync(lambda: notifications.append(notify))

        return TransactionNotifications().flat_map(defer)

    return self.base.save_reply(reply).flat_map(persisted)