README
¶
wsep
wsep is a high performance command execution protocol over WebSocket. It can be thought of as SSH over WebSockets without encryption.
The package offers the wsep.Execer interface so that local, SSH, and WebSocket execution can be interchanged. This is particular useful when testing.
Examples
Error handling is omitted for brevity.
Client
conn, _, _ := websocket.Dial(ctx, "ws://remote.exec.addr", nil)
defer conn.Close(websocket.StatusAbnormalClosure, "terminate process")
execer := wsep.RemoteExecer(conn)
process, _ := execer.Start(ctx, wsep.Command{
Command: "cat",
Args: []string{"go.mod"},
Stdin: false,
})
go io.Copy(os.Stderr, process.Stderr())
go io.Copy(os.Stdout, process.Stdout())
process.Wait()
conn.Close(websocket.StatusNormalClosure, "normal closure")
Server
func (s server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
conn, _ := websocket.Accept(w, r, nil)
wsep.Serve(r.Context(), conn, wsep.LocalExecer{})
ws.Close(websocket.StatusNormalClosure, "normal closure")
}
Development / Testing
Start a local executor:
go run ./dev/server
Start a client:
go run ./dev/client tty --id 1 -- bash
go run ./dev/client notty -- ls -la
Benchmarks
Local sh through a local wsep connection
$ head -c 100000000 /dev/urandom > /tmp/random; cat /tmp/random | pv | time ./bin/client notty -- sh -c "cat > /dev/null"
95.4MiB 0:00:00 [ 269MiB/s] [ <=> ]
./bin/client notty -- sh -c "cat > /dev/null" 0.32s user 0.31s system 31% cpu 2.019 total
Local sh directly
$ head -c 100000000 /dev/urandom > /tmp/random; cat /tmp/random | pv | time sh -c "cat > /dev/null"
95.4MiB 0:00:00 [1.73GiB/s] [ <=> ]
sh -c "cat > /dev/null" 0.00s user 0.02s system 32% cpu 0.057 total
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Command ¶
type Command struct {
// ID allows reconnecting commands that have a TTY.
ID string
Command string
Args []string
TTY bool
Stdin bool
UID uint32
GID uint32
Env []string
WorkingDir string
}
Command represents an external command to be run
type Execer ¶
Execer starts commands.
func RemoteExecer ¶
RemoteExecer creates an execution interface from a WebSocket connection.
type LocalExecer ¶
type LocalExecer struct {
// ChildProcessPriority overrides the default niceness of all child processes launch by LocalExecer.
ChildProcessPriority *int
}
LocalExecer executes command on the local system.
type Process ¶
type Process interface {
// Pid is populated immediately during a successful start with the process ID.
Pid() int
// Stdout returns an io.WriteCloser that will pipe writes to the remote command.
// Closure of stdin sends the corresponding close message.
Stdin() io.WriteCloser
// Stdout returns an io.Reader that is connected to the command's standard output.
Stdout() io.Reader
// Stderr returns an io.Reader that is connected to the command's standard error.
Stderr() io.Reader
// Resize resizes the TTY if a TTY is enabled.
Resize(ctx context.Context, rows, cols uint16) error
// Wait returns ExitError when the command terminates with a non-zero exit code.
Wait() error
// Close terminates the process and underlying connection(s).
// It must be called otherwise a connection or process may leak.
Close() error
}
Process represents a started command.
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.