service.proto

// Copyright 2024 The PipeCD Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package grpc.service.pipedservice;
option go_package = "github.com/pipe-cd/pipecd/pkg/app/server/service/pipedservice";

import "validate/validate.proto";
import "pkg/model/command.proto";
import "pkg/model/common.proto";
import "pkg/model/application.proto";
import "pkg/model/application_live_state.proto";
import "pkg/model/deployment.proto";
import "pkg/model/logblock.proto";
import "pkg/model/piped.proto";
import "pkg/model/event.proto";
import "pkg/model/analysis_result.proto";

// PipedService contains all RPC definitions for piped.
// All of these RPCs are only called by piped and authenticated by using PIPED_TOKEN.
service PipedService {
    // ReportStat is periodically sent to report its realtime status/stats to control-plane.
    // The received stats will be pushed to the metrics collector.
    rpc ReportStat(ReportStatRequest) returns (ReportStatResponse) {}

    // ReportPipedMeta is sent while starting up to report its metadata
    // such as configured cloud providers.
    rpc ReportPipedMeta(ReportPipedMetaRequest) returns (ReportPipedMetaResponse) {}

    // ListApplications returns a list of registered applications
    // that should be managed by the requested piped.
    // Disabled applications should not be included in the response.
    // Piped uses this RPC to fetch and sync the application configuration into its local database.
    rpc ListApplications(ListApplicationsRequest) returns (ListApplicationsResponse) {}

    // ReportApplicationSyncState is used to update the sync status of an application.
    rpc ReportApplicationSyncState(ReportApplicationSyncStateRequest) returns (ReportApplicationSyncStateResponse) {}

    // ReportApplicationDeployingStatus is used to report whether the specified application is deploying or not.
    rpc ReportApplicationDeployingStatus(ReportApplicationDeployingStatusRequest) returns (ReportApplicationDeployingStatusResponse) {}

    // ReportApplicationMostRecentDeployment is used to update the basic information about
    // the most recent deployment of a specific application.
    rpc ReportApplicationMostRecentDeployment(ReportApplicationMostRecentDeploymentRequest) returns (ReportApplicationMostRecentDeploymentResponse) {}

    // GetApplicationMostRecentDeployment returns the most recent deployment of the given application.
    rpc GetApplicationMostRecentDeployment(GetApplicationMostRecentDeploymentRequest) returns (GetApplicationMostRecentDeploymentResponse) {}

    // GetDeployment returns the deployment for given deployment ID.
    rpc GetDeployment(GetDeploymentRequest) returns (GetDeploymentResponse) {}

    // ListNotCompletedDeployments returns a list of not completed deployments
    // which are managed by this piped.
    // DeploymentController component uses this RPC to spawns/syncs its local deployment executors.
    rpc ListNotCompletedDeployments(ListNotCompletedDeploymentsRequest) returns (ListNotCompletedDeploymentsResponse) {}

    // CreateDeployment creates/triggers a new deployment for an application
    // that is managed by this piped.
    // This will be used by DeploymentTrigger component.
    rpc CreateDeployment(CreateDeploymentRequest) returns (CreateDeploymentResponse) {}

    // ReportDeploymentPlanned is used to update the status
    // of a specific deployment to PLANNED.
    rpc ReportDeploymentPlanned(ReportDeploymentPlannedRequest) returns (ReportDeploymentPlannedResponse) {}

    // ReportDeploymentStatusChanged is used to update the status
    // of a specific deployment to RUNNING or ROLLING_BACK.
    rpc ReportDeploymentStatusChanged(ReportDeploymentStatusChangedRequest) returns (ReportDeploymentStatusChangedResponse) {}

    // ReportDeploymentCompleted is used to update the status
    // of a specific deployment to SUCCESS | FAILURE | CANCELLED.
    rpc ReportDeploymentCompleted(ReportDeploymentCompletedRequest) returns (ReportDeploymentCompletedResponse) {}

    // SaveDeploymentMetadata is used to persist the metadata of a specific deployment.
    // Different value for the same key will overwrite the previous value for that key.
    rpc SaveDeploymentMetadata(SaveDeploymentMetadataRequest) returns (SaveDeploymentMetadataResponse) {}

    // SaveStageMetadata is used to persist the metadata
    // of a specific stage of a deployment.
    // Different value for the same key will overwrite the previous value for that key.
    rpc SaveStageMetadata(SaveStageMetadataRequest) returns (SaveStageMetadataResponse) {}

    // ReportStageLogs is used to save the log of a pipeline stage.
    rpc ReportStageLogs(ReportStageLogsRequest) returns (ReportStageLogsResponse) {}

    // ReportStageLogsFromLastCheckpoint is used to save the full logs from the most recently saved point.
    rpc ReportStageLogsFromLastCheckpoint(ReportStageLogsFromLastCheckpointRequest) returns (ReportStageLogsFromLastCheckpointResponse) {}

    // ReportStageStatusChanged is used to update the status
    // of a specific stage of a deployment.
    rpc ReportStageStatusChanged(ReportStageStatusChangedRequest) returns (ReportStageStatusChangedResponse) {}

    // ListUnhandledCommands is periodically called to obtain the commands
    // that should be handled.
    // Whenever an user makes an interaction from WebUI (cancel/approve/sync)
    // a new command with a unique identifier will be generated an saved into the datastore.
    // Piped uses this RPC to list all still-not-handled commands to handle them,
    // then report back the result to server.
    // On other side, the web will periodically check the command status and feedback the result to user.
    // In the future, we may need a solution to remove all old-handled commands from datastore for space.
    rpc ListUnhandledCommands(ListUnhandledCommandsRequest) returns (ListUnhandledCommandsResponse) {}

    // ReportCommandHandled is called to mark a specific command as handled.
    // The request payload will contain the handle status as well as any additional result data.
    // The handle result should be updated to both datastore and cache (for reading from web).
    rpc ReportCommandHandled(ReportCommandHandledRequest) returns (ReportCommandHandledResponse) {}

    // ReportApplicationLiveState is periodically sent to correct full state of an application.
    // For kubernetes application, this contains a full tree of its kubernetes resources.
    // The tree data should be written into filestore immediately and then the state in cache should be refreshsed too.
    rpc ReportApplicationLiveState(ReportApplicationLiveStateRequest) returns (ReportApplicationLiveStateResponse) {}

    // ReportApplicationLiveStateEvents is sent to submit one or multiple events
    // about the changes of application live state.
    // Control plane uses the received events to update the state of application-resource-tree.
    // We want to start by a simple solution at this initial stage of development,
    // so the API server just handles as below:
    // - loads the releated application-resource-tree from the cache
    // - checks and builds new state for the application-resource-tree
    // - updates new state into cache (cache data is for reading while handling web requests)
    // In the future, we may want to redesign the behavior of this RPC by using pubsub/queue pattern.
    // After receiving the events, all of them will be published into a queue immediately,
    // and then another Handler service will pick them inorder to apply to build new state.
    // By that way we can control the traffic to the datastore in a better way.
    rpc ReportApplicationLiveStateEvents(ReportApplicationLiveStateEventsRequest) returns (ReportApplicationLiveStateEventsResponse) {}

    // GetLatestEvent returns the latest event that meets the given conditions.
    rpc GetLatestEvent(GetLatestEventRequest) returns (GetLatestEventResponse) {}

    // ListEvents returns a list of Events inside the given range.
    rpc ListEvents(ListEventsRequest) returns (ListEventsResponse) {}
    // ReportEventHandled marks the given all events as handled.
    // Deprecated. This is only for the old Piped agents.
    rpc ReportEventsHandled(ReportEventsHandledRequest) returns (ReportEventsHandledResponse) {}
    // ReportEventStatuses reports a status list of events.
    rpc ReportEventStatuses(ReportEventStatusesRequest) returns (ReportEventStatusesResponse) {}

    // GetLatestAnalysisResult returns the most successful analysis result.
    rpc GetLatestAnalysisResult(GetLatestAnalysisResultRequest) returns (GetLatestAnalysisResultResponse) {}

    // GetLatestAnalysisResult updates the most successful analysis result.
    rpc PutLatestAnalysisResult(PutLatestAnalysisResultRequest) returns (PutLatestAnalysisResultResponse) {}

    // GetDesiredVersion returns the desired version of the given Piped.
    rpc GetDesiredVersion(GetDesiredVersionRequest) returns (GetDesiredVersionResponse) {}

    // UpdateApplicationConfigurations updates application configurations.
    rpc UpdateApplicationConfigurations(UpdateApplicationConfigurationsRequest) returns (UpdateApplicationConfigurationsResponse) {}
    // ReportLatestUnusedApplicationConfigurations puts the latest configurations of applications that isn't registered yet.
    rpc ReportUnregisteredApplicationConfigurations(ReportUnregisteredApplicationConfigurationsRequest) returns (ReportUnregisteredApplicationConfigurationsResponse) {}

    // CreateDeploymentChain creates a new deployment chain object and all required commands to
    // trigger deployment for applications in the chain.
    rpc CreateDeploymentChain(CreateDeploymentChainRequest) returns (CreateDeploymentChainResponse) {}
    // DeploymentPlannable checks the completion and status of the previous block in the deployment chain,
    // only when all the nodes of the previous block are completed with a success status,
    // the nodes of the next block will be treated as processable.
    // In case the previous block of this deployment is finished with FAILURE | CANCELLED status,
    // `cancel` flag will be returned to aware piped to stop this deployment.
    rpc InChainDeploymentPlannable(InChainDeploymentPlannableRequest) returns (InChainDeploymentPlannableResponse) {}
}

enum ListOrder {
    NONE = 0;
    ASC = 1;
    DESC = 2;
}

message ReportStatRequest {
    // Metrics byte sequence in OpenMetrics format.
    bytes piped_stats = 1;
}

message ReportStatResponse {
    int64 report_interval = 1;
}

message ReportPipedMetaRequest {
    string version = 1;
    repeated model.Piped.CloudProvider cloud_providers = 2;
    repeated model.Piped.PlatformProvider platform_providers = 6;
    repeated model.ApplicationGitRepository repositories = 3;
    model.Piped.SecretEncryption secret_encryption = 4;
    string config = 5;
}

message ReportPipedMetaResponse {
    string name = 1 [(validate.rules).string.min_len = 1];
    string web_base_url = 2;
}

message ListApplicationsRequest {
}

message ListApplicationsResponse {
    repeated model.Application applications = 1;
}

message ReportApplicationSyncStateRequest {
    string application_id = 1 [(validate.rules).string.min_len = 1];
    model.ApplicationSyncState state = 2 [(validate.rules).message.required = true];
}

message ReportApplicationSyncStateResponse {
}

message ReportApplicationDeployingStatusRequest {
    string application_id = 1 [(validate.rules).string.min_len = 1];
    bool deploying = 2;
}

message ReportApplicationDeployingStatusResponse {
}

message ReportApplicationMostRecentDeploymentRequest {
    string application_id = 1 [(validate.rules).string.min_len = 1];
    model.DeploymentStatus status = 2 [(validate.rules).enum.defined_only = true];
    model.ApplicationDeploymentReference deployment = 3 [(validate.rules).message.required = true];
}

message ReportApplicationMostRecentDeploymentResponse {
}

message GetApplicationMostRecentDeploymentRequest {
    string application_id = 1 [(validate.rules).string.min_len = 1];
    model.DeploymentStatus status = 2 [(validate.rules).enum.defined_only = true];
}

message GetApplicationMostRecentDeploymentResponse {
    model.ApplicationDeploymentReference deployment = 1 [(validate.rules).message.required = true];
}

message GetDeploymentRequest {
    string id = 1 [(validate.rules).string.min_len = 1];
}

message GetDeploymentResponse {
    model.Deployment deployment = 1 [(validate.rules).message.required = true];
}

message ListNotCompletedDeploymentsRequest {
}

message ListNotCompletedDeploymentsResponse {
    repeated model.Deployment deployments = 1;
    string cursor = 2;
}

message CreateDeploymentRequest {
    model.Deployment deployment = 1 [(validate.rules).message.required = true];
}

message CreateDeploymentResponse {
}

message ReportDeploymentPlannedRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    // Simple description about what this deployment does.
    // Empty means nothing has changed compared to when the deployment was created.
    string summary = 2;
    // The human-readable description why the deployment is at current status.
    string status_reason = 3;
    // Hash value of the most recently successfully deployed commit.
    string running_commit_hash = 4;
    // The config file name used by the last successful deployment.
    string running_config_filename = 9;
    // The application version this deployment is trying to deploy.
    string version = 5;
    repeated model.ArtifactVersion versions = 10;
    // The planned stages.
    // Empty means nothing has changed compared to when the deployment was created.
    repeated model.PipelineStage stages = 6;
    // DeploymentChainId represents the deployment chain id which the deployment
    // belongs to. Empty means this deployment does not belong to any chain.
    string deployment_chain_id = 7;
    // DeploymentChainBlockIndex represents the block in deployment chain which
    // the deployment assigned to.
    uint32 deployment_chain_block_index = 8;
}

message ReportDeploymentPlannedResponse {
}

message ReportDeploymentStatusChangedRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    // We only accept RUNNING or ROLLING_BACK.
    model.DeploymentStatus status = 2 [(validate.rules).enum = {in: [2,3]}];
    // The human-readable description why the deployment is at current status.
    string status_reason = 3;
    // DeploymentChainId represents the deployment chain id which the deployment
    // belongs to. Empty means this deployment does not belong to any chain.
    string deployment_chain_id = 4;
    // DeploymentChainBlockIndex represents the block in deployment chain which
    // the deployment assigned to.
    uint32 deployment_chain_block_index = 5;
}

message ReportDeploymentStatusChangedResponse {
}

message ReportDeploymentCompletedRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    // The status of deployment.
    model.DeploymentStatus status = 2 [(validate.rules).enum.defined_only = true];
    // The human-readable description why the deployment is at current status.
    string status_reason = 3;
    // The completed statuses of all stages.
    map<string,model.StageStatus> stage_statuses = 4;
    // DeploymentChainId represents the deployment chain id which the deployment
    // belongs to. Empty means this deployment does not belong to any chain.
    string deployment_chain_id = 5;
    // DeploymentChainBlockIndex represents the block in deployment chain which
    // the deployment assigned to.
    uint32 deployment_chain_block_index = 6;
    // The completion time of deployment.
    int64 completed_at = 13 [(validate.rules).int64.gt = 0];
}

message ReportDeploymentCompletedResponse {
}

message SaveDeploymentMetadataRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    map<string,string> metadata = 2;
}

message SaveDeploymentMetadataResponse {
}

message SaveStageMetadataRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    string stage_id = 2 [(validate.rules).string.min_len = 1];
    map<string,string> metadata = 3;
}

message SaveStageMetadataResponse {
}

message ReportStageLogsRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    string stage_id = 2 [(validate.rules).string.min_len = 1];
    int32 retried_count = 3;
    repeated model.LogBlock blocks = 4;
}

message ReportStageLogsResponse {
}

message ReportStageLogsFromLastCheckpointRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    string stage_id = 2 [(validate.rules).string.min_len = 1];
    int32 retried_count = 3;
    repeated model.LogBlock blocks = 4;
    bool completed = 5;
}

message ReportStageLogsFromLastCheckpointResponse {
}

message ReportStageStatusChangedRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    string stage_id = 2 [(validate.rules).string.min_len = 1];
    model.StageStatus status = 3 [(validate.rules).enum.defined_only = true];
    // The human-readable description why the stage is at current status.
    string status_reason = 4;
    repeated string requires = 5;
    bool visible = 6;
    int32 retried_count = 7;
    int64 completed_at = 13 [(validate.rules).int64.gt = 0];
}

message ReportStageStatusChangedResponse {
}

message ListUnhandledCommandsRequest {
}

message ListUnhandledCommandsResponse {
    repeated model.Command commands = 1;
}

message ReportCommandHandledRequest {
    string command_id = 1 [(validate.rules).string.min_len = 1];
    model.CommandStatus status = 2 [(validate.rules).enum.defined_only = true];
    map<string,string> metadata = 3;
    int64 handled_at = 4 [(validate.rules).int64.gt = 0];
    // Additional output data to be stored in filestore.
    bytes output = 5;
}

message ReportCommandHandledResponse {
}

message ReportApplicationLiveStateRequest {
    model.ApplicationLiveStateSnapshot snapshot = 1 [(validate.rules).message.required = true];
}

message ReportApplicationLiveStateResponse {
}

message ReportApplicationLiveStateEventsRequest {
    repeated model.KubernetesResourceStateEvent kubernetes_events = 1;
}

message ReportApplicationLiveStateEventsResponse {
    repeated string failed_ids = 1;
}

message GetLatestEventRequest {
    string name = 1 [(validate.rules).string.min_len = 1];
    map<string,string> labels = 2;
}

message GetLatestEventResponse {
    model.Event event = 1 [(validate.rules).message.required = true];
}


message ListEventsRequest {
    enum Status {
        ALL = 0;
        NOT_HANDLED = 1;
        SUCCESS = 2;
        FAILURE = 3;
        OUTDATED = 4;
    }
    int64 from = 1;
    int64 to = 2;
    ListOrder order = 3 [(validate.rules).enum.defined_only = true];
    Status status = 4 [(validate.rules).enum.defined_only = true];
}

message ListEventsResponse {
    repeated model.Event events = 1;
}

message ReportEventsHandledRequest {
    repeated string event_ids = 1 [(validate.rules).repeated.min_items = 1];
}

message ReportEventsHandledResponse {
}

message ReportEventStatusesRequest {
    message Event {
        string id = 1 [(validate.rules).string.min_len = 1];
        model.EventStatus status = 2 [(validate.rules).enum.defined_only = true];
        string status_description = 3 [(validate.rules).string.min_len = 1];
    }
    repeated Event events = 1;
}

message ReportEventStatusesResponse {
}

message GetLatestAnalysisResultRequest {
    string application_id = 1 [(validate.rules).string.min_len = 1];
}

message GetLatestAnalysisResultResponse {
    model.AnalysisResult analysis_result = 1 [(validate.rules).message.required = true];
}

message PutLatestAnalysisResultRequest {
    string application_id = 1 [(validate.rules).string.min_len = 1];
    model.AnalysisResult analysis_result = 2 [(validate.rules).message.required = true];
}

message PutLatestAnalysisResultResponse {
}

message GetDesiredVersionRequest {
}

message GetDesiredVersionResponse {
    string version = 1;
}


message UpdateApplicationConfigurationsRequest {
    // The application configurations that should be updated.
    repeated model.ApplicationInfo applications = 1;
}

message UpdateApplicationConfigurationsResponse {
}

message ReportUnregisteredApplicationConfigurationsRequest {
    // All the latest application configurations that isn't registered yet.
    // Note that ALL configs are always be contained every time.
    repeated model.ApplicationInfo applications = 1;
}

message ReportUnregisteredApplicationConfigurationsResponse {
}

message CreateDeploymentChainRequest {
    // Note: The matcher use AND operator to merge all conditions used to determine
    // which apps should be trigger as node in chain.
    message ApplicationMatcher {
        string name = 1;
        // The kind is one of: KUBERNETES, TERRAFORM, CLOUDRUN, LAMBDA, ECS.
        // This kind will be cast to model.ApplicationKind and we use string to use
        // empty string as default value in case this matcher field is not set.
        string kind = 2;
        map<string,string> labels = 3;
    }

    model.Deployment first_deployment = 1 [(validate.rules).message.required = true];
    repeated ApplicationMatcher matchers = 2;
}

message CreateDeploymentChainResponse {
}

message InChainDeploymentPlannableRequest {
    string deployment_id = 1 [(validate.rules).string.min_len = 1];
    string deployment_chain_id = 2 [(validate.rules).string.min_len = 1];
    uint32 deployment_chain_block_index = 3;
}

message InChainDeploymentPlannableResponse {
    // plannable used to determine whether piped should start planning the given development.
    bool plannable = 1;
    // cancel used to determine whether piped should cancel the given development.
    bool cancel = 2;
    string cancel_reason = 3;
}