envelope

Documentation

Overview

Package envelope implements a sidecar-like process that connects a weavelet to its environment.

Index

• type Envelope
  • func NewEnvelope(ctx context.Context, wlet *protos.EnvelopeInfo, config *protos.AppConfig) (*Envelope, error)
  • func (e *Envelope) GetHealth() protos.HealthStatus
  • func (e *Envelope) GetLoad() (*protos.LoadReport, error)
  • func (e *Envelope) GetMetrics() ([]*metrics.MetricSnapshot, error)
  • func (e *Envelope) GetProfile(req *protos.GetProfileRequest) ([]byte, error)
  • func (e *Envelope) Pid() int
  • func (e *Envelope) Serve(h EnvelopeHandler) error
  • func (e *Envelope) UpdateComponents(components []string) error
  • func (e *Envelope) UpdateRoutingInfo(routing *protos.RoutingInfo) error
  • func (e *Envelope) WeaveletInfo() *protos.WeaveletInfo
• type EnvelopeHandler

Types

type Envelope

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

Envelope starts and manages a weavelet in a subprocess.

For more information, refer to runtime/protos/runtime.proto and https://serviceweaver.dev/blog/deployers.html.

func NewEnvelope

func NewEnvelope(ctx context.Context, wlet *protos.EnvelopeInfo, config *protos.AppConfig) (*Envelope, error)

NewEnvelope creates a new envelope, starting a weavelet subprocess and establishing a bidirectional connection with it. The weavelet process can be stopped at any time by canceling the passed-in context.

You can issue RPCs *to* the weavelet using the returned Envelope. To start receiving messages *from* the weavelet, call [Serve].

func (*Envelope) GetHealth

func (e *Envelope) GetHealth() protos.HealthStatus

GetHealth returns the health status of the weavelet.

func (*Envelope) GetLoad

func (e *Envelope) GetLoad() (*protos.LoadReport, error)

GetLoad gets a load report from the weavelet.

func (*Envelope) GetMetrics

func (e *Envelope) GetMetrics() ([]*metrics.MetricSnapshot, error)

GetMetrics returns a weavelet's metrics.

func (*Envelope) GetProfile

func (e *Envelope) GetProfile(req *protos.GetProfileRequest) ([]byte, error)

GetProfile gets a profile from the weavelet.

func (*Envelope) Pid

func (e *Envelope) Pid() int

Pid returns the process id of the subprocess.

func (*Envelope) Serve

func (e *Envelope) Serve(h EnvelopeHandler) error

Serve accepts incoming messages from the weavelet. RPC requests are handled serially in the order they are received. Serve blocks until the connection terminates, returning the error that caused it to terminate. You can cancel the connection by cancelling the context passed to NewEnvelope. This method never returns a non-nil error.

func (*Envelope) UpdateComponents

func (e *Envelope) UpdateComponents(components []string) error

UpdateComponents updates the weavelet with the latest set of components it should be running.

func (*Envelope) UpdateRoutingInfo

func (e *Envelope) UpdateRoutingInfo(routing *protos.RoutingInfo) error

UpdateRoutingInfo updates the weavelet with a component's most recent routing info.

func (*Envelope) WeaveletInfo

func (e *Envelope) WeaveletInfo() *protos.WeaveletInfo

WeaveletInfo returns information about the started weavelet.

type EnvelopeHandler

type EnvelopeHandler interface {
	// ActivateComponent ensures that the provided component is running
	// somewhere. A call to ActivateComponent also implicitly signals that a
	// weavelet is interested in receiving routing info for the component.
	ActivateComponent(context.Context, *protos.ActivateComponentRequest) (*protos.ActivateComponentReply, error)

	// GetListenerAddress returns the address the weavelet should listen on for
	// a particular listener.
	GetListenerAddress(context.Context, *protos.GetListenerAddressRequest) (*protos.GetListenerAddressReply, error)

	// ExportListener exports the provided listener. Exporting a listener
	// typically, but not always, involves running a proxy that forwards
	// traffic to the provided address.
	ExportListener(context.Context, *protos.ExportListenerRequest) (*protos.ExportListenerReply, error)

	// GetSelfCertificate returns the certificate and the private key the
	// weavelet should use for network connection establishment. The weavelet
	// will issue this request each time it establishes a connection with
	// another weavelet.
	// NOTE: This method is only called if mTLS was enabled for the weavelet,
	// by passing it an EnvelopeInfo with mtls=true.
	GetSelfCertificate(context.Context, *protos.GetSelfCertificateRequest) (*protos.GetSelfCertificateReply, error)

	// VerifyClientCertificate verifies the certificate chain presented by
	// a network client attempting to connect to the weavelet. It returns an
	// error if the network connection should not be established with the
	// client. Otherwise, it returns the list of weavelet components that the
	// client is authorized to invoke methods on.
	//
	// NOTE: This method is only called if mTLS was enabled for the weavelet,
	// by passing it an EnvelopeInfo with mtls=true.
	VerifyClientCertificate(context.Context, *protos.VerifyClientCertificateRequest) (*protos.VerifyClientCertificateReply, error)

	// VerifyServerCertificate verifies the certificate chain presented by
	// the server the weavelet is attempting to connect to. It returns an
	// error iff the server identity doesn't match the identity of the specified
	// component.
	//
	// NOTE: This method is only called if mTLS was enabled for the weavelet,
	// by passing it an EnvelopeInfo with mtls=true.
	VerifyServerCertificate(context.Context, *protos.VerifyServerCertificateRequest) (*protos.VerifyServerCertificateReply, error)

	// HandleLogEntry handles a log entry.
	HandleLogEntry(context.Context, *protos.LogEntry) error

	// HandleTraceSpans handles a set of trace spans.
	HandleTraceSpans(context.Context, *protos.TraceSpans) error
}

EnvelopeHandler handles messages from the weavelet. Values passed to the handlers are only valid for the duration of the handler's execution.