syntax = "proto3";

// If you make any changes make sure you run: make regenerate-proto

package gitlab.agent.reverse_tunnel.rpc;

option go_package = "gitlab.com/gitlab-org/cluster-integration/gitlab-agent/v18/internal/tunnel/rpc";

import "internal/tool/grpctool/automata/automata.proto";
import "internal/tunnel/info/info.proto";
import "buf/validate/validate.proto";
// https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto
import "google/rpc/status.proto";

message StartStreaming {
}

message MetadataValues {
  // At least one item, but it can be empty.
  repeated bytes value = 1 [(buf.validate.field).repeated.min_items = 1];
}

// This is a map<> key-value entry as a message.
// We don't use map<> because we want bytes as key, which is not allowed in map<>.
// See https://protobuf.dev/programming-guides/proto3/#backwards
message MetadataKV {
  // No validation is performed when the data is binary in headers with name ending with -bin.
  // See https://grpc.io/docs/what-is-grpc/core-concepts/#metadata.
  // See https://github.com/grpc/grpc-go/blob/v1.67.1/internal/metadata/metadata.go#L100-L132.
  // TODO: once `matches()` works on the `bytes` type, remove the `string()` cast. See https://github.com/bufbuild/protovalidate/issues/268.
  option (buf.validate.message).cel = {
    id: "valid_metadata"
    expression:
      "this.key.endsWith(bytes('-bin')) ? ''"
        ": this.value.value.all(v, string(v).matches('^[\\x20-\\x7E]*$')) ? ''"
        ": 'invalid metadata value'"
  };
  bytes key = 1 [(buf.validate.field).bytes.pattern = "^:?[a-z0-9._-]+$"];
  MetadataValues value = 2 [(buf.validate.field).required = true];
}

message GatewayResponse {
  // Tunnel is ready, can start forwarding stream.
  message TunnelReady {
  }

  // No tunnels available at the moment.
  message NoTunnel {
  }

  // Headers is a gRPC metadata.
  message Header {
    repeated MetadataKV meta = 1;
  }

  // Message is a gRPC message data.
  message Message {
    bytes data = 1;
  }

  // Trailer is a gRPC trailer metadata.
  message Trailer {
    repeated MetadataKV meta = 1;
  }

  // Error represents a gRPC error that should be returned.
  message Error {
    // Error status as returned by gRPC.
    // See https://cloud.google.com/apis/design/errors.
    google.rpc.Status status = 1 [(buf.validate.field).required = true];
  }

  oneof msg {
    option (buf.validate.oneof).required = true;
    option (grpctool.automata.first_allowed_field) = -1;
    option (grpctool.automata.first_allowed_field) = 1;
    option (grpctool.automata.first_allowed_field) = 6;

    TunnelReady tunnel_ready = 1 [
      (grpctool.automata.next_allowed_field) = 2
    ];
    Header header = 2 [
      (grpctool.automata.next_allowed_field) = 3,
      (grpctool.automata.next_allowed_field) = 4
    ];
    Message message = 3 [
      (grpctool.automata.next_allowed_field) = 3,
      (grpctool.automata.next_allowed_field) = 4
    ];
    Trailer trailer = 4 [
      (grpctool.automata.next_allowed_field) = 5,
      (grpctool.automata.next_allowed_field) = -1
    ];
    Error error = 5 [
      (grpctool.automata.next_allowed_field) = -1
    ];
    NoTunnel no_tunnel = 6 [
      (grpctool.automata.next_allowed_field) = -1,
      (grpctool.automata.next_allowed_field) = 1
    ];
  }
}

message Descriptor {
  info.APIDescriptor api_descriptor = 1 [(buf.validate.field).required = true];
}

// Header is a gRPC metadata.
message Header {
  repeated MetadataKV meta = 1;
}

// Message is a gRPC message data.
message Message {
  bytes data = 1;
}

// Trailer is a gRPC trailer metadata.
message Trailer {
  repeated MetadataKV meta = 1;
}

// Error represents a gRPC error that should be returned.
message Error {
  // Error status as returned by gRPC.
  // See https://cloud.google.com/apis/design/errors.
  google.rpc.Status status = 1 [(buf.validate.field).required = true];
}

message ConnectRequest {
  oneof msg {

    option (grpctool.automata.first_allowed_field) = 1;
    option (buf.validate.oneof).required = true;

    Descriptor descriptor = 1 [
      (grpctool.automata.next_allowed_field) = 2,
      (grpctool.automata.next_allowed_field) = 5
    ];
    Header header = 2 [
      (grpctool.automata.next_allowed_field) = 3,
      (grpctool.automata.next_allowed_field) = 4
    ];
    Message message = 3 [
      (grpctool.automata.next_allowed_field) = 3,
      (grpctool.automata.next_allowed_field) = 4
    ];
    Trailer trailer = 4 [
      (grpctool.automata.next_allowed_field) = 5,
      (grpctool.automata.next_allowed_field) = -1
    ];
    Error error = 5 [
      (grpctool.automata.next_allowed_field) = -1
    ];
  }
}

message RequestInfo {
  string method_name = 1 [(buf.validate.field).string.min_bytes = 1];
  repeated MetadataKV meta = 2;
}

message CloseSend {
}

message ConnectResponse {
  oneof msg {

    option (grpctool.automata.first_allowed_field) = 1;
    option (grpctool.automata.first_allowed_field) = -1; // EOF means there is nothing to do
    option (buf.validate.oneof).required = true;

    RequestInfo request_info = 1 [
      (grpctool.automata.next_allowed_field) = 2,
      (grpctool.automata.next_allowed_field) = 3,
      (grpctool.automata.next_allowed_field) = -1
    ];
    Message message = 2 [
      (grpctool.automata.next_allowed_field) = 2,
      (grpctool.automata.next_allowed_field) = 3,
      (grpctool.automata.next_allowed_field) = -1
    ];
    CloseSend close_send = 3 [
      (grpctool.automata.next_allowed_field) = -1
    ];
  }
}

service ReverseTunnel {
  // Connect to server to establish a reverse tunnel.
  rpc Connect (stream ConnectRequest) returns (stream ConnectResponse) {
  }
}
