@spine-event-engine/proto 2.0.0-snapshot.2

package/proto/spine/core/event.proto

@@ -0,0 +1,197 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.core;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_package = "io.spine.core";
+option java_multiple_files = true;
+option java_outer_classname = "EventProto";
+
+import "google/protobuf/any.proto";
+import "google/protobuf/timestamp.proto";
+
+import "spine/core/actor_context.proto";
+import "spine/core/command.proto";
+import "spine/core/diagnostics.proto";
+import "spine/core/enrichment.proto";
+import "spine/core/version.proto";
+
+// Event identifier.
+message EventId {
+    option (is).java_type = "io.spine.core.EventIdMixin";
+    option (SPI_type) = true;
+
+    // A value of the event identifier.
+    //
+    // In most cases it would be a generated UUID-based string.
+    //
+    string value = 1;
+}
+
+// `Event` is something that happened in the past.
+//
+// An event consists of two parts: event message and its context.
+//
+// The `message` is the domain model part of the event.
+// Event messages are named in the past tense.
+//
+// The type of the event is defined by the type of the enclosed message.
+// When we speak about an 'event' as a typed thing, we refer to the message of the event.
+//
+// An event subscriber uses the type of the event message to receive events of this type.
+//
+// There can be multiple subscribers per event type.
+//
+// The event context contains attributes common for all events.
+// It can also contain additional attributes added by the code handling the event.
+//
+// There is a special case of an event - a rejection event.
+// A rejection event represents erroneous conditions in business, which do not allow executing
+// a command. The event is a rejection event if the `EventContext.rejection` field is present.
+//
+// See `EventContext.rejection` to determine the event kind.
+//
+message Event {
+    option (is).java_type = "EventMixin";
+    option (SPI_type) = true;
+
+    // The ID of the event.
+    EventId id = 1 [(required) = true];
+
+    // The message of the event wrapped into `Any`.
+    google.protobuf.Any message = 2 [(required) = true, (validate) = true];
+
+    // The context of the event.
+    EventContext context = 3 [(required) = true];
+}
+
+// Meta-information for an event.
+message EventContext {
+    option (is).java_type = "EventContextMixin";
+    option (SPI_type) = true;
+
+    // When the event occurred.
+    google.protobuf.Timestamp timestamp = 1 [(required) = true];
+
+    oneof origin {
+        // The context of the command that generated this event.
+        CommandContext command_context = 2 [(validate) = true, deprecated = true];
+
+        // The context of the event that generated this event.
+        EventContext event_context = 6 [(validate) = true, deprecated = true];
+
+        Origin past_message = 14 [(validate) = true];
+
+        // The event was imported using this `ActorContext`.
+        ActorContext import_context = 11 [(validate) = true];
+    }
+
+    // An ID of the origin message.
+    //
+    // The case of this `oneof` is always the same as the case of `origin` (except for
+    // the `import_context`, which does not have a corresponding field in `origin_id`).
+    //
+    // The `origin` and `origin_id` groups are not merged for the reasons of binary compatibility.
+    //
+    oneof origin_id {
+
+        // The ID of the origin command.
+        CommandId command_id = 12 [deprecated = true];
+
+        // The ID of the origin event.
+        EventId event_id = 13 [deprecated = true];
+    }
+
+    // An ID of the root command, which led to this event.
+    //
+    // If the event is a reaction to another event, then this attribute holds the identifier
+    // of the very first command in this chain.
+    //
+    // This field is not populated if the event was imported.
+    //
+    CommandId root_command_id = 9 [deprecated = true];
+
+    // The ID of the entity that generated the event.
+    //
+    // Examples of event producers are: aggregates, process managers.
+    //
+    google.protobuf.Any producer_id = 3 [(required) = true];
+
+    // The version of the entity after the event was applied.
+    Version version = 4 [(validate) = true];
+
+    // Optional enrichment of the event.
+    Enrichment enrichment = 5;
+
+    // An internal runtime attribute, which marks an event as external to the `BoundedContext`
+    // in which the event is being processed.
+    bool external = 8 [(internal) = true];
+
+    // The context of the associated rejection event.
+    //
+    // If the associated event is a rejection event, this field is present.
+    //
+    RejectionEventContext rejection = 10;
+
+    // Deleted fields.
+    reserved 7;
+    reserved "rejection_context";
+}
+
+// Meta-information about a rejection event.
+//
+message RejectionEventContext {
+    option (SPI_type) = true;
+
+    core.Command command = 3;
+
+    // A stacktrace from the code, which generated the rejection message (if available).
+    string stacktrace = 2;
+
+    // The message of the command that caused the rejection.
+    google.protobuf.Any command_message = 1 [deprecated = true];
+}
+
+// Enumeration of possible event validation technical error reasons.
+enum EventValidationError {
+
+    // Reserved value.
+    UNKNOWN_REASON = 0;
+
+    // The event type is not supported by the server.
+    UNSUPPORTED_EVENT = 1;
+
+    // The event message is invalid according to custom Protobuf options set.
+    INVALID_EVENT = 2;
+
+    // The event was already handled before.
+    DUPLICATE_EVENT = 3;
+}

package/proto/spine/core/response.proto

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.core;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_package = "io.spine.core";
+option java_multiple_files = true;
+option java_outer_classname = "ResponseProto";
+
+import "google/protobuf/empty.proto";
+
+import "spine/base/error.proto";
+import "spine/core/event.proto";
+
+// The result of a call returned by a service.
+//
+// A service may return `ok` or an `error` (technical problem) or a `rejection`.
+// The client may expect results (returned via a separate call to the read-side or via event
+// stream) only upon receiving the `ok` status.
+//
+message Response {
+    option (is).java_type = "ResponseMixin";
+
+    // The response status.
+    Status status = 1 [(required) = true];
+}
+
+// The response status.
+message Status {
+    oneof status {
+        option (choice).required = true;
+
+        // The request was accepted to execution.
+        google.protobuf.Empty ok = 1;
+
+        // The technical error occurred upon receiving the request, and no further
+        // processing would occur.
+        base.Error error = 2;
+
+        // It is not possible to satisfy the request because of the business rejection.
+        core.Event rejection = 3;
+    }
+}

package/proto/spine/core/tenant_id.proto

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.core;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_package = "io.spine.core";
+option java_multiple_files = true;
+option java_outer_classname = "TenantIdProto";
+
+import "spine/net/internet_domain.proto";
+import "spine/net/email_address.proto";
+
+// An identifier of a tenant in a multi-tenant application.
+//
+// Commands sent in such an application must have a non-default value of
+// the `tenant_id` field in `CommandContext`.
+//
+message TenantId {
+    oneof kind {
+        // The tenant has an Internet domain name.
+        net.InternetDomain domain = 1;
+
+        // The tenant is a person or an organization without a domain name.
+        net.EmailAddress email = 2;
+
+        // reserved 3 to 19;
+
+        // Application-specific value.
+        string value = 20;
+    }
+
+    reserved 3 to 19;
+}

package/proto/spine/core/user_id.proto

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2022, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+syntax = "proto3";
+
+package spine.core;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_package = "io.spine.core";
+option java_multiple_files = true;
+option java_outer_classname = "UserIdProto";
+
+// A string-based identifier of the user.
+message UserId {
+    // User ID value.
+    string value = 1;
+}
+

package/proto/spine/core/version.proto

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+syntax = "proto3";
+
+package spine.core;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_package = "io.spine.core";
+option java_outer_classname = "VersionProto";
+option java_multiple_files = true;
+
+import "google/protobuf/timestamp.proto";
+
+// A version number with the timestamp of the version creation.
+message Version {
+    option (is).java_type = "io.spine.core.VersionMixin";
+
+    // Order versions by their number first, and then by their timestamp.
+    //
+    // Versions are compared by their `number` first; when the numbers are equal,
+    // the `timestamp` of the version creation breaks the tie.
+    //
+    option (compare_by) = {
+        field: "number"
+        field: "timestamp"
+    };
+
+    // A zero-based version number.
+    //
+    // When numbering versions of entities, the zero value is reserved for
+    // the "pre-initialization" version of an entity.
+    //
+    int32 number = 1 [(min).value = "0"];
+
+    // A moment in time when the new version was created.
+    google.protobuf.Timestamp timestamp = 2 [(required) = true];
+}

package/proto/spine/delivery/admin/admin_service.proto

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2000-2026 TeamDev. All rights reserved.
+ * TeamDev PROPRIETARY and CONFIDENTIAL.
+ * Use is subject to license terms.
+ */
+syntax = "proto3";
+
+package spine.delivery;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_package = "io.spine.delivery.admin.grpc";
+option java_outer_classname = "AdminServiceProto";
+option java_multiple_files = true;
+option java_generate_equals_and_hash = true;
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/empty.proto";
+
+import "spine/server/delivery/delivery.proto";
+
+// Acts as a backend implementation for `AdminService`
+service AdminService {
+
+    // Gets an information about shards on Liquor server.
+    rpc GetShardInfo(google.protobuf.Empty) returns (ShardInfoList);
+
+    // Subscribes to the updates of shard info.
+    //
+    // The first received `SubscriptionResponse` is an acknowledgement of a successfully created
+    // subscription and contains only the `created` filed set. All other responses contain
+    // `ShardInfoUpdate`. It is guaranteed that the acknowledgement is sent only once as a first
+    // response and never repeated again. Also, it is impossible that any update comes
+    // before the acknowledgement.
+    //
+    // Users should consider the subscription as created only after receiving the acknowledgement
+    // in the `SubscriptionResponse`. All changes in the system occurred before the subscription
+    // acknowledgement is not tracked by this call.
+    //
+    // Each update is sent as a single `ShardInfoUpdate`.
+    //
+    rpc SubscribeToShardUpdates(google.protobuf.Empty) returns (stream SubscriptionResponse);
+}
+
+// An outcome of the subscription to the `ShardInfoUpdate`.
+message SubscriptionResponse {
+
+    oneof value {
+
+        // Indicates that the subscription is created.
+        bool created = 1;
+
+        // An update of the shard state.
+        ShardInfoUpdate update = 2;
+    }
+}
+
+// An update of the shard info.
+message ShardInfoUpdate {
+
+    spine.server.delivery.ShardIndex index = 1 [(required) = true];
+
+    // New status of the shard.
+    ShardStatus new_status = 2;
+
+    // New time when the shard was picked for delivery last time.
+    google.protobuf.Timestamp when_last_picked = 3;
+
+    // New number of messages present in the shard.
+    int32 new_messages_count = 4;
+}
+
+// A list of `ShardInfo`.
+message ShardInfoList {
+
+    repeated ShardInfo shards = 1;
+}
+
+// Information about shard status on the Liquor server.
+message ShardInfo {
+
+    // Index of the shard.
+    spine.server.delivery.ShardIndex index = 1 [(required) = true];
+
+    // Shows whether the shard picked for delivery or not.
+    ShardStatus status = 2 [(required) = true];
+
+    // When the shard was picked for delivery last time.
+    //
+    // Can be unset if the shard has never been picked by workers.
+    google.protobuf.Timestamp last_picked = 3;
+
+    // Number of messages present in the shard.
+    //
+    // The `(required)` option is not applicable to scalar `int32` fields in the current
+    // Spine validation rules, so it is not set here; `0` is a valid value.
+    int32 messages = 4;
+}
+
+// Current status of the shard.
+enum ShardStatus {
+    SS_UNKNOWN = 0;
+
+    // Shard is picked for delivery.
+    PICKED = 1;
+
+    // Shard is not picked for delivery.
+    NOT_PICKED = 2;
+}

package/proto/spine/delivery/commands.proto

@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2000-2026 TeamDev. All rights reserved.
+ * TeamDev PROPRIETARY and CONFIDENTIAL.
+ * Use is subject to license terms.
+ */
+
+syntax = "proto3";
+
+package spine.delivery;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_package = "io.spine.delivery.command";
+option java_outer_classname = "CommandsProto";
+option java_multiple_files = true;
+option java_generate_equals_and_hash = true;
+
+import "google/protobuf/duration.proto";
+
+import "spine/server/delivery/inbox.proto";
+import "spine/server/delivery/delivery.proto";
+
+// Writes a new message to the Inbox.
+message WriteMessage {
+    option (is).java_type = "io.spine.delivery.WithInboxMessage";
+
+    // The message to be written to the Inbox.
+    spine.server.delivery.InboxMessage message = 1 [(required) = true];
+}
+
+// Writes new messages to the Inbox.
+message WriteMessages {
+
+    // A shard into which the messages are written.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The messages to be written to the Inbox.
+    repeated spine.server.delivery.InboxMessage message = 2 [(required) = true];
+}
+
+// Removes a message from the Inbox.
+message RemoveMessage {
+    option (is).java_type = "io.spine.delivery.WithInboxMessage";
+
+    // The message to be removed from the Inbox.
+    spine.server.delivery.InboxMessage message = 1 [(required) = true];
+}
+
+// Removes messages from the Inbox.
+message RemoveMessages {
+
+    // A shard from which the messages are removed.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The messages to be removed from the Inbox.
+    repeated spine.server.delivery.InboxMessage message = 2 [(required) = true];
+}
+
+// Picks up the shard for processing.
+message PickUpShard {
+
+    // The shard to pick up work from.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The worker that is going to perform the work.
+    spine.server.delivery.WorkerId worker = 2 [(required) = true];
+}
+
+// Releases the shard which has been previously picked up.
+message ReleaseShard {
+
+    // The shard to release.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The worker that was performing the work.
+    spine.server.delivery.WorkerId worker = 2 [(required) = true];
+}
+
+// Releases the sharded work sessions that were picked up before the configured
+// inactivity period.
+message ReleaseExpiredSessions {
+
+    // The duration of the period after which the shard delivery session is considered expired.
+    google.protobuf.Duration inactivity_period = 1 [(required) = true];
+}