@dogmatiq/protobuf 0.4.1 → 0.6.0

package/artifacts/dist/envelopepb/envelope_pb.d.ts

@@ -10,7 +10,9 @@ export declare const file_github_com_dogmatiq_protobuf_envelopepb_envelope: GenF
 /**
  * Envelope is a container for a Dogma message and its meta-data.
  *
- * It is wire-compatible with [MultiEnvelope].
+ * An Envelope can be decoded as a single-body [MultiEnvelope]. Decoding a
+ * MultiEnvelope as an Envelope is only safe when it contains exactly one body;
+ * multiple bodies merge when decoded into the singular body field.
  *
  * @generated from message dogma.protobuf.v1.Envelope
  */
@@ -33,7 +35,6 @@ export declare const EnvelopeSchema: GenMessage<Envelope>;
  * MultiEnvelope is an efficient encoding of an ordered sequence of [Envelope]
  * values that share common header context.
  *
- *
  * @generated from message dogma.protobuf.v1.MultiEnvelope
  */
 export type MultiEnvelope = Message$1<"dogma.protobuf.v1.MultiEnvelope"> & {
@@ -140,6 +141,12 @@ export type Message = Message$1<"dogma.protobuf.v1.Message"> & {
  */
 export declare const MessageSchema: GenMessage<Message>;
 /**
+ * Header contains origin and causal context that can be common to messages
+ * produced by the same cause.
+ *
+ * Extensions and baggage from the header and body are combined by message
+ * type. Body values take precedence over header values of the same type.
+ *
  * @generated from message dogma.protobuf.v1.Header
  */
 export type Header = Message$1<"dogma.protobuf.v1.Header"> & {

package/artifacts/dist/identitypb/identity_pb.d.ts

@@ -16,6 +16,8 @@ export type Identity = Message<"dogma.protobuf.v1.Identity"> & {
     /**
      * Name is the entity's human-readable name.
      *
+     * The name MUST be between 1 and 255 bytes when encoded as UTF-8.
+     *
      * The name should be unique enough to allow a human to identify the entity
      * without ambiguity. There is no hard requirement for uniqueness.
      *

package/artifacts/dist/messaginggrpc/errors_pb.d.ts

@@ -24,3 +24,27 @@ export type UnrecognizedEventStream = Message<"dogma.messaging.v1.UnrecognizedEv
  * Use `create(UnrecognizedEventStreamSchema)` to create a new message.
  */
 export declare const UnrecognizedEventStreamSchema: GenMessage<UnrecognizedEventStream>;
+/**
+ * EventStreamConsumerTooSlow is an error-details value for RESOURCE_EXHAUSTED
+ * errors returned by WatchEvents when a client cannot keep up and the server
+ * can no longer deliver a stream contiguously.
+ *
+ * A client that is behind the tail does not cause this error while contiguous
+ * delivery remains possible.
+ *
+ * @generated from message dogma.messaging.v1.EventStreamConsumerTooSlow
+ */
+export type EventStreamConsumerTooSlow = Message<"dogma.messaging.v1.EventStreamConsumerTooSlow"> & {
+    /**
+     * EventStreamId is the ID of the stream that could no longer be delivered
+     * contiguously.
+     *
+     * @generated from field: dogma.protobuf.v1.UUID event_stream_id = 1;
+     */
+    eventStreamId?: UUID | undefined;
+};
+/**
+ * Describes the message dogma.messaging.v1.EventStreamConsumerTooSlow.
+ * Use `create(EventStreamConsumerTooSlowSchema)` to create a new message.
+ */
+export declare const EventStreamConsumerTooSlowSchema: GenMessage<EventStreamConsumerTooSlow>;

package/artifacts/dist/messaginggrpc/errors_pb.js

@@ -6,9 +6,14 @@ import { file_github_com_dogmatiq_protobuf_uuidpb_uuid } from "../uuidpb/uuid_pb
 /**
  * Describes the file github.com/dogmatiq/protobuf/messaginggrpc/errors.proto.
  */
-export const file_github_com_dogmatiq_protobuf_messaginggrpc_errors = /*@__PURE__*/ fileDesc("CjdnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGMvZXJyb3JzLnByb3RvEhJkb2dtYS5tZXNzYWdpbmcudjEiSwoXVW5yZWNvZ25pemVkRXZlbnRTdHJlYW0SMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJREIsWipnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGNiCGVkaXRpb25zcOkH", [file_github_com_dogmatiq_protobuf_uuidpb_uuid]);
+export const file_github_com_dogmatiq_protobuf_messaginggrpc_errors = /*@__PURE__*/ fileDesc("CjdnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGMvZXJyb3JzLnByb3RvEhJkb2dtYS5tZXNzYWdpbmcudjEiSwoXVW5yZWNvZ25pemVkRXZlbnRTdHJlYW0SMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRCJOChpFdmVudFN0cmVhbUNvbnN1bWVyVG9vU2xvdxIwCg9ldmVudF9zdHJlYW1faWQYASABKAsyFy5kb2dtYS5wcm90b2J1Zi52MS5VVUlEQixaKmdpdGh1Yi5jb20vZG9nbWF0aXEvcHJvdG9idWYvbWVzc2FnaW5nZ3JwY2IIZWRpdGlvbnNw6Qc", [file_github_com_dogmatiq_protobuf_uuidpb_uuid]);
 /**
  * Describes the message dogma.messaging.v1.UnrecognizedEventStream.
  * Use `create(UnrecognizedEventStreamSchema)` to create a new message.
  */
 export const UnrecognizedEventStreamSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_messaginggrpc_errors, 0);
+/**
+ * Describes the message dogma.messaging.v1.EventStreamConsumerTooSlow.
+ * Use `create(EventStreamConsumerTooSlowSchema)` to create a new message.
+ */
+export const EventStreamConsumerTooSlowSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_messaginggrpc_errors, 1);

package/artifacts/dist/messaginggrpc/eventstreamconsumer_pb.d.ts

@@ -1,6 +1,7 @@
 import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
 import type { MultiEnvelope } from "../envelopepb/envelope_pb.js";
 import type { UUID } from "../uuidpb/uuid_pb.js";
+import type { MessageFilter } from "./filter_pb.js";
 import type { Message } from "@bufbuild/protobuf";
 /**
  * Describes the file github.com/dogmatiq/protobuf/messaginggrpc/eventstreamconsumer.proto.
@@ -14,12 +15,11 @@ export declare const file_github_com_dogmatiq_protobuf_messaginggrpc_eventstream
  */
 export type WatchEventsRequest = Message<"dogma.messaging.v1.WatchEventsRequest"> & {
     /**
-     * MessageTypeIds is the set of message type IDs of the event types to
-     * include in the segments. An empty set matches every event.
+     * Filter describes the events to deliver.
      *
-     * @generated from field: repeated dogma.protobuf.v1.UUID message_type_ids = 1;
+     * @generated from field: dogma.messaging.v1.MessageFilter filter = 1;
      */
-    messageTypeIds: UUID[];
+    filter?: MessageFilter | undefined;
 };
 /**
  * Describes the message dogma.messaging.v1.WatchEventsRequest.
@@ -48,12 +48,11 @@ export type ReadEventsRequest = Message<"dogma.messaging.v1.ReadEventsRequest">
      */
     beginOffset: bigint;
     /**
-     * MessageTypeIds is the set of message type IDs of the event types to
-     * include in the segments. An empty set matches every event.
+     * Filter describes the events to deliver.
      *
-     * @generated from field: repeated dogma.protobuf.v1.UUID message_type_ids = 3;
+     * @generated from field: dogma.messaging.v1.MessageFilter filter = 3;
      */
-    messageTypeIds: UUID[];
+    filter?: MessageFilter | undefined;
 };
 /**
  * Describes the message dogma.messaging.v1.ReadEventsRequest.
@@ -120,25 +119,22 @@ export declare const EventStreamSegmentSchema: GenMessage<EventStreamSegment>;
  */
 export declare const EventStreamConsumerAPI: GenService<{
     /**
-     * WatchEvents delivers events of the requested message types as they are
-     * appended to any event stream offered by the server, for as long as the call
-     * is open.
-     *
-     * The feed starts at the tail of each stream. The first [EventStreamSegment]
-     * the client receives for a stream tells it that the stream exists and where
-     * in the stream the feed begins. After this first segment, each subsequent
-     * segment for the same stream begins at the end offset of the one before it.
-     *
-     * The server MAY send a first segment for every stream it offers, or only for
-     * those streams that contain events of a requested type. In the latter case
-     * the server MUST decide from the events in the stream, not from the types
-     * that the server is able to record.
-     *
-     * If the server can no longer deliver a stream contiguously, for example
-     * because the client has fallen too far behind, it closes the call. A client
-     * that reconnects MUST expect to have missed events. On the new call, the
-     * first segment it receives for each stream again tells it where the feed
-     * begins, which is not necessarily where the previous call left off.
+     * WatchEvents delivers events from all streams available from the server.
+     * Events are delivered as they are appended, provided they match the
+     * request's filter.
+     *
+     * The feed starts at the tail of each stream. Every available stream that
+     * already contains matching events is represented by at least one segment.
+     * The first [EventStreamSegment] received for a stream may be empty, but it
+     * tells the client that the stream exists and the offset at which delivery
+     * begins. Each subsequent segment for that stream begins at the end offset
+     * of the previous segment.
+     *
+     * If the client cannot keep up and the server can no longer deliver a stream
+     * contiguously, the call ends with RESOURCE_EXHAUSTED and an attached
+     * [EventStreamConsumerTooSlow] value identifying the affected stream.
+     *
+     * A missing or invalid message filter results in INVALID_ARGUMENT.
      *
      * @generated from rpc dogma.messaging.v1.EventStreamConsumerAPI.WatchEvents
      */
@@ -148,20 +144,20 @@ export declare const EventStreamConsumerAPI: GenService<{
         output: typeof EventStreamSegmentSchema;
     };
     /**
-     * ReadEvents delivers the events of the requested message types from a
-     * single stream, in order, starting at a specific offset and ending at the
-     * end of the stream as it stands when the server reaches it.
+     * ReadEvents delivers events that match the request's filter from a single
+     * event stream, in order, beginning at the requested offset.
+     *
+     * The first segment begins at the requested offset. Each subsequent segment
+     * begins at the end offset of the previous segment. Delivery ends when the
+     * server reaches the end of the stream, at which point it closes the call.
      *
-     * It is intended for a consumer whose checkpoint is behind the offset at
-     * which [EventStreamConsumerAPI.WatchEvents] began delivering the stream.
-     * It delivers what the caller has missed, then the server closes the call.
+     * An unrecognized stream ID results in NOT_FOUND with an attached
+     * [UnrecognizedEventStream] value. See [UnrecognizedEventStreamError].
      *
-     * If the requested stream ID is not recognized the server MUST return a
-     * NOT_FOUND error with an attached [UnrecognizedEventStream] value. See
-     * [UnrecognizedEventStreamError].
+     * A requested offset beyond the end of the stream results in OUT_OF_RANGE.
+     * An offset equal to the end of the stream is valid and returns no events.
      *
-     * If the requested offset is greater than the offset that the next event
-     * appended to the stream will have, an OUT_OF_RANGE error occurs.
+     * A missing or invalid message filter results in INVALID_ARGUMENT.
      *
      * @generated from rpc dogma.messaging.v1.EventStreamConsumerAPI.ReadEvents
      */

package/artifacts/dist/messaginggrpc/eventstreamconsumer_pb.js

@@ -4,10 +4,11 @@
 import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
 import { file_github_com_dogmatiq_protobuf_envelopepb_envelope } from "../envelopepb/envelope_pb.js";
 import { file_github_com_dogmatiq_protobuf_uuidpb_uuid } from "../uuidpb/uuid_pb.js";
+import { file_github_com_dogmatiq_protobuf_messaginggrpc_filter } from "./filter_pb.js";
 /**
  * Describes the file github.com/dogmatiq/protobuf/messaginggrpc/eventstreamconsumer.proto.
  */
-export const file_github_com_dogmatiq_protobuf_messaginggrpc_eventstreamconsumer = /*@__PURE__*/ fileDesc("CkRnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGMvZXZlbnRzdHJlYW1jb25zdW1lci5wcm90bxISZG9nbWEubWVzc2FnaW5nLnYxIkcKEldhdGNoRXZlbnRzUmVxdWVzdBIxChBtZXNzYWdlX3R5cGVfaWRzGAEgAygLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRCKVAQoRUmVhZEV2ZW50c1JlcXVlc3QSMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIbCgxiZWdpbl9vZmZzZXQYAiABKARCBaoBAggCEjEKEG1lc3NhZ2VfdHlwZV9pZHMYAyADKAsyFy5kb2dtYS5wcm90b2J1Zi52MS5VVUlEIrMBChJFdmVudFN0cmVhbVNlZ21lbnQSMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIbCgxiZWdpbl9vZmZzZXQYAiABKARCBaoBAggCEhkKCmVuZF9vZmZzZXQYAyABKARCBaoBAggCEjMKCWVudmVsb3BlcxgEIAMoCzIgLmRvZ21hLnByb3RvYnVmLnYxLk11bHRpRW52ZWxvcGUy2AEKFkV2ZW50U3RyZWFtQ29uc3VtZXJBUEkSXwoLV2F0Y2hFdmVudHMSJi5kb2dtYS5tZXNzYWdpbmcudjEuV2F0Y2hFdmVudHNSZXF1ZXN0GiYuZG9nbWEubWVzc2FnaW5nLnYxLkV2ZW50U3RyZWFtU2VnbWVudDABEl0KClJlYWRFdmVudHMSJS5kb2dtYS5tZXNzYWdpbmcudjEuUmVhZEV2ZW50c1JlcXVlc3QaJi5kb2dtYS5tZXNzYWdpbmcudjEuRXZlbnRTdHJlYW1TZWdtZW50MAFCLFoqZ2l0aHViLmNvbS9kb2dtYXRpcS9wcm90b2J1Zi9tZXNzYWdpbmdncnBjYghlZGl0aW9uc3DpBw", [file_github_com_dogmatiq_protobuf_envelopepb_envelope, file_github_com_dogmatiq_protobuf_uuidpb_uuid]);
+export const file_github_com_dogmatiq_protobuf_messaginggrpc_eventstreamconsumer = /*@__PURE__*/ fileDesc("CkRnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGMvZXZlbnRzdHJlYW1jb25zdW1lci5wcm90bxISZG9nbWEubWVzc2FnaW5nLnYxIkcKEldhdGNoRXZlbnRzUmVxdWVzdBIxCgZmaWx0ZXIYASABKAsyIS5kb2dtYS5tZXNzYWdpbmcudjEuTWVzc2FnZUZpbHRlciKVAQoRUmVhZEV2ZW50c1JlcXVlc3QSMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIbCgxiZWdpbl9vZmZzZXQYAiABKARCBaoBAggCEjEKBmZpbHRlchgDIAEoCzIhLmRvZ21hLm1lc3NhZ2luZy52MS5NZXNzYWdlRmlsdGVyIrMBChJFdmVudFN0cmVhbVNlZ21lbnQSMAoPZXZlbnRfc3RyZWFtX2lkGAEgASgLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJRBIbCgxiZWdpbl9vZmZzZXQYAiABKARCBaoBAggCEhkKCmVuZF9vZmZzZXQYAyABKARCBaoBAggCEjMKCWVudmVsb3BlcxgEIAMoCzIgLmRvZ21hLnByb3RvYnVmLnYxLk11bHRpRW52ZWxvcGUy2AEKFkV2ZW50U3RyZWFtQ29uc3VtZXJBUEkSXwoLV2F0Y2hFdmVudHMSJi5kb2dtYS5tZXNzYWdpbmcudjEuV2F0Y2hFdmVudHNSZXF1ZXN0GiYuZG9nbWEubWVzc2FnaW5nLnYxLkV2ZW50U3RyZWFtU2VnbWVudDABEl0KClJlYWRFdmVudHMSJS5kb2dtYS5tZXNzYWdpbmcudjEuUmVhZEV2ZW50c1JlcXVlc3QaJi5kb2dtYS5tZXNzYWdpbmcudjEuRXZlbnRTdHJlYW1TZWdtZW50MAFCLFoqZ2l0aHViLmNvbS9kb2dtYXRpcS9wcm90b2J1Zi9tZXNzYWdpbmdncnBjYghlZGl0aW9uc3DpBw", [file_github_com_dogmatiq_protobuf_envelopepb_envelope, file_github_com_dogmatiq_protobuf_uuidpb_uuid, file_github_com_dogmatiq_protobuf_messaginggrpc_filter]);
 /**
  * Describes the message dogma.messaging.v1.WatchEventsRequest.
  * Use `create(WatchEventsRequestSchema)` to create a new message.

package/artifacts/dist/messaginggrpc/filter.d.ts

@@ -0,0 +1,6 @@
+import type { MessageFilter } from "./filter_pb.js";
+/**
+ * Throws an error if x matches no message types or contains an invalid message
+ * type ID.
+ */
+export declare function validateMessageFilter(x: MessageFilter | undefined): void;

package/artifacts/dist/messaginggrpc/filter.js

@@ -0,0 +1,23 @@
+import { validateUUID } from "../uuidpb/uuid.js";
+/**
+ * Throws an error if x matches no message types or contains an invalid message
+ * type ID.
+ */
+export function validateMessageFilter(x) {
+    const types = x?.types;
+    if (types?.case === "all") {
+        return;
+    }
+    const ids = types?.case === "specific" ? types.value.ids : [];
+    if (ids.length === 0) {
+        throw new Error("message filter must match all message types or at least one specific type");
+    }
+    ids.forEach((id, i) => {
+        try {
+            validateUUID(id);
+        }
+        catch (cause) {
+            throw new Error(`invalid message type ID at index ${i}: ${cause.message}`, { cause });
+        }
+    });
+}

package/artifacts/dist/messaginggrpc/filter_pb.d.ts

@@ -0,0 +1,64 @@
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { Empty } from "@bufbuild/protobuf/wkt";
+import type { UUID } from "../uuidpb/uuid_pb.js";
+import type { Message } from "@bufbuild/protobuf";
+/**
+ * Describes the file github.com/dogmatiq/protobuf/messaginggrpc/filter.proto.
+ */
+export declare const file_github_com_dogmatiq_protobuf_messaginggrpc_filter: GenFile;
+/**
+ * MessageFilter describes a set of messages to deliver.
+ *
+ * @generated from message dogma.messaging.v1.MessageFilter
+ */
+export type MessageFilter = Message<"dogma.messaging.v1.MessageFilter"> & {
+    /**
+     * Types determines which message types match. One alternative must be set.
+     *
+     * @generated from oneof dogma.messaging.v1.MessageFilter.types
+     */
+    types: {
+        /**
+         * All matches all message types.
+         *
+         * @generated from field: google.protobuf.Empty all = 1;
+         */
+        value: Empty;
+        case: "all";
+    } | {
+        /**
+         * Specific matches the listed message types.
+         *
+         * @generated from field: dogma.messaging.v1.MessageFilter.MessageTypes specific = 2;
+         */
+        value: MessageFilter_MessageTypes;
+        case: "specific";
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+};
+/**
+ * Describes the message dogma.messaging.v1.MessageFilter.
+ * Use `create(MessageFilterSchema)` to create a new message.
+ */
+export declare const MessageFilterSchema: GenMessage<MessageFilter>;
+/**
+ * MessageTypes describes a set of specific message types.
+ *
+ * @generated from message dogma.messaging.v1.MessageFilter.MessageTypes
+ */
+export type MessageFilter_MessageTypes = Message<"dogma.messaging.v1.MessageFilter.MessageTypes"> & {
+    /**
+     * Ids is the set of message type IDs that match the filter.
+     * The list must not be empty.
+     *
+     * @generated from field: repeated dogma.protobuf.v1.UUID ids = 1;
+     */
+    ids: UUID[];
+};
+/**
+ * Describes the message dogma.messaging.v1.MessageFilter.MessageTypes.
+ * Use `create(MessageFilter_MessageTypesSchema)` to create a new message.
+ */
+export declare const MessageFilter_MessageTypesSchema: GenMessage<MessageFilter_MessageTypes>;

package/artifacts/dist/messaginggrpc/filter_pb.js

@@ -0,0 +1,20 @@
+// @generated by protoc-gen-es v2.16.0 with parameter "target=ts,import_extension=js"
+// @generated from file github.com/dogmatiq/protobuf/messaginggrpc/filter.proto (package dogma.messaging.v1, edition 2024)
+/* eslint-disable */
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
+import { file_google_protobuf_empty } from "@bufbuild/protobuf/wkt";
+import { file_github_com_dogmatiq_protobuf_uuidpb_uuid } from "../uuidpb/uuid_pb.js";
+/**
+ * Describes the file github.com/dogmatiq/protobuf/messaginggrpc/filter.proto.
+ */
+export const file_github_com_dogmatiq_protobuf_messaginggrpc_filter = /*@__PURE__*/ fileDesc("CjdnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGMvZmlsdGVyLnByb3RvEhJkb2dtYS5tZXNzYWdpbmcudjEiuQEKDU1lc3NhZ2VGaWx0ZXISJQoDYWxsGAEgASgLMhYuZ29vZ2xlLnByb3RvYnVmLkVtcHR5SAASQgoIc3BlY2lmaWMYAiABKAsyLi5kb2dtYS5tZXNzYWdpbmcudjEuTWVzc2FnZUZpbHRlci5NZXNzYWdlVHlwZXNIABo0CgxNZXNzYWdlVHlwZXMSJAoDaWRzGAEgAygLMhcuZG9nbWEucHJvdG9idWYudjEuVVVJREIHCgV0eXBlc0IsWipnaXRodWIuY29tL2RvZ21hdGlxL3Byb3RvYnVmL21lc3NhZ2luZ2dycGNiCGVkaXRpb25zcOkH", [file_google_protobuf_empty, file_github_com_dogmatiq_protobuf_uuidpb_uuid]);
+/**
+ * Describes the message dogma.messaging.v1.MessageFilter.
+ * Use `create(MessageFilterSchema)` to create a new message.
+ */
+export const MessageFilterSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_messaginggrpc_filter, 0);
+/**
+ * Describes the message dogma.messaging.v1.MessageFilter.MessageTypes.
+ * Use `create(MessageFilter_MessageTypesSchema)` to create a new message.
+ */
+export const MessageFilter_MessageTypesSchema = /*@__PURE__*/ messageDesc(file_github_com_dogmatiq_protobuf_messaginggrpc_filter, 0, 0);

package/artifacts/dist/messaginggrpc/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./errors_pb.js";
 export * from "./eventstreamconsumer_pb.js";
+export * from "./filter.js";
+export * from "./filter_pb.js";

package/artifacts/dist/messaginggrpc/index.js

@@ -1,2 +1,4 @@
 export * from "./errors_pb.js";
 export * from "./eventstreamconsumer_pb.js";
+export * from "./filter.js";
+export * from "./filter_pb.js";

package/artifacts/dist/uuidpb/uuid.js

@@ -42,6 +42,12 @@ export function uuidEquals(a, b) {
  * (name-based) UUID.
  */
 export function validateUUID(x) {
+    if (x.upper < 0n ||
+        x.upper > MAX_UINT64 ||
+        x.lower < 0n ||
+        x.lower > MAX_UINT64) {
+        throw new Error("UUID components must be unsigned 64-bit integers");
+    }
     const version = (x.upper >> 8n) & 0xf0n;
     if (version !== 0x40n && version !== 0x50n) {
         throw new Error("UUID must use version 4 or 5");
@@ -82,6 +88,7 @@ export function parseUUID(str) {
         lower: BigInt("0x" + hex.slice(16)),
     });
 }
+const MAX_UINT64 = 0xffffffffffffffffn;
 const PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 // toBytes returns the 16-byte big-endian representation of a UUID.
 function toBytes(x) {

package/artifacts/dist/uuidpb/uuid_pb.d.ts

@@ -7,6 +7,9 @@ export declare const file_github_com_dogmatiq_protobuf_uuidpb_uuid: GenFile;
 /**
  * UUID is a size-optimized representation of an RFC 9562 UUID.
  *
+ * UUID values MUST use version 4 (random) or version 5 (name-based), and the
+ * RFC 9562 variant.
+ *
  * @generated from message dogma.protobuf.v1.UUID
  */
 export type UUID = Message<"dogma.protobuf.v1.UUID"> & {

package/envelopepb/envelope.proto

@@ -10,7 +10,9 @@ import "github.com/dogmatiq/protobuf/uuidpb/uuid.proto";
 
 // Envelope is a container for a Dogma message and its meta-data.
 //
-// It is wire-compatible with [MultiEnvelope].
+// An Envelope can be decoded as a single-body [MultiEnvelope]. Decoding a
+// MultiEnvelope as an Envelope is only safe when it contains exactly one body;
+// multiple bodies merge when decoded into the singular body field.
 message Envelope {
   Header header = 1;
   Body   body   = 2;
@@ -18,7 +20,6 @@ message Envelope {
 
 // MultiEnvelope is an efficient encoding of an ordered sequence of [Envelope]
 // values that share common header context.
-//
 message MultiEnvelope {
   Header        header = 1;
   repeated Body bodies = 2;
@@ -73,6 +74,11 @@ message Message {
   bytes data = 3 [features.field_presence = IMPLICIT];
 }
 
+// Header contains origin and causal context that can be common to messages
+// produced by the same cause.
+//
+// Extensions and baggage from the header and body are combined by message
+// type. Body values take precedence over header values of the same type.
 message Header {
   // CausationId is the ID of the message that was the direct cause of the
   // messages.

package/identitypb/identity.proto

@@ -11,6 +11,8 @@ import "github.com/dogmatiq/protobuf/uuidpb/uuid.proto";
 message Identity {
   // Name is the entity's human-readable name.
   //
+  // The name MUST be between 1 and 255 bytes when encoded as UTF-8.
+  //
   // The name should be unique enough to allow a human to identify the entity
   // without ambiguity. There is no hard requirement for uniqueness.
   //

package/messaginggrpc/errors.proto

@@ -11,3 +11,15 @@ message UnrecognizedEventStream {
   // EventStreamId is the ID of the unrecognized stream.
   dogma.protobuf.v1.UUID event_stream_id = 1;
 }
+
+// EventStreamConsumerTooSlow is an error-details value for RESOURCE_EXHAUSTED
+// errors returned by WatchEvents when a client cannot keep up and the server
+// can no longer deliver a stream contiguously.
+//
+// A client that is behind the tail does not cause this error while contiguous
+// delivery remains possible.
+message EventStreamConsumerTooSlow {
+  // EventStreamId is the ID of the stream that could no longer be delivered
+  // contiguously.
+  dogma.protobuf.v1.UUID event_stream_id = 1;
+}

package/messaginggrpc/eventstreamconsumer.proto

@@ -5,54 +5,51 @@ option go_package = "github.com/dogmatiq/protobuf/messaginggrpc";
 
 import "github.com/dogmatiq/protobuf/envelopepb/envelope.proto";
 import "github.com/dogmatiq/protobuf/uuidpb/uuid.proto";
+import "github.com/dogmatiq/protobuf/messaginggrpc/filter.proto";
 
 // EventStreamConsumerAPI is a service for consuming event messages from
 // offset-based, ordered event streams.
 service EventStreamConsumerAPI {
-  // WatchEvents delivers events of the requested message types as they are
-  // appended to any event stream offered by the server, for as long as the call
-  // is open.
+  // WatchEvents delivers events from all streams available from the server.
+  // Events are delivered as they are appended, provided they match the
+  // request's filter.
   //
-  // The feed starts at the tail of each stream. The first [EventStreamSegment]
-  // the client receives for a stream tells it that the stream exists and where
-  // in the stream the feed begins. After this first segment, each subsequent
-  // segment for the same stream begins at the end offset of the one before it.
+  // The feed starts at the tail of each stream. Every available stream that
+  // already contains matching events is represented by at least one segment.
+  // The first [EventStreamSegment] received for a stream may be empty, but it
+  // tells the client that the stream exists and the offset at which delivery
+  // begins. Each subsequent segment for that stream begins at the end offset
+  // of the previous segment.
   //
-  // The server MAY send a first segment for every stream it offers, or only for
-  // those streams that contain events of a requested type. In the latter case
-  // the server MUST decide from the events in the stream, not from the types
-  // that the server is able to record.
+  // If the client cannot keep up and the server can no longer deliver a stream
+  // contiguously, the call ends with RESOURCE_EXHAUSTED and an attached
+  // [EventStreamConsumerTooSlow] value identifying the affected stream.
   //
-  // If the server can no longer deliver a stream contiguously, for example
-  // because the client has fallen too far behind, it closes the call. A client
-  // that reconnects MUST expect to have missed events. On the new call, the
-  // first segment it receives for each stream again tells it where the feed
-  // begins, which is not necessarily where the previous call left off.
+  // A missing or invalid message filter results in INVALID_ARGUMENT.
   rpc WatchEvents(WatchEventsRequest) returns (stream EventStreamSegment);
 
-  // ReadEvents delivers the events of the requested message types from a
-  // single stream, in order, starting at a specific offset and ending at the
-  // end of the stream as it stands when the server reaches it.
+  // ReadEvents delivers events that match the request's filter from a single
+  // event stream, in order, beginning at the requested offset.
   //
-  // It is intended for a consumer whose checkpoint is behind the offset at
-  // which [EventStreamConsumerAPI.WatchEvents] began delivering the stream.
-  // It delivers what the caller has missed, then the server closes the call.
+  // The first segment begins at the requested offset. Each subsequent segment
+  // begins at the end offset of the previous segment. Delivery ends when the
+  // server reaches the end of the stream, at which point it closes the call.
   //
-  // If the requested stream ID is not recognized the server MUST return a
-  // NOT_FOUND error with an attached [UnrecognizedEventStream] value. See
-  // [UnrecognizedEventStreamError].
+  // An unrecognized stream ID results in NOT_FOUND with an attached
+  // [UnrecognizedEventStream] value. See [UnrecognizedEventStreamError].
   //
-  // If the requested offset is greater than the offset that the next event
-  // appended to the stream will have, an OUT_OF_RANGE error occurs.
+  // A requested offset beyond the end of the stream results in OUT_OF_RANGE.
+  // An offset equal to the end of the stream is valid and returns no events.
+  //
+  // A missing or invalid message filter results in INVALID_ARGUMENT.
   rpc ReadEvents(ReadEventsRequest) returns (stream EventStreamSegment);
 }
 
 // WatchEventsRequest is the input to the [EventStreamConsumerAPI.WatchEvents]
 // method.
 message WatchEventsRequest {
-  // MessageTypeIds is the set of message type IDs of the event types to
-  // include in the segments. An empty set matches every event.
-  repeated dogma.protobuf.v1.UUID message_type_ids = 1;
+  // Filter describes the events to deliver.
+  MessageFilter filter = 1;
 }
 
 // ReadEventsRequest is the input to the [EventStreamConsumerAPI.ReadEvents]
@@ -66,9 +63,8 @@ message ReadEventsRequest {
   // are delivered, then the call is closed.
   uint64 begin_offset = 2 [features.field_presence = IMPLICIT];
 
-  // MessageTypeIds is the set of message type IDs of the event types to
-  // include in the segments. An empty set matches every event.
-  repeated dogma.protobuf.v1.UUID message_type_ids = 3;
+  // Filter describes the events to deliver.
+  MessageFilter filter = 3;
 }
 
 // EventStreamSegment is a contiguous piece of one event stream, the half-open

package/messaginggrpc/filter.proto

@@ -0,0 +1,26 @@
+edition = "2024";
+package dogma.messaging.v1;
+
+option go_package = "github.com/dogmatiq/protobuf/messaginggrpc";
+
+import "google/protobuf/empty.proto";
+import "github.com/dogmatiq/protobuf/uuidpb/uuid.proto";
+
+// MessageFilter describes a set of messages to deliver.
+message MessageFilter {
+  // MessageTypes describes a set of specific message types.
+  message MessageTypes {
+    // Ids is the set of message type IDs that match the filter.
+    // The list must not be empty.
+    repeated dogma.protobuf.v1.UUID ids = 1;
+  }
+
+  // Types determines which message types match. One alternative must be set.
+  oneof types {
+    // All matches all message types.
+    google.protobuf.Empty all = 1;
+
+    // Specific matches the listed message types.
+    MessageTypes specific = 2;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogmatiq/protobuf",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Protocol Buffers and gRPC definitions for Dogma",
   "keywords": [
     "dogma",
@@ -62,7 +62,7 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@bufbuild/protobuf": "^2.16.0",
     "@bufbuild/protoc-gen-es": "^2.16.0",
-    "@types/node": "^20.19.43",
+    "@types/node": "^26.6.6",
     "@vitest/coverage-v8": "^5.0.5",
     "prettier": "^3.9.10",
     "prettier-plugin-organize-imports": "^4.3.0",

package/uuidpb/uuid.proto

@@ -4,6 +4,9 @@ package dogma.protobuf.v1;
 option go_package = "github.com/dogmatiq/protobuf/uuidpb";
 
 // UUID is a size-optimized representation of an RFC 9562 UUID.
+//
+// UUID values MUST use version 4 (random) or version 5 (name-based), and the
+// RFC 9562 variant.
 message UUID {
   uint64 upper = 1 [features.field_presence = IMPLICIT];
   uint64 lower = 2 [features.field_presence = IMPLICIT];