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

package/proto/spine/delivery/events.proto

@@ -0,0 +1,107 @@
+/*
+ * 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.event";
+option java_outer_classname = "EventsProto";
+option java_multiple_files = true;
+option java_generate_equals_and_hash = true;
+
+import "google/protobuf/timestamp.proto";
+
+import "spine/server/delivery/inbox.proto";
+import "spine/server/delivery/delivery.proto";
+
+// A new message was written to a particular Inbox.
+message MessageWritten {
+    option (is).java_type = "io.spine.delivery.WithInboxMessage";
+
+    // The message that was written to the Inbox.
+    spine.server.delivery.InboxMessage message = 1 [(required) = true];
+}
+
+// New messages were written to a particular Inbox.
+message MessagesWritten {
+
+    // A shard into which the messages are written.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The messages that were written to the Inbox.
+    repeated spine.server.delivery.InboxMessage message = 2 [(required) = true];
+}
+
+// A message was removed from a particular Inbox.
+message MessageRemoved {
+    option (is).java_type = "io.spine.delivery.WithInboxMessage";
+
+    // The message that was removed from the Inbox.
+    spine.server.delivery.InboxMessage message = 1 [(required) = true];
+}
+
+// Messages were removed from a particular Inbox.
+message MessagesRemoved {
+
+    // A shard from which the messages are removed.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The messages that were removed from the Inbox.
+    repeated spine.server.delivery.InboxMessage message = 2 [(required) = true];
+}
+
+// A shard has been picked up by a worker.
+message ShardPickedUp {
+
+    // The shard in which the worker has picked up work from.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // An identifier of the worker, which picked up the shard.
+    spine.server.delivery.WorkerId worker = 2 [(required) = true];
+
+    // The time when the `worker` has picked up the shard.
+    google.protobuf.Timestamp when_picked = 3 [(required) = true];
+}
+
+// A shard has been released by a worker.
+message ShardReleased {
+
+    // The shard that was released.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // An identifier of the worker that released the shard.
+    spine.server.delivery.WorkerId worker = 2 [(required) = true];
+
+    // The time when the `worker` has released the shard.
+    google.protobuf.Timestamp when_released = 3 [(required) = true];
+}
+
+// Sharded work sessions that were picked up before the specified inactivity period were released.
+message ExpiredSessionsReleased {
+
+    // The shards that were released if any.
+    repeated ExpiredSession shard = 1;
+}
+
+// The expired sharded work session.
+message ExpiredSession {
+
+    // The shard that was released.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // An identifier of the worker that released the shard.
+    spine.server.delivery.WorkerId worker = 2 [(required) = true];
+
+    // The time when the `worker` has picked up the shard.
+    google.protobuf.Timestamp when_picked = 3 [(required) = true];
+
+    // The time when the `worker` has released the shard.
+    google.protobuf.Timestamp when_released = 4 [(required) = true];
+}

package/proto/spine/delivery/message_delivery.proto

@@ -0,0 +1,90 @@
+/*
+ * 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";
+option java_outer_classname = "MessageDeliveryServiceProto";
+option java_multiple_files = true;
+option java_generate_equals_and_hash = true;
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/empty.proto";
+
+import "spine/delivery/commands.proto";
+import "spine/delivery/events.proto";
+import "spine/delivery/pick_up_outcome.proto";
+import "spine/server/delivery/inbox.proto";
+import "spine/server/delivery/delivery.proto";
+
+
+// Acts as a back-end implementation for `InboxStorage`.
+service InboxService {
+
+    // Writes a single message to the `InboxStorage`.
+    rpc WriteOne(WriteMessage) returns (google.protobuf.Empty);
+
+    // Writes several messages to the `InboxStorage`.
+    rpc WriteMany(WriteMessages) returns (google.protobuf.Empty);
+
+    // Removes a single message from the `InboxStorage`.
+    rpc RemoveOne(RemoveMessage) returns (google.protobuf.Empty);
+
+    // Removes several messages from the `InboxStorage`.
+    rpc RemoveMany(RemoveMessages) returns (google.protobuf.Empty);
+
+    // Finds a single message by its ID.
+    rpc FindOne(spine.server.delivery.InboxMessageId) returns (OptionalInboxMessage);
+
+    // Finds many messages according to the query parameters.
+    rpc FindManyInShard(ReadMessagesSinceTime) returns (PageOfMessages);
+
+    // Finds the latest `InboxMessage` in `TO_DELIVER` status, which belongs to the specified shard.
+    rpc NewestMessageToDeliver(spine.server.delivery.ShardIndex) returns (OptionalInboxMessage);
+}
+
+// Acts as a back-end implementation for `ShardSessionRegistry`.
+service ShardService {
+
+    // Picks up the shard for processing.
+    rpc PickShard(PickUpShard) returns (LiquorPickUpOutcome);
+
+    // Releases the shard after its processing is done.
+    rpc ReleaseSession(ReleaseShard) returns (google.protobuf.Empty);
+
+    // Releases sessions which were picked up earlier that the configured inactivity period.
+    rpc ReleaseSessions(ReleaseExpiredSessions) returns (ExpiredSessionsReleased);
+}
+
+// A query to read `InboxMessage`s.
+message ReadMessagesSinceTime {
+
+    // The shard to which the target messages belong.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The point in time, being the earliest receival time for the target messages.
+    google.protobuf.Timestamp since_when = 2;
+
+    // The maximum number of matched messages to return.
+    int32 page_size = 3;
+}
+
+// A result of `ReadMessagesSinceTime` query execution.
+message PageOfMessages {
+
+    // The messages read.
+    repeated spine.server.delivery.InboxMessage message = 1;
+}
+
+// An optional `InboxMessage` that may or may not have been found in the `InboxStorage`.
+message OptionalInboxMessage {
+
+    spine.server.delivery.InboxMessage message = 1;
+}

package/proto/spine/delivery/pick_up_outcome.proto

@@ -0,0 +1,40 @@
+/*
+ * 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";
+option java_outer_classname = "LiquorPickUpOutcomeProto";
+option java_multiple_files = true;
+option java_generate_equals_and_hash = true;
+
+import "spine/delivery/events.proto";
+import "spine/delivery/rejections.proto";
+
+// An outcome of the shard pick up attempt.
+//
+// This is a Liquor-internal type that is created as counterpart of `PickUpOutcome` introduced in
+// `spine-core` in version `1.9.x`. Liquor servers are already using the core library `2.0.x`
+// which doesn't have this type yet. That's why this counterpart helps to connect Liquor servers
+// that using core `2.0.x` and Liquor clients that are on core `1.9.x`.
+//
+message LiquorPickUpOutcome {
+
+    oneof value {
+
+        option (choice).required = true;
+
+        // Signals that he shard is successfully picked up.
+        ShardPickedUp picked_up = 1;
+
+        // Signals that the shard could not be picked up as it's already picked by another worker.
+        ShardAlreadyPickedUp already_picked_up = 2;
+    }
+}

package/proto/spine/delivery/rejections.proto

@@ -0,0 +1,49 @@
+/*
+ * 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.rejection";
+option java_generate_equals_and_hash = true;
+
+import "google/protobuf/timestamp.proto";
+import "spine/server/delivery/delivery.proto";
+
+// A shard cannot be picked up because some worker has already picked it up.
+message ShardAlreadyPickedUp {
+
+    // The shard in which some worker has picked up work in.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The worker that picked up the work in the shard.
+    spine.server.delivery.WorkerId worker = 2 [(required) = true];
+
+    // When the worker picked up the work in the shard.
+    google.protobuf.Timestamp when_picked = 3 [(required) = true];
+}
+
+// A shard cannot be release by the worker.
+message UnableToReleaseShard {
+
+    // The shard that should have been released.
+    spine.server.delivery.ShardIndex shard = 1 [(required) = true];
+
+    // The worker which was trying to release the `shard`.
+    spine.server.delivery.WorkerId worker = 2 [(required) = true];
+
+    Reason reason = 3;
+
+    // The reason why the shard cannot be released.
+    message Reason {
+
+        string value = 1 [(required) = true];
+    }
+}

package/proto/spine/deployment/node_discovery.proto

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2026, CodeMatters. 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
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+syntax = "proto3";
+
+package spine.deployment;
+
+import "google/protobuf/timestamp.proto";
+import "spine/options.proto";
+import "spine/server/server_environment.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_multiple_files = true;
+
+// An identifier of one application-node registration.
+message NodeRegistrationId {
+
+    // The value of the identifier.
+    string value = 1 [(required) = true];
+}
+
+// A network endpoint advertised by an application node.
+message ApplicationNodeEndpoint {
+
+    // The HTTP or HTTPS origin without a trailing slash.
+    string origin = 1 [(required) = true];
+
+    // The TLS server name explicitly configured for an HTTPS endpoint.
+    //
+    // An empty value means that the endpoint origin determines the server name.
+    //
+    string tls_server_name = 2;
+}
+
+// A time-limited registration of an available application node.
+message ApplicationNodeLease {
+
+    // The application node that owns the registration.
+    spine.server.NodeId node_id = 1 [(required) = true, (validate) = true];
+
+    // The endpoint through which the node accepts requests.
+    ApplicationNodeEndpoint endpoint = 2 [(required) = true, (validate) = true];
+
+    // The time after which the registration is no longer current.
+    google.protobuf.Timestamp when_expires = 3 [(required) = true];
+
+    // The identifier that fences one registration lifetime.
+    NodeRegistrationId registration_id = 4 [(required) = true, (validate) = true];
+}

package/proto/spine/net/email_address.proto

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2023, 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.net;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_multiple_files = true;
+option java_outer_classname = "EmailAddressProto";
+option java_package = "io.spine.net";
+
+// An email address.
+//
+// See https://github.com/SpineEventEngine/base/issues/361.
+message EmailAddress {
+
+    // String value of the address.
+    //
+    // No validation is performed for the passed value.
+    string value = 1;
+}

package/proto/spine/net/internet_domain.proto

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2023, 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.net;
+
+import "spine/options.proto";
+
+option (type_url_prefix) = "type.spine.io";
+option java_multiple_files = true;
+option java_outer_classname = "InternetDomainProto";
+option java_package = "io.spine.net";
+
+// An Internet domain name.
+message InternetDomain {
+    // The value of the domain name.
+    //
+    // It is the responsibility of the application to provide a correct value for this field.
+    string value = 1;
+}