wire

package
v0.2.26 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package wire is the emulated shell's relay protocol: length-delimited protobuf Frames over a Unix socket, one invocation per connection (wire.proto, docs/explainers/2026-11-01-emulated-shell-sandbox.md).

Index

Constants

View Source
const ChunkSize = 64 << 10

ChunkSize is the largest stdin, stdout or stderr chunk a peer sends.

View Source
const MaxFrame = 1 << 20

MaxFrame is the largest encoded frame, 1 MiB (spec §10.1); larger lengths fail before allocation.

View Source
const Version = 1

Version is the only protocol version the broker accepts.

Variables

Functions

This section is empty.

Types

type Cancel

type Cancel struct {
	Reason []byte `protobuf:"bytes,1,opt,name=reason,proto3" json:"reason,omitempty"`
	// contains filtered or unexported fields
}

func (*Cancel) Descriptor deprecated

func (*Cancel) Descriptor() ([]byte, []int)

Deprecated: Use Cancel.ProtoReflect.Descriptor instead.

func (*Cancel) GetReason

func (x *Cancel) GetReason() []byte

func (*Cancel) ProtoMessage

func (*Cancel) ProtoMessage()

func (*Cancel) ProtoReflect

func (x *Cancel) ProtoReflect() protoreflect.Message

func (*Cancel) Reset

func (x *Cancel) Reset()

func (*Cancel) String

func (x *Cancel) String() string

type Frame

type Frame struct {
	Version uint32 `protobuf:"varint,1,opt,name=version,proto3" json:"version,omitempty"`
	// Types that are valid to be assigned to Body:
	//
	//	*Frame_InvokeStart
	//	*Frame_StdinChunk
	//	*Frame_StdinEof
	//	*Frame_StdoutChunk
	//	*Frame_StderrChunk
	//	*Frame_InvokeExit
	//	*Frame_Cancel
	Body isFrame_Body `protobuf_oneof:"body"`
	// contains filtered or unexported fields
}

func (*Frame) Descriptor deprecated

func (*Frame) Descriptor() ([]byte, []int)

Deprecated: Use Frame.ProtoReflect.Descriptor instead.

func (*Frame) GetBody

func (x *Frame) GetBody() isFrame_Body

func (*Frame) GetCancel

func (x *Frame) GetCancel() *Cancel

func (*Frame) GetInvokeExit

func (x *Frame) GetInvokeExit() *InvokeExit

func (*Frame) GetInvokeStart

func (x *Frame) GetInvokeStart() *InvokeStart

func (*Frame) GetStderrChunk

func (x *Frame) GetStderrChunk() []byte

func (*Frame) GetStdinChunk

func (x *Frame) GetStdinChunk() []byte

func (*Frame) GetStdinEof

func (x *Frame) GetStdinEof() *StdinEOF

func (*Frame) GetStdoutChunk

func (x *Frame) GetStdoutChunk() []byte

func (*Frame) GetVersion

func (x *Frame) GetVersion() uint32

func (*Frame) ProtoMessage

func (*Frame) ProtoMessage()

func (*Frame) ProtoReflect

func (x *Frame) ProtoReflect() protoreflect.Message

func (*Frame) Reset

func (x *Frame) Reset()

func (*Frame) String

func (x *Frame) String() string

type Frame_Cancel

type Frame_Cancel struct {
	Cancel *Cancel `protobuf:"bytes,8,opt,name=cancel,proto3,oneof"` // either way
}

type Frame_InvokeExit

type Frame_InvokeExit struct {
	InvokeExit *InvokeExit `protobuf:"bytes,7,opt,name=invoke_exit,json=invokeExit,proto3,oneof"` // host→guest, last frame
}

type Frame_InvokeStart

type Frame_InvokeStart struct {
	InvokeStart *InvokeStart `protobuf:"bytes,2,opt,name=invoke_start,json=invokeStart,proto3,oneof"` // guest→host, first frame only
}

type Frame_StderrChunk

type Frame_StderrChunk struct {
	StderrChunk []byte `protobuf:"bytes,6,opt,name=stderr_chunk,json=stderrChunk,proto3,oneof"` // host→guest
}

type Frame_StdinChunk

type Frame_StdinChunk struct {
	StdinChunk []byte `protobuf:"bytes,3,opt,name=stdin_chunk,json=stdinChunk,proto3,oneof"` // guest→host
}

type Frame_StdinEof

type Frame_StdinEof struct {
	StdinEof *StdinEOF `protobuf:"bytes,4,opt,name=stdin_eof,json=stdinEof,proto3,oneof"` // guest→host
}

type Frame_StdoutChunk

type Frame_StdoutChunk struct {
	StdoutChunk []byte `protobuf:"bytes,5,opt,name=stdout_chunk,json=stdoutChunk,proto3,oneof"` // host→guest
}

type InvokeExit

type InvokeExit struct {
	Code    uint32 `protobuf:"varint,1,opt,name=code,proto3" json:"code,omitempty"`      // 0-255
	Message []byte `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"` // sanitized text for the guest's stderr
	// contains filtered or unexported fields
}

func (*InvokeExit) Descriptor deprecated

func (*InvokeExit) Descriptor() ([]byte, []int)

Deprecated: Use InvokeExit.ProtoReflect.Descriptor instead.

func (*InvokeExit) GetCode

func (x *InvokeExit) GetCode() uint32

func (*InvokeExit) GetMessage

func (x *InvokeExit) GetMessage() []byte

func (*InvokeExit) ProtoMessage

func (*InvokeExit) ProtoMessage()

func (*InvokeExit) ProtoReflect

func (x *InvokeExit) ProtoReflect() protoreflect.Message

func (*InvokeExit) Reset

func (x *InvokeExit) Reset()

func (*InvokeExit) String

func (x *InvokeExit) String() string

type InvokeStart

type InvokeStart struct {
	ExecId   []byte   `protobuf:"bytes,1,opt,name=exec_id,json=execId,proto3" json:"exec_id,omitempty"`       // claimed execution; the broker compares it with the socket's own
	Name     []byte   `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`                         // registered command name
	Cwd      []byte   `protobuf:"bytes,3,opt,name=cwd,proto3" json:"cwd,omitempty"`                           // guest path
	Args     [][]byte `protobuf:"bytes,4,rep,name=args,proto3" json:"args,omitempty"`                         // argv without the command name
	GuestEnv [][]byte `protobuf:"bytes,5,rep,name=guest_env,json=guestEnv,proto3" json:"guest_env,omitempty"` // KEY=VALUE, untrusted metadata
	// contains filtered or unexported fields
}

InvokeStart is entirely guest-controlled. There is deliberately no host environment field.

func (*InvokeStart) Descriptor deprecated

func (*InvokeStart) Descriptor() ([]byte, []int)

Deprecated: Use InvokeStart.ProtoReflect.Descriptor instead.

func (*InvokeStart) GetArgs

func (x *InvokeStart) GetArgs() [][]byte

func (*InvokeStart) GetCwd

func (x *InvokeStart) GetCwd() []byte

func (*InvokeStart) GetExecId

func (x *InvokeStart) GetExecId() []byte

func (*InvokeStart) GetGuestEnv

func (x *InvokeStart) GetGuestEnv() [][]byte

func (*InvokeStart) GetName

func (x *InvokeStart) GetName() []byte

func (*InvokeStart) ProtoMessage

func (*InvokeStart) ProtoMessage()

func (*InvokeStart) ProtoReflect

func (x *InvokeStart) ProtoReflect() protoreflect.Message

func (*InvokeStart) Reset

func (x *InvokeStart) Reset()

func (*InvokeStart) String

func (x *InvokeStart) String() string

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader reads frames from one connection.

func NewReader

func NewReader(r io.Reader) *Reader

NewReader returns a Reader on r.

func (*Reader) Read

func (r *Reader) Read() (*Frame, error)

Read reads one frame. It refuses frames over MaxFrame, other versions, empty bodies, and unknown fields anywhere, so a forged field such as a host environment is an error, not silently ignored.

type StdinEOF

type StdinEOF struct {
	// contains filtered or unexported fields
}

func (*StdinEOF) Descriptor deprecated

func (*StdinEOF) Descriptor() ([]byte, []int)

Deprecated: Use StdinEOF.ProtoReflect.Descriptor instead.

func (*StdinEOF) ProtoMessage

func (*StdinEOF) ProtoMessage()

func (*StdinEOF) ProtoReflect

func (x *StdinEOF) ProtoReflect() protoreflect.Message

func (*StdinEOF) Reset

func (x *StdinEOF) Reset()

func (*StdinEOF) String

func (x *StdinEOF) String() string

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer writes frames; it is safe for concurrent use, so stdout and stderr can share a connection.

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter returns a Writer on w.

func (*Writer) Write

func (w *Writer) Write(f *Frame) error

Write sets the version and writes f as one length-delimited message.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL