queueservice

type AcknowledgeMessageRequest struct {
	QueueName     string                     `protobuf:"bytes,1,opt,name=queue_name,json=queueName,proto3" json:"queue_name,omitempty"`
	MessageId     string                     `protobuf:"bytes,2,opt,name=message_id,json=messageId,proto3" json:"message_id,omitempty"`
	State         v11.Message_Metadata_State `protobuf:"varint,3,opt,name=state,proto3,enum=chronoqueue.api.message.v1.Message_Metadata_State" json:"state,omitempty"`
	StreamEntryId string                     `protobuf:"bytes,4,opt,name=stream_entry_id,json=streamEntryId,proto3" json:"stream_entry_id,omitempty"`
	// Optional stable identifier to consistently represent the same consumer
	WorkerId *string `protobuf:"bytes,5,opt,name=worker_id,json=workerId,proto3,oneof" json:"worker_id,omitempty"`
	// Attempt identifier to validate acknowledgment against current attempt
	AttemptId *string `protobuf:"bytes,6,opt,name=attempt_id,json=attemptId,proto3,oneof" json:"attempt_id,omitempty"`
	// contains filtered or unexported fields
}

type AcknowledgeMessageResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type CreateQueueRequest struct {
	Name     string            `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	Metadata *v1.QueueMetadata `protobuf:"bytes,2,opt,name=metadata,proto3,oneof" json:"metadata,omitempty"`
	// contains filtered or unexported fields
}

type CreateQueueResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type CreateScheduleRequest struct {
	Schedule *v12.Schedule `protobuf:"bytes,1,opt,name=schedule,proto3" json:"schedule,omitempty"`
	// contains filtered or unexported fields
}

type CreateScheduleResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type DeleteFromDLQRequest struct {
	DlqName   string `protobuf:"bytes,1,opt,name=dlq_name,json=dlqName,proto3" json:"dlq_name,omitempty"`
	MessageId string `protobuf:"bytes,2,opt,name=message_id,json=messageId,proto3" json:"message_id,omitempty"`
	// contains filtered or unexported fields
}

type DeleteFromDLQResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type DeleteQueueRequest struct {
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// contains filtered or unexported fields
}

type DeleteQueueResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type DeleteScheduleRequest struct {
	ScheduleId string `protobuf:"bytes,1,opt,name=schedule_id,json=scheduleId,proto3" json:"schedule_id,omitempty"`
	// contains filtered or unexported fields
}

type DeleteScheduleResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type DeleteSchemaRequest struct {
	SchemaId string `protobuf:"bytes,1,opt,name=schema_id,json=schemaId,proto3" json:"schema_id,omitempty"` // Schema identifier
	Version  int32  `protobuf:"varint,2,opt,name=version,proto3" json:"version,omitempty"`                  // Schema version (0 = delete all versions)
	// contains filtered or unexported fields
}

type DeleteSchemaResponse struct {
	Success         bool  `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	VersionsDeleted int32 `protobuf:"varint,2,opt,name=versions_deleted,json=versionsDeleted,proto3" json:"versions_deleted,omitempty"` // Number of versions deleted
	// contains filtered or unexported fields
}

type GetDLQMessagesRequest struct {
	DlqName string `protobuf:"bytes,1,opt,name=dlq_name,json=dlqName,proto3" json:"dlq_name,omitempty"`
	Limit   int32  `protobuf:"varint,2,opt,name=limit,proto3" json:"limit,omitempty"`
	// contains filtered or unexported fields
}

type GetDLQMessagesResponse struct {
	Messages []*v11.Message `protobuf:"bytes,1,rep,name=messages,proto3" json:"messages,omitempty"`
	// contains filtered or unexported fields
}

type GetDLQStatsRequest struct {
	DlqName string `protobuf:"bytes,1,opt,name=dlq_name,json=dlqName,proto3" json:"dlq_name,omitempty"`
	// contains filtered or unexported fields
}

type GetDLQStatsResponse struct {
	Name         string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	MessageCount int64  `protobuf:"varint,2,opt,name=message_count,json=messageCount,proto3" json:"message_count,omitempty"`
	CreatedAt    int64  `protobuf:"varint,3,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
	UpdatedAt    int64  `protobuf:"varint,4,opt,name=updated_at,json=updatedAt,proto3" json:"updated_at,omitempty"`
	// contains filtered or unexported fields
}

type GetNextMessageRequest struct {
	QueueName      string               `protobuf:"bytes,1,opt,name=queue_name,json=queueName,proto3" json:"queue_name,omitempty"`
	LeaseDuration  *durationpb.Duration `protobuf:"bytes,2,opt,name=lease_duration,json=leaseDuration,proto3" json:"lease_duration,omitempty"`
	ExclusivityKey string               `protobuf:"bytes,3,opt,name=exclusivity_key,json=exclusivityKey,proto3" json:"exclusivity_key,omitempty"`
	// Optional stable identifier for the worker/consumer. If absent, server may generate one.
	WorkerId *string `protobuf:"bytes,4,opt,name=worker_id,json=workerId,proto3,oneof" json:"worker_id,omitempty"`
	// Attempt identifier to validate lease against current attempt
	AttemptId *string `protobuf:"bytes,5,opt,name=attempt_id,json=attemptId,proto3,oneof" json:"attempt_id,omitempty"`
	// contains filtered or unexported fields
}

type GetNextMessageResponse struct {
	Message       *v11.Message `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"`
	StreamEntryId string       `protobuf:"bytes,2,opt,name=stream_entry_id,json=streamEntryId,proto3" json:"stream_entry_id,omitempty"`
	// Echo or assign the worker_id used for this lease
	WorkerId *string `protobuf:"bytes,3,opt,name=worker_id,json=workerId,proto3,oneof" json:"worker_id,omitempty"`
	// Attempt identifier for this lease
	AttemptId *string `protobuf:"bytes,4,opt,name=attempt_id,json=attemptId,proto3,oneof" json:"attempt_id,omitempty"`
	// contains filtered or unexported fields
}

type GetQueueStateRequest struct {
	QueueName string `protobuf:"bytes,1,opt,name=queue_name,json=queueName,proto3" json:"queue_name,omitempty"`
	// contains filtered or unexported fields
}

type GetQueueStateResponse struct {
	StateCounts      map[string]int32       `` /* 169-byte string literal not displayed */
	EarliestDeadline *timestamppb.Timestamp `protobuf:"bytes,2,opt,name=earliest_deadline,json=earliestDeadline,proto3" json:"earliest_deadline,omitempty"`
	// contains filtered or unexported fields
}

type GetScheduleHistoryRequest struct {
	ScheduleId string `protobuf:"bytes,1,opt,name=schedule_id,json=scheduleId,proto3" json:"schedule_id,omitempty"`
	Limit      int64  `protobuf:"varint,2,opt,name=limit,proto3" json:"limit,omitempty"`
	// contains filtered or unexported fields
}

type GetScheduleHistoryResponse struct {
	ScheduleHistory *v12.ScheduleHistory `protobuf:"bytes,1,opt,name=schedule_history,json=scheduleHistory,proto3" json:"schedule_history,omitempty"`
	// contains filtered or unexported fields
}

type GetScheduleRequest struct {
	ScheduleId string `protobuf:"bytes,1,opt,name=schedule_id,json=scheduleId,proto3" json:"schedule_id,omitempty"`
	// contains filtered or unexported fields
}

type GetScheduleResponse struct {
	Schedule *v12.Schedule `protobuf:"bytes,1,opt,name=schedule,proto3" json:"schedule,omitempty"`
	// contains filtered or unexported fields
}

type GetSchemaRequest struct {
	SchemaId string `protobuf:"bytes,1,opt,name=schema_id,json=schemaId,proto3" json:"schema_id,omitempty"` // Schema identifier
	Version  int32  `protobuf:"varint,2,opt,name=version,proto3" json:"version,omitempty"`                  // Schema version (0 = latest)
	// contains filtered or unexported fields
}

type GetSchemaResponse struct {
	Schema *v13.Schema `protobuf:"bytes,1,opt,name=schema,proto3" json:"schema,omitempty"` // Full schema object
	// contains filtered or unexported fields
}

type ListQueuesRequest struct {
	Prefix string `protobuf:"bytes,1,opt,name=prefix,proto3" json:"prefix,omitempty"`
	// contains filtered or unexported fields
}

type ListQueuesResponse struct {
	Queues []*v1.Queue `protobuf:"bytes,1,rep,name=queues,proto3" json:"queues,omitempty"`
	// contains filtered or unexported fields
}

type ListSchedulesRequest struct {
	Prefix string `protobuf:"bytes,1,opt,name=prefix,proto3" json:"prefix,omitempty"`
	// contains filtered or unexported fields
}

type ListSchedulesResponse struct {
	Schedules []*v12.Schedule `protobuf:"bytes,1,rep,name=schedules,proto3" json:"schedules,omitempty"`
	// contains filtered or unexported fields
}

type ListSchemasRequest struct {
	Prefix     string `protobuf:"bytes,1,opt,name=prefix,proto3" json:"prefix,omitempty"`                            // Filter by schema_id prefix
	Limit      int32  `protobuf:"varint,2,opt,name=limit,proto3" json:"limit,omitempty"`                             // Maximum number of results (default: 100)
	ActiveOnly bool   `protobuf:"varint,3,opt,name=active_only,json=activeOnly,proto3" json:"active_only,omitempty"` // Only return active schemas
	// contains filtered or unexported fields
}

type ListSchemasResponse struct {
	Schemas    []*SchemaInfo `protobuf:"bytes,1,rep,name=schemas,proto3" json:"schemas,omitempty"`
	TotalCount int32         `protobuf:"varint,2,opt,name=total_count,json=totalCount,proto3" json:"total_count,omitempty"`
	// contains filtered or unexported fields
}

type PauseScheduleRequest struct {
	ScheduleId string `protobuf:"bytes,1,opt,name=schedule_id,json=scheduleId,proto3" json:"schedule_id,omitempty"`
	// contains filtered or unexported fields
}

type PauseScheduleResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type PeekQueueMessagesRequest struct {
	QueueName     string                                  `protobuf:"bytes,1,opt,name=queue_name,json=queueName,proto3" json:"queue_name,omitempty"`
	Limit         int64                                   `protobuf:"varint,2,opt,name=limit,proto3" json:"limit,omitempty"`
	PriorityRange *PeekQueueMessagesRequest_PriorityRange `protobuf:"bytes,3,opt,name=priority_range,json=priorityRange,proto3,oneof" json:"priority_range,omitempty"`
	// contains filtered or unexported fields
}

type PeekQueueMessagesRequest_PriorityRange struct {
	Min int64 `protobuf:"varint,1,opt,name=min,proto3" json:"min,omitempty"`
	Max int64 `protobuf:"varint,2,opt,name=max,proto3" json:"max,omitempty"`
	// contains filtered or unexported fields
}

type PeekQueueMessagesResponse struct {
	Messages []*v11.Message `protobuf:"bytes,1,rep,name=messages,proto3" json:"messages,omitempty"`
	// contains filtered or unexported fields
}

type PostMessageRequest struct {
	QueueName string       `protobuf:"bytes,1,opt,name=queue_name,json=queueName,proto3" json:"queue_name,omitempty"`
	Message   *v11.Message `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"`
	// contains filtered or unexported fields
}

type PostMessageResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type PreviewCalendarScheduleRequest struct {
	CalendarSchedule *v12.CalendarSchedule `protobuf:"bytes,1,opt,name=calendar_schedule,json=calendarSchedule,proto3" json:"calendar_schedule,omitempty"`
	Count            int32                 `protobuf:"varint,2,opt,name=count,proto3" json:"count,omitempty"` // Number of execution times to preview (default: 10, max: 100)
	// contains filtered or unexported fields
}

type PreviewCalendarScheduleResponse struct {
	ExecutionTimes []*timestamppb.Timestamp `protobuf:"bytes,1,rep,name=execution_times,json=executionTimes,proto3" json:"execution_times,omitempty"`
	Timezone       string                   `protobuf:"bytes,2,opt,name=timezone,proto3" json:"timezone,omitempty"`
	PreviewStart   *timestamppb.Timestamp   `protobuf:"bytes,3,opt,name=preview_start,json=previewStart,proto3" json:"preview_start,omitempty"`
	TotalCount     int32                    `protobuf:"varint,4,opt,name=total_count,json=totalCount,proto3" json:"total_count,omitempty"`
	// contains filtered or unexported fields
}

type PurgeDLQRequest struct {
	DlqName string `protobuf:"bytes,1,opt,name=dlq_name,json=dlqName,proto3" json:"dlq_name,omitempty"`
	// contains filtered or unexported fields
}

type PurgeDLQResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type QueueServiceClient interface {
	// CreateQueue creates a new queue with specified configuration.
	//
	// Use to:
	// - Define retry behavior (max_attempts, lease_duration)
	// - Set up dead letter queue for failed messages
	// - Configure priority handling
	// - Enforce message schemas
	//
	// Example:
	//
	//	POST /v1/queues
	//	{
	//	  "queue": {
	//	    "name": "order-processing",
	//	    "metadata": {
	//	      "default_max_attempts": 3,
	//	      "lease_duration": "5m",
	//	      "dead_letter_queue_name": "order-dlq",
	//	      "auto_create_dlq": true
	//	    }
	//	  }
	//	}
	//
	// Returns: Queue details
	// Errors:
	//   - AlreadyExists: Queue with this name exists
	//   - InvalidArgument: Invalid configuration (negative lease_duration, etc.)
	CreateQueue(ctx context.Context, in *CreateQueueRequest, opts ...grpc.CallOption) (*CreateQueueResponse, error)
	// DeleteQueue permanently deletes a queue and all its messages.
	//
	// WARNING: This operation is irreversible. All pending and running messages are lost.
	//
	// Use when:
	// - Decommissioning a feature
	// - Cleaning up test queues
	// - Removing unused queues
	//
	// Best practice: Drain queue first (stop posting, wait for workers to finish).
	//
	// Example:
	//
	//	DELETE /v1/queues/order-processing
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Queue doesn't exist
	DeleteQueue(ctx context.Context, in *DeleteQueueRequest, opts ...grpc.CallOption) (*DeleteQueueResponse, error)
	// ListQueues returns all queues in your ChronoQueue instance.
	//
	// Use for:
	// - Monitoring dashboards
	// - Queue discovery
	// - Debugging
	//
	// Example:
	//
	//	GET /v1/queues
	//
	// Returns: List of Queue objects with metadata
	ListQueues(ctx context.Context, in *ListQueuesRequest, opts ...grpc.CallOption) (*ListQueuesResponse, error)
	// GetQueueState returns current queue statistics and health.
	//
	// Provides:
	// - Message counts by state (PENDING, RUNNING, COMPLETED, ERRORED)
	// - Rate metrics (messages/sec, processing time)
	// - DLQ size
	//
	// Use for:
	// - Health checks
	// - Autoscaling decisions (scale workers based on PENDING count)
	// - Alerting (high ERRORED count, DLQ growth)
	//
	// Example:
	//
	//	GET /v1/queues/order-processing/state
	//	Response:
	//	{
	//	  "pending_count": 150,
	//	  "running_count": 10,
	//	  "completed_count": 5420,
	//	  "errored_count": 3,
	//	  "dlq_count": 2
	//	}
	//
	// Returns: QueueState with counts and metrics
	GetQueueState(ctx context.Context, in *GetQueueStateRequest, opts ...grpc.CallOption) (*GetQueueStateResponse, error)
	// PostMessage adds a new message to a queue.
	//
	// Use for:
	// - Asynchronous task execution
	// - Event-driven workflows
	// - Job scheduling
	// - Load leveling
	//
	// Features:
	// - Delayed execution (scheduled_time)
	// - Priority ordering
	// - Schema validation
	// - Deduplication (idempotency_key)
	// - Exclusive processing (exclusivity_key)
	//
	// Example - immediate execution:
	//
	//	POST /v1/queues/order-processing/messages
	//	{
	//	  "message": {
	//	    "metadata": {
	//	      "payload": {"data": "..."},
	//	      "priority": 100
	//	    }
	//	  }
	//	}
	//
	// Example - delayed execution (send email in 1 hour):
	//
	//	{
	//	  "message": {
	//	    "metadata": {
	//	      "payload": {"data": "..."},
	//	      "scheduled_time": "2024-12-01T15:00:00Z"
	//	    }
	//	  }
	//	}
	//
	// Returns: Message with assigned message_id
	// Errors:
	//   - NotFound: Queue doesn't exist
	//   - InvalidArgument: Schema validation failed, invalid scheduled_time
	//   - AlreadyExists: Duplicate idempotency_key (within dedup window)
	PostMessage(ctx context.Context, in *PostMessageRequest, opts ...grpc.CallOption) (*PostMessageResponse, error)
	// GetNextMessage retrieves the next available message for processing.
	//
	// This is the primary worker API. Call in a loop to continuously process messages.
	//
	// Behavior:
	// - Returns highest priority PENDING message
	// - Message moves to RUNNING state
	// - Lease timer starts (worker has lease_duration to process)
	// - If lease expires without ACK → message returns to PENDING for retry
	//
	// Concurrency:
	// - Multiple workers can call simultaneously
	// - Each worker gets a different message (no duplicates)
	// - Use exclusivity_key for single-threaded processing of related messages
	//
	// Example worker loop:
	//
	//	for {
	//	    resp := client.GetNextMessage(ctx, &GetNextMessageRequest{
	//	        QueueName: "order-processing",
	//	        LeaseDuration: durationpb.New(5 * time.Minute),
	//	    })
	//	    if resp.Message == nil {
	//	        time.Sleep(1 * time.Second)  // No messages available
	//	        continue
	//	    }
	//
	//	    err := processMessage(resp.Message)
	//	    if err != nil {
	//	        // Let lease expire → automatic retry
	//	        continue
	//	    }
	//
	//	    client.AcknowledgeMessage(ctx, &AcknowledgeMessageRequest{
	//	        QueueName: "order-processing",
	//	        MessageId: resp.Message.MessageId,
	//	    })
	//	}
	//
	// Returns: Message (or empty if no messages available)
	// Errors:
	//   - NotFound: Queue doesn't exist
	GetNextMessage(ctx context.Context, in *GetNextMessageRequest, opts ...grpc.CallOption) (*GetNextMessageResponse, error)
	// AcknowledgeMessage marks a message as successfully processed.
	//
	// Call this after successfully processing a message retrieved by GetNextMessage.
	//
	// Effects:
	// - Message moves to COMPLETED state
	// - Message removed from queue
	// - Queue stats updated
	//
	// Important: You must ACK within the lease_duration, or the message returns
	// to PENDING and may be delivered to another worker.
	//
	// Example:
	//
	//	POST /v1/queues/order-processing/messages/msg-123:acknowledge
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Message doesn't exist or already acknowledged
	//   - DeadlineExceeded: Lease already expired
	AcknowledgeMessage(ctx context.Context, in *AcknowledgeMessageRequest, opts ...grpc.CallOption) (*AcknowledgeMessageResponse, error)
	// RenewMessageLease extends the processing time for a message.
	//
	// Use when:
	// - Processing takes longer than expected
	// - Long-running batch operations
	// - External API calls with unpredictable latency
	//
	// Call periodically during processing to prevent lease expiration.
	//
	// Example pattern (heartbeat-style lease renewal):
	//
	//	msg := getNextMessage()
	//	done := make(chan bool)
	//
	//	go func() {
	//	    ticker := time.NewTicker(leaseDuration / 2)
	//	    defer ticker.Stop()
	//	    for {
	//	        select {
	//	        case <-ticker.C:
	//	            renewMessageLease(msg.MessageId)
	//	        case <-done:
	//	            return
	//	        }
	//	    }
	//	}()
	//
	//	processMessage(msg)
	//	close(done)
	//	acknowledgeMessage(msg.MessageId)
	//
	// Returns: Updated message with new lease expiration
	// Errors:
	//   - NotFound: Message doesn't exist or already completed
	//   - FailedPrecondition: Message not in RUNNING state
	RenewMessageLease(ctx context.Context, in *RenewMessageLeaseRequest, opts ...grpc.CallOption) (*RenewMessageLeaseResponse, error)
	// PeekQueueMessages views messages without leasing them.
	//
	// Use for:
	// - Debugging (inspect message payloads)
	// - Monitoring (see what's pending)
	// - Admin dashboards
	//
	// Does NOT:
	// - Change message state
	// - Create leases
	// - Affect message ordering
	//
	// Example:
	//
	//	GET /v1/queues/order-processing/messages:peek?count=10
	//
	// Returns: List of messages (up to requested count)
	PeekQueueMessages(ctx context.Context, in *PeekQueueMessagesRequest, opts ...grpc.CallOption) (*PeekQueueMessagesResponse, error)
	// SendMessageHeartBeat indicates a worker is still processing a message.
	//
	// Alternative to RenewMessageLease with similar purpose but lighter weight.
	// Useful for tracking worker health without extending lease.
	//
	// Example:
	//
	//	POST /v1/queues/order-processing/messages:heartbeat
	//	{
	//	  "message_ids": ["msg-123", "msg-456"]
	//	}
	//
	// Returns: Empty response
	SendMessageHeartBeat(ctx context.Context, in *SendMessageHeartBeatRequest, opts ...grpc.CallOption) (*SendMessageHeartBeatResponse, error)
	// CreateSchedule creates a recurring message posting schedule.
	//
	// Use for:
	// - Cron-style job scheduling (daily reports, hourly cleanup)
	// - Business calendar scheduling (first business day of month)
	// - Recurring notifications (reminders, alerts)
	// - Periodic batch processing
	//
	// Supports:
	// - Simple cron expressions: "0 9 * * 1-5" (weekdays at 9 AM)
	// - Complex calendar rules: "last Friday of each quarter"
	// - Timezone-aware scheduling
	// - Holiday handling
	//
	// Example - daily report at 8 AM EST:
	//
	//	POST /v1/schedules
	//	{
	//	  "schedule": {
	//	    "schedule_id": "daily-sales-report",
	//	    "metadata": {
	//	      "cron_schedule": "0 8 * * *",
	//	      "timezone": "America/New_York",
	//	      "queue_name": "reports",
	//	      "payload": {...}
	//	    }
	//	  }
	//	}
	//
	// Returns: Created schedule with next_run time
	// Errors:
	//   - AlreadyExists: schedule_id already in use
	//   - InvalidArgument: Invalid cron expression or calendar rule
	CreateSchedule(ctx context.Context, in *CreateScheduleRequest, opts ...grpc.CallOption) (*CreateScheduleResponse, error)
	// DeleteSchedule permanently removes a schedule.
	//
	// Effects:
	// - Schedule stops creating new messages
	// - Existing messages already posted remain in queue
	// - Schedule history is preserved
	//
	// Example:
	//
	//	DELETE /v1/schedules/daily-sales-report
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Schedule doesn't exist
	DeleteSchedule(ctx context.Context, in *DeleteScheduleRequest, opts ...grpc.CallOption) (*DeleteScheduleResponse, error)
	// GetSchedule retrieves schedule details and current state.
	//
	// Returns:
	// - Schedule configuration
	// - Current state (SCHEDULED, PAUSED, CANCELED, ERRORED)
	// - Next execution time
	// - Last execution time
	// - Execution count
	//
	// Example:
	//
	//	GET /v1/schedules/daily-sales-report
	//
	// Returns: Schedule object
	// Errors:
	//   - NotFound: Schedule doesn't exist
	GetSchedule(ctx context.Context, in *GetScheduleRequest, opts ...grpc.CallOption) (*GetScheduleResponse, error)
	// ListSchedules returns all schedules.
	//
	// Use for:
	// - Admin dashboards
	// - Monitoring active schedules
	// - Discovering schedules
	//
	// Example:
	//
	//	GET /v1/schedules
	//
	// Returns: List of Schedule objects
	ListSchedules(ctx context.Context, in *ListSchedulesRequest, opts ...grpc.CallOption) (*ListSchedulesResponse, error)
	// GetScheduleHistory returns execution history for a schedule.
	//
	// Shows:
	// - Past executions with timestamps
	// - Messages created by each execution
	// - Success/failure status
	//
	// Use for:
	// - Debugging missed executions
	// - Auditing schedule activity
	// - Verifying schedule correctness
	//
	// Example:
	//
	//	GET /v1/schedules/daily-sales-report/history
	//
	// Returns: ScheduleHistory with execution records
	GetScheduleHistory(ctx context.Context, in *GetScheduleHistoryRequest, opts ...grpc.CallOption) (*GetScheduleHistoryResponse, error)
	// PauseSchedule temporarily stops a schedule from creating messages.
	//
	// Use when:
	// - Temporarily disabling a feature
	// - During maintenance windows
	// - Debugging issues
	//
	// Effects:
	// - Schedule state → PAUSED
	// - No new messages created
	// - Can be resumed later with ResumeSchedule
	//
	// Example:
	//
	//	POST /v1/schedules/daily-sales-report:pause
	//
	// Returns: Updated schedule
	// Errors:
	//   - NotFound: Schedule doesn't exist
	PauseSchedule(ctx context.Context, in *PauseScheduleRequest, opts ...grpc.CallOption) (*PauseScheduleResponse, error)
	// ResumeSchedule reactivates a paused schedule.
	//
	// Effects:
	// - Schedule state → SCHEDULED
	// - Resumes creating messages on next scheduled time
	// - Does NOT backfill missed executions during pause
	//
	// Example:
	//
	//	POST /v1/schedules/daily-sales-report:resume
	//
	// Returns: Updated schedule with next_run
	// Errors:
	//   - NotFound: Schedule doesn't exist
	//   - FailedPrecondition: Schedule not in PAUSED state
	ResumeSchedule(ctx context.Context, in *ResumeScheduleRequest, opts ...grpc.CallOption) (*ResumeScheduleResponse, error)
	// GetDLQMessages retrieves messages from a dead letter queue.
	//
	// Dead letter queues contain:
	// - Messages that exhausted retry attempts
	// - Messages that caused persistent errors
	// - Messages rejected by workers
	//
	// Use for:
	// - Investigating failures
	// - Manual reprocessing after fixing bugs
	// - Identifying systematic issues
	//
	// Example:
	//
	//	GET /v1/dlq/order-dlq/messages?limit=50
	//
	// Returns: List of failed messages with error details
	GetDLQMessages(ctx context.Context, in *GetDLQMessagesRequest, opts ...grpc.CallOption) (*GetDLQMessagesResponse, error)
	// RequeueFromDLQ moves a message from DLQ back to its original queue.
	//
	// Use after:
	// - Fixing bugs that caused failures
	// - Resolving external service outages
	// - Correcting data issues
	//
	// Effects:
	// - Message removed from DLQ
	// - Message added back to original queue as PENDING
	// - attempts_left reset (or set to specified value)
	//
	// Example:
	//
	//	POST /v1/dlq/order-dlq/messages/msg-123:requeue
	//	{
	//	  "max_attempts": 3  // Give it 3 more tries
	//	}
	//
	// Returns: Requeued message
	// Errors:
	//   - NotFound: Message not in DLQ
	RequeueFromDLQ(ctx context.Context, in *RequeueFromDLQRequest, opts ...grpc.CallOption) (*RequeueFromDLQResponse, error)
	// DeleteFromDLQ permanently removes a message from the DLQ.
	//
	// Use when:
	// - Message is not recoverable
	// - Data is no longer relevant
	// - Cleaning up test data
	//
	// WARNING: This is permanent. Message cannot be recovered.
	//
	// Example:
	//
	//	DELETE /v1/dlq/order-dlq/messages/msg-123
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Message not in DLQ
	DeleteFromDLQ(ctx context.Context, in *DeleteFromDLQRequest, opts ...grpc.CallOption) (*DeleteFromDLQResponse, error)
	// PurgeDLQ removes all messages from a dead letter queue.
	//
	// Use when:
	// - Cleaning up after incident
	// - Clearing test data
	// - DLQ too large to manage individually
	//
	// WARNING: This is irreversible. All DLQ messages are permanently deleted.
	//
	// Example:
	//
	//	POST /v1/dlq/order-dlq:purge
	//
	// Returns: Count of deleted messages
	PurgeDLQ(ctx context.Context, in *PurgeDLQRequest, opts ...grpc.CallOption) (*PurgeDLQResponse, error)
	// GetDLQStats returns statistics about a dead letter queue.
	//
	// Provides:
	// - Message count
	// - Age of oldest message
	// - Common error types
	// - Failure rate trends
	//
	// Use for:
	// - Monitoring DLQ health
	// - Alerting on DLQ growth
	// - Identifying systemic issues
	//
	// Example:
	//
	//	GET /v1/dlq/order-dlq/stats
	//
	// Returns: DLQ statistics
	GetDLQStats(ctx context.Context, in *GetDLQStatsRequest, opts ...grpc.CallOption) (*GetDLQStatsResponse, error)
	// ValidateCalendarSchedule checks if a calendar schedule is valid.
	//
	// Validates:
	// - Cron expression syntax
	// - Calendar rule correctness
	// - Timezone validity
	// - Holiday rule logic
	//
	// Use before CreateSchedule to catch configuration errors.
	//
	// Example:
	//
	//	POST /v1/calendar-schedules:validate
	//	{
	//	  "calendar_schedule": {...}
	//	}
	//
	// Returns: Validation result with errors if invalid
	ValidateCalendarSchedule(ctx context.Context, in *ValidateCalendarScheduleRequest, opts ...grpc.CallOption) (*ValidateCalendarScheduleResponse, error)
	// PreviewCalendarSchedule shows next N execution times for a schedule.
	//
	// Use to:
	// - Verify schedule behaves as expected
	// - Test complex calendar rules
	// - Confirm timezone handling
	// - Preview holiday exceptions
	//
	// Example:
	//
	//	POST /v1/calendar-schedules:preview
	//	{
	//	  "calendar_schedule": {...},
	//	  "count": 10  // Next 10 executions
	//	}
	//
	//	Response:
	//	{
	//	  "next_runs": [
	//	    "2024-01-02T09:00:00Z",
	//	    "2024-01-03T09:00:00Z",
	//	    "2024-01-04T09:00:00Z",
	//	    ...
	//	  ]
	//	}
	//
	// Returns: List of upcoming execution timestamps
	PreviewCalendarSchedule(ctx context.Context, in *PreviewCalendarScheduleRequest, opts ...grpc.CallOption) (*PreviewCalendarScheduleResponse, error)
	// RegisterSchema creates or updates a message validation schema.
	//
	// Use for:
	// - Enforcing message structure
	// - API contract validation
	// - Data quality checks
	// - Type safety
	//
	// Schema versioning:
	// - Each schema has a schema_id and version number
	// - Multiple versions can coexist
	// - Queues reference schema_id (use highest active version)
	//
	// Example:
	//
	//	POST /v1/schemas
	//	{
	//	  "schema": {
	//	    "schema_id": "order-schema",
	//	    "version": 2,
	//	    "content": "{...JSON Schema...}",
	//	    "content_type": "json-schema"
	//	  }
	//	}
	//
	// Returns: Registered schema
	// Errors:
	//   - AlreadyExists: schema_id + version already exists
	//   - InvalidArgument: Invalid schema syntax
	RegisterSchema(ctx context.Context, in *RegisterSchemaRequest, opts ...grpc.CallOption) (*RegisterSchemaResponse, error)
	// GetSchema retrieves a specific schema version.
	//
	// Example:
	//
	//	GET /v1/schemas/order-schema/versions/2
	//
	// Returns: Schema details
	// Errors:
	//   - NotFound: Schema not found
	GetSchema(ctx context.Context, in *GetSchemaRequest, opts ...grpc.CallOption) (*GetSchemaResponse, error)
	// ListSchemas returns all registered schemas.
	//
	// Use for:
	// - Schema discovery
	// - Admin dashboards
	// - Schema management
	//
	// Example:
	//
	//	GET /v1/schemas
	//
	// Returns: List of schemas (all versions)
	ListSchemas(ctx context.Context, in *ListSchemasRequest, opts ...grpc.CallOption) (*ListSchemasResponse, error)
	// DeleteSchema removes a schema version.
	//
	// Effects:
	// - Schema version deleted
	// - Queues using this schema will fail validation
	//
	// Best practice: Mark schema as inactive (is_active = false) instead
	// of deleting to preserve validation history.
	//
	// Example:
	//
	//	DELETE /v1/schemas/order-schema/versions/1
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Schema not found
	//   - FailedPrecondition: Schema in use by active queues
	DeleteSchema(ctx context.Context, in *DeleteSchemaRequest, opts ...grpc.CallOption) (*DeleteSchemaResponse, error)
	// ValidatePayload validates a payload against a schema without posting a message.
	//
	// Use for:
	// - Pre-flight validation
	// - Testing schema changes
	// - Client-side validation
	// - Development/debugging
	//
	// Example:
	//
	//	POST /v1/schemas/order-schema/versions/2:validate
	//	{
	//	  "payload": {
	//	    "data": "{\"orderId\": \"ORD-123\", ...}"
	//	  }
	//	}
	//
	// Returns: ValidationResult (valid=true or list of errors)
	ValidatePayload(ctx context.Context, in *ValidatePayloadRequest, opts ...grpc.CallOption) (*ValidatePayloadResponse, error)
}

type QueueServiceServer interface {
	// CreateQueue creates a new queue with specified configuration.
	//
	// Use to:
	// - Define retry behavior (max_attempts, lease_duration)
	// - Set up dead letter queue for failed messages
	// - Configure priority handling
	// - Enforce message schemas
	//
	// Example:
	//
	//	POST /v1/queues
	//	{
	//	  "queue": {
	//	    "name": "order-processing",
	//	    "metadata": {
	//	      "default_max_attempts": 3,
	//	      "lease_duration": "5m",
	//	      "dead_letter_queue_name": "order-dlq",
	//	      "auto_create_dlq": true
	//	    }
	//	  }
	//	}
	//
	// Returns: Queue details
	// Errors:
	//   - AlreadyExists: Queue with this name exists
	//   - InvalidArgument: Invalid configuration (negative lease_duration, etc.)
	CreateQueue(context.Context, *CreateQueueRequest) (*CreateQueueResponse, error)
	// DeleteQueue permanently deletes a queue and all its messages.
	//
	// WARNING: This operation is irreversible. All pending and running messages are lost.
	//
	// Use when:
	// - Decommissioning a feature
	// - Cleaning up test queues
	// - Removing unused queues
	//
	// Best practice: Drain queue first (stop posting, wait for workers to finish).
	//
	// Example:
	//
	//	DELETE /v1/queues/order-processing
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Queue doesn't exist
	DeleteQueue(context.Context, *DeleteQueueRequest) (*DeleteQueueResponse, error)
	// ListQueues returns all queues in your ChronoQueue instance.
	//
	// Use for:
	// - Monitoring dashboards
	// - Queue discovery
	// - Debugging
	//
	// Example:
	//
	//	GET /v1/queues
	//
	// Returns: List of Queue objects with metadata
	ListQueues(context.Context, *ListQueuesRequest) (*ListQueuesResponse, error)
	// GetQueueState returns current queue statistics and health.
	//
	// Provides:
	// - Message counts by state (PENDING, RUNNING, COMPLETED, ERRORED)
	// - Rate metrics (messages/sec, processing time)
	// - DLQ size
	//
	// Use for:
	// - Health checks
	// - Autoscaling decisions (scale workers based on PENDING count)
	// - Alerting (high ERRORED count, DLQ growth)
	//
	// Example:
	//
	//	GET /v1/queues/order-processing/state
	//	Response:
	//	{
	//	  "pending_count": 150,
	//	  "running_count": 10,
	//	  "completed_count": 5420,
	//	  "errored_count": 3,
	//	  "dlq_count": 2
	//	}
	//
	// Returns: QueueState with counts and metrics
	GetQueueState(context.Context, *GetQueueStateRequest) (*GetQueueStateResponse, error)
	// PostMessage adds a new message to a queue.
	//
	// Use for:
	// - Asynchronous task execution
	// - Event-driven workflows
	// - Job scheduling
	// - Load leveling
	//
	// Features:
	// - Delayed execution (scheduled_time)
	// - Priority ordering
	// - Schema validation
	// - Deduplication (idempotency_key)
	// - Exclusive processing (exclusivity_key)
	//
	// Example - immediate execution:
	//
	//	POST /v1/queues/order-processing/messages
	//	{
	//	  "message": {
	//	    "metadata": {
	//	      "payload": {"data": "..."},
	//	      "priority": 100
	//	    }
	//	  }
	//	}
	//
	// Example - delayed execution (send email in 1 hour):
	//
	//	{
	//	  "message": {
	//	    "metadata": {
	//	      "payload": {"data": "..."},
	//	      "scheduled_time": "2024-12-01T15:00:00Z"
	//	    }
	//	  }
	//	}
	//
	// Returns: Message with assigned message_id
	// Errors:
	//   - NotFound: Queue doesn't exist
	//   - InvalidArgument: Schema validation failed, invalid scheduled_time
	//   - AlreadyExists: Duplicate idempotency_key (within dedup window)
	PostMessage(context.Context, *PostMessageRequest) (*PostMessageResponse, error)
	// GetNextMessage retrieves the next available message for processing.
	//
	// This is the primary worker API. Call in a loop to continuously process messages.
	//
	// Behavior:
	// - Returns highest priority PENDING message
	// - Message moves to RUNNING state
	// - Lease timer starts (worker has lease_duration to process)
	// - If lease expires without ACK → message returns to PENDING for retry
	//
	// Concurrency:
	// - Multiple workers can call simultaneously
	// - Each worker gets a different message (no duplicates)
	// - Use exclusivity_key for single-threaded processing of related messages
	//
	// Example worker loop:
	//
	//	for {
	//	    resp := client.GetNextMessage(ctx, &GetNextMessageRequest{
	//	        QueueName: "order-processing",
	//	        LeaseDuration: durationpb.New(5 * time.Minute),
	//	    })
	//	    if resp.Message == nil {
	//	        time.Sleep(1 * time.Second)  // No messages available
	//	        continue
	//	    }
	//
	//	    err := processMessage(resp.Message)
	//	    if err != nil {
	//	        // Let lease expire → automatic retry
	//	        continue
	//	    }
	//
	//	    client.AcknowledgeMessage(ctx, &AcknowledgeMessageRequest{
	//	        QueueName: "order-processing",
	//	        MessageId: resp.Message.MessageId,
	//	    })
	//	}
	//
	// Returns: Message (or empty if no messages available)
	// Errors:
	//   - NotFound: Queue doesn't exist
	GetNextMessage(context.Context, *GetNextMessageRequest) (*GetNextMessageResponse, error)
	// AcknowledgeMessage marks a message as successfully processed.
	//
	// Call this after successfully processing a message retrieved by GetNextMessage.
	//
	// Effects:
	// - Message moves to COMPLETED state
	// - Message removed from queue
	// - Queue stats updated
	//
	// Important: You must ACK within the lease_duration, or the message returns
	// to PENDING and may be delivered to another worker.
	//
	// Example:
	//
	//	POST /v1/queues/order-processing/messages/msg-123:acknowledge
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Message doesn't exist or already acknowledged
	//   - DeadlineExceeded: Lease already expired
	AcknowledgeMessage(context.Context, *AcknowledgeMessageRequest) (*AcknowledgeMessageResponse, error)
	// RenewMessageLease extends the processing time for a message.
	//
	// Use when:
	// - Processing takes longer than expected
	// - Long-running batch operations
	// - External API calls with unpredictable latency
	//
	// Call periodically during processing to prevent lease expiration.
	//
	// Example pattern (heartbeat-style lease renewal):
	//
	//	msg := getNextMessage()
	//	done := make(chan bool)
	//
	//	go func() {
	//	    ticker := time.NewTicker(leaseDuration / 2)
	//	    defer ticker.Stop()
	//	    for {
	//	        select {
	//	        case <-ticker.C:
	//	            renewMessageLease(msg.MessageId)
	//	        case <-done:
	//	            return
	//	        }
	//	    }
	//	}()
	//
	//	processMessage(msg)
	//	close(done)
	//	acknowledgeMessage(msg.MessageId)
	//
	// Returns: Updated message with new lease expiration
	// Errors:
	//   - NotFound: Message doesn't exist or already completed
	//   - FailedPrecondition: Message not in RUNNING state
	RenewMessageLease(context.Context, *RenewMessageLeaseRequest) (*RenewMessageLeaseResponse, error)
	// PeekQueueMessages views messages without leasing them.
	//
	// Use for:
	// - Debugging (inspect message payloads)
	// - Monitoring (see what's pending)
	// - Admin dashboards
	//
	// Does NOT:
	// - Change message state
	// - Create leases
	// - Affect message ordering
	//
	// Example:
	//
	//	GET /v1/queues/order-processing/messages:peek?count=10
	//
	// Returns: List of messages (up to requested count)
	PeekQueueMessages(context.Context, *PeekQueueMessagesRequest) (*PeekQueueMessagesResponse, error)
	// SendMessageHeartBeat indicates a worker is still processing a message.
	//
	// Alternative to RenewMessageLease with similar purpose but lighter weight.
	// Useful for tracking worker health without extending lease.
	//
	// Example:
	//
	//	POST /v1/queues/order-processing/messages:heartbeat
	//	{
	//	  "message_ids": ["msg-123", "msg-456"]
	//	}
	//
	// Returns: Empty response
	SendMessageHeartBeat(context.Context, *SendMessageHeartBeatRequest) (*SendMessageHeartBeatResponse, error)
	// CreateSchedule creates a recurring message posting schedule.
	//
	// Use for:
	// - Cron-style job scheduling (daily reports, hourly cleanup)
	// - Business calendar scheduling (first business day of month)
	// - Recurring notifications (reminders, alerts)
	// - Periodic batch processing
	//
	// Supports:
	// - Simple cron expressions: "0 9 * * 1-5" (weekdays at 9 AM)
	// - Complex calendar rules: "last Friday of each quarter"
	// - Timezone-aware scheduling
	// - Holiday handling
	//
	// Example - daily report at 8 AM EST:
	//
	//	POST /v1/schedules
	//	{
	//	  "schedule": {
	//	    "schedule_id": "daily-sales-report",
	//	    "metadata": {
	//	      "cron_schedule": "0 8 * * *",
	//	      "timezone": "America/New_York",
	//	      "queue_name": "reports",
	//	      "payload": {...}
	//	    }
	//	  }
	//	}
	//
	// Returns: Created schedule with next_run time
	// Errors:
	//   - AlreadyExists: schedule_id already in use
	//   - InvalidArgument: Invalid cron expression or calendar rule
	CreateSchedule(context.Context, *CreateScheduleRequest) (*CreateScheduleResponse, error)
	// DeleteSchedule permanently removes a schedule.
	//
	// Effects:
	// - Schedule stops creating new messages
	// - Existing messages already posted remain in queue
	// - Schedule history is preserved
	//
	// Example:
	//
	//	DELETE /v1/schedules/daily-sales-report
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Schedule doesn't exist
	DeleteSchedule(context.Context, *DeleteScheduleRequest) (*DeleteScheduleResponse, error)
	// GetSchedule retrieves schedule details and current state.
	//
	// Returns:
	// - Schedule configuration
	// - Current state (SCHEDULED, PAUSED, CANCELED, ERRORED)
	// - Next execution time
	// - Last execution time
	// - Execution count
	//
	// Example:
	//
	//	GET /v1/schedules/daily-sales-report
	//
	// Returns: Schedule object
	// Errors:
	//   - NotFound: Schedule doesn't exist
	GetSchedule(context.Context, *GetScheduleRequest) (*GetScheduleResponse, error)
	// ListSchedules returns all schedules.
	//
	// Use for:
	// - Admin dashboards
	// - Monitoring active schedules
	// - Discovering schedules
	//
	// Example:
	//
	//	GET /v1/schedules
	//
	// Returns: List of Schedule objects
	ListSchedules(context.Context, *ListSchedulesRequest) (*ListSchedulesResponse, error)
	// GetScheduleHistory returns execution history for a schedule.
	//
	// Shows:
	// - Past executions with timestamps
	// - Messages created by each execution
	// - Success/failure status
	//
	// Use for:
	// - Debugging missed executions
	// - Auditing schedule activity
	// - Verifying schedule correctness
	//
	// Example:
	//
	//	GET /v1/schedules/daily-sales-report/history
	//
	// Returns: ScheduleHistory with execution records
	GetScheduleHistory(context.Context, *GetScheduleHistoryRequest) (*GetScheduleHistoryResponse, error)
	// PauseSchedule temporarily stops a schedule from creating messages.
	//
	// Use when:
	// - Temporarily disabling a feature
	// - During maintenance windows
	// - Debugging issues
	//
	// Effects:
	// - Schedule state → PAUSED
	// - No new messages created
	// - Can be resumed later with ResumeSchedule
	//
	// Example:
	//
	//	POST /v1/schedules/daily-sales-report:pause
	//
	// Returns: Updated schedule
	// Errors:
	//   - NotFound: Schedule doesn't exist
	PauseSchedule(context.Context, *PauseScheduleRequest) (*PauseScheduleResponse, error)
	// ResumeSchedule reactivates a paused schedule.
	//
	// Effects:
	// - Schedule state → SCHEDULED
	// - Resumes creating messages on next scheduled time
	// - Does NOT backfill missed executions during pause
	//
	// Example:
	//
	//	POST /v1/schedules/daily-sales-report:resume
	//
	// Returns: Updated schedule with next_run
	// Errors:
	//   - NotFound: Schedule doesn't exist
	//   - FailedPrecondition: Schedule not in PAUSED state
	ResumeSchedule(context.Context, *ResumeScheduleRequest) (*ResumeScheduleResponse, error)
	// GetDLQMessages retrieves messages from a dead letter queue.
	//
	// Dead letter queues contain:
	// - Messages that exhausted retry attempts
	// - Messages that caused persistent errors
	// - Messages rejected by workers
	//
	// Use for:
	// - Investigating failures
	// - Manual reprocessing after fixing bugs
	// - Identifying systematic issues
	//
	// Example:
	//
	//	GET /v1/dlq/order-dlq/messages?limit=50
	//
	// Returns: List of failed messages with error details
	GetDLQMessages(context.Context, *GetDLQMessagesRequest) (*GetDLQMessagesResponse, error)
	// RequeueFromDLQ moves a message from DLQ back to its original queue.
	//
	// Use after:
	// - Fixing bugs that caused failures
	// - Resolving external service outages
	// - Correcting data issues
	//
	// Effects:
	// - Message removed from DLQ
	// - Message added back to original queue as PENDING
	// - attempts_left reset (or set to specified value)
	//
	// Example:
	//
	//	POST /v1/dlq/order-dlq/messages/msg-123:requeue
	//	{
	//	  "max_attempts": 3  // Give it 3 more tries
	//	}
	//
	// Returns: Requeued message
	// Errors:
	//   - NotFound: Message not in DLQ
	RequeueFromDLQ(context.Context, *RequeueFromDLQRequest) (*RequeueFromDLQResponse, error)
	// DeleteFromDLQ permanently removes a message from the DLQ.
	//
	// Use when:
	// - Message is not recoverable
	// - Data is no longer relevant
	// - Cleaning up test data
	//
	// WARNING: This is permanent. Message cannot be recovered.
	//
	// Example:
	//
	//	DELETE /v1/dlq/order-dlq/messages/msg-123
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Message not in DLQ
	DeleteFromDLQ(context.Context, *DeleteFromDLQRequest) (*DeleteFromDLQResponse, error)
	// PurgeDLQ removes all messages from a dead letter queue.
	//
	// Use when:
	// - Cleaning up after incident
	// - Clearing test data
	// - DLQ too large to manage individually
	//
	// WARNING: This is irreversible. All DLQ messages are permanently deleted.
	//
	// Example:
	//
	//	POST /v1/dlq/order-dlq:purge
	//
	// Returns: Count of deleted messages
	PurgeDLQ(context.Context, *PurgeDLQRequest) (*PurgeDLQResponse, error)
	// GetDLQStats returns statistics about a dead letter queue.
	//
	// Provides:
	// - Message count
	// - Age of oldest message
	// - Common error types
	// - Failure rate trends
	//
	// Use for:
	// - Monitoring DLQ health
	// - Alerting on DLQ growth
	// - Identifying systemic issues
	//
	// Example:
	//
	//	GET /v1/dlq/order-dlq/stats
	//
	// Returns: DLQ statistics
	GetDLQStats(context.Context, *GetDLQStatsRequest) (*GetDLQStatsResponse, error)
	// ValidateCalendarSchedule checks if a calendar schedule is valid.
	//
	// Validates:
	// - Cron expression syntax
	// - Calendar rule correctness
	// - Timezone validity
	// - Holiday rule logic
	//
	// Use before CreateSchedule to catch configuration errors.
	//
	// Example:
	//
	//	POST /v1/calendar-schedules:validate
	//	{
	//	  "calendar_schedule": {...}
	//	}
	//
	// Returns: Validation result with errors if invalid
	ValidateCalendarSchedule(context.Context, *ValidateCalendarScheduleRequest) (*ValidateCalendarScheduleResponse, error)
	// PreviewCalendarSchedule shows next N execution times for a schedule.
	//
	// Use to:
	// - Verify schedule behaves as expected
	// - Test complex calendar rules
	// - Confirm timezone handling
	// - Preview holiday exceptions
	//
	// Example:
	//
	//	POST /v1/calendar-schedules:preview
	//	{
	//	  "calendar_schedule": {...},
	//	  "count": 10  // Next 10 executions
	//	}
	//
	//	Response:
	//	{
	//	  "next_runs": [
	//	    "2024-01-02T09:00:00Z",
	//	    "2024-01-03T09:00:00Z",
	//	    "2024-01-04T09:00:00Z",
	//	    ...
	//	  ]
	//	}
	//
	// Returns: List of upcoming execution timestamps
	PreviewCalendarSchedule(context.Context, *PreviewCalendarScheduleRequest) (*PreviewCalendarScheduleResponse, error)
	// RegisterSchema creates or updates a message validation schema.
	//
	// Use for:
	// - Enforcing message structure
	// - API contract validation
	// - Data quality checks
	// - Type safety
	//
	// Schema versioning:
	// - Each schema has a schema_id and version number
	// - Multiple versions can coexist
	// - Queues reference schema_id (use highest active version)
	//
	// Example:
	//
	//	POST /v1/schemas
	//	{
	//	  "schema": {
	//	    "schema_id": "order-schema",
	//	    "version": 2,
	//	    "content": "{...JSON Schema...}",
	//	    "content_type": "json-schema"
	//	  }
	//	}
	//
	// Returns: Registered schema
	// Errors:
	//   - AlreadyExists: schema_id + version already exists
	//   - InvalidArgument: Invalid schema syntax
	RegisterSchema(context.Context, *RegisterSchemaRequest) (*RegisterSchemaResponse, error)
	// GetSchema retrieves a specific schema version.
	//
	// Example:
	//
	//	GET /v1/schemas/order-schema/versions/2
	//
	// Returns: Schema details
	// Errors:
	//   - NotFound: Schema not found
	GetSchema(context.Context, *GetSchemaRequest) (*GetSchemaResponse, error)
	// ListSchemas returns all registered schemas.
	//
	// Use for:
	// - Schema discovery
	// - Admin dashboards
	// - Schema management
	//
	// Example:
	//
	//	GET /v1/schemas
	//
	// Returns: List of schemas (all versions)
	ListSchemas(context.Context, *ListSchemasRequest) (*ListSchemasResponse, error)
	// DeleteSchema removes a schema version.
	//
	// Effects:
	// - Schema version deleted
	// - Queues using this schema will fail validation
	//
	// Best practice: Mark schema as inactive (is_active = false) instead
	// of deleting to preserve validation history.
	//
	// Example:
	//
	//	DELETE /v1/schemas/order-schema/versions/1
	//
	// Returns: Empty response
	// Errors:
	//   - NotFound: Schema not found
	//   - FailedPrecondition: Schema in use by active queues
	DeleteSchema(context.Context, *DeleteSchemaRequest) (*DeleteSchemaResponse, error)
	// ValidatePayload validates a payload against a schema without posting a message.
	//
	// Use for:
	// - Pre-flight validation
	// - Testing schema changes
	// - Client-side validation
	// - Development/debugging
	//
	// Example:
	//
	//	POST /v1/schemas/order-schema/versions/2:validate
	//	{
	//	  "payload": {
	//	    "data": "{\"orderId\": \"ORD-123\", ...}"
	//	  }
	//	}
	//
	// Returns: ValidationResult (valid=true or list of errors)
	ValidatePayload(context.Context, *ValidatePayloadRequest) (*ValidatePayloadResponse, error)
}

type RegisterSchemaRequest struct {
	SchemaId    string            `protobuf:"bytes,1,opt,name=schema_id,json=schemaId,proto3" json:"schema_id,omitempty"`          // Unique schema identifier
	Name        string            `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`                                  // Human-readable schema name
	Description string            `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`                    // Schema description
	Content     string            `protobuf:"bytes,4,opt,name=content,proto3" json:"content,omitempty"`                            // JSON Schema content
	ContentType string            `protobuf:"bytes,5,opt,name=content_type,json=contentType,proto3" json:"content_type,omitempty"` // Schema type (default: "json-schema")
	Metadata    map[string]string ``                                                                                               // Additional metadata
	/* 143-byte string literal not displayed */
	// contains filtered or unexported fields
}

type RegisterSchemaResponse struct {
	SchemaId  string `protobuf:"bytes,1,opt,name=schema_id,json=schemaId,proto3" json:"schema_id,omitempty"`     // Schema identifier
	Version   int32  `protobuf:"varint,2,opt,name=version,proto3" json:"version,omitempty"`                      // Assigned schema version
	CreatedAt int64  `protobuf:"varint,3,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"` // Creation timestamp
	// contains filtered or unexported fields
}

type RenewMessageLeaseRequest struct {
	QueueName     string               `protobuf:"bytes,1,opt,name=queue_name,json=queueName,proto3" json:"queue_name,omitempty"`
	MessageId     string               `protobuf:"bytes,2,opt,name=message_id,json=messageId,proto3" json:"message_id,omitempty"`
	LeaseDuration *durationpb.Duration `protobuf:"bytes,3,opt,name=lease_duration,json=leaseDuration,proto3" json:"lease_duration,omitempty"`
	// contains filtered or unexported fields
}

type RenewMessageLeaseResponse struct {
	RemainingTime *durationpb.Duration       `protobuf:"bytes,1,opt,name=remaining_time,json=remainingTime,proto3" json:"remaining_time,omitempty"`
	State         v11.Message_Metadata_State `protobuf:"varint,2,opt,name=state,proto3,enum=chronoqueue.api.message.v1.Message_Metadata_State" json:"state,omitempty"`
	// contains filtered or unexported fields
}

type RequeueFromDLQRequest struct {
	DlqName     string `protobuf:"bytes,1,opt,name=dlq_name,json=dlqName,proto3" json:"dlq_name,omitempty"`
	MessageId   string `protobuf:"bytes,2,opt,name=message_id,json=messageId,proto3" json:"message_id,omitempty"`
	TargetQueue string `protobuf:"bytes,3,opt,name=target_queue,json=targetQueue,proto3" json:"target_queue,omitempty"`
	// contains filtered or unexported fields
}

type RequeueFromDLQResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type ResumeScheduleRequest struct {
	ScheduleId string `protobuf:"bytes,1,opt,name=schedule_id,json=scheduleId,proto3" json:"schedule_id,omitempty"`
	// contains filtered or unexported fields
}

type ResumeScheduleResponse struct {
	Success bool `protobuf:"varint,1,opt,name=success,proto3" json:"success,omitempty"`
	// contains filtered or unexported fields
}

type SchemaInfo struct {
	SchemaId      string `protobuf:"bytes,1,opt,name=schema_id,json=schemaId,proto3" json:"schema_id,omitempty"`
	LatestVersion int32  `protobuf:"varint,2,opt,name=latest_version,json=latestVersion,proto3" json:"latest_version,omitempty"` // Latest version number
	Name          string `protobuf:"bytes,3,opt,name=name,proto3" json:"name,omitempty"`
	Description   string `protobuf:"bytes,4,opt,name=description,proto3" json:"description,omitempty"`
	CreatedAt     int64  `protobuf:"varint,5,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
	UpdatedAt     int64  `protobuf:"varint,6,opt,name=updated_at,json=updatedAt,proto3" json:"updated_at,omitempty"`
	VersionCount  int32  `protobuf:"varint,7,opt,name=version_count,json=versionCount,proto3" json:"version_count,omitempty"` // Total number of versions
	IsActive      bool   `protobuf:"varint,8,opt,name=is_active,json=isActive,proto3" json:"is_active,omitempty"`
	// contains filtered or unexported fields
}

type SendMessageHeartBeatRequest struct {
	QueueName     string `protobuf:"bytes,1,opt,name=queue_name,json=queueName,proto3" json:"queue_name,omitempty"`
	MessageId     string `protobuf:"bytes,2,opt,name=message_id,json=messageId,proto3" json:"message_id,omitempty"`
	StreamEntryId string `protobuf:"bytes,3,opt,name=stream_entry_id,json=streamEntryId,proto3" json:"stream_entry_id,omitempty"`
	// Optional stable identifier to consistently represent the same consumer
	WorkerId *string `protobuf:"bytes,4,opt,name=worker_id,json=workerId,proto3,oneof" json:"worker_id,omitempty"`
	// Attempt identifier to validate heartbeat against current attempt
	AttemptId *string `protobuf:"bytes,5,opt,name=attempt_id,json=attemptId,proto3,oneof" json:"attempt_id,omitempty"`
	// contains filtered or unexported fields
}