vsrpc

Documentation

Overview

Package vsrpc provides the RPC server that Visual Studio uses to interact with azd programmatically.

The RPC server is implemented using JSON-RPC 2.0 over WebSockets.

Index

• Constants
• type AspireHost
• type DeleteMode
• type DeploymentResult
• type Environment
• type EnvironmentInfo
• type Handler
  • func NewHandler(f any) Handler
• type InitializeServerOptions
• type MessageKind
• type MessageSeverity
• type Observer
  • func (o *Observer[T]) OnCompleted(ctx context.Context) error
  • func (o *Observer[T]) OnNext(ctx context.Context, value T) error
  • func (o *Observer[T]) UnmarshalJSON(data []byte) error
• type ProgressMessage
  • func (m ProgressMessage) WithMessage(message string) ProgressMessage
• type RequestContext
• type Resource
• type Server
  • func NewServer(rootContainer *ioc.NestedContainer) *Server
  • func (s *Server) Serve(l net.Listener) error
• type Service
• type Session

Constants

const (
	DeleteModeLocal = 1 << iota
	DeleteModeAzureResources
)

Types

type AspireHost

type AspireHost struct {
	Name     string
	Path     string
	Services []*Service
}

type DeleteMode

type DeleteMode uint32

type DeploymentResult

type DeploymentResult struct {
	Success      bool
	Time         time.Time
	Message      string
	DeploymentId string
}

type Environment

type Environment struct {
	Name           string
	IsCurrent      bool
	Properties     map[string]string
	Services       []*Service
	Values         map[string]string
	LastDeployment *DeploymentResult `json:",omitempty"`
	Resources      []*Resource
}

type EnvironmentInfo

type EnvironmentInfo struct {
	Name       string
	IsCurrent  bool
	DotEnvPath string
}

type Handler

type Handler func(ctx context.Context, conn jsonrpc2.Conn, reply jsonrpc2.Replier, req jsonrpc2.Request) error

Handler is the type of function that handles incoming RPC requests.

func NewHandler

func NewHandler(f any) Handler

NewHandler is a generic helper for creating a Handler from an arbitrary function. The function must:

- Take a context.Context as its first argument. - Return either an error or a value and an error.

If f does not meet these requirements, NewHandler will panic.

type InitializeServerOptions

type InitializeServerOptions struct {
	// When non nil, AuthenticationEndpoint is the endpoint to connect to for authentication. It is in the same form as
	// expected by the AZD_AUTH_ENDPOINT environment variable. Note that both AuthenticationEndpoint and AuthenticationKey
	// need to be set for external authentication to be used.
	AuthenticationEndpoint *string `json:",omitempty"`
	// When non nil, AuthenticationKey is the key to use for authenticating to the server. It is in the same form as
	// expected by the AZD_AUTH_KEY environment variable. Note that both AuthenticationEndpoint and AuthenticationKey
	// need to be set for external authentication to be used.
	AuthenticationKey *string `json:",omitempty"`
	// When non nil, AuthenticationCertificate is a base64-encoded x509 certificate used to trust and
	// secure the communications to the server. It is in the same form as the AZD_AUTH_CERT environment variable.
	AuthenticationCertificate *string `json:",omitempty"`
}

type MessageKind

type MessageKind int

const (
	Logging MessageKind = iota
	Important
)

type MessageSeverity

type MessageSeverity int

const (
	Info MessageSeverity = iota
	Warning
	Error
)

type Observer

type Observer[T any] struct {
	// contains filtered or unexported fields
}

Observer is treated special by our JSON-RPC implementation and plays nicely with StreamJsonRpc's ideas on how to marshal an Observer<T> in .NET.

The way this works is that that we can send a notification back to to the server with the method `$/invokeProxy/{handle}/{onCompleted|onNext}`. When marshalled as an argument, the wire format of Observer<T> is:

{
  "__jsonrpc_marshaled": 1,
  "handle": <some-integer>
}

func (*Observer[T]) OnCompleted

func (o *Observer[T]) OnCompleted(ctx context.Context) error

func (*Observer[T]) OnNext

func (o *Observer[T]) OnNext(ctx context.Context, value T) error

func (*Observer[T]) UnmarshalJSON

func (o *Observer[T]) UnmarshalJSON(data []byte) error

type ProgressMessage

type ProgressMessage struct {
	Message            string
	Severity           MessageSeverity
	Time               time.Time
	Kind               MessageKind
	Code               string
	AdditionalInfoLink string
}

func (ProgressMessage) WithMessage

func (m ProgressMessage) WithMessage(message string) ProgressMessage

WithMessage returns a new ProgressMessage with the given message and timestamp set to now.

type RequestContext

type RequestContext struct {
	// The active session.
	Session Session

	// The app host project path.
	HostProjectPath string
}

RequestContext provides the context for a request to the server. It identifies the active session and the azd project being operated on.

type Resource

type Resource struct {
	Name string
	Type string
	Id   string
}

type Server

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

func NewServer

func NewServer(rootContainer *ioc.NestedContainer) *Server

func (*Server) Serve

func (s *Server) Serve(l net.Listener) error

Serve calls http.Serve with the given listener and a handler that serves the VS RPC protocol.

type Service

type Service struct {
	Name       string
	IsExternal bool
	Path       string
	Endpoint   *string `json:",omitempty"`
	ResourceId *string `json:",omitempty"`
}

type Session

type Session struct {
	Id string
}

Session represents an active connection to the server. It is returned by InitializeAsync and holds an opaque connection id that the server can use to identify the client across multiple RPC calls (since our service is exposed over multiple endpoints a single client may have multiple connections to the server, and we want a way to correlate them so we can cache state across connections).