service.proto

syntax = "proto3";
package jobruntime;




// More information about cgroup controllers: https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html#controllers
message JobResourceLimits {
    // memory usage throttle limit.
    uint64 memory_high = 1;
    // memory usage hard limit. if the cgroup reaches this limit, the system OOM killer is invoked on the cgroup
    uint64 memory_max = 2;


    // The weight in the range [1, 10000]. The default is 100.
    // If several different processes (in different cgroups) want to run on a contended system, 
    // workloads with larger CPU weights get more CPU time than workloads with small weights.
    uint32 cpu_weight = 3;

    // Defines how much CPU time that cgroup can use
    // In the controller, it's defined as two values, and the default is defined as "max 100000" which indicates
    // that the group may consume up to the first value in the period of the second value.
    // Setting this value will change only the first value, so it is possible to set it in the range of [0, 100000],
    // e.g using 50000 means that the cgroup my consume 50ms out of 100ms period, which is roughly 50% of the CPU time.
    // Times are in microseconds.
    uint32 cpu_max = 4;

    // Specifies the relative amount IO time the cgroup can use in relation to its siblings. Defaults to 100. The weights are in the range [1, 10000] 
    uint32 io_weight = 5;
}

message JobStopRequest {
    string uuid = 1;
}

message JobStopResponse {}

message JobStartRequest {
    // The first value should be path to the file that is associated with the process being started
    // Next values are arguments that will be passed to the process
    repeated string args = 1;
    JobResourceLimits limits = 2;
}

message JobStartResponse {
    string uuid = 1;
}

message JobLogsRequest {
    string uuid = 1;
}

message JobLogsResponse {
    bytes data = 1;
}

message JobStatusRequest {
    string uuid = 1;
}

message JobStatusResponse {
    string uuid = 1;
    string owner = 2;

    // If the job is running then process PID will be provided, otherwise exit_code of the process.
    oneof status {
        int32 pid = 3;
        int32 exit_code = 4;
        int32 signal = 5;
    }
}


service JobRuntime {
    rpc StartJob(JobStartRequest) returns (JobStartResponse);

    // Stops the job by sending SIGKILL to the process
    // Note: We could implement it by first sending SIGTERM signal to politely ask a program to terminate and then after specified timeout send a SIGKILL signal
    // but I think that SIGKILL is enough for this project
    rpc StopJob(JobStopRequest) returns (JobStopResponse);
    rpc FetchJobStatus(JobStatusRequest) returns (JobStatusResponse);
    rpc FetchJobLogs(JobLogsRequest) returns (stream JobLogsResponse);
}