spawn

syntax = "proto3";

package spawn.actors;

import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";

option java_package = "io.spawn.actors";
option go_package = "github.com/eigr/go-support/eigr/actors;actors";

message Registry {
  map<string, Actor> actors = 1;
}

message ActorSystem {
  string name = 1;
  Registry registry = 2;
}

// A strategy for save state.
message ActorSnapshotStrategy {
  oneof strategy {
    // the timeout strategy.
    TimeoutStrategy timeout = 1;
  }
}

// A strategy which a user function's entity is passivated.
message ActorDeactivationStrategy {
  oneof strategy {
    // the timeout strategy.
    TimeoutStrategy timeout = 1;
  }
}

// A strategy based on a timeout.
message TimeoutStrategy {
  // The timeout in millis
  int64 timeout = 1;
}

// A action represents an action that the user can perform on an Actor.
// Actions in supporting languages are represented by functions or methods.
// An Actor action has nothing to do with the semantics of Actions in a
// CQRS/EventSourced system. It just represents an action that supporting
// languages can invoke.
message Action {

  // The name of the function or method in the supporting language that has been
  // registered in Ator.
  string name = 1;
}

// A FixedTimerAction is similar to a regular Action, its main differences are
// that it is scheduled to run at regular intervals and only takes the actor's
// state as an argument. Timer Actions are good for executing loops that
// manipulate the actor's own state. In Elixir or other languages in BEAM it
// would be similar to invoking Process.send_after(self(), atom, msg, timeout)
message FixedTimerAction {

  // The time to wait until the action is triggered
  int32 seconds = 1;

  // See Action description Above
  Action action = 2;
}

message ActorState {
  map<string, string> tags = 1;
  google.protobuf.Any state = 2;
}

// Metadata represents a set of key-value pairs that can be used to
// provide additional information about an Actor.
message Metadata {
  // A channel group represents a way to send actions to various actors
  // that belong to a certain semantic group. Following the Pub-Sub pattern.
  repeated Channel channel_group = 1;

  map<string, string> tags = 2;
}

// Represents a Pub-Sub binding, where a actor can be subscribed to a channel
// and map a specific action to a specific topic if necessary
// if the action is not informed, the default action will be "receive".
message Channel {
  string topic = 1;
  string action = 2;
}

// The type that defines the runtime characteristics of the Actor.
// Regardless of the type of actor it is important that
// all actors are registered during the proxy and host initialization phase.
enum Kind {
  // When no type is informed, the default to be assumed will be the Named
  // pattern.
  UNKNOW_KIND = 0;

  // NAMED actors as the name suggests have only one real instance of themselves
  // running during their entire lifecycle. That is, they are the opposite of
  // the UNNAMED type Actors.
  NAMED = 1;

  // UNNAMED actors are used to create children of this based actor at runtime
  UNNAMED = 2;

  // Pooled Actors are similar to Unnamed actors, but unlike them,
  // their identifying name will always be the one registered at the system
  // initialization stage. The great advantage of Pooled actors is that they
  // have multiple instances of themselves acting as a request service pool.
  // Pooled actors are also stateless actors, that is, they will not have their
  // in-memory state persisted via Statesstore. This is done to avoid problems
  // with the correctness of the stored state.
  // Pooled Actors are generally used for tasks where the Actor Model would
  // perform worse than other concurrency models and for tasks that do not
  // require state concerns. Integration flows, data caching, proxies are good
  // examples of use cases for this type of Actor.
  POOLED = 3;

  // Reserved for future use
  PROXY = 4;

  TASK = 5;

  // Projection actors are used to project data from different actor streams.
  PROJECTION = 6;
}

message ProjectionSubject {
    string actor = 1;
    string source_action = 2;
    string action = 3;
    google.protobuf.Timestamp start_time = 4;
}

message EventsRetentionStrategy {
    oneof strategy {
        int64 duration_ms = 1;
        bool infinite = 2;
    }
}

message ProjectionSettings {
    // Define this for projections that need to listen to events
    repeated ProjectionSubject subjects = 1;

    // Define this for actors that can emit events
    bool sourceable = 2;
    
    // The strategy for event store retention 
    EventsRetentionStrategy events_retention_strategy = 3;

    // Define how we consume events from subjects
    bool strict_events_ordering = 4;
}

message ActorSettings {

  // Indicates the type of Actor to be configured.
  Kind kind = 1;

  // Indicates whether an actor's state should be persisted in a definitive
  // store.
  bool stateful = 2;

  // Snapshot strategy
  ActorSnapshotStrategy snapshot_strategy = 3;

  // Deactivate strategy
  ActorDeactivationStrategy deactivation_strategy = 4;

  // When kind is POOLED this is used to define minimun actor instances
  int32 min_pool_size = 5;

  // When kind is POOLED this is used to define maximum actor instances
  int32 max_pool_size = 6;

  // Event source settings
  ProjectionSettings projection_settings = 7;

  // Actor's state type
  string state_type = 8;
}

message ActorId {
  // The name of a Actor Entity.
  string name = 1;

  // Name of a ActorSystem
  string system = 2;

  // When the Actor is of the Unnamed type,
  // the name of the parent Actor must be informed here.
  string parent = 3;
}

message Actor {
  // Actor Identification
  ActorId id = 1;

  // A Actor state.
  ActorState state = 2;

  // Actor metadata
  Metadata metadata = 6;

  // Actor settings.
  ActorSettings settings = 3;

  // The actions registered for an actor
  repeated Action actions = 4;

  // The registered timer actions for an actor.
  repeated FixedTimerAction timer_actions = 5;
}