syntax = "proto3";

package iws;

option go_package = "github.com/gitpod-io/gitpod/ws-daemon/api";

service InWorkspaceService {
    // PrepareForUserNS prepares a workspace container for wrapping it in a user namespace.
    // A container that called this function MUST call Teardown.
    //
    // This call will make the workspace container's rootfs shared, and mount the workspace
    // container's rootfs as a shiftfs mark under `/.workspace/mark` if the workspace has
    // the daemon hostPath mount. Can only be used once per workspace.
    rpc PrepareForUserNS(PrepareForUserNSRequest) returns (PrepareForUserNSResponse) {}

    // WriteIDMapping writes a new user/group ID mapping to /proc/<pid>/uid_map (gid_map respectively). This is used
    // for user namespaces and is available four times every 10 seconds.
    rpc WriteIDMapping(WriteIDMappingRequest) returns (WriteIDMappingResponse) {}

    // MountProc mounts a masked proc in the container's rootfs.
    // For now this can be used only once per workspace.
    rpc MountProc(MountProcRequest) returns (MountProcResponse) {}

    // Teardown prepares workspace content backups and unmounts shiftfs mounts. The canary is supposed to be triggered
    // when the workspace is about to shut down, e.g. using the PreStop hook of a Kubernetes container.
    rpc Teardown(TeardownRequest) returns (TeardownResponse) {}
}

message PrepareForUserNSRequest {}
message PrepareForUserNSResponse {}

message WriteIDMappingResponse {
    string message = 1;
    uint32 error_code = 2;
}
message WriteIDMappingRequest {
    message Mapping {
        uint32 container_id = 1;
        uint32 host_id = 2;
        uint32 size = 3;
    }

    int64 pid = 1;
    bool gid = 2;
    repeated Mapping mapping = 3;
}

message MountProcRequest {
    string target = 1;
    int64 pid = 2;
}
message MountProcResponse {}

message TeardownRequest {
}
message TeardownResponse {
    bool success = 2;
}