package runme.runner.v1

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc CreateSession (CreateSessionRequest, CreateSessionResponse)

  runner.proto:408

  message CreateSessionRequest

  runner.proto:29

  • map<string, string> metadata = 1

    metadata is a map of client specific metadata.

  • repeated string envs = 2

    envs field provides an initial set of environment variables for a newly created session.

  • optional Project project = 3

    optional project from which to immediately load environment variables

  • SessionEnvStoreType env_store_type = 4

    optional selection of which env store implementation to sue

  message CreateSessionResponse

  runner.proto:44

  • optional Session session = 1

• rpc GetSession (GetSessionRequest, GetSessionResponse)

  runner.proto:409

  message GetSessionRequest

  runner.proto:48

  • string id = 1

  message GetSessionResponse

  runner.proto:52

  • optional Session session = 1

• rpc ListSessions (ListSessionsRequest, ListSessionsResponse)

  runner.proto:410

  message ListSessionsRequest

  runner.proto:56

  (message has no fields)

  message ListSessionsResponse

  runner.proto:58

  • repeated Session sessions = 1

• rpc DeleteSession (DeleteSessionRequest, DeleteSessionResponse)

  runner.proto:411

  message DeleteSessionRequest

  runner.proto:62

  • string id = 1

  message DeleteSessionResponse

  runner.proto:66

  (message has no fields)

• rpc MonitorEnvStore (MonitorEnvStoreRequest, stream MonitorEnvStoreResponse)

  runner.proto:413

  message MonitorEnvStoreRequest

  runner.proto:351

  • optional Session session = 1

  message MonitorEnvStoreResponse

  runner.proto:399

  • MonitorEnvStoreType type = 1

  • oneof data

    • MonitorEnvStoreResponseSnapshot snapshot = 2

• rpc Execute (stream ExecuteRequest, stream ExecuteResponse)

  runner.proto:422

  Execute executes a program. Examine "ExecuteRequest" to explore configuration options. It's a bidirectional stream RPC method. It expects the first "ExecuteRequest" to contain details of a program to execute. Subsequent "ExecuteRequest" should only contain "input_data" as other fields will be ignored.

  message ExecuteRequest

  runner.proto:125

  • string program_name = 1

    program_name is a name of the program to execute. If it's not a path (relative or absolute), the runner will try to resolve the name. For example: "sh", "/bin/bash".

  • repeated string arguments = 2

    arguments is a list of arguments passed to the program.

  • string directory = 3

    directory to execute the program in.

  • repeated string envs = 4

    envs is a list of additional environment variables that will be injected to the executed program.

  • repeated string commands = 5

    commands are commands to be executed by the program. The commands are joined and executed as a script. For example: "echo 'Hello, World'", "ls -l /etc". This is mutually exclusive with the script field.

  • string script = 6

    script is code to be executed by the program. Individual lines are joined with the new line character. This is mutually exclusive with the commands field.

  • bool tty = 7

    tty when true allocates a pseudo-TTY.

  • bytes input_data = 8

    input_data is a byte array that will be send as input to the program.

  • ExecuteStop stop = 9

    stop requests the running process to be stopped. It is allowed only in the consecutive calls.

  • optional Winsize winsize = 10

    sets pty winsize has no effect in non-interactive mode

  • bool background = 11

    background indicates a background process this will send the process' PID as a first response

  • string session_id = 20

    session_id indicates in which Session the program should execute. Executing in a Session might provide additional context like environment variables.

  • SessionStrategy session_strategy = 21

    strategy for selecting session

  • optional Project project = 22

    project for this runner used to load environment variables from .env files

  • bool store_last_output = 23

    whether to store the stdout of the last ran block in the environment variable `__`

  • CommandMode command_mode = 24

  • string language_id = 25

    language id associated with script

  • string file_extension = 26

    file extension associated with script

  • string known_id = 27

    optional well known id for cell/block. "know" meaning that CLI/notebook UX have id/name for cells/blocks that contain commands. While the runner doesn't require the name to work, it is useful for auxiliary concerns (e.g. tracing, logging, etc).

  • string known_name = 28

    optional well known name for cell/block. "know" meaning that CLI/notebook UX have id/name for cells/blocks that contain commands. While the runner doesn't require the name to work, it is useful for auxiliary concerns (e.g. tracing, logging, etc).

  message ExecuteResponse

  runner.proto:213

  • optional google.protobuf.UInt32Value exit_code = 1

    exit_code is sent only in the final message.

  • bytes stdout_data = 2

    stdout_data contains bytes from stdout since the last response.

  • bytes stderr_data = 3

    stderr_data contains bytes from stderr since the last response.

  • optional ProcessPID pid = 4

    pid contains the process' PID this is only sent once in an initial response for background processes.

  • string mime_type = 5

    mime_type is a detected MIME type of the stdout_data. This is only sent once in the first response containing stdout_data.

• rpc ResolveProgram (ResolveProgramRequest, ResolveProgramResponse)

  runner.proto:428

  ResolveProgram resolves variables from a script or a list of commands using the provided sources, which can be a list of environment variables, a session, or a project. For now, the resolved variables are only the exported ones using `export`.

  message ResolveProgramRequest

  runner.proto:240

  • oneof source

    use script for unnormalized cell content whereas commands is for normalized shell commands

    • ResolveProgramCommandList commands = 1

      commands are commands to be executed by the program. The commands are joined and executed as a script.

    • string script = 2

      script is code to be executed by the program. Individual lines are joined with the new line character.

  • ResolveProgramRequest.Mode mode = 3

    mode determines how variables resolution occurs. It is usually based on document or cell annotation config.

  • repeated string env = 4

    env is a list of explicit environment variables that will be used to resolve the environment variables found in the source.

  • string session_id = 5

    session_id indicates which session is the source of environment variables. If not provided, the most recent session can be used using session_strategy.

  • SessionStrategy session_strategy = 6

    session_strategy is a strategy for selecting the session.

  • optional Project project = 7

    project used to load environment variables from .env files.

  • string language_id = 8

    language id associated with script

  • ResolveProgramRequest.Retention retention = 9

    retention determines how variables are retained once resolved.

  message ResolveProgramResponse

  runner.proto:301

  • string script = 1

  • optional ResolveProgramCommandList commands = 2

    use script until commands normalization is implemented

  • repeated ResolveProgramResponse.VarResult vars = 3

Used in: notebook.v1alpha1.ResolveNotebookRequest, ExecuteRequest

• COMMAND_MODE_UNSPECIFIED = 0

• COMMAND_MODE_INLINE_SHELL = 1

• COMMAND_MODE_TEMP_FILE = 2

• COMMAND_MODE_TERMINAL = 3

• COMMAND_MODE_DAGGER = 4

Used in: ExecuteRequest

• EXECUTE_STOP_UNSPECIFIED = 0

• EXECUTE_STOP_INTERRUPT = 1

• EXECUTE_STOP_KILL = 2

Used in: MonitorEnvStoreResponse

• repeated MonitorEnvStoreResponseSnapshot.SnapshotEnv envs = 1

Used in: SnapshotEnv

• uint32 code = 1

• string message = 2

Used in: MonitorEnvStoreResponseSnapshot

• Status status = 1

• string name = 2

• string spec = 3

• string origin = 4

• string original_value = 5

• string resolved_value = 6

• string create_time = 7

• string update_time = 8

• repeated Error errors = 9

• bool is_required = 10

• string description = 11

Used in: SnapshotEnv

• STATUS_UNSPECIFIED = 0

• STATUS_LITERAL = 1

• STATUS_HIDDEN = 2

• STATUS_MASKED = 3

Used in: MonitorEnvStoreResponse

• MONITOR_ENV_STORE_TYPE_UNSPECIFIED = 0

• MONITOR_ENV_STORE_TYPE_SNAPSHOT = 1

  possible expansion to have a "timeline" view MONITOR_ENV_STORE_TYPE_TIMELINE = 2;

Used in: ExecuteResponse

• int64 pid = 1

Used in: CreateSessionRequest, ExecuteRequest, ResolveProgramRequest

• string root = 1

  project root folder

• repeated string env_load_order = 2

  list of environment files to try and load start with

• Project.DirEnv env_direnv = 3

  specifies if and how direnv should be used

Used in: Project

• DIR_ENV_UNSPECIFIED = 0

  unspecified is the default value

• DIR_ENV_ENABLED_WARN = 1

  enabled, only warn on direnv errors

• DIR_ENV_ENABLED_ERROR = 2

  enabled, error on direnv errors

• DIR_ENV_DISABLED = 3

  disabled means to not use direnv

Used in: ResolveProgramRequest, ResolveProgramResponse

• repeated string lines = 1

  commands are commands to be executed by the program. The commands are joined and executed as a script. For example: ["echo 'Hello, World'", "ls -l /etc"].

Used in: ResolveProgramRequest

• MODE_UNSPECIFIED = 0

  unspecified is auto (default) which prompts for all unresolved environment variables. Subsequent runs will likely resolve via the session.

• MODE_PROMPT_ALL = 1

  prompt always means to prompt for all environment variables.

• MODE_SKIP_ALL = 2

  skip means to not prompt for any environment variables. All variables will be marked as resolved.

Used in: ResolveProgramRequest

• RETENTION_UNSPECIFIED = 0

• RETENTION_FIRST_RUN = 1

  first run means to always retain the first resolved value.

• RETENTION_LAST_RUN = 2

  last run means to always retain the last resolved value.

Used in: VarResult

• STATUS_UNSPECIFIED = 0

  unspecified is the default value and it means unresolved.

• STATUS_UNRESOLVED_WITH_MESSAGE = 1

  unresolved with message means that the variable is unresolved but it contains a message. E.g. FOO=this is message

• STATUS_UNRESOLVED_WITH_PLACEHOLDER = 2

  unresolved with placeholder means that the variable is unresolved but it contains a placeholder. E.g. FOO="this is placeholder"

• STATUS_RESOLVED = 3

  resolved means that the variable is resolved.

• STATUS_UNRESOLVED_WITH_SECRET = 4

  unresolved with secret means that the variable is unresolved and it requires treatment as a secret.

Used in: ResolveProgramResponse

• Status status = 1

  prompt indicates the resolution status of the env variable.

• string name = 2

  name is the name of the environment variable.

• string original_value = 3

  original_value is a default value of the environment variable. It might be a value that is assigned to the variable in the script, like FOO=bar or FOO=${FOO:-bar}. If the variable is not assigned, it is an empty string.

• string resolved_value = 4

  resolved_value is a value of the environment variable resolved from a source. If it is an empty string, it means that the environment variable is not resolved.

Used in: CreateSessionResponse, GetSessionResponse, ListSessionsResponse, MonitorEnvStoreRequest

• string id = 1

• repeated string envs = 2

  envs keeps track of session environment variables. They can be modified by executing programs which alter them through "export" and "unset" commands.

• map<string, string> metadata = 3

  metadata is a map of client specific metadata.

env store implementation

Used in: CreateSessionRequest

• SESSION_ENV_STORE_TYPE_UNSPECIFIED = 0

  uses default env store

• SESSION_ENV_STORE_TYPE_OWL = 1

  uses owl store

strategy for selecting a session in an initial execute request

Used in: ExecuteRequest, ResolveProgramRequest

• SESSION_STRATEGY_UNSPECIFIED = 0

  uses session_id field to determine session if none is present, a new session is created

• SESSION_STRATEGY_MOST_RECENT = 1

  uses most recently used session on the grpc server if there is none, a new one is created

Used in: ExecuteRequest

• uint32 rows = 1

  number of rows (in cells)

• uint32 cols = 2

  number of columns (in cells)

• uint32 x = 3

  width in pixels

• uint32 y = 4

  height in pixels