liveshare

Documentation

Overview

Package liveshare is a Go client library for the Visual Studio Live Share service, which provides collaborative, distributed editing and debugging. See https://docs.microsoft.com/en-us/visualstudio/liveshare for an overview.

It provides the ability for a Go program to connect to a Live Share workspace (Connect), to expose a TCP port on a remote host (UpdateSharedVisibility), to start an SSH server listening on an exposed port (StartSSHServer), and to forward connections between the remote port and a local listening TCP port (ForwardToListener) or a local Go reader/writer (Forward).

Index

• type ChannelID
• type Options
• type Port
• type PortChangeKind
• type PortForwarder
  • func NewPortForwarder(session portForwardingSession, name string, remotePort int, keepAlive bool) *PortForwarder
  • func (fwd *PortForwarder) Forward(ctx context.Context, conn io.ReadWriteCloser) error
  • func (fwd *PortForwarder) ForwardToListener(ctx context.Context, listen net.Listener) (err error)
• type PortNotification
• type Session
  • func Connect(ctx context.Context, opts Options) (*Session, error)
  • func (s *Session) Close() error
  • func (s *Session) GetSharedServers(ctx context.Context) ([]*Port, error)
  • func (s *Session) KeepAlive(reason string)
  • func (s *Session) OpenStreamingChannel(ctx context.Context, id ChannelID) (ssh.Channel, error)
  • func (s *Session) RebuildContainer(ctx context.Context, full bool) error
  • func (s *Session) StartJupyterServer(ctx context.Context) (int, string, error)
  • func (s *Session) StartSSHServer(ctx context.Context) (int, string, error)
  • func (s *Session) StartSSHServerWithOptions(ctx context.Context, options StartSSHServerOptions) (int, string, error)
  • func (s *Session) StartSharing(ctx context.Context, sessionName string, port int) (ChannelID, error)
  • func (s *Session) UpdateSharedServerPrivacy(ctx context.Context, port int, visibility string) error
  • func (s *Session) WaitForPortNotification(ctx context.Context, port int, notifType PortChangeKind) (*PortNotification, error)
• type StartSSHServerOptions

Types

type ChannelID

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

A ChannelID is an identifier for an exposed port on a remote container that may be used to open an SSH channel to it.

type Options

type Options struct {
	ClientName     string // ClientName is the name of the connecting client.
	SessionID      string
	SessionToken   string // token for SSH session
	RelaySAS       string
	RelayEndpoint  string
	HostPublicKeys []string
	Logger         logger      // required
	TLSConfig      *tls.Config // (optional)
}

An Options specifies Live Share connection parameters.

type Port

type Port struct {
	SourcePort                       int    `json:"sourcePort"`
	DestinationPort                  int    `json:"destinationPort"`
	SessionName                      string `json:"sessionName"`
	StreamName                       string `json:"streamName"`
	StreamCondition                  string `json:"streamCondition"`
	BrowseURL                        string `json:"browseUrl"`
	IsPublic                         bool   `json:"isPublic"`
	IsTCPServerConnectionEstablished bool   `json:"isTCPServerConnectionEstablished"`
	HasTLSHandshakePassed            bool   `json:"hasTLSHandshakePassed"`
	Privacy                          string `json:"privacy"`
}

Port describes a port exposed by the container.

type PortChangeKind

type PortChangeKind string

const (
	PortChangeKindStart  PortChangeKind = "start"
	PortChangeKindUpdate PortChangeKind = "update"
)

type PortForwarder

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

A PortForwarder forwards TCP traffic over a Live Share session from a port on a remote container to a local destination such as a network port or Go reader/writer.

func NewPortForwarder

func NewPortForwarder(session portForwardingSession, name string, remotePort int, keepAlive bool) *PortForwarder

NewPortForwarder returns a new PortForwarder for the specified remote port and Live Share session. The name describes the purpose of the remote port or service. The keepAlive flag indicates whether the session should be kept alive with port forwarding traffic.

func (*PortForwarder) Forward

func (fwd *PortForwarder) Forward(ctx context.Context, conn io.ReadWriteCloser) error

Forward forwards traffic between the container's remote port and the specified read/write stream. On return, the stream is closed.

func (*PortForwarder) ForwardToListener

func (fwd *PortForwarder) ForwardToListener(ctx context.Context, listen net.Listener) (err error)

ForwardToListener forwards traffic between the container's remote port and a local port, which must already be listening for connections. (Accepting a listener rather than a port number avoids races against other processes opening ports, and against a client connecting to the socket prematurely.)

ForwardToListener accepts and handles connections on the local port until it encounters the first error, which may include context cancellation. Its error result is always non-nil. The caller is responsible for closing the listening port.

type PortNotification

type PortNotification struct {
	Success bool // Helps us disambiguate between the SharingSucceeded/SharingFailed events
	// The following are properties included in the SharingSucceeded/SharingFailed events sent by the server sharing service in the Codespace
	Port        int            `json:"port"`
	ChangeKind  PortChangeKind `json:"changeKind"`
	ErrorDetail string         `json:"errorDetail"`
	StatusCode  int            `json:"statusCode"`
}

type Session

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

A Session represents the session between a connected Live Share client and server.

func Connect

func Connect(ctx context.Context, opts Options) (*Session, error)

Connect connects to a Live Share workspace specified by the options, and returns a session representing the connection. The caller must call the session's Close method to end the session.

func (*Session) Close

func (s *Session) Close() error

Close should be called by users to clean up RPC and SSH resources whenever the session is no longer active.

func (*Session) GetSharedServers

func (s *Session) GetSharedServers(ctx context.Context) ([]*Port, error)

GetSharedServers returns a description of each container port shared by a prior call to StartSharing by some client.

func (*Session) KeepAlive

func (s *Session) KeepAlive(reason string)

KeepAlive accepts a reason that is retained if there is no active reason to send to the server.

func (*Session) OpenStreamingChannel

func (s *Session) OpenStreamingChannel(ctx context.Context, id ChannelID) (ssh.Channel, error)

func (*Session) RebuildContainer

func (s *Session) RebuildContainer(ctx context.Context, full bool) error

func (*Session) StartJupyterServer

func (s *Session) StartJupyterServer(ctx context.Context) (int, string, error)

StartJupyterServer starts a Juypyter server in the container and returns the port on which it listens and the server URL.

func (*Session) StartSSHServer

func (s *Session) StartSSHServer(ctx context.Context) (int, string, error)

StartSSHServer starts an SSH server in the container, installing sshd if necessary, applies specified options, and returns the port on which it listens and the user name clients should provide.

func (*Session) StartSSHServerWithOptions

func (s *Session) StartSSHServerWithOptions(ctx context.Context, options StartSSHServerOptions) (int, string, error)

StartSSHServerWithOptions starts an SSH server in the container, installing sshd if necessary, applies specified options, and returns the port on which it listens and the user name clients should provide.

func (*Session) StartSharing

func (s *Session) StartSharing(ctx context.Context, sessionName string, port int) (ChannelID, error)

StartSharing tells the Live Share host to start sharing the specified port from the container. The sessionName describes the purpose of the remote port or service. It returns an identifier that can be used to open an SSH channel to the remote port.

func (*Session) UpdateSharedServerPrivacy

func (s *Session) UpdateSharedServerPrivacy(ctx context.Context, port int, visibility string) error

UpdateSharedServerPrivacy controls port permissions and visibility scopes for who can access its URLs in the browser.

func (*Session) WaitForPortNotification

func (s *Session) WaitForPortNotification(ctx context.Context, port int, notifType PortChangeKind) (*PortNotification, error)

WaitForPortNotification waits for a port notification to be received. It returns the notification or an error if the notification is not received before the context is cancelled or it fails to parse the notification.

type StartSSHServerOptions

type StartSSHServerOptions struct {
	UserPublicKeyFile string
}