bsdkrun - v1.4.0

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

CacheEntry

</>

A stored cache entry, as reported by bsdkrun cache ls --json.

pub type CacheEntry {
  CacheEntry(
    key: String,
    path: String,
    compression: String,
    size: Int,
    created: Int,
    digest: String,
  )
}

Constructors 

  • CacheEntry(
  key: String,
  path: String,
  compression: String,
  size: Int,
  created: Int,
  digest: String,
)

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)

RestoreResult

</>

What a bsdkrun cache restore --json did. A miss is not an error — check restored.

pub type RestoreResult {
  RestoreResult(
    restored: Bool,
    requested_key: String,
    key: option.Option(String),
    path: option.Option(String),
    size: option.Option(Int),
    compression: option.Option(String),
    created: option.Option(Int),
  )
}

Constructors

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

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

Values

cache_entry_decoder

</> 
pub fn cache_entry_decoder() -> decode.Decoder(CacheEntry)

Decoder for one cache ls --json row, and for cache save --json.

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_one

</> 
pub fn decode_one(
  raw: String,
  label: String,
  row: decode.Decoder(a),
) -> Result(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. Decode a single JSON object, as decode_rows does for a list.

decode_rows

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

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.

restore_result_decoder

</> 
pub fn restore_result_decoder() -> decode.Decoder(RestoreResult)

Decoder for cache restore --json.

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.

✨ Search Document