Plan: Implement SSS for GRPC

Summary

• Learn about server-side scripting (https://docs.indiscale.com/caosdb-deploy/server_side_scripting.html)
• Create follow-up issues for adding a gRPC API to SSS: caosdb-proto#25 #362

Expected Behavior

gRPC API should support server-side scripting.

Actual Behavior

It does not.

added Statustodo label

changed iteration to Sprint Mar 3, 2025 - Mar 16, 2025

changed the description

assigned to @joschaschmiedt

changed title from Implement SSS for GRPC to Plan: Implement SSS for GRPC

changed milestone to %Internal development: next steps GRPC API

added (D label

set weight to 8

changed the description

An SSS API needs the following:

• specify script name
• positional arguments
• named arguments
• files to be uploaded along with the call to the script

I drafted a gRPC API covering the current state as well as some future ideas (async execution, created files, execution id for bookkeeping) (see also branch f-sss4grpc of caosdb-proto)

syntax = "proto3";

package caosdb.scripting.v1alpha1;

option java_multiple_files = true;
option java_package = "org.caosdb.api.scripting.v1alpha1";

message NamedArgument {
  // The name of the argument
  string name = 1;
  // The value of the argument
  string value = 2;
}

message ExecuteScriptRequest {
  // The script to execute
  string script_filename = 1;
  // The timeout for the script execution in milliseconds
  int64 timeout_ms = 2;
  // The positional arguments for the script
  repeated string positional_arguments = 3;
  // The named arguments for the script
  repeated NamedArgument named_arguments = 4;
  // The files to be used by the script (will be uploaded to the server)
  repeated string script_files = 5;
  // IDEA: Whether the script should be executed asynchronously
  bool run_async = 6;
}

enum ScriptExecutionResult {
  // The result of the script execution is unspecified
  SCRIPT_EXECUTION_RESULT_UNSPECIFIED = 0;
  // The script execution was successful
  SCRIPT_EXECUTION_RESULT_SUCCESS = 1;
  // The script execution failed (general/unspecified failure)
  SCRIPT_EXECUTION_RESULT_GENERAL_FAILURE = 2;
  // The script does not exist
  SCRIPT_EXECUTION_RESULT_SCRIPT_DOES_NOT_EXIST = 3;
  // The script is not executable
  SCRIPT_EXECUTION_RESULT_SCRIPT_NOT_EXECUTABLE = 4;
  // The script execution failed due to a script error
  SCRIPT_EXECUTION_RESULT_SCRIPT_ERROR = 5;
  // The script execution failed during setup, e.g. due to configuration errors
  SCRIPT_EXECUTION_RESULT_SCRIPT_SETUP_ERROR = 6;
  // The script execution timed out
  SCRIPT_EXECUTION_RESULT_SCRIPT_TIMEOUT = 7;
  // The script execution was cancelled for another reason
  SCRIPT_EXECUTION_RESULT_CANCELLED = 8;
  // The script execution was denied due to insufficient permissions
  SCRIPT_EXECUTION_RESULT_PERMISSION_DENIED = 9;
  // The script is running and the result is not yet available (only for async scripts)
  SCRIPT_EXECUTION_RESULT_RUNNING = 10;
}

// IDEA: Give the script execution an id to be able to track it
message ScriptExecutionId {
  // Id of the script execution
  string script_execution_id = 1;
}

message ExecuteScriptResponse {
  // Id of the script execution
  ScriptExecutionId script_execution_id = 1;
  // The script to execute
  string script_filename = 2;
  // The result of the script execution
  ScriptExecutionResult result = 3;
  // Script return code
  int32 return_code = 4;
  // The standard output of the script
  string stdout = 5;
  // The standard error of the script
  string stderr = 6;
  // IDEA: The user who executed the script
  string executing_user = 7;
  // IDEA: The date and time when the script was started
  string execution_start_datetime = 8;
  // IDEA: The date and time when the script was finished
  string execution_end_datetime = 9;
  // IDEA: The duration of the script execution
  string execution_duration = 10;
  // IDEA: Return a list of files created by the script. These files will be available for download.
  //       The files will be deleted after a certain time? How should the server know about
  //       about these?
  repeated string created_files = 11;
}

service ServerSideScriptingService {
  // Executes a script on the server side
  rpc ExecuteScript(ExecuteScriptRequest) returns (ExecuteScriptResponse) {}
  // IDEA: Get the status of a script execution
  rpc GetScriptExecutionStatus(ScriptExecutionId) returns (ExecuteScriptResponse) {}
  // IDEA: Delete temp files (only for admins?)
  //   rpc DeleteTempFiles(DeleteTempFilesRequest) returns (DeleteTempFilesResponse) {}
  // IDEA: Wait for a script execution to finish
  //   rpc WaitForScriptExecution(ScriptExecutionId, TimeoutDuration) returns (ExecuteScriptResponse) {}
}

Covering the current functionality should be relatively straightforward with the exception of the files that are uploaded along with the request. Uploading files via gRPC still has limitations (see also #354) and may be changed substantially.

mentioned in issue caosdb-proto#25

marked this issue as related to #362

marked the checklist item Learn about server-side scripting (https://docs.indiscale.com/caosdb-deploy/server_side_scripting.html) as completed

marked the checklist item Create follow-up issues for adding a gRPC API to SSS as completed

changed the description

added Statusdoing label and removed Statustodo label

assigned to @salexan