bsdkrun/types

Typed records mirroring bsdkrun’s --json output, their decoders, and the result of running a command inside a guest.

The same records also back bsdkrun/client (the remote GraphQL client): sandbox_info_from_graphql and command_result_from_graphql decode the daemon’s camelCase GraphQL responses into these exact same SandboxInfo / CommandResult types, so code written against the local, CLI-shelling API and code written against a remote daemon see identical shapes.

Types

CommandResult

</>

The captured result of running a command in a guest.

pub type CommandResult {
  CommandResult(
    stdout: String,
    stderr: String,
    exit_code: Int,
    command: String,
  )
}

Constructors

CommandResult(
  stdout: String,
  stderr: String,
  exit_code: Int,
  command: String,
)

ExecResult

</>

The captured result of client.exec — a one-shot command run through openShell + shellOutput + closeShell (see bsdkrun/client).

Unlike the local CommandResult, output is a single interleaved BitArray rather than separate stdout/stderr: the daemon’s shell protocol is a pty, which does not keep the streams apart.

pub type ExecResult {
  ExecResult(exit_code: Int, output: BitArray)
}

Constructors

ExecResult(exit_code: Int, output: BitArray)

ImageInfo

</>

An image, as reported by bsdkrun images --json.

pub type ImageInfo {
  ImageInfo(
    id: String,
    reference: String,
    digest: String,
    size: Int,
    rootfs: String,
    created_at: Int,
  )
}

Constructors

ImageInfo(
  id: String,
  reference: String,
  digest: String,
  size: Int,
  rootfs: String,
  created_at: Int,
)

NetworkInfo

</>

A global network, as reported by bsdkrun network ls --json.

pub type NetworkInfo {
  NetworkInfo(
    name: String,
    subnet: String,
    gateway: String,
    members: Int,
    running: Int,
    up: Bool,
    created_at: option.Option(Int),
  )
}

Constructors

NetworkInfo(
  name: String,
  subnet: String,
  gateway: String,
  members: Int,
  running: Int,
  up: Bool,
  created_at: option.Option(Int),
)

PortForward

</>

A host->guest TCP port forward, as reported by bsdkrun ps --json.

pub type PortForward {
  PortForward(bind: String, host: Int, guest: Int)
}

Constructors

PortForward(bind: String, host: Int, guest: Int)

SandboxInfo

</>

A machine, as reported by bsdkrun ps --json.

pub type SandboxInfo {
  SandboxInfo(
    id: String,
    name: option.Option(String),
    image: String,
    kind: String,
    command: String,
    running: Bool,
    exit_code: option.Option(Int),
    pid: option.Option(Int),
    detached: Bool,
    cpus: Int,
    mem: Int,
    volume: option.Option(String),
    state_dir: String,
    network: option.Option(String),
    net_ip: option.Option(String),
    created_at: Int,
    finished_at: option.Option(Int),
    ports: List(PortForward),
  )
}

Constructors

SandboxInfo(
  id: String,
  name: option.Option(String),
  image: String,
  kind: String,
  command: String,
  running: Bool,
  exit_code: option.Option(Int),
  pid: option.Option(Int),
  detached: Bool,
  cpus: Int,
  mem: Int,
  volume: option.Option(String),
  state_dir: String,
  network: option.Option(String),
  net_ip: option.Option(String),
  created_at: Int,
  finished_at: option.Option(Int),
  ports: List(PortForward),
)

ShellEvent

</>

One event from a live shellOutput or machineLogs subscription, as delivered to a bsdkrun/subject.Subject by bsdkrun/client.

pub type ShellEvent {
  ShellData(BitArray)
  ShellExit(Int)
  ShellError(String)
  ShellClosed
}

Constructors

```
ShellData(BitArray)
```
A chunk of output, already base64-decoded.
```
ShellExit(Int)
```
The session’s command exited. Terminal — no further events follow.
```
ShellError(String)
```
The subscription itself failed (a GraphQL error message, or the socket closing). Terminal.
```
ShellClosed
```
The subscription ended with no more data (a GraphQL complete, or the caller unsubscribed). Terminal.

ShellSessionInfo

</>

A shell session, as reported by the daemon’s openShell mutation / shellSessions query.

pub type ShellSessionInfo {
  ShellSessionInfo(
    id: String,
    machine_id: String,
    finished: Bool,
    truncated: Bool,
  )
}

Constructors

ShellSessionInfo(
  id: String,
  machine_id: String,
  finished: Bool,
  truncated: Bool,
)

SubscriptionEvent

</>

One event from client.subscribe, the generic subscription escape hatch.

pub type SubscriptionEvent {
  SubNext(dynamic.Dynamic)
  SubError(String)
  SubComplete
}

Constructors

```
SubNext(dynamic.Dynamic)
```
One next payload’s data, exactly as the operation’s document shapes it — decode it the same way you would decode client.request’s result.
```
SubError(String)
```
A GraphQL error message (or the socket closing). Terminal.
```
SubComplete
```
A GraphQL complete. Terminal.

VolumeInfo

</>

A persistent volume, as reported by bsdkrun volume ls --json.

pub type VolumeInfo {
  VolumeInfo(
    name: String,
    guest: option.Option(String),
    base: option.Option(String),
    path: String,
    size: String,
    created_at: option.Option(Int),
    tracked: Bool,
  )
}

Constructors

VolumeInfo(
  name: String,
  guest: option.Option(String),
  base: option.Option(String),
  path: String,
  size: String,
  created_at: option.Option(Int),
  tracked: Bool,
)

Values

command_result_from_graphql

</>

pub fn command_result_from_graphql(
  dyn: dynamic.Dynamic,
  label: String,
) -> Result(CommandResult, error.Error)

Decode a GraphQL CommandResult object ({ exitCode stdout stderr }, what every lifecycle mutation returns) into the local CommandResult type. GraphQL’s CommandResult has no command field — the mutation name is supplied by the caller (bsdkrun/client) so error messages still name the operation that failed, exactly as the local CLI path does.

decode_base64_chunk

</>

pub fn decode_base64_chunk(data_base64: String) -> BitArray

Base64-decode one shellOutput/machineLogs chunk’s dataBase64 field. Invalid base64 (should not happen — the daemon only ever sends what it itself encoded) decodes as empty, so a display glitch never becomes a crash.

decode_rows

</>

pub fn decode_rows(
  raw: String,
  label: String,
  row: decode.Decoder(a),
) -> Result(List(a), error.Error)

Decode a --json list payload. Blank output — which the CLI emits when there is nothing to list — decodes as the empty list.

image_info_decoder

</>

pub fn image_info_decoder() -> decode.Decoder(ImageInfo)

Decoder for one images --json row.

int_field

</>

pub fn int_field(
  dyn: dynamic.Dynamic,
  name: String,
  default: Int,
) -> Int

Decode a Dynamic’s Int field by name, defaulting to default when the field is absent, null, or the wrong shape.

is_ok

</>

pub fn is_ok(res: CommandResult) -> Bool

Whether the command succeeded (exit 0).

lines

</>

pub fn lines(res: CommandResult) -> List(String)

Non-empty stdout lines.

network_info_decoder

</>

pub fn network_info_decoder() -> decode.Decoder(NetworkInfo)

Decoder for one network ls --json row.

optional_string_field

</>

pub fn optional_string_field(
  dyn: dynamic.Dynamic,
  name: String,
) -> option.Option(String)

Decode a decode.optional_field(name, option.None, decode.optional(inner), next) shaped field returning a String. A convenience for the few call sites outside this module (bsdkrun/client) that need one field decoded out of a Dynamic without building a full record decoder.

port_forward_decoder

</>

pub fn port_forward_decoder() -> decode.Decoder(PortForward)

Decoder for one ports entry of a ps --json row.

sandbox_info_decoder

</>

pub fn sandbox_info_decoder() -> decode.Decoder(SandboxInfo)

Decoder for one ps --json row.

sandbox_info_from_graphql

</>

pub fn sandbox_info_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(SandboxInfo, error.Error)

Decode a GraphQL Machine object (the machine/machines query result, or data.machine from a raw client.request call) into a SandboxInfo.

shell_session_info_from_graphql

</>

pub fn shell_session_info_from_graphql(
  dyn: dynamic.Dynamic,
) -> Result(ShellSessionInfo, error.Error)

Decode a GraphQL ShellSessionInfo object (openShell’s result, or a row of shellSessions).

status

</>

pub fn status(info: SandboxInfo) -> String

"running" or "exited" — the status column bsdkrun ps prints.

string_field

</>

pub fn string_field(
  dyn: dynamic.Dynamic,
  name: String,
  default: String,
) -> String

Decode a Dynamic’s String field by name, defaulting to default when the field is absent, null, or the wrong shape.

text

</>

pub fn text(res: CommandResult) -> String

stdout with trailing newlines trimmed — the common case.

volume_info_decoder

</>

pub fn volume_info_decoder() -> decode.Decoder(VolumeInfo)

Decoder for one volume ls --json row.