data.proto

// Copyright 2023 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
//
//     https://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.events.firebase.dataconnect.v1;

import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/code.proto";

option csharp_namespace = "Google.Events.Protobuf.Firebase.DataConnect.V1";
option php_namespace = "Google\\Events\\Firebase\\DataConnect\\V1";
option ruby_package = "Google::Events::Firebase::DataConnect::V1";

// A Firebase Data Connect service.
message Service {
  // Identifier. The relative resource name of the Firebase Data Connect
  // service, in the format:
  // ```
  // projects/{project}/locations/{location}/services/{service}
  // ```
  // Note that the service ID is specific to Firebase Data Connect and does not
  // correspond to any of the instance IDs of the underlying data source
  // connections.
  string name = 1;

  // Output only. [Output only] Create time stamp.
  google.protobuf.Timestamp create_time = 2;

  // Output only. [Output only] Update time stamp.
  google.protobuf.Timestamp update_time = 3;

  // Optional. Labels as key value pairs.
  map<string, string> labels = 4;

  // Optional. Stores small amounts of arbitrary data.
  map<string, string> annotations = 5;

  // Output only. System-assigned, unique identifier.
  string uid = 6;

  // Output only. A field that if true, indicates that the system is working
  // update the service.
  bool reconciling = 7;

  // Optional. Mutable human-readable name. 63 character limit.
  string display_name = 8;

  // Output only. This checksum is computed by the server based on the value of
  // other fields, and may be sent on update and delete requests to ensure the
  // client has an up-to-date value before proceeding.
  // [AIP-154](https://google.aip.dev/154)
  string etag = 99;
}

// A data source that backs Firebase Data Connect services.
message Datasource {
  // Settings and configurations of the underlying data source.
  oneof configuration {
    // PostgreSQL configurations.
    PostgreSql postgresql = 2;
  }
}

// Settings for PostgreSQL data source.
message PostgreSql {
  // Configure the behavior before deploying this schema.
  // Default to `schema_validation=STRICT` if not specified.
  oneof before_deploy {
    // Optional. Configure how much Postgresql schema validation to perform.
    SqlSchemaValidation schema_validation = 3;

    // Optional. Configure how to perform Postgresql schema migration.
    SqlSchemaMigration schema_migration = 5;
  }

  // Settings and configurations of the underlying database.
  oneof configuration {
    // No Postgres data source is linked.
    // If set, don't allow `database` and `schema_validation` to be configured.
    bool unlinked = 4;

    // Cloud SQL configurations.
    CloudSqlInstance cloud_sql = 2;
  }

  // Required. Name of the PostgreSQL database.
  string database = 1;
}

// Settings for CloudSQL instance configuration.
message CloudSqlInstance {
  // Required. Name of the CloudSQL instance, in the format:
  // ```
  // projects/{project}/locations/{location}/instances/{instance}
  // ```
  string instance = 1;
}

// The application schema of a Firebase Data Connect service.
message Schema {
  // Identifier. The relative resource name of the schema, in the format:
  // ```
  // projects/{project}/locations/{location}/services/{service}/schemas/{schema}
  // ```
  // Right now, the only supported schema is "main".
  string name = 1;

  // Output only. [Output only] Create time stamp.
  google.protobuf.Timestamp create_time = 2;

  // Output only. [Output only] Update time stamp.
  google.protobuf.Timestamp update_time = 3;

  // Optional. Labels as key value pairs.
  map<string, string> labels = 4;

  // Optional. Stores small amounts of arbitrary data.
  map<string, string> annotations = 5;

  // Required. The data sources linked in the schema.
  repeated Datasource datasources = 11;

  // Required. The source files that comprise the application schema.
  Source source = 7;

  // Output only. System-assigned, unique identifier.
  string uid = 8;

  // Output only. A field that if true, indicates that the system is working to
  // compile and deploy the schema.
  bool reconciling = 9;

  // Optional. Mutable human-readable name. 63 character limit.
  string display_name = 10;

  // Output only. This checksum is computed by the server based on the value of
  // other fields, and may be sent on update and delete requests to ensure the
  // client has an up-to-date value before proceeding.
  // [AIP-154](https://google.aip.dev/154)
  string etag = 99;
}

// Connector consists of a set of operations, i.e. queries and mutations.
message Connector {
  // Identifier. The relative resource name of the connector, in the format:
  // ```
  // projects/{project}/locations/{location}/services/{service}/connectors/{connector}
  // ```
  string name = 1;

  // Output only. [Output only] Create time stamp.
  google.protobuf.Timestamp create_time = 2;

  // Output only. [Output only] Update time stamp.
  google.protobuf.Timestamp update_time = 3;

  // Optional. Labels as key value pairs.
  map<string, string> labels = 4;

  // Optional. Stores small amounts of arbitrary data.
  map<string, string> annotations = 5;

  // Required. The source files that comprise the connector.
  Source source = 6;

  // Output only. System-assigned, unique identifier.
  string uid = 7;

  // Output only. A field that if true, indicates that the system is working to
  // compile and deploy the connector.
  bool reconciling = 8;

  // Optional. Mutable human-readable name. 63 character limit.
  string display_name = 9;

  // Output only. This checksum is computed by the server based on the value of
  // other fields, and may be sent on update and delete requests to ensure the
  // client has an up-to-date value before proceeding.
  // [AIP-154](https://google.aip.dev/154)
  string etag = 99;
}

// Used to represent a set of source files.
message Source {
  // Required. The files that comprise the source set.
  repeated File files = 1;
}

// Individual files.
message File {
  // Required. The file name including folder path, if applicable. The path
  // should be relative to a local workspace (e.g.
  // dataconnect/(schema|connector)/*.gql) and not an absolute path (e.g.
  // /absolute/path/(schema|connector)/*.gql).
  string path = 1;

  // Required. The file's textual content.
  string content = 2;
}

// Configure how much SQL Schema to perform for the given schema.
enum SqlSchemaValidation {
  // Unspecified SQL schema validation.
  // Default to STRICT.
  SQL_SCHEMA_VALIDATION_UNSPECIFIED = 0;

  // Skip no SQL schema validation. Use it with extreme caution.
  // CreateSchema or UpdateSchema will succeed even if SQL database is
  // unavailable or SQL schema is incompatible.
  // Generated SQL may fail at execution time.
  NONE = 1;

  // Connect to the SQL database and validate that the SQL DDL matches the
  // schema exactly. Surface any discrepancies as `FAILED_PRECONDITION` with an
  // `IncompatibleSqlSchemaError` error detail.
  STRICT = 2;

  // Connect to the SQL database and validate that the SQL DDL has all the SQL
  // resources used in the given Firebase Data Connect Schema. Surface any
  // missing resources as `FAILED_PRECONDITION` with an
  // `IncompatibleSqlSchemaError` error detail. Succeed even if there are
  // unknown tables and columns.
  COMPATIBLE = 3;
}

// Configure how to perform SQL Schema migration before deploying the Schema.
enum SqlSchemaMigration {
  // Unspecified SQL schema migration.
  SQL_SCHEMA_MIGRATION_UNSPECIFIED = 0;

  // Connect to the SQL database and identify any missing SQL resources used
  // in the given Firebase Data Connect Schema.
  // Automatically create necessary SQL resources (SQL table, column, etc)
  // before deploying the schema.
  // During migration steps, the SQL Schema must comply with the previous
  // before_deploy setting in case the migration is interrupted.
  // Therefore, the previous before_deploy setting must not be
  // `schema_validation=STRICT`.
  MIGRATE_COMPATIBLE = 1;
}

// The data within all Service events.
message ServiceEventData {
  // Optional. The Service event payload. Unset for deletion events.
  Service payload = 1;
}

// The data within all Schema events.
message SchemaEventData {
  // Optional. The Schema event payload. Unset for deletion events.
  Schema payload = 1;
}

// The data within all Connector events.
message ConnectorEventData {
  // Optional. The Connector event payload. Unset for deletion events.
  Connector payload = 1;
}

// GraphqlError contains the error information of a GraphQL query or mutation.
message GraphqlError {
  // The detailed error message.
  // The message should help developer understand the underlying problem without
  // leaking internal data.
  string message = 1;

  // The source locations where the error occurred.
  // Locations should help developers and toolings identify the source of error
  // quickly.
  //
  // Included in admin endpoints (`ExecuteGraphql`, `ExecuteGraphqlRead`,
  // `IntrospectGraphql`, `ImpersonateQuery` and `ImpersonateMutation`,
  // `UpdateSchema` and `UpdateConnector`) to reference the provided GraphQL
  // GQL document.
  //
  // Omitted in `ExecuteMutation` and `ExecuteQuery` since the caller shouldn't
  // have access access the underlying GQL source.
  repeated SourceLocation locations = 2;

  // The result field which could not be populated due to error.
  //
  // Clients can use path to identify whether a null result is intentional or
  // caused by a runtime error.
  // It should be a list of string or index from the root of GraphQL query
  // document.
  google.protobuf.ListValue path = 3;

  // Additional error information.
  GraphqlErrorExtensions extensions = 4;
}

// GraphqlErrorExtensions contains additional information of `GraphqlError`.
message GraphqlErrorExtensions {
  // The source file name where the error occurred.
  // Included only for `UpdateSchema` and `UpdateConnector`, it corresponds
  // to `File.path` of the provided `Source`.
  string file = 1;

  // Maps to canonical gRPC codes.
  // If not specified, it represents `Code.INTERNAL`.
  google.rpc.Code code = 2;

  // More detailed error message to assist debugging.
  // It contains application business logic that are inappropriate to leak
  // publicly.
  //
  // In the emulator, Data Connect API always includes it to assist local
  // development and debugging.
  // In the backend, ConnectorService always hides it.
  // GraphqlService without impersonation always include it.
  // GraphqlService with impersonation includes it only if explicitly opted-in
  // with `include_debug_details` in `GraphqlRequestExtensions`.
  string debug_details = 3;
}

// SourceLocation references a location in a GraphQL source.
message SourceLocation {
  // Line number starting at 1.
  int32 line = 1;

  // Column number starting at 1.
  int32 column = 2;
}

message Mutation {
  // The result of the execution of the requested operation.
  // If an error was raised before execution begins, the data entry should not
  // be present in the result. (a request error:
  // https://spec.graphql.org/draft/#sec-Errors.Request-Errors) If an error was
  // raised during the execution that prevented a valid response, the data entry
  // in the response should be null. (a field error:
  // https://spec.graphql.org/draft/#sec-Errors.Error-Result-Format)
  google.protobuf.Struct data = 1;

  // Values for GraphQL variables provided in this request.
  google.protobuf.Struct variables = 3;

  // Errors of this response.
  // If the data entry in the response is not present, the errors entry must be
  // present.
  // It conforms to https://spec.graphql.org/draft/#sec-Errors.
  repeated GraphqlError errors = 2;
}

// The data within all Mutation events.
message MutationEventData {
  Mutation payload = 1;
}