syntax = "proto3";

package spearlet;

// Spearlet invocation & execution services.
// Spearlet 调用与执行服务。
//
// This file defines:
// - InvocationService: submit an invocation
// - ExecutionService: query / terminate / list executions
//
// 该文件定义：
// - InvocationService：提交一次调用
// - ExecutionService：查询 / 终止 / 列举执行记录
//
// Terminology / 术语：
// - invocation_id: client-side request correlation id / 客户端侧请求关联 ID
// - execution_id: unique execution record id on the node / 节点侧执行记录 ID
// - function_name: runtime entrypoint selector / runtime 入口选择器

import "google/protobuf/timestamp.proto";

enum ExecutionMode {
  // Unspecified.
  // 未指定。
  EXECUTION_MODE_UNSPECIFIED = 0;

  // Synchronous invocation.
  // 同步调用。
  EXECUTION_MODE_SYNC = 1;

  // Asynchronous invocation.
  // 异步调用。
  EXECUTION_MODE_ASYNC = 2;
}

enum ExecutionStatus {
  // Unspecified.
  // 未指定。
  EXECUTION_STATUS_UNSPECIFIED = 0;

  // Queued and pending.
  // 已入队，等待执行。
  EXECUTION_STATUS_PENDING = 1;

  // Running.
  // 执行中。
  EXECUTION_STATUS_RUNNING = 2;

  // Completed successfully.
  // 成功完成。
  EXECUTION_STATUS_COMPLETED = 3;

  // Failed.
  // 执行失败。
  EXECUTION_STATUS_FAILED = 4;

  // Terminated.
  // 已终止。
  EXECUTION_STATUS_TERMINATED = 5;

  // Timed out.
  // 超时。
  EXECUTION_STATUS_TIMEOUT = 6;
}

message Payload {
  // MIME-like content type.
  // 类 MIME content type。
  string content_type = 1;

  // Raw bytes.
  // 原始字节。
  bytes data = 2;
}

message Error {
  // Machine-readable error code.
  // 机器可读错误码。
  string code = 1;

  // Human-readable error message.
  // 人类可读错误信息。
  string message = 2;
}

message InvokeRequest {
  // Client-provided invocation ID.
  // 客户端提供的 invocation ID。
  string invocation_id = 1;

  // Client-provided execution ID.
  // 客户端提供的 execution ID。
  string execution_id = 2;

  // Target task ID.
  // 目标 task ID。
  string task_id = 3;

  // Entry function name.
  // 入口函数名。
  //
  // Special value "__spear_default_entry__" (or empty) means "let runtime decide".
  // 特殊值 "__spear_default_entry__"（或留空）表示“由 runtime 自行决定入口点”。
  //
  // For WASM/WASI modules, runtime may choose `_start` first, then fallback to `main`.
  // 对于 WASM/WASI 模块，runtime 通常优先选择 `_start`，否则回退到 `main`。
  string function_name = 4;

  Payload input = 5;
  map<string, string> headers = 6;
  map<string, string> environment = 7;

  // Optional request timeout.
  // 可选请求超时。
  uint64 timeout_ms = 8;

  // Optional session identifier.
  // 可选会话标识。
  string session_id = 9;

  // Invocation mode.
  // 调用模式。
  ExecutionMode mode = 10;

  // Force runtime to create a new instance (best-effort).
  // 强制 runtime 创建新实例（best-effort）。
  bool force_new_instance = 11;

  // Extra metadata for routing / debugging.
  // 额外元数据（路由 / 调试用）。
  map<string, string> metadata = 12;
}

message InvokeResponse {
  string invocation_id = 1;
  string execution_id = 2;
  string instance_id = 3;

  ExecutionStatus status = 4;
  Payload output = 5;
  Error error = 6;

  // Execution start time (if available).
  // 执行开始时间（若可用）。
  google.protobuf.Timestamp started_at = 7;

  // Execution completion time (if available).
  // 执行结束时间（若可用）。
  google.protobuf.Timestamp completed_at = 8;
}

service InvocationService {
  // One-shot invocation.
  // 一次性调用。
  rpc Invoke(InvokeRequest) returns (InvokeResponse);
}

message GetExecutionRequest {
  // Target execution ID.
  // 目标 execution ID。
  string execution_id = 1;

  // Whether to include output bytes in the response.
  // 是否在响应中包含输出字节。
  bool include_output = 2;
}

message Execution {
  // Invocation ID.
  // 调用 ID。
  string invocation_id = 1;

  // Execution ID.
  // 执行 ID。
  string execution_id = 2;

  // Task ID.
  // 任务 ID。
  string task_id = 3;

  // Function name.
  // 函数名。
  string function_name = 4;

  // Instance ID.
  // 实例 ID。
  string instance_id = 5;

  // Execution status.
  // 执行状态。
  ExecutionStatus status = 6;

  // Output payload.
  // 输出 payload。
  Payload output = 7;

  // Error details.
  // 错误详情。
  Error error = 8;

  // Start time.
  // 开始时间。
  google.protobuf.Timestamp started_at = 9;

  // Completion time.
  // 结束时间。
  google.protobuf.Timestamp completed_at = 10;
}

message TerminateExecutionRequest {
  // Target execution ID.
  // 目标 execution ID。
  string execution_id = 1;

  // Best-effort termination reason.
  // best-effort 终止原因。
  string reason = 2;
}

message TerminateExecutionResponse {
  // Whether termination request is accepted.
  // 是否接受终止请求。
  bool success = 1;

  // Final status after termination (best-effort).
  // 终止后的最终状态（best-effort）。
  ExecutionStatus final_status = 2;

  // Human readable message.
  // 人类可读信息。
  string message = 3;
}

message ListExecutionsRequest {
  // Optional filter by task_id.
  // 可选按 task_id 过滤。
  string task_id = 1;

  // Optional filter by invocation_id.
  // 可选按 invocation_id 过滤。
  string invocation_id = 2;

  // Maximum number of items.
  // 最大返回条数。
  uint32 limit = 3;

  // Pagination token.
  // 分页 token。
  string page_token = 4;
}

message ListExecutionsResponse {
  // Execution records.
  // 执行记录。
  repeated Execution executions = 1;

  // Pagination token for the next page.
  // 下一页分页 token。
  string next_page_token = 2;
}

service ExecutionService {
  // Get execution record by execution_id.
  // 按 execution_id 获取执行记录。
  rpc GetExecution(GetExecutionRequest) returns (Execution);

  // Terminate an execution.
  // 终止执行。
  rpc TerminateExecution(TerminateExecutionRequest) returns (TerminateExecutionResponse);

  // List executions with optional filters.
  // 列举执行记录（支持可选过滤）。
  rpc ListExecutions(ListExecutionsRequest) returns (ListExecutionsResponse);
}
