// Copyright 2019 Google LLC.
//
// 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 google.cloud.functions.v1beta2;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option go_package = "google.golang.org/genproto/googleapis/cloud/functions/v1beta2;functions";
option java_multiple_files = true;
option java_outer_classname = "FunctionsProto";
option java_package = "com.google.cloud.functions.v1beta2";
option objc_class_prefix = "GCF";

// A service that application uses to manipulate triggers and functions.
service CloudFunctionsService {
  option (google.api.default_host) = "cloudfunctions.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";

  // Returns a list of functions that belong to the requested project.
  rpc ListFunctions(ListFunctionsRequest) returns (ListFunctionsResponse) {
    option (google.api.http) = {
      get: "/v1beta2/{location=projects/*/locations/*}/functions"
    };
    option (google.api.method_signature) = "location";
  }

  // Returns a function with the given name from the requested project.
  rpc GetFunction(GetFunctionRequest) returns (CloudFunction) {
    option (google.api.http) = {
      get: "/v1beta2/{name=projects/*/locations/*/functions/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Creates a new function. If a function with the given name already exists in
  // the specified project, the long running operation will return
  // `ALREADY_EXISTS` error.
  rpc CreateFunction(CreateFunctionRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1beta2/{location=projects/*/locations/*}/functions"
      body: "function"
    };
    option (google.api.method_signature) = "location,function";
    option (google.longrunning.operation_info) = {
      response_type: "CloudFunction"
      metadata_type: "OperationMetadataV1Beta2"
    };
  }

  // Updates existing function.
  rpc UpdateFunction(UpdateFunctionRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      put: "/v1beta2/{name=projects/*/locations/*/functions/*}"
      body: "function"
    };
    option (google.api.method_signature) = "name,function";
    option (google.longrunning.operation_info) = {
      response_type: "CloudFunction"
      metadata_type: "OperationMetadataV1Beta2"
    };
  }

  // Deletes a function with the given name from the specified project. If the
  // given function is used by some trigger, the trigger will be updated to
  // remove this function.
  rpc DeleteFunction(DeleteFunctionRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v1beta2/{name=projects/*/locations/*/functions/*}"
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "google.protobuf.Empty"
      metadata_type: "OperationMetadataV1Beta2"
    };
  }

  // Synchronously invokes a deployed Cloud Function. To be used for testing
  // purposes as very limited traffic is allowed. For more information on
  // the actual limits refer to [API Calls](
  // https://cloud.google.com/functions/quotas#rate_limits).
  rpc CallFunction(CallFunctionRequest) returns (CallFunctionResponse) {
    option (google.api.http) = {
      post: "/v1beta2/{name=projects/*/locations/*/functions/*}:call"
      body: "*"
    };
    option (google.api.method_signature) = "name,data";
  }

  // Returns a signed URL for uploading a function source code.
  // For more information about the signed URL usage see:
  // https://cloud.google.com/storage/docs/access-control/signed-urls
  // Once the function source code upload is complete, the used signed
  // URL should be provided in CreateFunction or UpdateFunction request
  // as a reference to the function source code.
  //
  // When uploading source code to the generated signed URL, please follow
  // these restrictions:
  //
  // * Source file type should be a zip file.
  // * Source file size should not exceed 100MB limit.
  // * No credentials should be attached - the signed URLs provide access to the
  //   target bucket using internal service identity; if credentials were
  //   attached, the identity from the credentials would be used, but that
  //   identity does not have permissions to upload files to the URL.
  //
  // When making a HTTP PUT request, these two headers need to be specified:
  //
  // * `content-type: application/zip`
  // * `x-goog-content-length-range: 0,104857600`
  //
  // And this header SHOULD NOT be specified:
  //
  // * `Authorization: Bearer YOUR_TOKEN`
  rpc GenerateUploadUrl(GenerateUploadUrlRequest) returns (GenerateUploadUrlResponse) {
    option (google.api.http) = {
      post: "/v1beta2/{parent=projects/*/locations/*}/functions:generateUploadUrl"
      body: "*"
    };
  }

  // Returns a signed URL for downloading deployed function source code.
  // The URL is only valid for a limited period and should be used within
  // minutes after generation.
  // For more information about the signed URL usage see:
  // https://cloud.google.com/storage/docs/access-control/signed-urls
  rpc GenerateDownloadUrl(GenerateDownloadUrlRequest) returns (GenerateDownloadUrlResponse) {
    option (google.api.http) = {
      post: "/v1beta2/{name=projects/*/locations/*/functions/*}:generateDownloadUrl"
      body: "*"
    };
  }
}

// Describes a Cloud Function that contains user computation executed in
// response to an event. It encapsulate function and triggers configurations.
message CloudFunction {
  option (google.api.resource) = {
    type: "cloudfunctions.googleapis.com/CloudFunction"
    pattern: "projects/{project}/locations/{location}/functions/{function}"
  };

  // A user-defined name of the function. Function names must be unique
  // globally and match pattern `projects/*/locations/*/functions/*`
  string name = 1;

  // The location of the function source code.
  oneof source_code {
    // The Google Cloud Storage URL, starting with gs://, pointing to the zip
    // archive which contains the function.
    string source_archive_url = 14;

    // The hosted repository where the function is defined.
    SourceRepository source_repository = 3;

    // The URL pointing to the hosted repository where the function is defined.
    // There are supported Cloud Source Repository URLs in the following
    // formats:
    //
    // To refer to a specific commit:
    // `https://source.developers.google.com/projects/*/repos/*/revisions/*/paths/*`
    // To refer to a moveable alias (branch):
    // `https://source.developers.google.com/projects/*/repos/*/moveable-aliases/*/paths/*`
    // In particular, to refer to HEAD use `master` moveable alias.
    // To refer to a specific fixed alias (tag):
    // `https://source.developers.google.com/projects/*/repos/*/fixed-aliases/*/paths/*`
    //
    // You may omit `paths/*` if you want to use the main directory.
    string source_repository_url = 18;

    // The Google Cloud Storage signed URL used for source uploading, generated
    // by [google.cloud.functions.v1beta2.GenerateUploadUrl][]
    string source_upload_url = 16;
  }

  // An event that triggers the function.
  oneof trigger {
    // An HTTPS endpoint type of source that can be triggered via URL.
    HTTPSTrigger https_trigger = 6;

    // A source that fires events in response to a condition in another service.
    EventTrigger event_trigger = 12;
  }

  // Output only. Status of the function deployment.
  CloudFunctionStatus status = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Name of the most recent operation modifying the function. If
  // the function status is `DEPLOYING` or `DELETING`, then it points to the
  // active operation.
  string latest_operation = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The name of the function (as defined in source code) that will be
  // executed. Defaults to the resource name suffix, if not specified. For
  // backward compatibility, if function with given name is not found, then the
  // system will try to use function named "function".
  // For Node.js this is name of a function exported by the module specified
  // in `source_location`.
  string entry_point = 9;

  // The runtime in which to run the function. Required when deploying a new
  // function, optional when updating an existing function. For a complete
  // list of possible choices, see the
  // [`gcloud` command
  // reference](/sdk/gcloud/reference/functions/deploy#--runtime).
  string runtime = 23;

  // The function execution timeout. Execution is considered failed and
  // can be terminated if the function is not completed at the end of the
  // timeout period. Defaults to 60 seconds.
  google.protobuf.Duration timeout = 10;

  // The amount of memory in MB available for a function.
  // Defaults to 256MB.
  int32 available_memory_mb = 11;

  // The email of the function's service account. If empty, defaults to
  // `{project_id}@appspot.gserviceaccount.com`.
  string service_account = 13;

  // Output only. The last update timestamp of a Cloud Function.
  google.protobuf.Timestamp update_time = 15 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The version identifier of the Cloud Function. Each deployment attempt
  // results in a new version of a function being created.
  int64 version_id = 20 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Labels associated with this Cloud Function.
  map<string, string> labels = 21;

  // Environment variables that shall be available during function execution.
  map<string, string> environment_variables = 22;

  // The limit on the maximum number of function instances that may coexist at a
  // given time.
  int32 max_instances = 24;

  // The VPC Network that this cloud function can connect to. It can be
  // either the fully-qualified URI, or the short name of the network resource.
  // If the short network name is used, the network must belong to the same
  // project. Otherwise, it must belong to a project within the same
  // organization. The format of this field is either
  // `projects/{project}/global/networks/{network}` or `{network}`, where
  // {project} is a project id where the network is defined, and {network} is
  // the short name of the network.
  //
  // This field is mutually exclusive with `vpc_connector` and will be replaced
  // by it.
  //
  // See [the VPC documentation](https://cloud.google.com/compute/docs/vpc) for
  // more information on connecting Cloud projects.
  string network = 25;

  // The VPC Network Connector that this cloud function can connect to. It can
  // be either the fully-qualified URI, or the short name of the network
  // connector resource. The format of this field is
  // `projects/*/locations/*/connectors/*`
  //
  // This field is mutually exclusive with `network` field and will eventually
  // replace it.
  //
  // See [the VPC documentation](https://cloud.google.com/compute/docs/vpc) for
  // more information on connecting Cloud projects.
  string vpc_connector = 26;
}

// Describes HTTPSTrigger, could be used to connect web hooks to function.
message HTTPSTrigger {
  // Output only. The deployed url for the function.
  string url = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Describes EventTrigger, used to request events be sent from another
// service.
message EventTrigger {
  // `event_type` names contain the service that is sending an event and the
  // kind of event that was fired. Must be of the form
  // `providers/*/eventTypes/*` e.g. Directly handle a Message published to
  // Google Cloud Pub/Sub `providers/cloud.pubsub/eventTypes/topic.publish`.
  //
  // Handle an object changing in Google Cloud Storage:
  // `providers/cloud.storage/eventTypes/object.change`
  //
  // Handle a write to the Firebase Realtime Database:
  // `providers/google.firebase.database/eventTypes/ref.write`
  string event_type = 1;

  // Which instance of the source's service should send events. E.g. for Pub/Sub
  // this would be a Pub/Sub topic at `projects/*/topics/*`. For Google Cloud
  // Storage this would be a bucket at `projects/*/buckets/*`. For any source
  // that only supports one instance per-project, this should be the name of the
  // project (`projects/*`)
  string resource = 2;

  // The hostname of the service that should be observed.
  //
  // If no string is provided, the default service implementing the API will
  // be used. For example, `storage.googleapis.com` is the default for all
  // event types in the `google.storage` namespace.
  string service = 6;

  // Specifies policy for failed executions.
  FailurePolicy failure_policy = 5;
}

// Describes the location of the function source in a remote repository.
message SourceRepository {
  // URL to the hosted repository where the function is defined. Only paths in
  // https://source.developers.google.com domain are supported. The path should
  // contain the name of the repository.
  string repository_url = 1;

  // The path within the repository where the function is defined. The path
  // should point to the directory where Cloud Functions files are located. Use
  // "/" if the function is defined directly in the root directory of a
  // repository.
  string source_path = 2;

  // The version of a function. Defaults to the latest version of the master
  // branch.
  oneof version {
    // The name of the branch from which the function should be fetched.
    string branch = 3;

    // The name of the tag that captures the state of the repository from
    // which the function should be fetched.
    string tag = 4;

    // The id of the revision that captures the state of the repository from
    // which the function should be fetched.
    string revision = 5;
  }

  // Output only. The id of the revision that was resolved at the moment of
  // function creation or update. For example when a user deployed from a
  // branch, it will be the revision id of the latest change on this branch at
  // that time. If user deployed from revision then this value will be always
  // equal to the revision specified by the user.
  string deployed_revision = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Describes the policy in case of function's execution failure.
// If empty, then defaults to ignoring failures (i.e. not retrying them).
message FailurePolicy {
  // Describes the retry policy in case of function's execution failure.
  // A function execution will be retried on any failure.
  // A failed execution will be retried up to 7 days with an exponential backoff
  // (capped at 10 seconds).
  // Retried execution is charged as any other execution.
  message Retry {

  }

  // Defines the action taken in case of a function execution failure.
  oneof action {
    // If specified, then the function will be retried in case of a failure.
    Retry retry = 1;
  }
}

// Request for the `CreateFunction` method.
message CreateFunctionRequest {
  // Required. The project and location in which the function should be created, specified
  // in the format `projects/*/locations/*`
  string location = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "locations.googleapis.com/Location"
    }
  ];

  // Required. Function to be created.
  CloudFunction function = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request for the `UpdateFunction` method.
message UpdateFunctionRequest {
  // Required. The name of the function to be updated.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudfunctions.googleapis.com/CloudFunction"
    }];

  // Required. New version of the function.
  CloudFunction function = 2 [(google.api.field_behavior) = REQUIRED];
}

// Describes the current stage of a deployment.
enum CloudFunctionStatus {
  // Status not specified.
  STATUS_UNSPECIFIED = 0;

  // Successfully deployed.
  READY = 1;

  // Not deployed correctly - behavior is undefined. The item should be updated
  // or deleted to move it out of this state.
  FAILED = 2;

  // Creation or update in progress.
  DEPLOYING = 3;

  // Deletion in progress.
  DELETING = 4;
}

// Request for the `GetFunction` method.
message GetFunctionRequest {
  // Required. The name of the function which details should be obtained.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudfunctions.googleapis.com/CloudFunction"
    }
  ];
}

// Request for the `ListFunctions` method.
message ListFunctionsRequest {
  // Required. The project and location from which the function should be listed,
  // specified in the format `projects/*/locations/*`
  // If you want to list functions in all locations, use "-" in place of a
  // location. When listing functions in all locations, if one or more
  // location(s) are unreachable, the response will contain functions from all
  // reachable locations along with the names of any unreachable locations.
  string location = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "locations.googleapis.com/Location"
    }
  ];

  // Maximum number of functions to return per call.
  int32 page_size = 2;

  // The value returned by the last
  // `ListFunctionsResponse`; indicates that
  // this is a continuation of a prior `ListFunctions` call, and that the
  // system should return the next page of data.
  string page_token = 3;
}

// Response for the `ListFunctions` method.
message ListFunctionsResponse {
  // The functions that match the request.
  repeated CloudFunction functions = 1;

  // If not empty, indicates that there may be more functions that match
  // the request; this value should be passed in a new
  // [google.cloud.functions.v1beta2.ListFunctionsRequest][google.cloud.functions.v1beta2.ListFunctionsRequest]
  // to get more functions.
  string next_page_token = 2;

  // Locations that could not be reached. The response does not include any
  // functions from these locations.
  repeated string unreachable = 3;
}

// Request for the `DeleteFunction` method.
message DeleteFunctionRequest {
  // Required. The name of the function which should be deleted.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudfunctions.googleapis.com/CloudFunction"
    }
  ];
}

// Request for the `CallFunction` method.
message CallFunctionRequest {
  // Required. The name of the function to be called.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudfunctions.googleapis.com/CloudFunction"
    }
  ];

  // Required. Input to be passed to the function.
  string data = 2 [(google.api.field_behavior) = REQUIRED];
}

// Response of `CallFunction` method.
message CallFunctionResponse {
  // Execution id of function invocation.
  string execution_id = 1;

  // Result populated for successful execution of synchronous function. Will
  // not be populated if function does not return a result through context.
  string result = 2;

  // Either system or user-function generated error. Set if execution
  // was not successful.
  string error = 3;
}

// Request of `GenerateUploadUrl` method.
message GenerateUploadUrlRequest {
  // The project and location in which the Google Cloud Storage signed URL
  // should be generated, specified in the format `projects/*/locations/*`.
  string parent = 1;
}

// Response of `GenerateUploadUrl` method.
message GenerateUploadUrlResponse {
  // The generated Google Cloud Storage signed URL that should be used for a
  // function source code upload. The uploaded file should be a zip archive
  // which contains a function.
  string upload_url = 1;
}

// Request of `GenerateDownloadUrl` method.
message GenerateDownloadUrlRequest {
  // The name of function for which source code Google Cloud Storage signed
  // URL should be generated.
  string name = 1;

  // The optional version of function.
  uint64 version_id = 2;
}

// Response of `GenerateDownloadUrl` method.
message GenerateDownloadUrlResponse {
  // The generated Google Cloud Storage signed URL that should be used for
  // function source code download.
  string download_url = 1;
}