grpcserver

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 11, 2026 License: MIT Imports: 48 Imported by: 0

Documentation

Overview

Package grpcserver implements the DaemonService gRPC service and the interceptors in front of it: those that authenticate a call's token, authorize it by the token's scopes, and audit it. It builds the gRPC servers the daemon serves the API with, on its Unix socket and over TCP.

Handlers validate the request, call the store or the instance manager, and convert the result. They take their dependencies as concrete types.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MetricDescriptions 

func MetricDescriptions() []metric.Description

MetricDescriptions returns the descriptions of every metric the API server serves, for the reference.

func NewSocketServer 

func NewSocketServer(server *Server) *grpc.Server

NewSocketServer returns a gRPC server for server's handlers on the Unix socket, to every call: whoever the socket's mode lets connect has control of the daemon. The audit log names the user and process that made each call.

func NewTCPServer 

func NewTCPServer(server *Server, tlsConfig *tls.Config) *grpc.Server

NewTCPServer returns a gRPC server for server's handlers, over TLS as tlsConfig says, to calls made with a token whose scopes allow them.

Types

type Config 

type Config struct {
	NetworkManager  *network.Manager
	InstanceManager *instance.Manager

	Starters      map[hypervisor.Type][]hypervisor.Starter
	ImageManager  *image.Manager
	KernelManager *kernel.Manager
	VolumeManager *volume.Manager
	TokenManager  *token.Manager

	// Events is the event log GetEvents reads.
	Events *event.Log

	// ListenAddress is the address the TCP listener is bound to, such as
	// [::]:9000, or empty if the API is not served over TCP.
	ListenAddress string

	// HostAddresses returns the host's own addresses, which a TCP listener
	// on all of them is reached at. Nil reports the listener's address as it
	// is.
	HostAddresses func() ([]netip.Addr, error)

	// Fingerprint is the fingerprint of the certificate the daemon is served
	// with over TCP, or empty if it is not.
	Fingerprint string

	// TokenFingerprint is the fingerprint every token carries, for clients
	// to check the daemon by: Fingerprint, or empty for a certificate
	// clients verify for themselves.
	TokenFingerprint string

	// DataDir is the data directory, whose disk GetResources reports on.
	DataDir string

	// CheckHost runs the checks behind the CheckHost call. If it is nil,
	// CheckHost checks nothing.
	CheckHost func(ctx context.Context, opts doctor.Options) iter.Seq[doctor.Result]

	// Version is the daemon's version, as GetHostInfo reports it.
	Version string

	// Keepalive is how the server finds clients that have gone without
	// closing their connection, and how often clients may ping it.
	Keepalive KeepaliveConfig

	// Logger is where the audit log and the calls refused for their token
	// are written. Nil is slog.Default().
	Logger *slog.Logger
}

Config holds the dependencies for creating a Server.

type KeepaliveConfig 

type KeepaliveConfig struct {
	// Interval is how long a connection may carry nothing before the server
	// pings the client.
	Interval time.Duration

	// Timeout is how long the server waits for the answer to a ping before
	// closing the connection.
	Timeout time.Duration

	// MinClientInterval is how often a client may ping the server at most,
	// even with no call in flight. A client pinging more often is
	// disconnected.
	MinClientInterval time.Duration
}

KeepaliveConfig is how the server and its clients check that the other is still there. A zero field is gRPC's default.

type Server 

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

Server implements dicerdv1.DaemonServiceServer through its embedded handlers.

func NewServer 

func NewServer(cfg Config) *Server

NewServer creates a Server with the given configuration.

func (*Server) CheckHost 

func (h *Server) CheckHost(
	req *dicerdv1.CheckHostRequest, stream grpc.ServerStreamingServer[dicerdv1.HostCheckResult],
) error

CheckHost checks that the host can run instances and that they can be reached, and boots a test instance if the request asks for one. It sends each result as soon as it is known. Booting a test instance needs a token with instances:write.

func (*Server) Collect 

func (s *Server) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector.

func (*Server) CopyFromInstance 

func (h *Server) CopyFromInstance(
	req *dicerdv1.CopyFromInstanceRequest, stream grpc.ServerStreamingServer[dicerdv1.CopyFromInstanceResponse],
) error

CopyFromInstance relays an archive out of a running instance to the client.

func (*Server) CopyToInstance 

func (h *Server) CopyToInstance(
	stream grpc.ClientStreamingServer[dicerdv1.CopyToInstanceRequest, emptypb.Empty],
) error

CopyToInstance relays an archive from the client into a running instance.

func (*Server) CreateInstance 

func (h *Server) CreateInstance(
	ctx context.Context, req *dicerdv1.CreateInstanceRequest,
) (*dicerdv1.Instance, error)

CreateInstance records an instance definition, pulling its image as the request's pull policy says. It does not boot anything unless the request asks for it.

func (*Server) CreateNetwork 

func (h *Server) CreateNetwork(
	ctx context.Context, req *dicerdv1.CreateNetworkRequest,
) (*dicerdv1.Network, error)

CreateNetwork records a network and sets up its bridge, refusing a subnet another network or the host is on. Unset gateway, MTU and nameservers take their defaults. A network whose bridge cannot be set up is not created.

func (*Server) CreateSnapshot 

func (h *Server) CreateSnapshot(
	ctx context.Context, req *dicerdv1.CreateSnapshotRequest,
) (*dicerdv1.Snapshot, error)

CreateSnapshot snapshots an instance.

func (*Server) CreateToken 

func (h *Server) CreateToken(ctx context.Context, req *dicerdv1.CreateTokenRequest) (*dicerdv1.IssuedToken, error)

CreateToken records a new token and returns its value, the only time it is returned. A request that names no scopes gets every one.

func (*Server) CreateVolume 

func (h *Server) CreateVolume(
	ctx context.Context, req *dicerdv1.CreateVolumeRequest,
) (*dicerdv1.Volume, error)

CreateVolume creates and formats a volume.

func (*Server) DeleteImage 

func (h *Server) DeleteImage(
	_ context.Context, req *dicerdv1.DeleteImageRequest,
) (*emptypb.Empty, error)

DeleteImage removes an image, refusing one that is in use unless the request forces it.

func (*Server) DeleteInstance 

func (h *Server) DeleteInstance(
	ctx context.Context, req *dicerdv1.DeleteInstanceRequest,
) (*emptypb.Empty, error)

DeleteInstance removes an instance and everything it owns but its volumes. An active instance is refused unless the request forces it.

func (*Server) DeleteKernel 

func (h *Server) DeleteKernel(
	_ context.Context, req *dicerdv1.DeleteKernelRequest,
) (*emptypb.Empty, error)

DeleteKernel removes a kernel and its copy on the host, refusing the default kernel and one an instance or snapshot boots.

func (*Server) DeleteNetwork 

func (h *Server) DeleteNetwork(
	ctx context.Context, req *dicerdv1.DeleteNetworkRequest,
) (*emptypb.Empty, error)

DeleteNetwork removes a network, its allocations and its bridge, refusing the default network and one an instance or snapshot is on.

func (*Server) DeleteSnapshot 

func (h *Server) DeleteSnapshot(
	ctx context.Context, req *dicerdv1.DeleteSnapshotRequest,
) (*emptypb.Empty, error)

DeleteSnapshot removes a snapshot.

func (*Server) DeleteToken 

func (h *Server) DeleteToken(ctx context.Context, req *dicerdv1.DeleteTokenRequest) (*emptypb.Empty, error)

DeleteToken removes a token, which no longer works.

func (*Server) DeleteVolume 

func (h *Server) DeleteVolume(
	_ context.Context, req *dicerdv1.DeleteVolumeRequest,
) (*emptypb.Empty, error)

DeleteVolume removes a volume and its data, refusing one an instance or snapshot mounts.

func (*Server) Describe 

func (s *Server) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

func (*Server) ExecInstance 

func (h *Server) ExecInstance(stream execClientStream) error

ExecInstance runs a command inside a running instance through its guest agent.

func (*Server) ForkInstance 

func (h *Server) ForkInstance(
	ctx context.Context, req *dicerdv1.ForkInstanceRequest,
) (*dicerdv1.Instance, error)

ForkInstance creates an instance as a copy of another. See instance.Manager.ForkInstance.

func (*Server) ForkSnapshot 

func (h *Server) ForkSnapshot(
	ctx context.Context, req *dicerdv1.ForkSnapshotRequest,
) (*dicerdv1.Instance, error)

ForkSnapshot creates an instance as a copy of the one a snapshot was taken of.

func (*Server) GetEvents 

func (h *Server) GetEvents(
	req *dicerdv1.GetEventsRequest, stream grpc.ServerStreamingServer[dicerdv1.GetEventsResponse],
) error

GetEvents sends the matching history, then new events if the request follows.

func (*Server) GetHostInfo 

func (h *Server) GetHostInfo(
	ctx context.Context, _ *dicerdv1.GetHostInfoRequest,
) (*dicerdv1.GetHostInfoResponse, error)

GetHostInfo reports the daemon's version, hostname, hypervisors and API addresses, and the token the call was made with.

func (*Server) GetImage 

func (h *Server) GetImage(
	_ context.Context, req *dicerdv1.GetImageRequest,
) (*dicerdv1.Image, error)

GetImage returns an image this host holds without contacting a registry.

func (*Server) GetInstance 

func (h *Server) GetInstance(
	_ context.Context, req *dicerdv1.GetInstanceRequest,
) (*dicerdv1.Instance, error)

GetInstance returns an instance with its status.

func (*Server) GetInstanceLogs 

func (h *Server) GetInstanceLogs(
	req *dicerdv1.GetInstanceLogsRequest,
	stream grpc.ServerStreamingServer[dicerdv1.InstanceLogChunk],
) error

GetInstanceLogs streams an instance's log to the client.

func (*Server) GetInstanceStats 

func (h *Server) GetInstanceStats(
	req *dicerdv1.GetInstanceStatsRequest,
	stream grpc.ServerStreamingServer[dicerdv1.GetInstanceStatsResponse],
) error

GetInstanceStats streams what instances use of the host. Stats are read once before the first batch, so that each batch can say how much CPU was used since the read before; an instance read for the first time, or started again since, is left out of the batch until it has been read twice.

func (*Server) GetKernel 

func (h *Server) GetKernel(
	_ context.Context, req *dicerdv1.GetKernelRequest,
) (*dicerdv1.Kernel, error)

GetKernel returns an imported kernel.

func (*Server) GetNetwork 

func (h *Server) GetNetwork(
	_ context.Context, req *dicerdv1.GetNetworkRequest,
) (*dicerdv1.Network, error)

GetNetwork returns a network with its address usage.

func (*Server) GetResources 

func (h *Server) GetResources(
	_ context.Context, _ *dicerdv1.GetResourcesRequest,
) (*dicerdv1.GetResourcesResponse, error)

GetResources reports the host's CPU, memory and disk, and what the instances hold of them.

func (*Server) GetSnapshot 

func (h *Server) GetSnapshot(
	_ context.Context, req *dicerdv1.GetSnapshotRequest,
) (*dicerdv1.Snapshot, error)

GetSnapshot returns a snapshot.

func (*Server) GetToken 

func (h *Server) GetToken(_ context.Context, req *dicerdv1.GetTokenRequest) (*dicerdv1.Token, error)

GetToken returns a token, without its secret.

func (*Server) GetVolume 

func (h *Server) GetVolume(
	_ context.Context, req *dicerdv1.GetVolumeRequest,
) (*dicerdv1.Volume, error)

GetVolume returns a volume.

func (*Server) ImportKernel 

func (h *Server) ImportKernel(
	stream grpc.ClientStreamingServer[dicerdv1.ImportKernelRequest, dicerdv1.Kernel],
) error

ImportKernel puts a kernel the client sends on the host, and records it once it is there.

func (*Server) ListImages 

func (h *Server) ListImages(
	_ context.Context, _ *dicerdv1.ListImagesRequest,
) (*dicerdv1.ListImagesResponse, error)

ListImages lists the images this host holds.

func (*Server) ListInstanceProcesses 

func (h *Server) ListInstanceProcesses(
	ctx context.Context, req *dicerdv1.ListInstanceProcessesRequest,
) (*dicerdv1.ListInstanceProcessesResponse, error)

ListInstanceProcesses asks a running instance's guest agent for the processes in the guest.

func (*Server) ListInstances 

func (h *Server) ListInstances(
	_ context.Context, _ *dicerdv1.ListInstancesRequest,
) (*dicerdv1.ListInstancesResponse, error)

ListInstances lists every instance with its status, sorted by name.

func (*Server) ListKernels 

func (h *Server) ListKernels(
	_ context.Context, _ *dicerdv1.ListKernelsRequest,
) (*dicerdv1.ListKernelsResponse, error)

ListKernels lists the imported kernels, sorted by name.

func (*Server) ListNetworkAllocations 

func (h *Server) ListNetworkAllocations(
	_ context.Context, req *dicerdv1.ListNetworkAllocationsRequest,
) (*dicerdv1.ListNetworkAllocationsResponse, error)

ListNetworkAllocations lists the addresses a network has allocated.

func (*Server) ListNetworks 

func (h *Server) ListNetworks(
	_ context.Context, _ *dicerdv1.ListNetworksRequest,
) (*dicerdv1.ListNetworksResponse, error)

ListNetworks lists the networks, sorted by name, with their address usage.

func (*Server) ListSnapshots 

func (h *Server) ListSnapshots(
	_ context.Context, req *dicerdv1.ListSnapshotsRequest,
) (*dicerdv1.ListSnapshotsResponse, error)

ListSnapshots lists the snapshots, or those of one instance.

func (*Server) ListTokens 

func (h *Server) ListTokens(context.Context, *dicerdv1.ListTokensRequest) (*dicerdv1.ListTokensResponse, error)

ListTokens lists the tokens, sorted by name, without their secrets.

func (*Server) ListVolumes 

func (h *Server) ListVolumes(
	_ context.Context, _ *dicerdv1.ListVolumesRequest,
) (*dicerdv1.ListVolumesResponse, error)

ListVolumes lists the volumes, sorted by name.

func (*Server) PauseInstance 

func (h *Server) PauseInstance(
	ctx context.Context, req *dicerdv1.PauseInstanceRequest,
) (*dicerdv1.Instance, error)

PauseInstance pauses a running instance.

func (*Server) PruneImages 

func (h *Server) PruneImages(
	_ context.Context, _ *dicerdv1.PruneImagesRequest,
) (*dicerdv1.PruneImagesResponse, error)

PruneImages removes the images nothing is defined to boot from.

func (*Server) PullImage 

func (h *Server) PullImage(
	req *dicerdv1.PullImageRequest,
	stream grpc.ServerStreamingServer[dicerdv1.PullImageProgress],
) error

PullImage pulls an image, streaming progress and finally the image.

func (*Server) RenameInstance 

func (h *Server) RenameInstance(
	ctx context.Context, req *dicerdv1.RenameInstanceRequest,
) (*dicerdv1.Instance, error)

RenameInstance changes a stopped instance's name.

func (*Server) ResizeInstance 

func (h *Server) ResizeInstance(
	ctx context.Context, req *dicerdv1.ResizeInstanceRequest,
) (*dicerdv1.Instance, error)

ResizeInstance changes a running instance's vCPUs and memory. See instance.Manager.Resize. What the request leaves out stays as it is.

func (*Server) RestoreSnapshot 

func (h *Server) RestoreSnapshot(
	ctx context.Context, req *dicerdv1.RestoreSnapshotRequest,
) (*dicerdv1.Instance, error)

RestoreSnapshot puts the instance a snapshot was taken of back as it was.

func (*Server) ResumeInstance 

func (h *Server) ResumeInstance(
	ctx context.Context, req *dicerdv1.ResumeInstanceRequest,
) (*dicerdv1.Instance, error)

ResumeInstance resumes a paused instance.

func (*Server) RotateToken 

func (h *Server) RotateToken(ctx context.Context, req *dicerdv1.RotateTokenRequest) (*dicerdv1.IssuedToken, error)

RotateToken gives a token a new secret and returns its new value. The old value no longer works.

func (*Server) StandbyInstance 

func (h *Server) StandbyInstance(
	ctx context.Context, req *dicerdv1.StandbyInstanceRequest,
) (*dicerdv1.Instance, error)

StandbyInstance freezes a running or paused instance to disk. See instance.Manager.Standby.

func (*Server) StartInstance 

func (h *Server) StartInstance(
	ctx context.Context, req *dicerdv1.StartInstanceRequest,
) (*dicerdv1.Instance, error)

StartInstance boots an instance.

func (*Server) StopInstance 

func (h *Server) StopInstance(
	ctx context.Context, req *dicerdv1.StopInstanceRequest,
) (*dicerdv1.Instance, error)

StopInstance shuts an instance down.

func (*Server) UpdateInstance 

func (h *Server) UpdateInstance(
	ctx context.Context, req *dicerdv1.UpdateInstanceRequest,
) (*dicerdv1.Instance, error)

UpdateInstance modifies an instance's definition. See instance.Manager.Update.

func (*Server) WaitInstance 

func (h *Server) WaitInstance(
	req *dicerdv1.WaitInstanceRequest, stream grpc.ServerStreamingServer[dicerdv1.WaitInstanceResponse],
) error

WaitInstance waits for an instance to stop and sends how it ended, or waits for it to be healthy.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.