syntax = "proto3";

package docker.swarmkit.v1;

import "gogoproto/gogo.proto";
import "google/protobuf/timestamp.proto";
import "plugin/plugin.proto";

// LogStream defines the stream from which the log message came.
enum LogStream {
	option (gogoproto.goproto_enum_prefix) = false;
	option (gogoproto.enum_customname) = "LogStream";

	LOG_STREAM_UNKNOWN = 0 [(gogoproto.enumvalue_customname) = "LogStreamUnknown"];
	LOG_STREAM_STDOUT = 1 [(gogoproto.enumvalue_customname) = "LogStreamStdout"];
	LOG_STREAM_STDERR = 2 [(gogoproto.enumvalue_customname) = "LogStreamStderr"];
}

message LogSubscriptionOptions {
	// Streams defines which log streams should be sent from the task source.
	// Empty means send all the messages.
	repeated LogStream streams = 1;

	// Follow instructs the publisher to continue sending log messages as they
	// are produced, after satisfying the initial query.
	bool follow = 2;

	// Tail defines how many messages relative to the log stream to send when
	// starting the stream.
	//
	// Positive values will skip that number of messages from the start of the
	// stream before publishing.
	//
	// Negative values will specify messages relative to the end of the stream,
	// offset by one. We can say that the last (-n-1) lines are returned when n
	// < 0. As reference, -1 would mean send no log lines (typically used with
	// follow), -2 would return the last log line, -11 would return the last 10
	// and so on.
	//
	// The default value of zero will return all logs.
	//
	// Note that this is very different from the Docker API.
	int64 tail = 3;

	// Since indicates that only log messages produced after this timestamp
	// should be sent.
	// Note: can't use stdtime because this field is nullable.
	google.protobuf.Timestamp since = 4;
}

// LogSelector will match logs from ANY of the defined parameters.
//
// For the best effect, the client should use the least specific parameter
// possible. For example, if they want to listen to all the tasks of a service,
// they should use the service id, rather than specifying the individual tasks.
message LogSelector {
	repeated string service_ids = 1;
	repeated string node_ids = 2;
	repeated string task_ids = 3;
}

// LogContext marks the context from which a log message was generated.
message LogContext {
	string service_id = 1;
	string node_id = 2;
	string task_id = 3;
}

// LogAttr is an extra key/value pair that may be have been set by users
message LogAttr {
	string key = 1;
	string value = 2;
}

// LogMessage
message LogMessage {
	// Context identifies the source of the log message.
	LogContext context = 1 [(gogoproto.nullable) = false];

	// Timestamp is the time at which the message was generated.
	// Note: can't use stdtime because this field is nullable.
	google.protobuf.Timestamp timestamp = 2;

	// Stream identifies the stream of the log message, stdout or stderr.
	LogStream stream = 3;

	// Data is the raw log message, as generated by the application.
	bytes data = 4;

	// Attrs is a list of key value pairs representing additional log details
	// that may have been returned from the logger
	repeated LogAttr attrs = 5 [(gogoproto.nullable) = false];
}

// Logs defines the methods for retrieving task logs messages from a cluster.
service Logs {
	// SubscribeLogs starts a subscription with the specified selector and options.
	//
	// The subscription will be distributed to relevant nodes and messages will
	// be collected and sent via the returned stream.
	//
	// The subscription will end with an EOF.
	rpc SubscribeLogs(SubscribeLogsRequest) returns (stream SubscribeLogsMessage) {
		option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
	}
}

message SubscribeLogsRequest {
	// LogSelector describes the logs to which the subscriber is
	LogSelector selector = 1;

	LogSubscriptionOptions options = 2;
}

message SubscribeLogsMessage {
	repeated LogMessage messages = 1 [(gogoproto.nullable) = false];
}

// LogBroker defines the API used by the worker to send task logs back to a
// manager. A client listens for subscriptions then optimistically retrieves
// logs satisfying said subscriptions, calling PublishLogs for results that are
// relevant.
//
// The structure of ListenSubscriptions is similar to the Dispatcher API but
// decoupled to allow log distribution to work outside of the regular task
// flow.
service LogBroker {
	// ListenSubscriptions starts a subscription stream for the node. For each
	// message received, the node should attempt to satisfy the subscription.
	//
	// Log messages that match the provided subscription should be sent via
	// PublishLogs.
	rpc ListenSubscriptions(ListenSubscriptionsRequest) returns (stream SubscriptionMessage) {
		option (docker.protobuf.plugin.tls_authorization) = {
			roles: "swarm-worker"
			roles: "swarm-manager"
		};
	}

	// PublishLogs receives sets of log messages destined for a single
	// subscription identifier.
	rpc PublishLogs(stream PublishLogsMessage) returns (PublishLogsResponse) {
		option (docker.protobuf.plugin.tls_authorization) = {
			roles: "swarm-worker"
			roles: "swarm-manager"
		};
	}
}

// ListenSubscriptionsRequest is a placeholder to begin listening for
// subscriptions.
message ListenSubscriptionsRequest { }

// SubscriptionMessage instructs the listener to start publishing messages for
// the stream or end a subscription.
//
// If Options.Follow == false, the worker should end the subscription on its own.
message SubscriptionMessage {
	// ID identifies the subscription.
	string id = 1;

	// Selector defines which sources should be sent for the subscription.
	LogSelector selector = 2;

	// Options specify how the subscription should be satisfied.
	LogSubscriptionOptions options = 3;

	// Close will be true if the node should shutdown the subscription with the
	// provided identifier.
	bool close = 4;
}

message PublishLogsMessage {
	// SubscriptionID identifies which subscription the set of messages should
	// be sent to. We can think of this as a "mail box" for the subscription.
	string subscription_id = 1;

	// Messages is the log message for publishing.
	repeated LogMessage messages = 2 [(gogoproto.nullable) = false];

	// Close is a boolean for whether or not the client has completed its log
	// stream. When close is called, the manager can hang up the subscription.
	// Any further logs from this subscription are an error condition. Any
	// messages included when close is set can be discarded
	bool close = 3;
}

message PublishLogsResponse { }