cloudstate.event_sourced.proto Maven / Gradle / Ivy

Go to download
// Copyright 2019 Lightbend Inc.
//
// 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
//
// 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.

// gRPC interface for Event Sourced Entity user functions.

syntax = "proto3";

package cloudstate.eventsourced;

// Any is used so that domain events defined according to the functions business domain can be embedded inside
// the protocol.
import "google/protobuf/any.proto";
import "cloudstate/entity.proto";

option java_package = "io.cloudstate.protocol";

// The init message. This will always be the first message sent to the entity when
// it is loaded.
message EventSourcedInit {

    string service_name = 1;

    // The ID of the entity.
    string entity_id = 2;

    // If present the entity should initialise its state using this snapshot.
    EventSourcedSnapshot snapshot = 3;
}

// A snapshot
message EventSourcedSnapshot {

    // The sequence number when the snapshot was taken.
    int64 snapshot_sequence = 1;

    // The snapshot.
    google.protobuf.Any snapshot = 2;
}

// An event. These will be sent to the entity when the entity starts up.
message EventSourcedEvent {

    // The sequence number of the event.
    int64 sequence = 1;

    // The event payload.
    google.protobuf.Any payload = 2;
}

// A reply to a command.
message EventSourcedReply {

    // The id of the command being replied to. Must match the input command.
    int64 command_id = 1;

    // The action to take
    ClientAction client_action = 2;

    // Any side effects to perform
    repeated SideEffect side_effects = 3;

    // A list of events to persist - these will be persisted before the reply
    // is sent.
    repeated google.protobuf.Any events = 4;

    // An optional snapshot to persist. It is assumed that this snapshot will have
    // the state of any events in the events field applied to it. It is illegal to
    // send a snapshot without sending any events.
    google.protobuf.Any snapshot = 5;
}

// Input message type for the gRPC stream in.
message EventSourcedStreamIn {
    oneof message {
        EventSourcedInit init = 1;
        EventSourcedEvent event = 2;
        Command command = 3;
    }
}

// Output message type for the gRPC stream out.
message EventSourcedStreamOut {
    oneof message {
        EventSourcedReply reply = 1;
        Failure failure = 2;
    }
}

// The Entity service
service EventSourced {

    // The stream. One stream will be established per active entity.
    // Once established, the first message sent will be Init, which contains the entity ID, and,
    // if the entity has previously persisted a snapshot, it will contain that snapshot. It will
    // then send zero to many event messages, one for each event previously persisted. The entity
    // is expected to apply these to its state in a deterministic fashion. Once all the events
    // are sent, one to many commands are sent, with new commands being sent as new requests for
    // the entity come in. The entity is expected to reply to each command with exactly one reply
    // message. The entity should reply in order, and any events that the entity requests to be
    // persisted the entity should handle itself, applying them to its own state, as if they had
    // arrived as events when the event stream was being replayed on load.
    rpc handle(stream EventSourcedStreamIn) returns (stream EventSourcedStreamOut) {}
}