shell

Documentation

Overview

Package shell contains a shell service, along with a gRPC server and client

Index

• Constants
• Variables
• func Named(name string) resource.Name
• func NewRPCServiceServer(coll resource.APIResourceCollection[Service]) interface{}
• type CopyFilesSourceType
  • func CopyFilesSourceTypeFromProto(p servicepb.CopyFilesSourceType) CopyFilesSourceType
  • func (t CopyFilesSourceType) String() string
  • func (t CopyFilesSourceType) ToProto() servicepb.CopyFilesSourceType
• type File
• type FileCopier
• type FileCopyFactory
  • func NewCopyFileToMachineFactory(destination string, preserve bool, shellSvc Service) FileCopyFactory
  • func NewLocalFileCopyFactory(destination string, preserve bool, relativeToHome bool) (FileCopyFactory, error)
• type FileReadCopier
  • func NewLocalFileReadCopier(paths []string, allowRecursive bool, relativeToHome bool, ...) (FileReadCopier, error)
• type Output
• type Service
  • func NewClientFromConn(ctx context.Context, conn rpc.ClientConn, remoteName string, ...) (Service, error)

Constants

const SubtypeName = "shell"

SubtypeName is the name of the type of service.

Variables

var API = resource.APINamespaceRDK.WithServiceType(SubtypeName)

API is a variable that identifies the shell service resource API.

var ErrMsgDirectoryCopyRequestNoRecursion = "file is a directory but copy recursion not used"

ErrMsgDirectoryCopyRequestNoRecursion should be returned when a file is included in a path for a copy request where recursion is not enabled.

Functions

func Named

func Named(name string) resource.Name

Named is a helper for getting the named service's typed resource name.

func NewRPCServiceServer

func NewRPCServiceServer(coll resource.APIResourceCollection[Service]) interface{}

NewRPCServiceServer constructs a framesystem gRPC service server. It is intentionally untyped to prevent use outside of tests.

Types

type CopyFilesSourceType

type CopyFilesSourceType int

CopyFilesSourceType indicates the types of files being transmitted.

const (
	// CopyFilesSourceTypeSingleFile is just one normal file being copied.
	CopyFilesSourceTypeSingleFile CopyFilesSourceType = iota
	// CopyFilesSourceTypeSingleDirectory is one top-level directory being
	// copied but the transmission may contain many files. This disambiguates
	// where to place the directory versus multiple files. Multiple files always
	// go within the target destination, but a single directory may be renamed
	// at the top depending on if the target destination exists or not. Either
	// way, the receiving side needs to know what is being worked with. This
	// is a consequence of mimicking SCP and is admittedly a bit involved as well
	// as probably annoying to implement correctly.
	CopyFilesSourceTypeSingleDirectory
	// CopyFilesSourceTypeMultipleFiles indicates multiple files will be transmitted.
	CopyFilesSourceTypeMultipleFiles
	// CopyFilesSourceTypeMultipleUnknown should never be used.
	CopyFilesSourceTypeMultipleUnknown
)

func CopyFilesSourceTypeFromProto

func CopyFilesSourceTypeFromProto(p servicepb.CopyFilesSourceType) CopyFilesSourceType

CopyFilesSourceTypeFromProto converts from proto to native.

func (CopyFilesSourceType) String

func (t CopyFilesSourceType) String() string

String returns a human-readable string of the type.

func (CopyFilesSourceType) ToProto

func (t CopyFilesSourceType) ToProto() servicepb.CopyFilesSourceType

ToProto converts from native to proto.

type File

type File struct {
	// RelativeName is the filesystem agnostic name.
	// For example, ~/my/file would appear as my/file.
	RelativeName string
	// The underlying data for the File and it must have
	// a non-nil fs.FileInfo.
	Data fs.File
}

A File is a complete File to be sent/received.

type FileCopier

type FileCopier interface {
	Copy(ctx context.Context, file File) error
	Close(ctx context.Context) error
}

A FileCopier receives files to copy into some implementation specific location. It is only safe to call for one file at a time.

type FileCopyFactory

type FileCopyFactory interface {
	MakeFileCopier(ctx context.Context, sourceType CopyFilesSourceType) (FileCopier, error)
}

A FileCopyFactory is used to create FileCopiers when the CopyFilesSourceType is not known until a later time. For example, asking to copy files from a machine results in an RPC that is likely to be handled by a method that knows how to make FileCopiers, but not what kind yet. This is a consequence of the current flow of operations and in the future the factory may become obviated.

func NewCopyFileToMachineFactory

func NewCopyFileToMachineFactory(
	destination string,
	preserve bool,
	shellSvc Service,
) FileCopyFactory

NewCopyFileToMachineFactory returns a simple FileCopyFactory that calls a service's CopyFilesToMachine method once the CopyFilesSourceType is discovered by the initiating process.

func NewLocalFileCopyFactory

func NewLocalFileCopyFactory(
	destination string,
	preserve bool,
	relativeToHome bool,
) (FileCopyFactory, error)

NewLocalFileCopyFactory returns a FileCopyFactory that is responsible for making FileCopiers that copy from the local filesystem. The destination is used later on in tandem with a the CopyFilesSourceType passed into MakeFileCopier.

type FileReadCopier

type FileReadCopier interface {
	ReadAll(ctx context.Context) error
	Close(ctx context.Context) error
}

A FileReadCopier is mostly a tee-like utility to read all files from somewhere and pass them through to some bound-to, underlying FileCopier. Similar to the FileCopyFactory, this abstraction exists so as to promote re-use across client/server interactions while reducing some extra abstractions like a FileReader/FileIterator.

func NewLocalFileReadCopier

func NewLocalFileReadCopier(
	paths []string,
	allowRecursive bool,
	relativeToHome bool,
	copyFactory FileCopyFactory,
) (FileReadCopier, error)

NewLocalFileReadCopier returns a FileReadCopier that will have its ReadAll method iteratively copy each file found indicated by paths into a FileCopier created by the FileCopyFactory. The Factory is used since we don't yet know what type of files we are going to copy until ReadAll is called.

type Output

type Output struct {
	Output string // reflects stdout
	Error  string // reflects stderr
	EOF    bool
}

Output reflects an instance of shell output on either stdout or stderr.

type Service

type Service interface {
	resource.Resource
	Shell(ctx context.Context, extra map[string]interface{}) (
		input chan<- string, oobInput chan<- map[string]interface{}, output <-chan Output, retErr error)

	// CopyFilesToMachines copies a stream of files from a client to the connected-to machine.
	// Initially, metadata is sent to describe the destination in the filesystem in addition
	// to what kind of file(s) are being sent. A FileCopier is returned that can be used
	// to copy files one by one-by-one. When files are done being copied, the returned FileCopier
	// MUST be closed. Returning a FileCopier over passing in the files was chosen so as to promote
	// the streaming of files, less copies of memory, and less open files.
	CopyFilesToMachine(
		ctx context.Context,
		sourceType CopyFilesSourceType,
		destination string,
		preserve bool,
		extra map[string]interface{},
	) (FileCopier, error)

	// CopyFilesFromMachine copies a stream of files from a connected-to machine to the calling client.
	// Essentially, it is the inverse of CopyFilesToMachine. The FileCopyFactory passed in will be
	// called once the service knows what kinds of files are being transmitted and that FileCopier
	// will be passed all the files to be copied one-by-one. The method will return once all files
	// are copied or an error happens in between.
	CopyFilesFromMachine(
		ctx context.Context,
		paths []string,
		allowRecursion bool,
		preserve bool,
		copyFactory FileCopyFactory,
		extra map[string]interface{},
	) error
}

A Service handles shells for a local robot.

func NewClientFromConn

func NewClientFromConn(
	ctx context.Context,
	conn rpc.ClientConn,
	remoteName string,
	name resource.Name,
	logger logging.Logger,
) (Service, error)

NewClientFromConn constructs a new Client from connection passed in.