// Copyright 2021 Lightbend Inc.

// gRPC interface for Akka Serverless Actions.

syntax = "proto3";

package akkaserverless.component.action;

option go_package = "github.com/lightbend/akkaserverless-go-sdk/akkaserverless/action;action";
option java_package = "com.akkaserverless.protocol";

import "akkaserverless/component/component.proto";
import "google/protobuf/any.proto";

// An action command.
//
// For unary and streamed out calls, the service name, command name and payload
// will always be set.
//
// For streamed in and duplex streamed calls, the first command sent will just
// contain the service name and command name, but no payload. This will indicate
// that the action has been invoked. Subsequent commands on the stream will only
// have the payload set, the service name and command name will not be set.
message ActionCommand {
  // The name of the service this action is on.
  string service_name = 2;
  // Command name
  string name = 3;
  // The command payload.
  google.protobuf.Any payload = 4;
  // Metadata
  Metadata metadata = 5;
}

// Action counterpart to ClientAction
message ActionResponse {
  oneof response {
    Failure failure = 1;
    Reply reply = 2;
    Forward forward = 3;
  }
  repeated SideEffect side_effects = 4;
}

// Service that the SDK (in the user function) implements to make actions
// available to the proxy
service Actions {
  // Handle a unary command.
  //
  // The input command will contain the service name, command name, request
  // metadata and the command payload. The reply may contain a direct reply, a
  // forward or a failure, and it may contain many side effects.
  rpc HandleUnary(ActionCommand) returns (ActionResponse);
  // Handle a streamed in command.
  //
  // The first message in will contain the request metadata, including the
  // service name and command name. It will not have an associated payload set.
  // This will be followed by zero to many messages in with a payload, but no
  // service name or command name set.
  //
  // If the underlying transport supports per stream metadata, rather than per
  // message metadata, then that metadata will only be included in the metadata
  // of the first message. In contrast, if the underlying transport supports per
  // message metadata, there will be no metadata on the first message, the
  // metadata will instead be found on each subsequent message.
  //
  // The semantics of stream closure in this protocol map 1:1 with the semantics
  // of gRPC stream closure, that is, when the client closes the stream, the
  // stream is considered half closed, and the server should eventually, but not
  // necessarily immediately, send a response message with a status code and
  // trailers.
  //
  // If however the server sends a response message before the client closes the
  // stream, the stream is completely closed, and the client should handle this
  // and stop sending more messages.
  //
  // Either the client or the server may cancel the stream at any time,
  // cancellation is indicated through an HTTP2 stream RST message.
  rpc HandleStreamedIn(stream ActionCommand) returns (ActionResponse);
  // Handle a streamed out command.
  //
  // The input command will contain the service name, command name, request
  // metadata and the command payload. Zero or more replies may be sent, each
  // containing either a direct reply, a forward or a failure, and each may
  // contain many side effects. The stream to the client will be closed when the
  // this stream is closed, with the same status as this stream is closed with.
  //
  // Either the client or the server may cancel the stream at any time,
  // cancellation is indicated through an HTTP2 stream RST message.
  rpc HandleStreamedOut(ActionCommand) returns (stream ActionResponse);
  // Handle a full duplex streamed command.
  //
  // The first message in will contain the request metadata, including the
  // service name and command name. It will not have an associated payload set.
  // This will be followed by zero to many messages in with a payload, but no
  // service name or command name set.
  //
  // Zero or more replies may be sent, each containing either a direct reply, a
  // forward or a failure, and each may contain many side effects.
  //
  // If the underlying transport supports per stream metadata, rather than per
  // message metadata, then that metadata will only be included in the metadata
  // of the first message. In contrast, if the underlying transport supports per
  // message metadata, there will be no metadata on the first message, the
  // metadata will instead be found on each subsequent message.
  //
  // The semantics of stream closure in this protocol map 1:1 with the semantics
  // of gRPC stream closure, that is, when the client closes the stream, the
  // stream is considered half closed, and the server should eventually, but not
  // necessarily immediately, close the stream with a status code and trailers.
  //
  // If however the server closes the stream with a status code and trailers,
  // the stream is immediately considered completely closed, and no further
  // messages sent by the client will be handled by the server.
  //
  // Either the client or the server may cancel the stream at any time,
  // cancellation is indicated through an HTTP2 stream RST message.
  rpc HandleStreamed(stream ActionCommand) returns (stream ActionResponse);
}