gitpod/components/supervisor-api/notification.proto

// Copyright (c) 2021 Gitpod GmbH. All rights reserved.
// Licensed under the GNU Affero General Public License (AGPL).
// See License.AGPL.txt in the project root for license information.

syntax = "proto3";

package supervisor;

import "google/api/annotations.proto";

option go_package = "github.com/gitpod-io/gitpod/supervisor/api";
option java_package = "io.gitpod.supervisor.api";

// Notification serivce allows external processes to notify the user and ask for
// decisions.
service NotificationService {

  // Prompts the user and asks for a decision. Typically called by some external
  // process. If the list of actions is empty this service returns immediately,
  // otherwise it blocks until the user has made their choice.
  rpc Notify(NotifyRequest) returns (NotifyResponse) {
    option (google.api.http) = {
      post : "/v1/notification/notify"
    };
  }

  // Subscribe to notifications. Typically called by the IDE.
  rpc Subscribe(SubscribeRequest) returns (stream SubscribeResponse) {
    option (google.api.http) = {
      get : "/v1/notification/subscribe"
    };
  }

  // Report a user's choice as a response to a notification. Typically called by
  // the IDE.
  rpc Respond(RespondRequest) returns (RespondResponse) {
    option (google.api.http) = {
      post : "/v1/notification/respond"
    };
  }

  // Called by the IDE to inform supervisor about which is the latest client
  // actively used by the user. We consider active the last IDE with focus.
  // Only 1 stream is kept open at any given time. A new subscription
  // overrides the previous one, causing the stream to close.
  // Supervisor will respond with a stream to which the IDE will listen
  // waiting to receive actions to run, for example: `open` or `preview`
  rpc SubscribeActive(SubscribeActiveRequest)
      returns (stream SubscribeActiveResponse) {
    option (google.api.http) = {
      post : "/v1/notification/subscribe-active"
    };
  }

  // Used by gp-cli to ask supervisor to request the active client
  // to run a given command (eg. open or preview)
  rpc NotifyActive(NotifyActiveRequest) returns (NotifyActiveResponse) {
    option (google.api.http) = {
      post : "/v1/notification/notify-action"
    };
  }

  // Used by the IDE to inform supervisor about the result (eg. success or
  // failure) of the action (eg. open or preview) requested via NotifyActive
  rpc NotifyActiveRespond(NotifyActiveRespondRequest)
      returns (NotifyActiveRespondResponse) {
    option (google.api.http) = {
      post : "/v1/notification/notify-action-respond"
    };
  }
}

message NotifyRequest {
  enum Level {
    ERROR = 0;
    WARNING = 1;
    INFO = 2;
  }
  Level level = 1;
  string message = 2;
  // if actions are empty, Notify will return immediately
  repeated string actions = 3;
}

message NotifyResponse {
  // action chosen by the user or empty string if cancelled
  string action = 1;
}

message SubscribeRequest {}

message SubscribeResponse {
  uint64 requestId = 1;
  NotifyRequest request = 2;
}

message RespondRequest {
  uint64 requestId = 1;
  NotifyResponse response = 2;
}

message RespondResponse {}

message NotifyActiveRequest {
  // open a file in editor
  message OpenData {
    repeated string urls = 1;
    // wait until all opened files are closed
    bool await = 2;
  }

  // ask editor to open a URL in its preview
  message PreviewData {
    string url = 1;
    // open the URL in a new browser tab
    bool external = 2;
  }

  oneof action_data {
    OpenData open = 1;
    PreviewData preview = 2;
  }
}

message NotifyActiveResponse {}

message SubscribeActiveRequest {}

message SubscribeActiveResponse {
  uint64 requestId = 1;
  NotifyActiveRequest request = 2;
}

message NotifyActiveRespondRequest {
  uint64 requestId = 1;
  NotifyActiveResponse response = 2;
}

message NotifyActiveRespondResponse {}