pcb

README

Pantopic Turbokube

An etcd compatible distributed database.

Status

This repository has two side-by-side implementations, one native and one in WebAssembly. The same test suite can be run against native, WebAssembly, or an etcd instance to evaluate parity.

Many uncommonly used etcd features are not implemented (such as locks and leader election).

Name

This model was originally named something else. A load test was created and named Turbokube due to its architecture. We commissioned a logo and made some stickers for the turbokube load test project and people liked the logo even knowing nothing bout the project. At the same time, some features like Lease ID selection in the Lease API forced us to lean toward an API that only supports the Go Client not the gRPC API which basically makes it tailor made for Kubernetes. So this model was renamed from config-bus to turbokube to adopt the logo and make the expected use case more clear.

Roadmap

This project is in alpha. Breaking changes should be expected until Beta.

• v0.0.x - Alpha
  • Migrate working implementation to Pantopic model (Wasm)
• v0.1.x - Beta
  • Add metrics
  • Test in production
• v1.x.x - General Availability
  • Proven long term stability in production

Documentation

Index

• Constants
• Variables
• func NewController(ctx context.Context, log *slog.Logger) *controller
• func NewEndpointHandler(grpcServer *grpc.Server) *endpointHandler
• func NewServiceCluster(client zongzi.ShardClient, apiAddr string) *serviceCluster
• func NewServiceKv(client zongzi.ShardClient) *kvService
• func NewServiceLease(client zongzi.ShardClient) *serviceLease
• func NewServiceMaintenance(client zongzi.ShardClient) *serviceMaintenance
• func NewServiceWatch(client zongzi.ShardClient) *serviceWatch
• func NewStateMachineFactory(logger *slog.Logger, dataDir string) zongzi.StateMachinePersistentFactory
• type ContextCopy
• type Controller
• type Entry
• type Result

Constants

const (
	KV_FLAG_PATCH uint8 = 1 << iota
	KV_FLAG_COMPRESSED
)

const (
	CMD_INTERNAL_TERM byte = iota
	CMD_INTERNAL_TICK
	CMD_KV_PUT
	CMD_KV_DELETE_RANGE
	CMD_KV_COMPACT
	CMD_KV_TXN
	CMD_LEASE_GRANT
	CMD_LEASE_REVOKE
	CMD_LEASE_KEEP_ALIVE
	CMD_LEASE_KEEP_ALIVE_BATCH
)

const (
	QUERY_KV_RANGE byte = iota
	QUERY_LEASE_LEASES
	QUERY_LEASE_TIME_TO_LIVE
	QUERY_WATCH_PROGRESS
	QUERY_HEADER
)

const (
	WatchMessageType_UNKNOWN byte = iota
	WatchMessageType_INIT
	WatchMessageType_EVENT
	WatchMessageType_SYNC
	WatchMessageType_NOTIFY
	WatchMessageType_CANCELED
	WatchMessageType_ERR_COMPACTED
	WatchMessageType_ERR_EXISTS
)

const (
	// PCB_TXN_OPS_LIMIT limits the maximum number of operations per transaction. Hard limit allows use of last
	// 10 bits of revision to represent subrevision. Max txn ops in K8s is set to 1000.
	// Etcd default max is 128 but max can be set as high as MaxInt64. !!! VIOLATES PARITY !!!
	PCB_TXN_OPS_LIMIT = 1024

	// PCB_LIMIT_KEY_LENGTH limits the maximum length of any key.
	// Key length is unlimited in etc. !!! VIOLATES PARITY !!!
	PCB_LIMIT_KEY_LENGTH = 480
)

const Uri = "zongzi://github.com/pantopic/turbokube"

const (
	WATCH_DEBOUNCE = 50 * time.Millisecond
)

Variables

var (
	// PCB_RANGE_COUNT_FULL determines whether to execute a full scan for every range request to generate count.
	// Disabling this will likely improve performance of range requests covering lots of keys.
	// Full count is used by Kubernetes in at least one place (api server storage) but only because More is missing.
	// See https://github.com/kubernetes/kubernetes/blob/e85c72d4177fba224cb1baa1b5abfb5980e6d867/staging/src/k8s.io/apiserver/pkg/storage/etcd3/store.go#L762
	// Enabled by default for parity.
	PCB_RANGE_COUNT_FULL = true

	// PCB_RANGE_COUNT_FAKE determines whether to return a count value 1 greater than the number of results
	// when there are more results in a range query. This should be sufficient to trick Kubernetes into functioning
	// correctly without incurring the cost of scanning the entire key range to generate a count for each range request.
	// Disabled by default for parity.
	PCB_RANGE_COUNT_FAKE = false

	// PCB_RANGE_COUNT_FILTER_CORRECT determines whether to apply filters to the result count. This is a bug in etcd
	// that they don't intend to fix. Min/max mod/created rev are not used by Kubernetes so parity is unimportant.
	// Enabled by default. !!! VIOLATES PARITY !!!
	PCB_RANGE_COUNT_FILTER_CORRECT = true

	// PCB_PATCH_ENABLED determines whether to enable patches for non-current key revisions
	// Enabled by default due to transparently.
	PCB_PATCH_ENABLED = true

	// PCB_COMPRESSION_ENABLED determines whether to snappy compress values
	// Enabled by default due to transparently.
	PCB_COMPRESSION_ENABLED = true

	// PCB_TXN_MULTI_WRITE_ENABLED determines whether to allow multiple writes to a single key during a transaction.
	// Disabled by default for parity.
	PCB_TXN_MULTI_WRITE_ENABLED = false

	// PCB_WATCH_ID_ZERO_INDEX determines whether to start watch IDs at 0 rather than 1. Starting at 0 is bad API design
	// because it confuses the zero value with the empty state. Sending an explicit watchID in a create request will
	// fail if a watch with that ID already exists for all values of watchID except 0 which will generate a new ID.
	// Disabled by default. !!! VIOLATES PARITY !!!
	PCB_WATCH_ID_ZERO_INDEX = false

	// PCB_TXN_OPS_MAX sets the maximum number of operations allowed per transaction.
	// Matches etcd by default. Limited by [PCB_TXN_OPS_LIMIT]
	PCB_TXN_OPS_MAX = 128

	// PCB_RESPONSE_SIZE_MAX sets the maximum request and response size.
	// Matches etcd by default.
	PCB_RESPONSE_SIZE_MAX = 10 * 1024 * 1024

	// PCB_WATCH_PROGRESS_NOTIFY_INTERVAL sets the duration of periodic watch progress notification.
	// Matches etcd by default.
	PCB_WATCH_PROGRESS_NOTIFY_INTERVAL = 10 * time.Minute

	// PCB_READ_LOCAL forces Linearizable range requests to be served as Serializable (stale) if:
	// 1. The client requests a specific revision
	// 2. That revision is available locally
	// This works because revisions are immutable.
	// Enabled by default.
	PCB_READ_LOCAL = true

	// PCB_BATCH_LEASE_RENEWAL specifies whether to introduce artificial latency when batching lease renewals.
	// Reduces total number of raft proposals to improve efficiency at the cost of increased latency for lease renewals.
	// Enabled by default.
	PCB_BATCH_LEASE_RENEWAL          = true
	PCB_BATCH_LEASE_RENEWAL_LIMIT    = 1000
	PCB_BATCH_LEASE_RENEWAL_INTERVAL = 500 * time.Millisecond
)

var (
	ErrChecksumInvalid = fmt.Errorf(`Checksum invalid`)
	ErrChecksumMissing = fmt.Errorf(`Checksum missing`)
	ErrValueInvalid    = fmt.Errorf(`Value invalid`)
	ErrPatchInvalid    = fmt.Errorf(`Patch invalid (missing next?)`)
	ErrKeyInvalid      = fmt.Errorf(`Key invalid`)
	ErrKeyMissing      = fmt.Errorf(`Key missing`)
	ErrLeaseKeyInvalid = fmt.Errorf(`Lease key invalid`)
	ErrNotFound        = fmt.Errorf(`Not found`)
	ErrTermExpired     = fmt.Errorf(`Term expired`)
)

Functions

func NewController

func NewController(ctx context.Context, log *slog.Logger) *controller

func NewEndpointHandler

func NewEndpointHandler(grpcServer *grpc.Server) *endpointHandler

func NewServiceCluster

func NewServiceCluster(client zongzi.ShardClient, apiAddr string) *serviceCluster

func NewServiceKv

func NewServiceKv(client zongzi.ShardClient) *kvService

func NewServiceLease

func NewServiceLease(client zongzi.ShardClient) *serviceLease

func NewServiceMaintenance

func NewServiceMaintenance(client zongzi.ShardClient) *serviceMaintenance

func NewServiceWatch

func NewServiceWatch(client zongzi.ShardClient) *serviceWatch

func NewStateMachineFactory

func NewStateMachineFactory(logger *slog.Logger, dataDir string) zongzi.StateMachinePersistentFactory

Types

type ContextCopy

type ContextCopy = func(dst, src context.Context) context.Context

type Controller

type Controller interface {
	Start(client zongzi.ShardClient, shard zongzi.Shard) (err error)
}

Controller operates background processes like epoch advancement and election notices

type Entry

type Entry = zongzi.Entry

type Result

type Result = zongzi.Result