GitHub

event_log_server

API reference for event_log_server.

The RPC handlers of an event log server (Effect's eventlog/EventLogServer), shared by the encrypted and unencrypted servers.

layer_rpc_handlers answers Hello with a one-time challenge kept on the connection (30 seconds from when it was generated), verifies Authenticate against the presented signing key and then the identity's binding, joins chunked writes and splits large changes. ConnectionWrites keeps a connection's own writes out of its change streams.

Values

AttributeTypeDescription
layer_auth_middlewareLayer[EventLogAuthentication]

Provides the connection's authenticated Identity, or fails Forbidden.

Types

TypeDefinitionDescription
OnWritetype OnWrite = Callable[[bytes, frozenset[str], ConnectionWrites], Effect[tuple[WriteAck, ...], EventLogProtocolError]]
Changestype Changes = Callable[[str, StoreId, int, ConnectionWrites], Stream[bytes, object]]

A connection's changes: (public_key, store_id, start_sequence, writes).

LatestSequencetype LatestSequence = Callable[[str, StoreId], Effect[int | None, object]]

The highest stored sequence of (public_key, store_id), None when the store is empty.

Classes

Functions

make_framer

make_framer() -> Callable[[bytes], list[SingleMessage | ChunkedMessage]]

Frames one encoded message for a response stream: a SingleMessage when it fits, else the pieces of a ChunkedMessage with the next id.

Returns Callable[[bytes], list[SingleMessage | ChunkedMessage]]

def make_framer() -> Callable[[bytes], list[SingleMessage | ChunkedMessage]]:
    """Frames one encoded message for a response stream: a ``SingleMessage``
    when it fits, else the pieces of a ``ChunkedMessage`` with the next id."""
    chunk_ids = itertools.count()

    def frame(data: bytes) -> list[SingleMessage | ChunkedMessage]:
        if len(data) <= CHUNK_SIZE:
            return [SingleMessage(data=data)]
        return list(ChunkedMessage.split(next(chunk_ids), data))

    return frame

layer_rpc_handlers

layer_rpc_handlers(*, remote_id, get_or_create_session_auth_binding, on_write, changes, latest_sequence, first_sequence=None, compaction=False, authorize_identity=None) -> Layer[HandlersFor[EventLogRemoteRpcs] | EventLogAuthentication]

The handlers of EventLogRemoteRpcs and the auth middleware.

Authenticate calls authorize_identity with the claimed public key and the presented signing public key, then verifies the signature against the presented key. Only a verified key goes to get_or_create_session_auth_binding, which gives the key bound to the public key (binding the presented one on first use); a key that differs from the binding is rejected. compaction sets HelloResponse.compaction: the server also serves EventLogCompactionRpcs.

ParameterTypeDescription
remote_idRemoteId
get_or_create_session_auth_bindingCallable[[str, bytes], Effect[bytes, object]]
on_writeOnWrite
changesChanges
latest_sequenceLatestSequence
first_sequenceint | None = None
compactionbool = False
authorize_identityCallable[[str, bytes], Effect[None, EventLogProtocolError]] | None = None

Returns Layer[HandlersFor[EventLogRemoteRpcs] | EventLogAuthentication]

def layer_rpc_handlers(
    *,
    remote_id: RemoteId,
    get_or_create_session_auth_binding: Callable[[str, bytes], Effect[bytes, object]],
    on_write: OnWrite,
    changes: Changes,
    latest_sequence: LatestSequence,
    first_sequence: int | None = None,
    compaction: bool = False,
    authorize_identity: Callable[[str, bytes], Effect[None, EventLogProtocolError]] | None = None,
) -> Layer[HandlersFor[EventLogRemoteRpcs] | EventLogAuthentication]:
    """The handlers of ``EventLogRemoteRpcs`` and the auth middleware.

    ``Authenticate`` calls ``authorize_identity`` with the claimed public key
    and the presented signing public key, then verifies the signature
    against the presented key. Only a verified key goes to
    ``get_or_create_session_auth_binding``, which gives the key bound to the
    public key (binding the presented one on first use); a key that differs
    from the binding is rejected. ``compaction`` sets
    ``HelloResponse.compaction``: the server also serves
    ``EventLogCompactionRpcs``."""

    def make():
        signing_keys: dict[str, bytes] = {}

        def bound_signing_key(
            public_key: str, presented: bytes
        ) -> Effect[bytes, EventLogProtocolError]:
            # Successful bindings are cached (at most 4096); failures are not.
            found = signing_keys.get(public_key)
            if found is not None:
                return succeed(found)

            def remember(key: bytes) -> bytes:
                if len(signing_keys) >= 4096:
                    del signing_keys[next(iter(signing_keys))]
                signing_keys[public_key] = key
                return key

            return (
                get_or_create_session_auth_binding(public_key, presented)
                .catch_cause(
                    lambda _: fail(
                        _forbidden("Authenticate", "Session auth binding lookup failed", public_key)
                    )
                )
                .map(remember)
            )

        to_frames = make_framer()

        def write_single(
            request: RpcRequest[WriteSinglePayload],
        ) -> Effect[tuple[WriteAck, ...], EventLogProtocolError]:
            return suspend(
                lambda: on_write(
                    request.payload["data"], _authenticated(request), _connection_writes(request)
                )
            )

        def write_chunked(
            request: RpcRequest[ChunkedMessage],
        ) -> Effect[tuple[WriteAck, ...], EventLogProtocolError]:
            def run() -> Effect[tuple[WriteAck, ...], EventLogProtocolError]:
                found = request.client.annotations.get_option(ChunkedMessageState)
                state = found.value if found is not None else ChunkedMessage.initial_join_state()
                if found is None:
                    request.client.annotate(ChunkedMessageState, state)
                data = ChunkedMessage.join(state, request.payload)
                if data is None:
                    return succeed(())
                return on_write(data, _authenticated(request), _connection_writes(request))

            return suspend(run)

        def changes_handler(
            request: RpcRequest[ChangesPayload],
        ) -> Stream[SingleMessage | ChunkedMessage, EventLogProtocolError]:
            payload = request.payload
            public_key = payload["public_key"]
            if public_key not in _authenticated(request):
                return stream_fail(
                    _forbidden("Changes", "Identity is not authenticated", public_key)
                )
            return (
                changes(
                    public_key,
                    payload["store_id"],
                    payload["start_sequence"],
                    _connection_writes(request),
                )
                .map_array(lambda chunk: tuple(m for data in chunk for m in to_frames(data)))
                .catch_cause(
                    lambda _: stream_fail(
                        EventLogProtocolError(
                            request_tag="Changes",
                            code="InternalServerError",
                            message="Decoding failure",
                            public_key=public_key,
                        )
                    )
                )
            )

        def latest_sequence_handler(
            request: RpcRequest[LatestSequencePayload],
        ) -> Effect[int | None, EventLogProtocolError]:
            public_key = request.payload["public_key"]
            if public_key not in _authenticated(request):
                return fail(
                    _forbidden("LatestSequence", "Identity is not authenticated", public_key)
                )
            return latest_sequence(public_key, request.payload["store_id"]).catch_cause(
                lambda _: fail(
                    EventLogProtocolError(
                        request_tag="LatestSequence",
                        code="InternalServerError",
                        message="Persistence failure",
                        public_key=public_key,
                    )
                )
            )

        return (
            EventLogRemoteRpcs.handlers()
            .handle(EventLogRemoteRpcs.hello)(_hello(remote_id, first_sequence, compaction))
            .handle(EventLogRemoteRpcs.authenticate)(
                _authenticate(remote_id, authorize_identity, bound_signing_key)
            )
            .handle(EventLogRemoteRpcs.write_single)(write_single)
            .handle(EventLogRemoteRpcs.write_chunked)(write_chunked)
            .handle(EventLogRemoteRpcs.changes)(changes_handler)
            .handle(EventLogRemoteRpcs.latest_sequence)(latest_sequence_handler)
        )

    return EventLogRemoteRpcs.to_layer_effect(sync(make)).pipe(provide_merge(layer_auth_middleware))