envelope

Documentation

Overview

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

Index

• type Child
• type Envelope
  • func NewEnvelope(ctx context.Context, wlet *protos.WeaveletArgs, 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, bool)
  • 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) WeaveletAddress() string
  • func (e *Envelope) WeaveletControl() control.WeaveletControl
• type EnvelopeHandler
• type InProcessChild
  • func NewInProcessChild() *InProcessChild
  • func (p *InProcessChild) Args() *protos.WeaveletArgs
  • func (p *InProcessChild) Pid() (int, bool)
  • func (p *InProcessChild) Start(ctx context.Context, config *protos.AppConfig, args *protos.WeaveletArgs) error
  • func (p *InProcessChild) Stderr() io.ReadCloser
  • func (p *InProcessChild) Stdout() io.ReadCloser
  • func (p *InProcessChild) Wait() error
• type Options
• type ProcessChild
  • func (p *ProcessChild) Pid() (int, bool)
  • func (p *ProcessChild) Start(ctx context.Context, config *protos.AppConfig, args *protos.WeaveletArgs) error
  • func (p *ProcessChild) Stderr() io.ReadCloser
  • func (p *ProcessChild) Stdout() io.ReadCloser
  • func (p *ProcessChild) Wait() error

Types

type Child

type Child interface {
	// Start starts the child.
	// REQUIRES: Start, Wait have not been called.
	Start(context.Context, *protos.AppConfig, *protos.WeaveletArgs) error

	// Wait for the child to exit.
	// REQUIRES: Start has been called.
	// REQUIRES: Wait has not been called.
	Wait() error

	// Different IO streams connecting us to the child
	Stdout() io.ReadCloser // Delivers Child stdout
	Stderr() io.ReadCloser // Delivers Child stderr

	// Identifier for child process, if available.
	Pid() (int, bool)
}

Child manages the child of an envelope. This is typically a child process, but tests may manage some in-process resources.

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.WeaveletArgs, config *protos.AppConfig, options Options) (*Envelope, error)

NewEnvelope creates a new envelope, starting a weavelet subprocess (via child.Start) 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, bool)

Pid returns the process id of the weavelet, if it is running in a separate process.

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) WeaveletAddress

func (e *Envelope) WeaveletAddress() string

WeaveletAddress returns the address that other components should dial to communicate with the weavelet.

func (*Envelope) WeaveletControl

func (e *Envelope) WeaveletControl() control.WeaveletControl

WeaveletControl returns the controller component for the weavelet managed by this envelope.

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 a WeaveletArgs 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 a WeaveletArgs 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 a WeaveletArgs with mtls=true.
	VerifyServerCertificate(context.Context, *protos.VerifyServerCertificateRequest) (*protos.VerifyServerCertificateReply, error)

	// LogBatches handles a batch of log entries.
	LogBatch(context.Context, *protos.LogEntryBatch) 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.

type InProcessChild

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

InProcessChild is a fake envelope.Child that represents the in-process weavelet.

func NewInProcessChild

func NewInProcessChild() *InProcessChild

func (*InProcessChild) Args

func (p *InProcessChild) Args() *protos.WeaveletArgs

func (*InProcessChild) Pid

func (p *InProcessChild) Pid() (int, bool)

func (*InProcessChild) Start

func (p *InProcessChild) Start(ctx context.Context, config *protos.AppConfig, args *protos.WeaveletArgs) error

func (*InProcessChild) Stderr

func (p *InProcessChild) Stderr() io.ReadCloser

func (*InProcessChild) Stdout

func (p *InProcessChild) Stdout() io.ReadCloser

func (*InProcessChild) Wait

func (p *InProcessChild) Wait() error

type Options

type Options struct {
	// Override for temporary directory.
	TmpDir string

	// Logger is used for logging internal messages. If nil, a default logger is used.
	Logger *slog.Logger

	// Tracer is used for tracing internal calls. If nil, internal calls are not traced.
	Tracer trace.Tracer

	// Child is used to run the weavelet. If nil, a sub-process is created.
	Child Child
}

Options contains optional arguments for the envelope.

type ProcessChild

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

ProcessChild is a Child implemented as a process.

func (*ProcessChild) Pid

func (p *ProcessChild) Pid() (int, bool)

func (*ProcessChild) Start

func (p *ProcessChild) Start(ctx context.Context, config *protos.AppConfig, args *protos.WeaveletArgs) error

func (*ProcessChild) Stderr

func (p *ProcessChild) Stderr() io.ReadCloser

func (*ProcessChild) Stdout

func (p *ProcessChild) Stdout() io.ReadCloser

func (*ProcessChild) Wait

func (p *ProcessChild) Wait() error