feat: add debug events API (#8533)

# Which Problems Are Solved

Add a debug API which allows pushing a set of events to be reduced in a
dedicated projection.
The events can carry a sleep duration which simulates a slow query
during projection handling.

# How the Problems Are Solved

- `CreateDebugEvents` allows pushing multiple events which simulate the
lifecycle of a resource. Each event has a `projectionSleep` field, which
issues a `pg_sleep()` statement query in the projection handler :
  - Add
  - Change
  - Remove
- `ListDebugEventsStates` list the current state of the projection,
optionally with a Trigger
- `GetDebugEventsStateByID` get the current state of the aggregate ID in
the projection, optionally with a Trigger


# Additional Changes

- none

# Additional Context

-  Allows reproduction of https://github.com/zitadel/zitadel/issues/8517

proto/zitadel/resources/debug_events/v3alpha/debug_events_service.proto

@@ -0,0 +1,223 @@
+syntax = "proto3";
+
+package zitadel.resources.debug_events.v3alpha;
+
+import "google/api/annotations.proto";
+import "google/api/field_behavior.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
+import "validate/validate.proto";
+
+import "zitadel/protoc_gen_zitadel/v2/options.proto";
+import "zitadel/object/v3alpha/object.proto";
+import "zitadel/resources/object/v3alpha/object.proto";
+import "zitadel/resources/debug_events/v3alpha/event.proto";
+import "zitadel/resources/debug_events/v3alpha/state.proto";
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/resources/debug_events/v3alpha;debug_events";
+
+option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
+  info: {
+    title: "Debug Service";
+    version: "3.0-preview";
+    description: "This API is intended to push specific debug payload through ZITADEL's storage system.";
+    contact:{
+      name: "ZITADEL"
+      url: "https://zitadel.com"
+      email: "hi@zitadel.com"
+    }
+    license: {
+      name: "Apache 2.0",
+      url: "https://github.com/zitadel/zitadel/blob/main/LICENSE";
+    };
+  };
+  schemes: HTTPS;
+  schemes: HTTP;
+
+  consumes: "application/json";
+  produces: "application/json";
+
+  consumes: "application/grpc";
+  produces: "application/grpc";
+
+  consumes: "application/grpc-web+proto";
+  produces: "application/grpc-web+proto";
+
+  host: "$CUSTOM-DOMAIN";
+  base_path: "/resources/v3alpha/debug";
+
+  external_docs: {
+    description: "Detailed information about ZITADEL",
+    url: "https://zitadel.com/docs"
+  }
+  security_definitions: {
+    security: {
+      key: "OAuth2";
+      value: {
+        type: TYPE_OAUTH2;
+        flow: FLOW_ACCESS_CODE;
+        authorization_url: "$CUSTOM-DOMAIN/oauth/v2/authorize";
+        token_url: "$CUSTOM-DOMAIN/oauth/v2/token";
+        scopes: {
+          scope: {
+            key: "openid";
+            value: "openid";
+          }
+          scope: {
+            key: "urn:zitadel:iam:org:project:id:zitadel:aud";
+            value: "urn:zitadel:iam:org:project:id:zitadel:aud";
+          }
+        }
+      }
+    }
+  }
+  security: {
+    security_requirement: {
+      key: "OAuth2";
+      value: {
+        scope: "openid";
+        scope: "urn:zitadel:iam:org:project:id:zitadel:aud";
+      }
+    }
+  }
+  responses: {
+    key: "403";
+    value: {
+      description: "Returned when the user does not have permission to access the resource.";
+      schema: {
+        json_schema: {
+          ref: "#/definitions/rpcStatus";
+        }
+      }
+    }
+  }
+  responses: {
+    key: "404";
+    value: {
+      description: "Returned when the resource does not exist.";
+      schema: {
+        json_schema: {
+          ref: "#/definitions/rpcStatus";
+        }
+      }
+    }
+  }
+};
+
+service ZITADELDebugEvents {
+  rpc CreateDebugEvents(CreateDebugEventsRequest) returns (CreateDebugEventsResponse) {
+    option (google.api.http) = {
+      post: "/"
+      body: "events"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.debug.write"
+      }
+      http_response: {
+        success_code: 201
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      summary: "Create a set of debug events.";
+      description: "Create a set of debug events which will be pushed to the eventstore and reduced to the projection."
+      responses: {
+        key: "200"
+        value: {
+          description: "OK";
+        }
+      };
+    };
+  }
+
+  rpc GetDebugEventsStateById(GetDebugEventsStateByIdRequest) returns (GetDebugEventsStateByIdResponse) {
+    option (google.api.http) = {
+      get: "/v3alpha/debug_events/{id}"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.debug.read"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "Debug events state successfully retrieved";
+        }
+      };
+    };
+  }
+
+  rpc ListDebugEventsStates(ListDebugEventsStatesRequest) returns (ListDebugEventsStatesResponse) {
+    option (google.api.http) = {
+      get: "/v3alpha/debug_events"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.debug.read"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "Debug events states successfully retrieved";
+        }
+      };
+    };
+  }
+}
+
+message CreateDebugEventsRequest {
+  optional zitadel.object.v3alpha.Instance instance = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      default: "\"domain from HOST or :authority header\""
+    }
+  ];
+  // unique identifier for the aggregate we want to push events to.
+  string aggregate_id = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1,
+      max_length: 200,
+      example: "\"69629026806489455\"";
+    }
+  ];
+  repeated Event events = 3;
+}
+
+message CreateDebugEventsResponse {
+  zitadel.resources.object.v3alpha.Details details = 1;
+}
+
+message GetDebugEventsStateByIdRequest {
+  // unique identifier of the aggregate.
+  string id = 1 [
+    (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1,
+      max_length: 200,
+      example: "\"69629026806489455\"";
+    }
+  ];
+  bool trigger_bulk = 2;
+}
+
+message GetDebugEventsStateByIdResponse {
+  State state = 1;
+}
+
+message ListDebugEventsStatesRequest {
+  bool trigger_bulk = 1;
+}
+
+message ListDebugEventsStatesResponse {
+  repeated State states = 1;
+}

proto/zitadel/resources/debug_events/v3alpha/event.proto

@@ -0,0 +1,47 @@
+syntax = "proto3";
+
+package zitadel.resources.debug_events.v3alpha;
+
+import "google/protobuf/duration.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/resources/debug_events/v3alpha;debug_events";
+
+message Event {
+  oneof event {
+      AddedEvent add = 1;
+      ChangedEvent change = 2;
+      RemovedEvent remove = 3;
+  }
+}
+
+message AddedEvent {
+  // issues a pg_sleep command in the projection reducer, simulating a slow query.
+  google.protobuf.Duration projection_sleep = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+        example: "\"5s\"";
+    }
+  ];
+  // optional text that can be set as a state.
+  optional string blob = 2;
+}
+
+message ChangedEvent {
+  // issues a pg_sleep command in the projection reducer, simulating a slow query.
+  google.protobuf.Duration projection_sleep = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+        example: "\"5s\"";
+    }
+  ];
+  // optional text that can be set as a state.
+  optional string blob = 2;
+}
+
+message RemovedEvent {
+  // issues a pg_sleep command in the projection reducer, simulating a slow query.
+  google.protobuf.Duration projection_sleep = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+        example: "\"5s\"";
+    }
+  ];
+}

proto/zitadel/resources/debug_events/v3alpha/state.proto

@@ -0,0 +1,14 @@
+syntax = "proto3";
+
+package zitadel.resources.debug_events.v3alpha;
+
+import "zitadel/resources/object/v3alpha/object.proto";
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/resources/debug_events/v3alpha;debug_events";
+
+message State {
+  // Details provide some base information (such as the last change date) of the schema.
+  zitadel.resources.object.v3alpha.Details details = 1;
+
+  string blob = 2;
+}