Documentation
¶
Overview ¶
Package system is ormos on a personal machine: it opens a single outbound WebSocket to the relay and serves terminal and port-proxy streams multiplexed over it. With no arguments it runs the tunnel; with a TTY it also shows a Bubble Tea status dashboard.
Supported platforms ¶
Linux and macOS. Every file in this package carries //go:build (linux && !android) || (darwin && !ios), and that is the whole statement.
The agent's job is to act on the machine it runs on: allocate a PTY, poll its master descriptor, read a terminal's foreground process group, deliver SIGHUP and then SIGKILL to a shell that will not exit, and take a file lock over the audit log. That is golang.org/x/sys/unix, which has no Windows implementation of any of it, so `go build .` for Windows reports that the package does not exist there rather than listing the symbols it is missing.
The tag names the two platforms rather than saying `unix`, which would also select the BSDs and Solaris. Nothing here is tested on those, and this is a program that hands out shells on the machine it runs on — the PTY and process-group paths are exactly the code that misbehaves quietly on a kernel nobody exercised. A build tag is a claim about where this is known to work, so it must not be wider than the set CI actually runs.
The !android and !ios halves are not pedantry: Go sets the linux tag on android and the darwin tag on ios, so a plain `linux || darwin` silently included both, and the whole agent selected and built for them. Android is Linux — /proc/net/tcp parsing, PTY allocation and process-group signalling all compile there, on a security model nothing here has considered.
CI holds up both halves: a macos-latest job runs the suite, and a step in ci.yml asserts that on every other platform Go knows about — Windows, the BSDs, Solaris, illumos, AIX, plan9, wasm, android and ios — nothing but relay is even selected. Without that step the claim would be unenforceable — `go build ./...` SKIPS packages with no buildable files, so a file that lost its tag would go unnoticed by every build in the pipeline.
The shared relay package is deliberately untagged: it is pure Go, the hosted relay imports it, and it cross-compiles for Windows today.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTerminalInputBackpressure means a local Write was not accepted. Callers // may retry after consuming output or yielding; bytes are never dropped. ErrTerminalInputBackpressure = errors.New("terminal input backpressure") // ErrTerminalInputTooLarge means one input exceeds the fixed per-call limit // and cannot become acceptable by retrying. ErrTerminalInputTooLarge = errors.New("terminal input is too large") // ErrTerminalClientClosed means this attachment has detached or its session // ended. It never means the shared shell was killed by the attachment. ErrTerminalClientClosed = errors.New("terminal attachment is closed") )
Functions ¶
func Main ¶
Main accepts `ormos`, `ormos --config PATH`, `ormos --help` and `ormos --version`, and nothing else — no `-h` shorthand, no subcommands. Parsed by hand rather than with the flag package, which would accept single-dash spellings and add its own -h.
The version is passed in rather than declared here: it is stamped at release time with -ldflags "-X main.version=...", and main is the one package name that flag can name without knowing this directory's import path.
Types ¶
type PortStatus ¶
PortStatus is one configured exposed port for this system, with whether it is currently being served (a local process is listening on it).
type Status ¶
type Status struct {
Connected bool
Sessions int
RelayURL string
Live map[int]bool // host's currently-listening ports (for live highlighting)
}
Status is a snapshot of system state for the TUI.
It carries only what a render actually reads. It used to also copy the whole log ring and d.ports on every call — 500ms, forever — into a Status.Logs and a Status.Ports nothing outside a test ever looked at. The ring now has a real consumer and is fetched by the tail through RecentLogs; Status.Ports is gone, because the TUI lists projects and ports from the relay's own reply (model.projects) and needs Live only to mark which of them are up.
d.ports itself stays: cachedPortConfigured reads it on the proxy port-allow path. It is only the per-render COPY of it that had no reader.
type TerminalClient ¶ added in v0.1.10
type TerminalClient struct {
// contains filtered or unexported fields
}
TerminalClient is a local attachment to a terminal session. Output is raw terminal bytes, including the reset-prefixed bounded replay sent on attach and resynchronisation. Callers must treat output slices as read-only.
Detach releases only this attachment; the session remains alive while any browser or local attachment remains, then follows terminalDetachTTL.
func (*TerminalClient) Detach ¶ added in v0.1.10
func (c *TerminalClient) Detach()
Detach releases this local attachment without ending its shared shell.
func (*TerminalClient) Done ¶ added in v0.1.10
func (c *TerminalClient) Done() <-chan struct{}
func (*TerminalClient) Output ¶ added in v0.1.10
func (c *TerminalClient) Output() <-chan []byte
Output is the bounded stream of terminal output for this attachment. It is not closed; receive it with Done. Done closes on Detach, slow-reader eviction, session/process exit, or policy revocation.
func (*TerminalClient) Resize ¶ added in v0.1.10
func (c *TerminalClient) Resize(cols, rows int) error
Resize updates the shared PTY's dimensions.
func (*TerminalClient) Write ¶ added in v0.1.10
func (c *TerminalClient) Write(p []byte) error
Write copies and queues input for the shared PTY without blocking on a non-reading slave. Local writes keep their acceptance order. Each live local attachment holds at most 256 accepted queued-or-in-flight calls and 1 MiB of implementation-owned copied bytes; rejected calls retain no copy. Success means admission completed before Detach; teardown may discard those accepted bytes. It returns ErrTerminalInputBackpressure when retrying may work, ErrTerminalInputTooLarge for a permanently oversized call, and ErrTerminalClientClosed after this attachment ends.
Source Files