wire

package module
v0.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: AGPL-3.0 Imports: 7 Imported by: 0

Documentation

Overview

Package wire is the Go binding of the silkd wire protocol, shared by the SDK and sandboxd: newline-delimited JSON frames over one connection per RPC, requests tagged by "op", responses by "type", binary payloads base64 in data fields. The authoritative contract is the shared corpus in protocol/wire/fixtures/v1 — silkd's Rust tests and this package's tests round-trip the same files.

Index

Constants

View Source 
const (
	// ProtoVersion is stamped into every request as "v"; silkd ignores
	// unknown fields, which is the forward-compatibility story.
	ProtoVersion = 1
	// MaxFrame mirrors silkd's frame cap.
	MaxFrame = 8 << 20

	// GitBranch.Action values (silkd's GitBranchOp).
	BranchList     = "list"
	BranchCreate   = "create"
	BranchDelete   = "delete"
	BranchCheckout = "checkout"

	// ErrorResp.Kind values (silkd's ErrorKind).
	KindBadRequest    = "bad_request"
	KindNotFound      = "not_found"
	KindUnimplemented = "unimplemented"
	KindInternal      = "internal"

	// Event.Kind values (silkd's EventKind).
	EventCreated  = "created"
	EventModified = "modified"
	EventDeleted  = "deleted"
	EventRenamed  = "renamed"

	// DirEntry.Kind and FileInfo.Kind values (silkd's FileKind).
	FileKindFile    = "file"
	FileKindDir     = "dir"
	FileKindSymlink = "symlink"
	FileKindOther   = "other"
)

Variables

This section is empty.

Functions

func AppendBulkRequest 

func AppendBulkRequest(buf []byte, op string, data []byte) []byte

AppendBulkRequest renders a data-carrying request frame — {"v":1,"op":<op>,"data":"<base64>"} plus newline — into buf, reused across calls on the bulk send paths (base64's alphabet needs no JSON escaping).

func EncodeRequest 

func EncodeRequest(r Request) ([]byte, error)

EncodeRequest renders {"v":1,"op":...,fields} without a trailing newline.

func EncodeResponse 

func EncodeResponse(r Response) ([]byte, error)

EncodeResponse renders {"type":...,fields} without a trailing newline.

func NewFrameScanner added in v0.1.4 

func NewFrameScanner(r io.Reader) *bufio.Scanner

NewFrameScanner wraps r for newline-delimited frames capped at MaxFrame. No pre-sized buffer: bulk frames outgrow any fixed start anyway.

Types

type Attach 

type Attach struct {
	PID uint32 `json:"pid"`
}

Attach streams a running process's buffered and live output.

func (Attach) Op 

func (Attach) Op() string

type B64 

type B64 []byte

B64 carries request payload bytes. It exists because silkd's deserializer requires a base64 string and rejects null — which is exactly what encoding/json emits for a nil []byte. Decoding needs no counterpart: []byte-kinded types already base64-decode by default.

func (B64) MarshalJSON 

func (b B64) MarshalJSON() ([]byte, error)

type Data 

type Data struct {
	Data B64 `json:"data"`
}

Data carries one chunk of an upload stream (FsWrite/FsPush payloads).

func (Data) Op 

func (Data) Op() string

type DataEnd 

type DataEnd struct{}

DataEnd terminates an upload stream.

func (DataEnd) Op 

func (DataEnd) Op() string

type DataResp 

type DataResp struct {
	Data []byte `json:"data"`
}

DataResp carries one chunk of a download stream (FsRead/FsPull payloads).

func (DataResp) RespType 

func (DataResp) RespType() string

type DirEntry 

type DirEntry struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
	Size uint64 `json:"size"`
}

DirEntry is one entry of Entries; Kind is one of the FileKind* consts.

type Done 

type Done struct{}

Done is the terminal frame of verbs with no payload result.

func (Done) RespType 

func (Done) RespType() string

type Entries 

type Entries struct {
	Entries []DirEntry `json:"entries"`
}

Entries answers FsList.

func (Entries) RespType 

func (Entries) RespType() string

type ErrorResp 

type ErrorResp struct {
	Kind    string `json:"kind"`
	Message string `json:"message"`
}

ErrorResp is the terminal frame of a failed verb; it implements error.

func (*ErrorResp) Error 

func (e *ErrorResp) Error() string

func (ErrorResp) RespType 

func (ErrorResp) RespType() string

type Event 

type Event struct {
	Kind string `json:"kind"`
	Path string `json:"path"`
}

Event is one FsWatch filesystem event; Kind is one of the Event* consts.

func (Event) RespType 

func (Event) RespType() string

type Exec 

type Exec struct {
	Argv    []string          `json:"argv"`
	Cwd     string            `json:"cwd,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	User    string            `json:"user,omitempty"`
	Detach  bool              `json:"detach"`
	Session string            `json:"session,omitempty"`
}

Exec starts a process; with Session set it runs inside that persistent shell instead. Detach is emitted even when false — it is part of the fixture corpus shape.

func (Exec) Op 

func (Exec) Op() string

type Exit 

type Exit struct {
	Code int32 `json:"code"`
}

Exit is the terminal frame of a foreground exec; -1 means killed or unknown.

func (Exit) RespType 

func (Exit) RespType() string

type FileInfo 

type FileInfo struct {
	Kind           string `json:"kind"`
	Size           uint64 `json:"size"`
	Mode           uint32 `json:"mode"`
	MtimeEpochSecs uint64 `json:"mtime_epoch_secs"`
}

FileInfo is the Stat payload; Mode carries permission bits only.

type FsFind 

type FsFind struct {
	Path    string `json:"path"`
	Pattern string `json:"pattern"`
	Glob    string `json:"glob,omitempty"`
}

FsFind streams Match frames for lines under Path matching Pattern; Glob narrows the walk to file names matching it (`*` and `?` wildcards).

func (FsFind) Op 

func (FsFind) Op() string

type FsList 

type FsList struct {
	Path string `json:"path"`
}

FsList streams a directory as batched Entries frames terminated by Done.

func (FsList) Op 

func (FsList) Op() string

type FsMkdir 

type FsMkdir struct {
	Path    string `json:"path"`
	Parents bool   `json:"parents"`
}

FsMkdir creates a directory.

func (FsMkdir) Op 

func (FsMkdir) Op() string

type FsPull 

type FsPull struct {
	Path string `json:"path"`
}

FsPull streams a path back as a tar stream (Data frames, then Done).

func (FsPull) Op 

func (FsPull) Op() string

type FsPush 

type FsPush struct {
	Dest string `json:"dest"`
}

FsPush extracts a client tar stream (Data frames) under dest.

func (FsPush) Op 

func (FsPush) Op() string

type FsRead 

type FsRead struct {
	Path string `json:"path"`
}

FsRead streams a file back as Data frames terminated by Done.

func (FsRead) Op 

func (FsRead) Op() string

type FsRename 

type FsRename struct {
	From string `json:"from"`
	To   string `json:"to"`
}

FsRename moves a file within the guest.

func (FsRename) Op 

func (FsRename) Op() string

type FsReplace 

type FsReplace struct {
	Files       []string `json:"files"`
	Pattern     string   `json:"pattern"`
	Replacement string   `json:"replacement"`
}

FsReplace rewrites Pattern to Replacement in each file, streaming one Replaced frame per file then Done.

func (FsReplace) Op 

func (FsReplace) Op() string

type FsRm 

type FsRm struct {
	Path      string `json:"path"`
	Recursive bool   `json:"recursive"`
}

FsRm removes a file or directory tree.

func (FsRm) Op 

func (FsRm) Op() string

type FsStat 

type FsStat struct {
	Path string `json:"path"`
}

FsStat returns file metadata.

func (FsStat) Op 

func (FsStat) Op() string

type FsWatch 

type FsWatch struct {
	Path      string `json:"path"`
	Recursive bool   `json:"recursive"`
}

FsWatch streams Event frames under Path until the connection closes.

func (FsWatch) Op 

func (FsWatch) Op() string

type FsWrite 

type FsWrite struct {
	Path string  `json:"path"`
	Mode *uint32 `json:"mode,omitempty"`
}

FsWrite streams Data frames into a file, atomically; nil Mode inherits or defaults.

func (FsWrite) Op 

func (FsWrite) Op() string

type GitAdd 

type GitAdd struct {
	Path  string   `json:"path"`
	Files []string `json:"files"`
}

GitAdd stages files under a repo.

func (GitAdd) Op 

func (GitAdd) Op() string

type GitBranch 

type GitBranch struct {
	Path   string `json:"path"`
	Action string `json:"action"`
	Name   string `json:"name,omitempty"`
}

GitBranch lists, creates, deletes, or checks out a branch. Action is list|create|delete|checkout ("op" is reserved by the frame tag).

func (GitBranch) Op 

func (GitBranch) Op() string

type GitBranches 

type GitBranches struct {
	Current  string   `json:"current"`
	Branches []string `json:"branches"`
}

GitBranches answers GitBranch list.

func (GitBranches) RespType 

func (GitBranches) RespType() string

type GitClone 

type GitClone struct {
	URL    string `json:"url"`
	Path   string `json:"path"`
	Branch string `json:"branch,omitempty"`
	Depth  uint32 `json:"depth,omitempty"`
	Auth   string `json:"auth,omitempty"`
}

GitClone clones a repo; network-lane only. Auth is a token passed as an in-memory Authorization header, never written to guest disk.

func (GitClone) Op 

func (GitClone) Op() string

type GitCommit 

type GitCommit struct {
	Path    string `json:"path"`
	Message string `json:"message"`
	Author  string `json:"author"`
}

GitCommit commits staged changes; Author is "Name <email>".

func (GitCommit) Op 

func (GitCommit) Op() string

type GitCommitResult 

type GitCommitResult struct {
	Hash string `json:"hash"`
}

GitCommitResult answers GitCommit with the new commit hash.

func (GitCommitResult) RespType 

func (GitCommitResult) RespType() string

type GitFileStatus 

type GitFileStatus struct {
	Path     string `json:"path"`
	Staged   string `json:"staged"`
	Unstaged string `json:"unstaged"`
}

GitFileStatus is one porcelain-v2 entry; Staged/Unstaged are XY status codes.

type GitPull 

type GitPull struct {
	Path string `json:"path"`
	Auth string `json:"auth,omitempty"`
}

GitPull pulls the current branch; network-lane only.

func (GitPull) Op 

func (GitPull) Op() string

type GitPush 

type GitPush struct {
	Path string `json:"path"`
	Auth string `json:"auth,omitempty"`
}

GitPush pushes the current branch; network-lane only.

func (GitPush) Op 

func (GitPush) Op() string

type GitStatus 

type GitStatus struct {
	Path string `json:"path"`
}

GitStatus asks for a repo's structured status.

func (GitStatus) Op 

func (GitStatus) Op() string

type GitStatusResult 

type GitStatusResult struct {
	Branch string          `json:"branch"`
	Ahead  uint32          `json:"ahead"`
	Behind uint32          `json:"behind"`
	Files  []GitFileStatus `json:"files"`
}

GitStatusResult answers GitStatus.

func (GitStatusResult) RespType 

func (GitStatusResult) RespType() string

type Info 

type Info struct{}

Info asks for the daemon's identity and counters — the readiness probe.

func (Info) Op 

func (Info) Op() string

type InfoResp 

type InfoResp struct {
	Version    string `json:"version"`
	Proto      uint32 `json:"proto"`
	UptimeSecs uint64 `json:"uptime_secs"`
	Procs      int    `json:"procs"`
	Sessions   int    `json:"sessions"`
}

InfoResp answers Info.

func (InfoResp) RespType 

func (InfoResp) RespType() string

type Kill 

type Kill struct {
	PID    uint32 `json:"pid"`
	Signal *int32 `json:"signal,omitempty"`
}

Kill signals a process; nil Signal means SIGKILL.

func (Kill) Op 

func (Kill) Op() string

type Logs 

type Logs struct {
	PID uint32 `json:"pid"`
}

Logs returns a process's ring-buffered output.

func (Logs) Op 

func (Logs) Op() string

type LspRequest 

type LspRequest struct {
	ServerID string `json:"server_id"`
}

LspRequest opens the JSON-RPC byte stream to a started language server.

func (LspRequest) Op 

func (LspRequest) Op() string

type LspStart 

type LspStart struct {
	Language string `json:"language"`
	Root     string `json:"root,omitempty"`
}

LspStart spawns the flavor image's language server for Language, rooted at Root.

func (LspStart) Op 

func (LspStart) Op() string

type LspStarted 

type LspStarted struct {
	ServerID string `json:"server_id"`
}

LspStarted answers LspStart.

func (LspStarted) RespType 

func (LspStarted) RespType() string

type LspStop 

type LspStop struct {
	ServerID string `json:"server_id"`
}

LspStop kills a started language server.

func (LspStop) Op 

func (LspStop) Op() string

type Match 

type Match struct {
	File    string `json:"file"`
	Line    uint64 `json:"line"`
	Content string `json:"content"`
}

Match is one FsFind hit; Line is 1-based.

func (Match) RespType 

func (Match) RespType() string

type PortForward 

type PortForward struct {
	Port uint16 `json:"port"`
}

PortForward relays a guest TCP port over this connection: Ready once connected, then Data both ways (DataEnd half-closes the guest socket); the guest server closing ends the stream with Done.

func (PortForward) Op 

func (PortForward) Op() string

type ProcInfo 

type ProcInfo struct {
	PID                uint32   `json:"pid"`
	Argv               []string `json:"argv"`
	Detached           bool     `json:"detached"`
	State              string   `json:"state"`
	ExitCode           *int32   `json:"exit_code,omitempty"`
	StartedAtEpochSecs uint64   `json:"started_at_epoch_secs"`
}

ProcInfo is one entry of Procs; ExitCode is absent while running.

type Procs 

type Procs struct {
	Procs []ProcInfo `json:"procs"`
}

Procs answers Ps.

func (Procs) RespType 

func (Procs) RespType() string

type Ps 

type Ps struct{}

Ps lists tracked processes.

func (Ps) Op 

func (Ps) Op() string

type PtyOpen 

type PtyOpen struct {
	Cols uint16            `json:"cols"`
	Rows uint16            `json:"rows"`
	Cwd  string            `json:"cwd,omitempty"`
	Env  map[string]string `json:"env,omitempty"`
	User string            `json:"user,omitempty"`
}

PtyOpen runs the guest shell under a pseudo-terminal: Started, then Stdout frames out and Stdin frames in, until the shell exits (Exit).

func (PtyOpen) Op 

func (PtyOpen) Op() string

type PtyResize 

type PtyResize struct {
	PID  uint32 `json:"pid"`
	Cols uint16 `json:"cols"`
	Rows uint16 `json:"rows"`
}

PtyResize resizes a live pty's window by pid.

func (PtyResize) Op 

func (PtyResize) Op() string

type Ready 

type Ready struct{}

Ready acknowledges an armed watch (events after it are guaranteed captured) or a connected port_forward.

func (Ready) RespType 

func (Ready) RespType() string

type Replaced 

type Replaced struct {
	File         string `json:"file"`
	Replacements uint64 `json:"replacements"`
}

Replaced reports one FsReplace file result.

func (Replaced) RespType 

func (Replaced) RespType() string

type Request 

type Request interface{ Op() string }

Request is a client→server frame; Op is its wire tag.

func DecodeRequest 

func DecodeRequest(line []byte) (Request, error)

DecodeRequest parses one frame into its op's concrete type.

type Response 

type Response interface{ RespType() string }

Response is a server→client frame; RespType is its wire tag.

func DecodeResponse 

func DecodeResponse(line []byte) (Response, error)

DecodeResponse parses one frame into its type's concrete Go type. Byte fields are freshly allocated per frame, so callers may retain them.

type SessionCreate 

type SessionCreate struct {
	ID  string            `json:"id,omitempty"`
	Cwd string            `json:"cwd,omitempty"`
	Env map[string]string `json:"env,omitempty"`
}

SessionCreate opens a persistent shell; empty ID lets silkd name it.

func (SessionCreate) Op 

func (SessionCreate) Op() string

type SessionCreated 

type SessionCreated struct {
	ID string `json:"id"`
}

SessionCreated answers SessionCreate.

func (SessionCreated) RespType 

func (SessionCreated) RespType() string

type SessionList 

type SessionList struct{}

SessionList lists live session ids.

func (SessionList) Op 

func (SessionList) Op() string

type SessionRm 

type SessionRm struct {
	ID string `json:"id"`
}

SessionRm kills a session's shell and process group.

func (SessionRm) Op 

func (SessionRm) Op() string

type Sessions 

type Sessions struct {
	Sessions []string `json:"sessions"`
}

Sessions answers SessionList.

func (Sessions) RespType 

func (Sessions) RespType() string

type Started 

type Started struct {
	PID uint32 `json:"pid"`
}

Started reports the spawned pid (synthetic when the OS pid is unknown).

func (Started) RespType 

func (Started) RespType() string

type Stat 

type Stat struct {
	Info FileInfo `json:"info"`
}

Stat answers FsStat.

func (Stat) RespType 

func (Stat) RespType() string

type Stderr 

type Stderr struct {
	Data []byte `json:"data"`
}

Stderr carries a chunk of process stderr.

func (Stderr) RespType 

func (Stderr) RespType() string

type Stdin 

type Stdin struct {
	Data B64 `json:"data"`
}

Stdin carries a chunk of exec stdin.

func (Stdin) Op 

func (Stdin) Op() string

type StdinClose 

type StdinClose struct{}

StdinClose signals stdin EOF to the running exec.

func (StdinClose) Op 

func (StdinClose) Op() string

type Stdout 

type Stdout struct {
	Data []byte `json:"data"`
}

Stdout carries a chunk of process stdout.

func (Stdout) RespType 

func (Stdout) RespType() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.