backend

README

Backend implementation notes

Store Concurrency

• The backend assumes at most one backend is running per-store-directory.
• The backend generally assumes that no other process will write to the store directory. (However, it is a bit more defensive about testing this assumption: if a store object is obviously missing or corrupted, it will complain.)
• The backend assumes that if and only if a store object is present in the store directory will a corresponding row exist in the objects table.
• The inProgress lock for a store path is acquired before accessing any store object. The lock is held while importing or accessing a store object. During access, the lock is released once it has been determined that the object exists. (Code may assume that if a store object exists at this time, it is fully constructed because of the previous bullet.) During import of a store object, the lock is released once it has been written to the filesystem and the row has been written to the objects table.

Documentation

Overview

Package backend provides a zbstore implementation backed by local compute resources.

Index

• Constants
• func CanSandbox() bool
• func SystemSupportsSandbox() bool
• func WithPeer(parent context.Context, peer jsonrpc.Handler) context.Context
• type BuildUser
  • func (user BuildUser) String() string
• type NARReceiver
  • func (r *NARReceiver) Cleanup(ctx context.Context)
  • func (r *NARReceiver) ReceiveNAR(trailer *zbstore.ExportTrailer)
  • func (r *NARReceiver) Write(p []byte) (n int, err error)
• type Options
• type Server
  • func NewServer(dir zbstore.Directory, dbPath string, opts *Options) *Server
  • func (s *Server) Close() error
  • func (s *Server) JSONRPC(ctx context.Context, req *jsonrpc.Request) (*jsonrpc.Response, error)
  • func (s *Server) NewNARReceiver(ctx context.Context) *NARReceiver

Constants

const DefaultBuildUsersGroup = "zbld"

DefaultBuildUsersGroup is the conventional name of the Unix group for the users that execute builders on behalf of the daemon.

Functions

func CanSandbox

func CanSandbox() bool

CanSandbox reports whether the current execution environment supports sandboxing.

func SystemSupportsSandbox

func SystemSupportsSandbox() bool

SystemSupportsSandbox reports whether the host operating system supports sandboxing.

func WithPeer

func WithPeer(parent context.Context, peer jsonrpc.Handler) context.Context

WithPeer returns a copy of parent in which the given handler is used as the client's connection.

Types

type BuildUser

type BuildUser struct {
	// UID is the user ID.
	UID int
	// GID is the user's primary group ID.
	GID int
}

BuildUser is a descriptor for a Unix user.

func (BuildUser) String

func (user BuildUser) String() string

type NARReceiver

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

NARReceiver is a per-connection zbstore.NARReceiver.

func (*NARReceiver) Cleanup

func (r *NARReceiver) Cleanup(ctx context.Context)

Cleanup releases any resources associated with the receiver.

func (*NARReceiver) ReceiveNAR

func (r *NARReceiver) ReceiveNAR(trailer *zbstore.ExportTrailer)

func (*NARReceiver) Write

func (r *NARReceiver) Write(p []byte) (n int, err error)

type Options

type Options struct {
	// RealDir is where the store objects are located physically on disk.
	// If empty, defaults to the store directory.
	RealDir string
	// BuildDir is where realizations' working directories will be placed.
	// If empty, defaults to [os.TempDir].
	BuildDir string

	// If DisableSandbox is true, then builders are always run without the sandbox.
	// Otherwise, sandboxing is used whenever possible.
	DisableSandbox bool
	// SandboxPaths is a map of paths inside the sandbox
	// to paths on the host machine.
	// These paths will be made available to sandboxed builders.
	SandboxPaths map[string]string

	// BuildUsers is the set of user IDs to use for builds on non-Windows systems.
	// If empty, then builds will use the current process's privileges.
	// [NewServer] will panic if multiple entries have the same user ID.
	BuildUsers []BuildUser
}

Options is the set of optional parameters to NewServer.

type Server

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

Server is a local store. Server implements jsonrpc.Handler and is intended to be used with jsonrpc.Serve.

func NewServer

func NewServer(dir zbstore.Directory, dbPath string, opts *Options) *Server

NewServer returns a new Server for the given store directory and database path. Callers are responsible for calling Server.Close on the returned server.

func (*Server) Close

func (s *Server) Close() error

Close releases any resources associated with the server.

func (*Server) JSONRPC

func (s *Server) JSONRPC(ctx context.Context, req *jsonrpc.Request) (*jsonrpc.Response, error)

JSONRPC implements the jsonrpc.Handler interface and serves the zbstore API.

func (*Server) NewNARReceiver

func (s *Server) NewNARReceiver(ctx context.Context) *NARReceiver

NewNARReceiver returns a new NARReceiver that is attached to the server. Callers are responsible for calling NARReceiver.Cleanup after the receiver is no longer in use.