@devvit/protos 0.12.0 → 0.12.1-next-2025-08-13-18-49-54-581208461.0

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/callback/v1/callback_service.proto

@@ -0,0 +1,92 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.callback.v1;
+
+import "google/protobuf/any.proto";
+import "google/protobuf/duration.proto";
+import "reddit/coreplatform/cloudroutines/event/v1/event.proto";
+import "reddit/coreplatform/events/cloudevent/v1/cloudevent.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/callbackpb/v1;callbackpb";
+
+// RPC Service for working with Cloudroutines callbacks
+service CallbackService {
+  // Invoke makes an RPC call to the user's registered callback in their application
+  rpc Invoke(InvokeRequest) returns (InvokeResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+
+  // TODO(marco.ferrer):12/11/23 we may want to add an RPC that the cloudroutines server can
+  // call when a consumer is in trouble or didnt like the result returned by the callback server
+  // then the sdk can record metrics or change application health, or deregister the callback.
+}
+
+// Request message containing the event to be processed by the user's registered callback
+message InvokeRequest {
+  // CloudEvent compliant event payload
+  reddit.coreplatform.events.cloudevent.v1.CloudEvent event = 1;
+  // Name of the callback function to be invoked
+  string callback_name = 2;
+}
+
+// Response message containing the user's registered callback response after processing an event
+message InvokeResponse {
+  OperationResult result = 1;
+}
+
+// OperationResult represents the result of a Cloudroutines operation, currently only a publication result
+message OperationResult {
+  oneof result {
+    Publication publication = 1;
+  }
+
+  // Publication represents a result of a Cloudroutines operation, consisting of a protobuf message
+  // and message route of the protobuf message
+  message Publication {
+    google.protobuf.Any message = 1;
+    reddit.coreplatform.cloudroutines.event.v1.MessageRoute message_route = 2;
+  }
+}
+
+// A finite set of policies which inform the Cloudroutines server on how to react to an error returned by the SDK server.
+message FailurePolicy {
+  // Undefined is the default error policy attached to all status errors when no policy was explicitly set
+  // by the user. This policy message enables the Cloudroutines server to detect when errors are surfaced
+  // from the client vs the network infrastructure.
+  message Undefined {}
+
+  // RetryAfter is the failure policy that indicates a message should be retried after the specified duration.
+  // This is the default failure policy applied if no failure policy is found on the callback error.
+  message RetryAfter {
+    google.protobuf.Duration duration = 1;
+  }
+
+  // BlockExecutionis the failure policy that does a best effort attempt at blocking further execution
+  // from the current message. Manual intervention is required.
+  message BlockExecution {
+    string reason = 1;
+  }
+
+  // Skip is the failure policy that indicates the current message can be dropped.
+  message Skip {
+    string reason = 1;
+  }
+
+  // DeadLetterQueue is the failure policy that adds the current message to a DLQ. The message routing
+  // can be set, otherwise defaults will be used based on the message.
+  message DeadLetterQueue {
+    string reason = 1;
+
+    // Message route allows a user to configure the destination for the DLQ message. If no route is defined,
+    // the SDK will infer the default route based on the message's protobuf fullname, eg. `dlq_{proto_full_name}`.
+    reddit.coreplatform.cloudroutines.event.v1.MessageRoute message_route = 2;
+  }
+
+  oneof policy {
+    Undefined undefined = 1;
+    RetryAfter retry_after = 2;
+    BlockExecution block_execution = 3;
+    Skip skip = 4;
+    DeadLetterQueue dead_letter_queue = 5;
+  }
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/event/v1/event.proto

@@ -0,0 +1,52 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.event.v1;
+
+import "google/protobuf/descriptor.proto";
+import "reddit/coreplatform/cloudroutines/workerpool/v1/workerpool.proto";
+import "validate/validate.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/eventpb/v1;eventpb";
+
+extend google.protobuf.MessageOptions {
+  EventMessageMetadata message = 78110999;
+}
+
+extend google.protobuf.FieldOptions {
+  EventFieldMetadata field = 78110999;
+}
+
+message EventMessageMetadata {
+  string default_topic = 1;
+  repeated reddit.coreplatform.cloudroutines.workerpool.v1.WorkerPool.Source publication_source_whitelist = 2;
+}
+
+message EventFieldMetadata {
+  bool sharding_identifier = 1;
+  string sharding_field_path = 2;
+}
+
+message MessageRoute {
+  // Cluster URI is optional. Defaults to the same cluster as the original protobuf message.
+  // This will be mapped internally to the correct publisher.
+  optional string cluster_uri = 1 [(validate.rules).string = {
+    // TODO: figure out the regex on :/?.&=[]
+    // pattern: "^[-_a-zA-Z0-9]+$",
+    min_len: 1
+    max_len: 64
+  }];
+
+  // Topic is optional. Defaults to `dlq_{proto_full_name}`.
+  optional string topic = 2 [(validate.rules).string = {
+    pattern: "^[-_a-zA-Z0-9]+$"
+    min_len: 1
+    max_len: 255
+  }];
+
+  // Partitioning value is optional. Defaults to the annotated field on the original protobuf message.
+  optional string partitioning_value = 3 [(validate.rules).string = {
+    pattern: "^[-_.a-zA-Z0-9]+$"
+    min_len: 1
+    max_len: 255
+  }];
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/experimental/v1/experimental.proto

@@ -0,0 +1,71 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.experimental.v1;
+
+import "google/protobuf/duration.proto";
+import "validate/validate.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/experimental/v1;experimentalpb";
+
+// Ensures that messages are processed in the strict order they are received.
+// This guarantees the sequence of message execution but may reduce throughput.
+// This is the default ordering if not specified, so it is not necessary to set this explicitly.
+//
+// *Note: If you're using the Python SDK, then KeyMessageOrdering is the default ordering.
+message StrictMessageOrdering {}
+
+// Enables out-of-order message execution.
+// Messages are batched and processed concurrently, increasing throughput but not guaranteeing order of receipt.
+message LooseMessageOrdering {}
+
+// Messages are processed concurrently, similar to LooseMessageOrdering, improving throughput.
+// However, messages with the same Kafka partitioning key will be processed in the order they arrive in.
+// This allows for controlled parallel processing with guarantees on order based on specific keys.
+//
+// *Note: This is the default ordering if not specified when using the Python SDK.
+message KeyMessageOrdering {}
+
+// Wrapper struct for all client alert configurations.
+message AlertConfig {
+  string sdk_version = 1;
+  optional ConsumerLagAlertConfig consumer_lag_alert_config = 2;
+}
+
+// Alert configuration for consumer lag. If the entire struct is left blank, the stated defaults are applied; otherwise, all fields must be set.
+// Currently, this is based off of Burrow's consumer lag metric.
+message ConsumerLagAlertConfig {
+  // Whether or not the alert is disabled.
+  // Defaults to false.
+  bool disabled = 1;
+
+  // The number of messages the consumer group needs to lag by for the alert to fire.
+  // Defaults to 25000.
+  int64 threshold = 2;
+
+  // How long the alert threshold must be sustained for the alert to fire.
+  // Defaults to 5 minutes. Maximum of 30 minutes.
+  google.protobuf.Duration threshold_duration = 3;
+
+  // Infrared v2 reddit-component name to route the alert to (see https://atlas.snooguts.net/catalog/default/component).
+  // Defaults to an empty value, which will route the alert based on the client namespace.
+  string component_name = 4;
+}
+
+message ExperimentalCallbackOptions {
+  // Specifies the delivery order of messages.
+  // Defaults to strict ordering if unset.
+  oneof message_ordering {
+    StrictMessageOrdering strict_ordering = 1;
+    LooseMessageOrdering loose_ordering = 2;
+    KeyMessageOrdering key_ordering = 3;
+  }
+
+  // Wrapper type containing configuration for all client alerts.
+  AlertConfig alert_config = 4;
+
+  // URI representing an arbitrary data source to consume messages from.
+  optional string data_source_uri = 5 [(validate.rules).string = {
+    uri: true
+    max_len: 255
+  }];
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/interop/analytics/v1/analytics.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.interop.analytics.v1;
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/interop/analyticspb/v1;analyticspb";
+
+// A protobuf wrapper for reddit analytics events. Used as a support shim for older, loosely structured
+// event payloads.
+message AnalyticsEvent {
+  // The event payload.
+  bytes data = 1;
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/interop/generic/v1/generic.proto

@@ -0,0 +1,12 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.interop.generic.v1;
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/interop/genericpb/v1;genericpb";
+
+// A protobuf wrapper for unprocessed messages. Used as a support shim for events containing raw byte payloads.
+// DO NOT use this without first contacting #core-events in Slack to discuss your use case.
+message Message {
+  // The event payload.
+  bytes payload = 1;
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/loadbalancing/v1/loadbalancing.proto

@@ -0,0 +1,43 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.loadbalancing.v1;
+
+import "google/protobuf/duration.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/loadbalancingpb/v1;loadbalancingpb";
+
+// Configuration for slow start throttling performed by the server on new worker instances.
+message SlowStartConfig {
+  // The duration of the slow start window. This is the amount of time spent ramping traffic. At the start of the window
+  // traffic is throttled to `min_allow_rate`. At the end of the window, traffic will no longer be throttled.
+  // This value defaults to 15s.
+  google.protobuf.Duration window = 1;
+
+  // The factor used to increase the traffic allowed as the ramp window progresses. An aggression of `1` results in a
+  // linearly increasing allow rate.
+  float ramp_aggression = 2;
+
+  // This value determines how much traffic is allowed to proceed when max throttling is applied. Usually at the start of
+  // the window.
+  float min_allow_rate = 3;
+}
+
+// This message is attached to an error status when the request failed due to reaching the concurrency limit.
+message ConcurrencyLimitReached {
+  // We're not adding any fields for now.
+}
+
+// This message is attached to an error status when the request failed due to slow start throttling being applied.
+// When this error is encountered, the client should retry the request at some point in the future. The new request
+// will either get routed to another address with less throttling or the current address's allow rate has increased.
+message SlowStartThrottle {
+  // The address that is being throttled.
+  string address = 1;
+
+  // How long it has been since the worker server was started and entered the ready state.
+  google.protobuf.Duration worker_age = 2;
+
+  // The percentage of requests that are allowed to proceed for this upstream address. This is a float64
+  // between 0.0-1.0.
+  double allow_rate = 3;
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/metadata/v1/metadata.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.metadata.v1;
+
+import "google/protobuf/descriptor.proto";
+import "google/protobuf/duration.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/metadatapb/v1;metadatapb";
+
+extend google.protobuf.MessageOptions {
+  MessageMetadata cloudroutines = 78010999;
+}
+
+message MessageMetadata {
+  bool enabled = 1;
+
+  google.protobuf.Duration retention_period = 2;
+
+  int32 partition_qty = 3;
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/operation/v1/operation.proto

@@ -0,0 +1,148 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.operation.v1;
+
+import "google/protobuf/timestamp.proto";
+import "google/rpc/status.proto";
+import "validate/validate.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/operationpb/v1;operationpb";
+
+// RPC Service for working with Cloudroutines operations
+service OperationService {
+  // Poll for the status of an operation
+  rpc PollOperationStatuses(PollOperationStatusesRequest) returns (PollOperationStatusesResponse) {
+    option idempotency_level = NO_SIDE_EFFECTS;
+  }
+
+  // Update the status of an operation
+  rpc PublishOperationStatus(PublishOperationStatusRequest) returns (PublishOperationStatusResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+
+  // Mark an operation as skippable
+  rpc SkipOperation(SkipOperationRequest) returns (SkipOperationResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+}
+
+// Request payload to check the statuses of Cloudroutines operations
+// This request requires the operationURI, consisting of the fully qualified Cloudroutines callback name and event ID.
+// If the retention period has elapsed, then requesting a previously valid operation URI will result in
+// a NOT_FOUND status code being returned.
+message PollOperationStatusesRequest {
+  // A list of operation URIs (RFC 3986) to request statuses for, each formatted as
+  // `{worker_pool_namespace}:{callback_name}:{eventID}`.
+  repeated string operation_uris = 1 [(validate.rules).repeated = {
+    min_items: 1
+    max_items: 10
+    items: {
+      string: {
+        uri: true
+        min_len: 1
+        max_len: 255
+      }
+    }
+  }];
+}
+
+// Response payload to check the statuses of Cloudroutines operations
+message PollOperationStatusesResponse {
+  // A map of operations by their URI to their statuses
+  map<string, Operation> associated_operations = 2;
+}
+
+// Request payload to update the status of a Cloudroutines operation
+// This request requires the operationURI, consisting of the fully qualified Cloudroutines callback name and event ID.
+message PublishOperationStatusRequest {
+  // The operation URI (RFC 3986), formatted as `{worker_pool_namespace}:{callback_name}:{eventID}`.
+  string operation_uri = 1 [(validate.rules).string = {
+    uri: true
+    min_len: 1
+    max_len: 255
+  }];
+
+  // The status to update the operation to, must be a valid status (not UNKNOWN). If the operation on the request
+  // is in an initial phase, any provided status value on the request will be ignored and default to UNKNOWN.
+  // Terminal statuses (any status that is not UNKNOWN) cannot be overwritten.
+  google.rpc.Status status = 3;
+
+  // The phase corresponding to the status update for the operation.
+  Phase phase = 4 [(validate.rules).enum = {
+    not_in: [0]
+  }];
+}
+
+// Response payload to update the status of a Cloudroutines operation
+message PublishOperationStatusResponse {}
+
+// Request payload to mark an operation as skippable
+message SkipOperationRequest {
+  // The operation URI (RFC 3986), formatted as `{worker_pool_namespace}:{callback_name}:{eventID}`.
+  string operation_uri = 1 [(validate.rules).string = {
+    uri: true
+    min_len: 1
+    max_len: 255
+  }];
+}
+
+// Response payload to mark an operation as skippable
+message SkipOperationResponse {}
+
+// Phase represents the individual states a Cloudroutines operation can be in throughout its lifecycle.
+enum Phase {
+  // No status was specified or set.
+  PHASE_UNSPECIFIED = 0;
+
+  // An operation is acknowledged by the system but not processed yet. The initial state.
+  PHASE_PENDING = 1;
+
+  // An operation has started processing within the system. Used only for long running operations.
+  PHASE_IN_PROGRESS = 2;
+
+  // An operation has successfully processed or ended up in an unrecoverable error state.
+  PHASE_COMPLETED = 3;
+}
+
+// An operation represents the Cloudroutines operation state including its current status.
+// Due to the nature of Cloudroutines, these are eventually consistent values.
+message Operation {
+  // The operation URI, formatted as `{worker_pool_namespace}:{callback_name}:{eventID}`.
+  // TODO: fix regex
+  string uri = 1 [(validate.rules).string = {
+    // pattern: "^[-_.a-zA-Z0-9]+$",
+    min_len: 1
+    max_len: 255
+  }];
+
+  // The phase of the operation.
+  Phase phase = 2;
+
+  // Operations that complete successfully will have a status `OK`. Any other status code indicates failure.
+  // Status will only be populated when phase is completed. If an operation produces any metadata or results,
+  // they will be available as additional details on the status.
+  google.rpc.Status status = 3;
+
+  // Time when the operation expires from both the event queue and status store.
+  google.protobuf.Timestamp expires_at = 4;
+}
+
+// Used internally within Cloudroutines to asynchronously store the given operation
+message StoreOperationStatus {
+  // The event ID, a unique identifier for an event.
+  string event_id = 1 [(validate.rules).string = {
+    min_len: 1
+    max_len: 255
+  }];
+
+  // The fully qualified Cloudroutines callback name (worker pool namespace + callback name) that processed the operation.
+  string fq_callback_name = 2 [(validate.rules).string = {
+    ignore_empty: true
+    // pattern: "^[-_.a-zA-Z0-9]+$",
+    min_len: 1
+    max_len: 255
+  }];
+
+  // The status to update the operation to, must be a valid status (not UNKNOWN).
+  google.rpc.Status status = 3;
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/publication/v1/publication_service.proto

@@ -0,0 +1,56 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.publication.v1;
+
+import "reddit/coreplatform/events/cloudevent/v1/cloudevent.proto";
+import "validate/validate.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/publicationpb/v1;publicationpb";
+
+service PublicationService {
+  // PublishEvent makes an RPC call to the Cloudroutines server to publish the given event at the given topic
+  rpc PublishEvent(PublishEventRequest) returns (PublishEventResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+}
+
+// Request message containing the event to be published by the user's registered callback
+// Server performs checks to ensure the request parameters are valid:
+// event type and topic are compatible, key is provided if topic is ordered
+message PublishEventRequest {
+  // CloudEvent compliant event payload
+  reddit.coreplatform.events.cloudevent.v1.CloudEvent event = 1 [(validate.rules).message.required = true];
+
+  // Topic to publish the given event to. Typically, this is the fully qualified message name of the event.
+  string topic = 2 [(validate.rules).string = {
+    pattern: "^[-_.a-zA-Z0-9]+$"
+    min_len: 1
+    max_len: 255
+  }];
+
+  // Value to use as the partition key (used for ordering) when publishing the given event.
+  // Must be set to guarantee ordering within a partition, if no ordering is necessary, then pass the event ID.
+  string partition_key = 3 [(validate.rules).string = {
+    pattern: "^[-_.a-zA-Z0-9]+$"
+    min_len: 1
+    max_len: 255
+  }];
+}
+
+// Response message containing the published event details
+message PublishEventResponse {
+  // Event detail information
+  EventDetails event_details = 1;
+}
+
+// Message containing the published event details
+message EventDetails {
+  // The event ID, a unique identifier of the event published
+  string event_id = 1;
+
+  // The topic the event was published to
+  string topic = 2;
+
+  // The partition key the event was published to
+  string partition_key = 3;
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/scheduling/v1/offsets.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.scheduling.v1;
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/schedulingpb/v1;schedulingpb";
+
+message DataSourceOffsetRange {
+  message KafkaTopicOffsetRange {
+    string topic = 1;
+    map<int32, int64> start_offset_by_partition = 2;
+    map<int32, int64> end_offset_by_partition = 3;
+  }
+
+  oneof offset_range {
+    KafkaTopicOffsetRange kafka_topic_offset_range = 1;
+  }
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/scheduling/v1/scheduling.proto

@@ -0,0 +1,25 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.scheduling.v1;
+
+import "reddit/coreplatform/events/cloudevent/v1/cloudevent.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/schedulingpb/v1;schedulingpb";
+
+service SchedulerService {
+  rpc ScheduleTask(ScheduleTaskRequest) returns (ScheduleTaskResponse) {
+    option idempotency_level = IDEMPOTENT;
+  }
+}
+
+message TaskReference {
+  string id = 1;
+}
+
+message ScheduleTaskRequest {
+  reddit.coreplatform.events.cloudevent.v1.CloudEvent event = 1;
+}
+
+message ScheduleTaskResponse {
+  TaskReference task_reference = 1;
+}

package/schema/.snootobuf/remoteSrcs/reddit/coreplatform/cloudroutines/testing/v1/testing.proto

@@ -0,0 +1,72 @@
+syntax = "proto3";
+
+package reddit.coreplatform.cloudroutines.testing.v1;
+
+import "reddit/coreplatform/cloudroutines/event/v1/event.proto";
+
+option go_package = "github.snooguts.net/reddit/cloudroutines/go/testingpb/v1;testingpb";
+
+// Request message containing the event to be processed by the user's registered event handler
+message ExampleEvent {
+  string user_id = 1 [(reddit.coreplatform.cloudroutines.event.v1.field) = {sharding_identifier: true}];
+
+  string subreddit_id = 2;
+}
+
+message ExampleTask {
+  string user_id = 1 [(reddit.coreplatform.cloudroutines.event.v1.field) = {sharding_identifier: true}];
+
+  string greeting = 2;
+}
+
+message ExampleCustomizedEvent {
+  option (reddit.coreplatform.cloudroutines.event.v1.message) = {
+    default_topic: "my_existing_topic"
+    publication_source_whitelist: [
+      {
+        deployment_reference: {
+          name: "reddit-service-cloudroutines-dummy-client"
+          namespace: "reddit-service-cloudroutines"
+        }
+      }
+    ]
+  };
+
+  string subreddit_id = 1 [(reddit.coreplatform.cloudroutines.event.v1.field) = {sharding_identifier: true}];
+}
+
+message ExampleCustomizedNestedEvent {
+  message Relation {
+    string relation_id = 1;
+    RelationDetails details = 2;
+  }
+
+  message RelationDetails {
+    string thing1_id = 1; // this is the sharding identifier
+    string thing2_id = 2;
+    int64 int64_field = 3;
+    repeated string repeated_string_field = 4;
+    float float_field = 5;
+  }
+
+  string event_id = 1;
+
+  Relation relation = 2 [(reddit.coreplatform.cloudroutines.event.v1.field) = {
+    sharding_identifier: true
+    sharding_field_path: "details.thing1_id"
+  }];
+
+  int64 int64_field = 3;
+  repeated string repeated_string_field = 4;
+  float float_field = 5;
+}
+
+message ExampleDLQEvent {
+  string user_id = 1 [(reddit.coreplatform.cloudroutines.event.v1.field) = {sharding_identifier: true}];
+
+  string subreddit_id = 2;
+}
+
+message ExampleResult {
+  string greeting = 1;
+}